From 2a6b19f0d5293bb0ecbcc53ff86100bfe07c8431 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Mon, 6 Jul 2026 22:03:01 +1200
Subject: [PATCH 01/73] KAN-278 chore: drop replaces lists from squashed
 baselines

All instances (prod/UAT/demo) are past the squash and have the baseline
rows recorded in their ledgers, so the replaces lists are dead weight
(the follow-up noted in PR #434). Removing them now makes the upcoming
client->company app-label surgery unambiguous: no stale ("client", ...)
entries for the migration loader to resolve.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/accounting/migrations/0001_baseline.py   |  10 -
 apps/accounting/migrations/0002_baseline.py   |   4 -
 apps/accounts/migrations/0001_baseline.py     |  18 --
 apps/accounts/migrations/0002_baseline.py     |   4 -
 .../0003_seed_system_automation_user.py       |   3 -
 apps/client/migrations/0001_baseline.py       |  26 --
 apps/crm/migrations/0001_baseline.py          |  10 -
 .../0002_seed_phone_call_schedules.py         |   3 -
 apps/job/migrations/0001_baseline.py          | 109 --------
 .../migrations/0002_seed_labour_subtypes.py   |   5 -
 apps/operations/migrations/0001_baseline.py   |   5 -
 apps/process/migrations/0001_baseline.py      |   6 -
 apps/purchasing/migrations/0001_baseline.py   |  36 ---
 apps/quoting/migrations/0001_baseline.py      |  23 --
 apps/workflow/migrations/0001_baseline.py     | 240 ------------------
 .../migrations/0002_seed_xero_pay_items.py    |   3 -
 .../0003_seed_celery_beat_schedules.py        |   5 -
 17 files changed, 510 deletions(-)

diff --git a/apps/accounting/migrations/0001_baseline.py b/apps/accounting/migrations/0001_baseline.py
index 2789339bc..e08f412b8 100644
--- a/apps/accounting/migrations/0001_baseline.py
+++ b/apps/accounting/migrations/0001_baseline.py
@@ -12,16 +12,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("accounting", "0001_initial"),
-        ("accounting", "0002_initial"),
-        ("accounting", "0003_alter_invoice_job"),
-        ("accounting", "0004_protect_critical_fks"),
-        ("accounting", "0005_quote_number"),
-        ("accounting", "0006_alter_bill_table_alter_billlineitem_table_and_more"),
-        ("accounting", "0007_partial_invoice_billing_metadata"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
     ]
diff --git a/apps/accounting/migrations/0002_baseline.py b/apps/accounting/migrations/0002_baseline.py
index 0c37215ac..c459575d3 100644
--- a/apps/accounting/migrations/0002_baseline.py
+++ b/apps/accounting/migrations/0002_baseline.py
@@ -8,10 +8,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("accounting", "0008_normalize_xero_raw_json_strings"),
-    ]
-
     dependencies = [
         ("accounting", "0001_baseline"),
         ("client", "0001_baseline"),
diff --git a/apps/accounts/migrations/0001_baseline.py b/apps/accounts/migrations/0001_baseline.py
index e4859523e..c2ac1e64e 100644
--- a/apps/accounts/migrations/0001_baseline.py
+++ b/apps/accounts/migrations/0001_baseline.py
@@ -11,24 +11,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("accounts", "0001_initial"),
-        ("accounts", "0002_initial"),
-        ("accounts", "0003_alter_historicalstaff_updated_at_and_more"),
-        ("accounts", "0004_add_staff_permissions_tables"),
-        ("accounts", "0005_alter_staff_groups_alter_staff_user_permissions"),
-        ("accounts", "0006_historicalstaff_date_left_staff_date_left"),
-        ("accounts", "0007_auto_20250730_2359"),
-        ("accounts", "0008_remove_historicalstaff_is_active_and_more"),
-        ("accounts", "0009_historicalstaff_xero_user_id_staff_xero_user_id"),
-        ("accounts", "0010_rename_is_staff_historicalstaff_is_office_staff_and_more"),
-        ("accounts", "0011_remove_ims_payroll_fields"),
-        ("accounts", "0012_add_base_wage_rate"),
-        ("accounts", "0013_alter_historicalstaff_table_alter_staff_table"),
-        ("accounts", "0014_add_is_workshop_staff"),
-        ("accounts", "0016_historicalstaff_default_labour_subtype_and_more"),
-    ]
-
     dependencies = []
 
     operations = [
diff --git a/apps/accounts/migrations/0002_baseline.py b/apps/accounts/migrations/0002_baseline.py
index 6faa3e2a1..97ef6434f 100644
--- a/apps/accounts/migrations/0002_baseline.py
+++ b/apps/accounts/migrations/0002_baseline.py
@@ -9,10 +9,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("accounts", "0017_backfill_staff_default_labour_subtype"),
-    ]
-
     dependencies = [
         ("accounts", "0001_baseline"),
         ("auth", "0012_alter_user_first_name_max_length"),
diff --git a/apps/accounts/migrations/0003_seed_system_automation_user.py b/apps/accounts/migrations/0003_seed_system_automation_user.py
index b460a50c9..d3b303a41 100644
--- a/apps/accounts/migrations/0003_seed_system_automation_user.py
+++ b/apps/accounts/migrations/0003_seed_system_automation_user.py
@@ -40,9 +40,6 @@ def delete_system_automation_user(
 
 
 class Migration(migrations.Migration):
-    replaces = [
-        ("accounts", "0015_create_system_automation_user"),
-    ]
 
     dependencies = [
         ("accounts", "0002_baseline"),
diff --git a/apps/client/migrations/0001_baseline.py b/apps/client/migrations/0001_baseline.py
index c6edd8ddf..eff64690a 100644
--- a/apps/client/migrations/0001_baseline.py
+++ b/apps/client/migrations/0001_baseline.py
@@ -14,32 +14,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("client", "0001_initial"),
-        ("client", "0002_clientcontact"),
-        ("client", "0003_add_xero_merge_tracking"),
-        ("client", "0004_populate_merge_fields"),
-        ("client", "0005_client_is_supplier"),
-        ("client", "0006_alter_client_name"),
-        ("client", "0007_delete_empty_name_contacts"),
-        ("client", "0008_merge_duplicate_contacts"),
-        ("client", "0009_clientcontact_unique_client_contact_name"),
-        ("client", "0010_add_is_active_to_clientcontact"),
-        ("client", "0011_convert_empty_strings_to_null"),
-        ("client", "0012_supplierpickupaddress"),
-        ("client", "0013_add_google_fields_to_pickup_address"),
-        ("client", "0014_add_suburb_to_pickup_address"),
-        ("client", "0015_populate_xero_addresses"),
-        ("client", "0016_alter_client_table_alter_clientcontact_table_and_more"),
-        ("client", "0017_reassign_stranded_merged_client_fks"),
-        ("client", "0018_client_allow_jobs"),
-        ("client", "0019_client_name_fts_index"),
-        ("client", "0020_suppliersearchalias_and_more"),
-        ("client", "0021_clientcontactmethod"),
-        ("client", "0022_client_name_trgm_index"),
-        ("client", "0023_drop_scalar_phone_fields"),
-    ]
-
     dependencies = []
 
     operations = [
diff --git a/apps/crm/migrations/0001_baseline.py b/apps/crm/migrations/0001_baseline.py
index b044779fc..99570b94b 100644
--- a/apps/crm/migrations/0001_baseline.py
+++ b/apps/crm/migrations/0001_baseline.py
@@ -12,16 +12,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("crm", "0001_initial"),
-        ("crm", "0003_phonecallrecording_archive_error"),
-        ("crm", "0004_phonecallrecord_job_link"),
-        ("crm", "0006_phone_endpoints_and_classification"),
-        ("crm", "0007_alter_phoneprovidersettings_password_and_more"),
-        ("crm", "0008_phone_call_number_indexes"),
-        ("crm", "0009_phone_call_normalized_numbers"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
         ("job", "0001_baseline"),
diff --git a/apps/crm/migrations/0002_seed_phone_call_schedules.py b/apps/crm/migrations/0002_seed_phone_call_schedules.py
index 08e3b5b03..a4d63c3ea 100644
--- a/apps/crm/migrations/0002_seed_phone_call_schedules.py
+++ b/apps/crm/migrations/0002_seed_phone_call_schedules.py
@@ -74,9 +74,6 @@ def remove_phone_call_schedules(
 
 
 class Migration(migrations.Migration):
-    replaces = [
-        ("crm", "0005_phone_call_sync_near_realtime"),
-    ]
 
     dependencies = [
         ("crm", "0001_baseline"),
diff --git a/apps/job/migrations/0001_baseline.py b/apps/job/migrations/0001_baseline.py
index b61ecbd07..37a56db51 100644
--- a/apps/job/migrations/0001_baseline.py
+++ b/apps/job/migrations/0001_baseline.py
@@ -15,115 +15,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("job", "0001_initial"),
-        ("job", "0002_alter_historicaljob_pricing_type_and_more"),
-        ("job", "0003_historicaljob_contact_email_job_contact_email"),
-        ("job", "0004_alter_historicaljob_contact_phone_and_more"),
-        ("job", "0005_remove_materialentry_source_stock_and_more"),
-        ("job", "0006_add_material_adjustment_jobpart_models"),
-        ("job", "0007_add_materialentry_add_adjustmententry"),
-        ("job", "0007_fix_jobpart_state"),
-        ("job", "0008_alter_jobpart_options_and_more"),
-        ("job", "0009_historicaljob_priority_job_priority_and_more"),
-        ("job", "0010_populate_priority_for_existing_jobs"),
-        ("job", "0011_rename_revenue_adjustment_adjustmententry_price_adjustment_and_more"),
-        ("job", "0011_update_purchase_order_line_reference"),
-        ("job", "0012_alter_jobevent_job"),
-        ("job", "0012_merge_20250604_2123"),
-        ("job", "0013_merge_20250605_0811"),
-        ("job", "0014_alter_jobpart_table"),
-        ("job", "0015_alter_historicaljob_client_alter_job_client_and_more"),
-        ("job", "0016_add_contact_foreignkey"),
-        ("job", "0017_migrate_contact_data"),
-        ("job", "0018_add_accounting_date_fields"),
-        ("job", "0018_costing_initial"),
-        ("job", "0019_job_latest_sets"),
-        ("job", "0019_populate_accounting_dates"),
-        ("job", "0020_change_priority_to_float"),
-        ("job", "0021_add_is_quote_adjustment_field"),
-        ("job", "0022_merge_20250615_1511"),
-        ("job", "0023_add_new_job_statuses"),
-        ("job", "0024_rename_pricing_jobpricing"),
-        ("job", "0025_update_job_statuses_for_kanban"),
-        ("job", "0026_alter_historicaljob_status_alter_job_status"),
-        ("job", "0027_quotespreadsheet"),
-        ("job", "0028_add_job_quote_chat_model"),
-        ("job", "0029_remove_historicaljob_contact_email_and_more"),
-        ("job", "0030_migrate_pricing_to_costing_and_cleanup"),
-        ("job", "0031_remove_jobpart_job_pricing_and_more"),
-        ("job", "0032_fix_blank_job_names"),
-        ("job", "0033_update_job_statuses_for_simplified_kanban"),
-        ("job", "0034_remove_legacy_status_choices"),
-        ("job", "0035_alter_jobevent_id"),
-        ("job", "0036_complete_uuid_transition"),
-        ("job", "0037_finalize_uuid_transition"),
-        ("job", "0038_add_event_deduplication"),
-        ("job", "0039_alter_job_options_costline_xero_expense_id_and_more"),
-        ("job", "0040_historicaljob_fully_invoiced_job_fully_invoiced"),
-        ("job", "0041_populate_fully_invoiced"),
-        ("job", "0042_add_xero_default_task_id"),
-        ("job", "0043_alter_costline_xero_last_modified_and_more"),
-        ("job", "0044_alter_costline_options_costline_created_at_and_more"),
-        ("job", "0045_create_job_delta_rejection"),
-        ("job", "0046_add_delta_fields_to_job_event"),
-        ("job", "0047_add_accounting_date_nullable"),
-        ("job", "0048_populate_accounting_date"),
-        ("job", "0049_make_accounting_date_not_null"),
-        ("job", "0050_backfill_costset_summaries"),
-        ("job", "0051_fix_costset_summary_default"),
-        ("job", "0052_alter_costline_desc"),
-        ("job", "0053_add_speed_quality_tradeoff"),
-        ("job", "0054_protect_critical_fks"),
-        ("job", "0055_add_price_cap"),
-        ("job", "0056_add_safety_document"),
-        ("job", "0057_safetydocument_google_docs"),
-        ("job", "0058_safetydocument_document_number_and_more"),
-        ("job", "0059_costline_approved"),
-        ("job", "0060_alter_historicaljob_rejected_flag_and_more"),
-        ("job", "0061_fix_labour_cost_lines"),
-        ("job", "0062_alter_costline_meta_ext_refs"),
-        ("job", "0063_job_payroll_category"),
-        ("job", "0064_job_default_xero_pay_item"),
-        ("job", "0065_make_default_xero_pay_item_required"),
-        ("job", "0066_zero_shop_job_revenue"),
-        ("job", "0067_normalize_wage_rate_multiplier"),
-        ("job", "0068_add_completed_at"),
-        ("job", "0069_fix_fully_invoiced"),
-        ("job", "0070_delete_safetydocument"),
-        ("job", "0071_add_rdti_type"),
-        ("job", "0072_rename_job_quote_c_job_id_24cfd1_idx_job_jobquot_job_id_c83a63_idx_and_more"),
-        ("job", "0073_add_min_max_people"),
-        ("job", "0074_jobdeltarejection_resolved_and_more"),
-        ("job", "0075_backfill_jobevent_status_from_historicaljob"),
-        ("job", "0076_add_jobevent_detail_field"),
-        ("job", "0077_backfill_jobevent_detail"),
-        ("job", "0078_backfill_jobevent_staff_from_history"),
-        ("job", "0079_alter_jobevent_staff_not_null"),
-        ("job", "0080_backfill_jobevent_status_delta"),
-        ("job", "0081_backfill_jobevent_creation_delta"),
-        ("job", "0082_drop_jobevent_description"),
-        ("job", "0083_enable_pg_trgm"),
-        ("job", "0084_reconcile_time_xero_pay_items"),
-        ("job", "0085_backfill_time_rate_multipliers"),
-        ("job", "0086_repoint_stale_time_pay_items"),
-        ("job", "0087_costline_staff_entry_seq"),
-        ("job", "0088_reclassify_stock_consumption_costlines"),
-        ("job", "0089_backfill_costline_staff_entry_seq"),
-        ("job", "0090_costline_staff_entry_seq_constraints"),
-        ("job", "0091_require_latest_costsets_drop_historicaljob"),
-        ("job", "0092_laboursubtype_joblabourrate"),
-        ("job", "0094_costline_labour_subtype"),
-        ("job", "0095_backfill_job_labour_rates_and_costline_subtypes"),
-        ("job", "0096_remove_job_charge_out_rate"),
-        ("job", "0097_alter_joblabourrate_options"),
-        ("job", "0100_reclassify_labour_cost_lines"),
-        ("job", "0101_reclassify_generic_labour_cost_lines"),
-        ("job", "0102_rerate_onsite_open_jobs"),
-        ("job", "0103_add_job_is_urgent"),
-        ("job", "0104_non_negative_labour_rates"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
         ("workflow", "0001_baseline"),
diff --git a/apps/job/migrations/0002_seed_labour_subtypes.py b/apps/job/migrations/0002_seed_labour_subtypes.py
index 10032f954..44a38c132 100644
--- a/apps/job/migrations/0002_seed_labour_subtypes.py
+++ b/apps/job/migrations/0002_seed_labour_subtypes.py
@@ -50,11 +50,6 @@ def unseed_subtypes(apps: StateApps, schema_editor: BaseDatabaseSchemaEditor) ->
 
 
 class Migration(migrations.Migration):
-    replaces = [
-        ("job", "0093_seed_labour_subtypes"),
-        ("job", "0098_clean_labour_subtype_catalogue"),
-        ("job", "0099_add_onsite_quoting_and_reactivate_delivery"),
-    ]
 
     dependencies = [
         ("job", "0001_baseline"),
diff --git a/apps/operations/migrations/0001_baseline.py b/apps/operations/migrations/0001_baseline.py
index f3924ffaf..2c906a9e7 100644
--- a/apps/operations/migrations/0001_baseline.py
+++ b/apps/operations/migrations/0001_baseline.py
@@ -12,11 +12,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("operations", "0001_initial_operations_models"),
-        ("operations", "0002_not_reached_in_horizon"),
-    ]
-
     dependencies = [
         ("job", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
diff --git a/apps/process/migrations/0001_baseline.py b/apps/process/migrations/0001_baseline.py
index b74ac9789..d0133ebc5 100644
--- a/apps/process/migrations/0001_baseline.py
+++ b/apps/process/migrations/0001_baseline.py
@@ -12,12 +12,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("process", "0001_initial"),
-        ("process", "0002_formentry_staff_historicalformentry_staff_and_more"),
-        ("process", "0003_alter_form_table_alter_formentry_table_and_more"),
-    ]
-
     dependencies = [
         ("job", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
diff --git a/apps/purchasing/migrations/0001_baseline.py b/apps/purchasing/migrations/0001_baseline.py
index f7f7e182e..fa1bd201f 100644
--- a/apps/purchasing/migrations/0001_baseline.py
+++ b/apps/purchasing/migrations/0001_baseline.py
@@ -14,42 +14,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("purchasing", "0001_move_purchase_models_state"),
-        ("purchasing", "0002_move_purchase_models_database"),
-        ("purchasing", "0003_alter_purchaseorder_xero_tenant_id_and_more"),
-        ("purchasing", "0004_stock"),
-        ("purchasing", "0005_add_stock_in_database"),
-        ("purchasing", "0006_add_stock_item_code_xero_id"),
-        ("purchasing", "0007_stock_unique_xero_id"),
-        ("purchasing", "0008_stock_parsed_at_stock_parser_confidence_and_more"),
-        ("purchasing", "0009_purchaseorderline_item_code"),
-        ("purchasing", "0010_add_raw_json_to_purchaseorder"),
-        ("purchasing", "0011_stock_xero_inventory_tracked"),
-        ("purchasing", "0012_add_unit_revenue_to_stock"),
-        ("purchasing", "0013_populate_unit_revenue_from_existing_data"),
-        ("purchasing", "0014_remove_retail_rate_field"),
-        ("purchasing", "0015_stock_active_source_purchase_order_line_id_and_more"),
-        ("purchasing", "0016_add_product_catalog_source"),
-        ("purchasing", "0017_remove_stock_notes"),
-        ("purchasing", "0018_add_xero_line_item_id"),
-        ("purchasing", "0019_populate_xero_line_item_id"),
-        ("purchasing", "0020_add_purchaseorderevent"),
-        ("purchasing", "0021_clean_po_line_descriptions"),
-        ("purchasing", "0022_add_pickup_address_to_po"),
-        ("purchasing", "0023_dedupe_stock_item_codes"),
-        ("purchasing", "0024_stock_item_code_unique"),
-        ("purchasing", "0025_add_xero_last_synced_to_stock"),
-        ("purchasing", "0026_remove_xero_last_synced_default"),
-        ("purchasing", "0027_add_created_by_to_purchase_order"),
-        ("purchasing", "0028_update_created_by_from_events"),
-        ("purchasing", "0029_alter_purchaseorder_table_and_more"),
-        ("purchasing", "0030_add_stock_updated_at"),
-        ("purchasing", "0031_stock_fts_index"),
-        ("purchasing", "0032_stock_parser_attempted_at"),
-        ("purchasing", "0033_use_aluminium_metal_type"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
         ("job", "0001_baseline"),
diff --git a/apps/quoting/migrations/0001_baseline.py b/apps/quoting/migrations/0001_baseline.py
index 979dba1d7..3bf913acc 100644
--- a/apps/quoting/migrations/0001_baseline.py
+++ b/apps/quoting/migrations/0001_baseline.py
@@ -13,29 +13,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("quoting", "0001_initial"),
-        ("quoting", "0002_supplierpricelist_supplierproduct_price_list"),
-        ("quoting", "0003_alter_supplierpricelist_supplier_and_more"),
-        ("quoting", "0004_scrapejob"),
-        ("quoting", "0005_alter_supplierproduct_unique_together_and_more"),
-        ("quoting", "0006_alter_supplierproduct_unique_together_and_more"),
-        ("quoting", "0007_supplierproduct_parsed_alloy_and_more"),
-        ("quoting", "0008_parse_existing_products"),
-        ("quoting", "0010_productparsingmapping_item_code_is_in_xero"),
-        ("quoting", "0011_add_mapping_hash_to_supplierproduct"),
-        ("quoting", "0012_supplierproduct_last_scraped"),
-        ("quoting", "0013_productparsingmapping_derived_key"),
-        ("quoting", "0014_make_parser_fields_nullable"),
-        ("quoting", "0015_protect_critical_fks"),
-        ("quoting", "0016_protect_supplier_relationships"),
-        ("quoting", "0017_add_is_discontinued_to_supplierproduct"),
-        ("quoting", "0018_mark_404_products_as_discontinued"),
-        ("quoting", "0019_use_aluminium_metal_type"),
-        ("quoting", "0020_suppliercredential_supplierscraperconfig_and_more"),
-        ("quoting", "0021_migrate_steel_and_tube_credentials"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
diff --git a/apps/workflow/migrations/0001_baseline.py b/apps/workflow/migrations/0001_baseline.py
index b7036553c..09e54e6ba 100644
--- a/apps/workflow/migrations/0001_baseline.py
+++ b/apps/workflow/migrations/0001_baseline.py
@@ -13,246 +13,6 @@ class Migration(migrations.Migration):
 
     initial = True
 
-    replaces = [
-        ("workflow", "0001_initial"),
-        ("workflow", "0003_companydefaults_alter_client_xero_contact_id"),
-        ("workflow", "0004_companydefaults_company_name"),
-        ("workflow", "0005_remove_companydefaults_id_and_more"),
-        ("workflow", "0006_quotepricing"),
-        ("workflow", "0007_remove_historicaljob_client_name_and_more"),
-        ("workflow", "0008_remove_jobpricing_job_pricing_number"),
-        ("workflow", "0009_historicaljob_job_is_valid_job_job_is_valid"),
-        ("workflow", "0010_remove_historicaljob_job_name_remove_job_job_name"),
-        ("workflow", "0011_remove_timeentry_minutes_timeentry_description_and_more"),
-        ("workflow", "0012_alter_timeentry_staff"),
-        ("workflow", "0013_alter_timeentry_date"),
-        ("workflow", "0014_historicaljob_quote_acceptance_date_and_more"),
-        ("workflow", "0015_historicaljob_delivery_date_job_delivery_date"),
-        ("workflow", "0016_materialentry_item_code"),
-        ("workflow", "0017_materialentry_comments"),
-        ("workflow", "0018_rename_cost_adjustmententry_cost_adjustment_and_more"),
-        ("workflow", "0019_alter_historicaljob_delivery_date_and_more"),
-        ("workflow", "0020_historicaljob_material_gauge_quantity_and_more"),
-        ("workflow", "0021_alter_historicaljob_description_and_more"),
-        ("workflow", "0022_alter_historicaljob_description_and_more"),
-        ("workflow", "0023_alter_historicaljob_contact_phone_and_more"),
-        ("workflow", "0024_alter_jobpricing_options_jobpricing_revision_number"),
-        ("workflow", "0025_historicaljob_latest_estimate_pricing_and_more"),
-        ("workflow", "0026_alter_job_latest_estimate_pricing_and_more"),
-        ("workflow", "0027_remove_jobpricing_job"),
-        ("workflow", "0028_jobpricing_job"),
-        ("workflow", "0029_alter_jobpricing_job"),
-        ("workflow", "0030_alter_jobpricing_job"),
-        ("workflow", "0031_alter_jobpricing_job"),
-        ("workflow", "0032_alter_job_latest_estimate_pricing_and_more"),
-        ("workflow", "0033_remove_jobpricing_job_and_more"),
-        ("workflow", "0034_alter_materialentry_quantity_and_more"),
-        ("workflow", "0035_alter_adjustmententry_comments_and_more"),
-        ("workflow", "0036_historicalstaff_hours_fri_historicalstaff_hours_mon_and_more"),
-        ("workflow", "0037_remove_historicalstaff_charge_out_rate_and_more"),
-        ("workflow", "0038_historicaljob_shop_job_job_shop_job"),
-        ("workflow", "0039_historicaljob_charge_out_rate_job_charge_out_rate"),
-        ("workflow", "0040_alter_historicaljob_charge_out_rate_and_more"),
-        ("workflow", "0041_timeentry_wage_rate_multiplier"),
-        ("workflow", "0042_jobpricing_job"),
-        ("workflow", "0043_alter_jobpricing_job"),
-        ("workflow", "0044_remove_timeentry_mins_per_item_timeentry_hours_and_more"),
-        ("workflow", "0045_remove_timeentry_minutes"),
-        ("workflow", "0046_alter_adjustmententry_options_alter_bill_options_and_more"),
-        ("workflow", "0047_rename_last_modified_bill_xero_last_modified_and_more"),
-        ("workflow", "0048_billlineitem_xero_id_invoicelineitem_xero_id"),
-        ("workflow", "0049_companydefaults_created_at_and_more"),
-        ("workflow", "0050_alter_historicalstaff_created_at_and_more"),
-        ("workflow", "0051_alter_historicalstaff_updated_at_and_more"),
-        ("workflow", "0052_alter_jobpricing_job"),
-        ("workflow", "0053_alter_job_latest_estimate_pricing_and_more"),
-        ("workflow", "0054_remove_historicaljob_shop_job_remove_job_shop_job_and_more"),
-        ("workflow", "0055_alter_historicaljob_description_and_more"),
-        ("workflow", "0056_rename_total_bill_total_excl_tax_and_more"),
-        ("workflow", "0057_rename_line_amount_billlineitem_line_amount_excl_tax_and_more"),
-        ("workflow", "0058_alter_billlineitem_options_and_more"),
-        ("workflow", "0059_rename_creditlineitem_creditnotelineitem_and_more"),
-        ("workflow", "0060_xerojournal_xerojournallineitem"),
-        ("workflow", "0061_xerojournallineitem_xero_last_modified"),
-        ("workflow", "0062_xerojournal_xero_last_modified"),
-        ("workflow", "0063_rename_date_xerojournal_journal_date"),
-        ("workflow", "0064_remove_xerojournallineitem_xero_last_modified"),
-        ("workflow", "0065_alter_xerojournal_journal_number"),
-        ("workflow", "0066_jobfile"),
-        ("workflow", "0067_jobfile_status"),
-        ("workflow", "0067_supplier_purchase_purchaseline_and_more"),
-        ("workflow", "0068_jobevent"),
-        ("workflow", "0068_purchase_created_at_purchase_updated_at_and_more"),
-        ("workflow", "0069_rename_user_jobevent_staff"),
-        ("workflow", "0070_jobevent_event_type"),
-        ("workflow", "0071_alter_jobevent_timestamp"),
-        ("workflow", "0072_merge_20250113_1626"),
-        ("workflow", "0073_jobpricing_is_historical"),
-        ("workflow", "0074_bill_xero_last_synced_client_xero_last_synced_and_more"),
-        ("workflow", "0075_invoice_online_url_quote"),
-        ("workflow", "0075_jobfile_print_on_jobsheet"),
-        ("workflow", "0076_invoice_job"),
-        ("workflow", "0076_remove_jobpricing_pricing_type_and_more"),
-        ("workflow", "0077_alter_quote_job"),
-        ("workflow", "0078_alter_quote_job"),
-        ("workflow", "0079_merge_20250207_1950"),
-        ("workflow", "0080_alter_historicaljob_material_gauge_quantity_and_more"),
-        ("workflow", "0080_historicaljob_complex_job_job_complex_job_and_more"),
-        ("workflow", "0081_add_last_xero_sync_to_company_defaults"),
-        ("workflow", "0082_add_last_xero_deep_sync"),
-        ("workflow", "0083_setup_xero_sync_service"),
-        ("workflow", "0084_cleanup_company_defaults"),
-        ("workflow", "0085_auto_20250302_2205"),
-        ("workflow", "0086_alter_historicaljob_contact_person_and_more"),
-        ("workflow", "0087_companydefaults_is_primary"),
-        ("workflow", "0088_merge_20250305_0549"),
-        ("workflow", "0089_companydefaults_starting_job_number_and_more"),
-        ("workflow", "0090_alter_staff_options"),
-        ("workflow", "0091_rename_coolected_historicaljob_collected_and_more"),
-        ("workflow", "0093_historicaljob_notes_job_notes"),
-        ("workflow", "0094_migrate_material_gauge_to_notes"),
-        ("workflow", "0095_alter_staff_options_and_more"),
-        ("workflow", "0096_merge_20250310_2039"),
-        ("workflow", "0097_alter_historicalstaff_ims_payroll_id_and_more"),
-        ("workflow", "0098_alter_historicalstaff_ims_payroll_id_and_more"),
-        ("workflow", "0099_historicaljob_created_by_job_created_by"),
-        ("workflow", "0100_companydefaults_xero_tenant_id"),
-        ("workflow", "0101_merge_20250317_1527"),
-        ("workflow", "0102_add_job_to_purchase_line"),
-        ("workflow", "0103_companydefaults_starting_po_number"),
-        ("workflow", "0104_alter_purchaseorder_expected_delivery"),
-        ("workflow", "0105_add_xero_fields_to_purchase_order"),
-        ("workflow", "0106_add_price_tbc_to_purchase_order_line"),
-        ("workflow", "0107_purchaseorder_online_url_purchaseorder_raw_json"),
-        ("workflow", "0108_xeroaccount_xero_last_synced"),
-        ("workflow", "0109_stock"),
-        ("workflow", "0110_purchaseorder_reference"),
-        ("workflow", "0111_alter_timeentry_minutes_per_item"),
-        ("workflow", "0112_remove_purchaseline_purchase_and_more"),
-        ("workflow", "0113_remove_stock_source_id_materialentry_source_stock_and_more"),
-        ("workflow", "0114_stock_is_active"),
-        ("workflow", "0115_alter_stock_id"),
-        ("workflow", "0116_stock_alloy_stock_location_stock_metal_type_and_more"),
-        ("workflow", "0117_alter_stock_metal_type"),
-        ("workflow", "0118_alter_materialentry_source_stock"),
-        ("workflow", "0119_alter_materialentry_source_stock"),
-        ("workflow", "0120_add_purchase_order_deleted_status"),
-        ("workflow", "0121_purchaseorderline_alloy_purchaseorderline_location_and_more"),
-        ("workflow", "0122_companydefaults_anthropic_api_key_and_more"),
-        ("workflow", "0123_alter_purchaseorder_order_date_and_more"),
-        ("workflow", "0124_companydefaults_billable_threshold_amber_and_more"),
-        ("workflow", "0125_normalize_po_numbers"),
-        ("workflow", "0126_alter_purchaseorder_order_date"),
-        ("workflow", "0127_remove_purchaseorder_raw_json_and_more"),
-        ("workflow", "0128_stock_retail_rate"),
-        ("workflow", "0129_companydefaults_gemini_api_key_stock_job_and_more"),
-        ("workflow", "0130_purchaseorderline_raw_line_data_stock_job_and_more"),
-        ("workflow", "0131_aiprovider_companydefaults_anthropic_api_key_and_more"),
-        ("workflow", "0132_stock_job_stock_source_purchase_order_line"),
-        ("workflow", "0133_bill_xero_tenant_id_client_xero_tenant_id_and_more"),
-        ("workflow", "0134_alter_purchaseorder_order_date"),
-        ("workflow", "0135_job_people_staff_icon_and_more"),
-        ("workflow", "0136_rename_job_status"),
-        ("workflow", "0137_auto_20250508_2012"),
-        ("workflow", "0138_stock_job_stock_source_purchase_order_line"),
-        ("workflow", "0139_bill_xero_tenant_id_client_xero_tenant_id_and_more"),
-        ("workflow", "0140_remove_staff_groups_remove_staff_user_permissions_and_more"),
-        ("workflow", "0141_remove_timeentry_job_pricing_remove_timeentry_staff_and_more"),
-        ("workflow", "0142_remove_historicaljob_client_and_more"),
-        ("workflow", "0143_alter_stock_job"),
-        ("workflow", "0144_remove_adjustmententry_job_pricing_and_more"),
-        ("workflow", "0145_fix_jobpricing_chain"),
-        ("workflow", "0146_delete_adjustmententry_delete_materialentry"),
-        ("workflow", "0147_companydefaults_po_prefix"),
-        ("workflow", "0148_client_primary_contact_email_and_more"),
-        ("workflow", "0149_remove_client_secondary_contact_email_and_more"),
-        ("workflow", "0150_client_all_phones"),
-        ("workflow", "0151_remove_purchaseline_purchase_and_more"),
-        ("workflow", "0152_remove_companydefaults_anthropic_api_key_and_more"),
-        ("workflow", "0153_delete_client_client"),
-        ("workflow", "0154_auto_20250604_1054"),
-        ("workflow", "0155_remove_stock_job_remove_stock_source_parent_stock_and_more"),
-        ("workflow", "0156_remove_stock_job_remove_stock_source_parent_stock_and_more"),
-        ("workflow", "0157_remove_bill_client_remove_billlineitem_bill_and_more"),
-        ("workflow", "0158_delete_bill_delete_billlineitem_delete_creditnote_and_more"),
-        ("workflow", "0159_add_shop_client_name_field"),
-        ("workflow", "0160_alter_aiprovider_provider_type"),
-        ("workflow", "0161_companydefaults_gdrive_quotes_folder_id_and_more"),
-        ("workflow", "0162_alter_companydefaults_gdrive_quotes_folder_id_and_more"),
-        ("workflow", "0163_rename_active_to_default_add_model_name"),
-        ("workflow", "0164_serviceapikey"),
-        ("workflow", "0165_app_error_models"),
-        ("workflow", "0166_alter_apperror_options_alter_xeroerror_options_and_more"),
-        ("workflow", "0167_alter_aiprovider_table"),
-        ("workflow", "0168_enhance_app_error_model"),
-        ("workflow", "0169_remove_aiprovider_company_field"),
-        ("workflow", "0170_companydefaults_xero_annual_leave_earnings_rate_id_and_more"),
-        ("workflow", "0171_protect_critical_fks"),
-        ("workflow", "0172_alter_xerotoken_scope"),
-        ("workflow", "0173_add_test_client_name_field"),
-        ("workflow", "0174_add_xero_payroll_models"),
-        ("workflow", "0175_make_payroll_fields_required"),
-        ("workflow", "0176_add_company_address_fields"),
-        ("workflow", "0177_add_company_email_url"),
-        ("workflow", "0178_add_company_acronym"),
-        ("workflow", "0179_add_xero_payroll_calendar_id"),
-        ("workflow", "0180_alter_xerotoken_scope"),
-        ("workflow", "0181_payrollcategory"),
-        ("workflow", "0182_populate_payroll_categories"),
-        ("workflow", "0183_remove_payroll_fields_from_companydefaults"),
-        ("workflow", "0184_add_xero_shortcode"),
-        ("workflow", "0185_fix_unpaid_leave_and_remove_posts_to_xero"),
-        ("workflow", "0186_simplify_payroll_category"),
-        ("workflow", "0188_delete_payrollcategory"),
-        ("workflow", "0189_add_xero_payroll_calendar_id"),
-        ("workflow", "0190_add_openai_provider_type"),
-        ("workflow", "0191_add_annual_leave_loading"),
-        ("workflow", "0192_add_financial_year_start_month"),
-        ("workflow", "0193_add_job_gp_target_percentage"),
-        ("workflow", "0194_add_profit_thresholds"),
-        ("workflow", "0195_rename_kpi_threshold_fields"),
-        ("workflow", "0196_alter_companydefaults_kpi_daily_billable_hours_amber_and_more"),
-        ("workflow", "0197_alter_xerotoken_scope"),
-        ("workflow", "0198_add_shared_drive_fields"),
-        ("workflow", "0199_populate_shared_drive_ids"),
-        ("workflow", "0200_xerosynccursor"),
-        ("workflow", "0201_add_xero_payroll_start_date"),
-        ("workflow", "0202_populate_xero_payroll_start_date"),
-        ("workflow", "0203_companydefaults_solo"),
-        ("workflow", "0204_alter_xerotoken_scope"),
-        ("workflow", "0205_companydefaults_company_phone"),
-        ("workflow", "0206_companydefaults_logo_companydefaults_logo_wide"),
-        ("workflow", "0207_unique_pay_item_name"),
-        ("workflow", "0208_enable_xero_sync"),
-        ("workflow", "0209_add_accounting_provider"),
-        ("workflow", "0209_rename_workflow_ap_timesta_ae5a69_idx_workflow_ap_timesta_a3d224_idx_and_more"),
-        ("workflow", "0210_merge_20260412_2225"),
-        ("workflow", "0211_apperror_app_error_resolved_msg_idx"),
-        ("workflow", "0212_companydefaults_singleton_check"),
-        ("workflow", "0213_companydefaults_weekend_timesheets_enabled"),
-        ("workflow", "0214_cachestate"),
-        ("workflow", "0215_add_daily_approved_hours_target"),
-        ("workflow", "0216_workshop_efficiency_factor"),
-        ("workflow", "0217_xeroapp"),
-        ("workflow", "0218_populate_xero_app"),
-        ("workflow", "0219_delete_xerotoken"),
-        ("workflow", "0221_drop_django_apscheduler_tables"),
-        ("workflow", "0222_remove_xero_sync_service"),
-        ("workflow", "0223_delete_cachestate"),
-        ("workflow", "0224_remove_app_error_resolved_msg_idx"),
-        ("workflow", "0225_alter_companydefaults_annual_leave_loading"),
-        ("workflow", "0227_delete_xero_journal"),
-        ("workflow", "0228_session_replay"),
-        ("workflow", "0230_session_replay_file_storage"),
-        ("workflow", "0231_companydefaults_shop_client_fk"),
-        ("workflow", "0232_rename_workflow_ap_timesta_a3d224_idx_workflow_apperror_time_sev_idx_and_more"),
-        ("workflow", "0233_companydefaults_job_delta_soft_fail_and_more"),
-        ("workflow", "0234_nullable_company_defaults_optional_urls"),
-        ("workflow", "0235_searchtelemetryevent"),
-        ("workflow", "0236_remove_companydefaults_charge_out_rate"),
-        ("workflow", "0237_remove_companydefaults_phone_fields"),
-    ]
-
     dependencies = [
         ("client", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
diff --git a/apps/workflow/migrations/0002_seed_xero_pay_items.py b/apps/workflow/migrations/0002_seed_xero_pay_items.py
index 35fff7c49..6dedb0c00 100644
--- a/apps/workflow/migrations/0002_seed_xero_pay_items.py
+++ b/apps/workflow/migrations/0002_seed_xero_pay_items.py
@@ -76,9 +76,6 @@ def delete_seed_xero_pay_items(
 
 
 class Migration(migrations.Migration):
-    replaces = [
-        ("workflow", "0187_create_xero_pay_item"),
-    ]
 
     dependencies = [
         ("workflow", "0001_baseline"),
diff --git a/apps/workflow/migrations/0003_seed_celery_beat_schedules.py b/apps/workflow/migrations/0003_seed_celery_beat_schedules.py
index 265608ed3..7df327045 100644
--- a/apps/workflow/migrations/0003_seed_celery_beat_schedules.py
+++ b/apps/workflow/migrations/0003_seed_celery_beat_schedules.py
@@ -145,11 +145,6 @@ def remove_schedules(apps: StateApps, schema_editor: BaseDatabaseSchemaEditor) -
 
 
 class Migration(migrations.Migration):
-    replaces = [
-        ("workflow", "0220_seed_celery_beat_schedule"),
-        ("workflow", "0226_seed_stock_metadata_parse_schedule"),
-        ("workflow", "0229_seed_session_replay_purge_schedule"),
-    ]
 
     dependencies = [
         ("workflow", "0002_seed_xero_pay_items"),

From 6657326e88fe89f05edac4f855e215c31279c6a4 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Mon, 6 Jul 2026 22:37:30 +1200
Subject: [PATCH 02/73] KAN-278 refactor: rename client app/model to company
 (backend + generated API client)

Pure structural rename - no behavioral change, zero row-value changes:
- apps/client -> apps/company (app label 'company'), model Client -> Company
- FK/field renames: Job.client, Invoice/Bill/CreditNote/Quote.client,
  PhoneCallRecord.client -> company; CompanyDefaults.shop_client ->
  shop_company, test_client_name -> test_company_name
- ClientContact/ClientContactMethod/Supplier class names unchanged (Stage B)
- Index/constraint renames (company_name_fts_idx, company_name_trgm_idx,
  crm_phone_company_call_idx, unique_company_* etc.)
- relabel_client_app surgery command: pre-migrate ledger relabel (deletes
  the 23 historic ghost rows, keeps 0001_baseline), content-type relabel,
  client_* -> company_* table renames; wired into deploy.sh before migrate
- Rename migrations on top of the squashed baselines: proxy Delete/Create
  dance around RenameModel (contenttypes trap), Remove-constraint ->
  RenameField -> Add-constraint ordering (Q()-condition trap)
- API surface: api/clients/ -> api/companies/, client_id/client_name ->
  company_*; schema.yml + generated api.ts regenerated (hand-written
  frontend swept in the follow-up commit on this branch)
- Persisted values deliberately unchanged (Step 3): telemetry domain
  'client', JobEvent 'client_changed', kanban 'client_contains',
  data-quality cross_client/effective_client_id, crm client_match param

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |    6 +-
 apps/accounting/migrations/0001_baseline.py   |    4 +-
 apps/accounting/migrations/0002_baseline.py   |    8 +-
 .../migrations/0003_rename_client_company.py  |   30 +
 apps/accounting/models/invoice.py             |   16 +-
 apps/accounting/models/quote.py               |    2 +-
 apps/accounting/serializers/core.py           |    6 +-
 .../serializers/rdti_spend_serializers.py     |    2 +-
 .../serializers/sales_pipeline_serializers.py |    2 +-
 .../accounting/serializers/wip_serializers.py |    2 +-
 apps/accounting/services/core.py              |   60 +-
 .../services/invoice_calculation.py           |    2 +-
 .../accounting/services/rdti_spend_service.py |    4 +-
 .../services/sales_pipeline_service.py        |    6 +-
 apps/accounting/services/wip_service.py       |    4 +-
 apps/accounting/tests/test_core_nplusone.py   |   22 +-
 .../tests/test_invoice_calculation.py         |   10 +-
 apps/accounting/tests/test_invoice_models.py  |    8 +-
 .../tests/test_sales_pipeline_service.py      |   58 +-
 apps/accounting/views/sales_forecast_view.py  |   16 +-
 .../management/commands/merge_clients.py      |  131 -
 apps/client/tests/test_client_jobs_queries.py |   31 -
 apps/client/urls_rest.py                      |  108 -
 apps/{client => company}/__init__.py          |   68 +-
 apps/{client => company}/admin.py             |    0
 apps/{client => company}/apps.py              |    4 +-
 .../management/commands/merge_companies.py    |  133 +
 .../migrations/0001_baseline.py               |   14 +-
 .../migrations/0002_rename_client_company.py  |  202 ++
 ...03_alter_clientcontact_company_and_more.py |   58 +
 .../migrations/__init__.py                    |    0
 apps/{client => company}/models.py            |  237 +-
 apps/{client => company}/serializers.py       |  124 +-
 apps/{client => company}/services/__init__.py |    8 +-
 .../services/company_merge_service.py}        |  100 +-
 .../services/company_rest_service.py}         |  544 +--
 .../services/duplicate_phone_report.py        |   34 +-
 .../services/geocoding_service.py             |    0
 apps/{client => company}/tests/__init__.py    |    0
 .../tests/test_company_fts_search.py}         |  176 +-
 .../tests/test_company_invoice_summary.py}    |   94 +-
 .../tests/test_company_jobs_queries.py        |   31 +
 .../tests/test_company_merge_service.py}      |  228 +-
 .../tests/test_contact_methods.py             |  164 +-
 .../tests/test_duplicate_phone_report.py      |   30 +-
 .../tests/test_get_company_for_xero.py}       |   64 +-
 apps/company/urls_rest.py                     |  108 +
 apps/{client => company}/utils.py             |    2 +-
 apps/{client => company}/views/__init__.py    |   34 +-
 .../views/address_views.py                    |    4 +-
 .../views/company_rest_views.py}              |  364 +-
 .../views/contact_method_viewset.py}          |   22 +-
 .../views/contact_viewset.py}                 |   32 +-
 .../views/supplier_pickup_address_viewset.py  |   24 +-
 .../views/supplier_search_alias_views.py      |   34 +-
 apps/crm/migrations/0001_baseline.py          |    6 +-
 .../migrations/0004_rename_client_company.py  |   30 +
 apps/crm/models.py                            |   20 +-
 apps/crm/serializers.py                       |   20 +-
 apps/crm/services/phone_call_service.py       |  102 +-
 apps/crm/tests/test_phone_call_service.py     |  134 +-
 apps/crm/tests/test_phone_endpoint_guard.py   |   20 +-
 apps/crm/views/phone_call_views.py            |   16 +-
 .../management/commands/create_shop_jobs.py   |    8 +-
 apps/job/migrations/0001_baseline.py          |    6 +-
 .../migrations/0003_rename_client_company.py  |   15 +
 apps/job/models/costing.py                    |    2 +-
 apps/job/models/job.py                        |   66 +-
 apps/job/models/job_event.py                  |    4 +-
 apps/job/serializers/costing_serializer.py    |   16 +-
 .../data_quality_report_serializers.py        |   12 +-
 .../job_profitability_report_serializers.py   |    2 +-
 apps/job/serializers/job_serializer.py        |  105 +-
 apps/job/serializers/kanban_serializer.py     |   12 +-
 apps/job/services/chat_service.py             |    2 +-
 apps/job/services/data_integrity_service.py   |  141 +-
 apps/job/services/data_quality_report.py      |    6 +-
 apps/job/services/job_profitability_report.py |    8 +-
 apps/job/services/job_rest_service.py         |   64 +-
 apps/job/services/job_service.py              |    2 +-
 apps/job/services/kanban_service.py           |   48 +-
 apps/job/services/labour_subtype_service.py   |    8 +-
 apps/job/services/mcp_chat_service.py         |    2 +-
 apps/job/services/quote_mode_controller.py    |    6 +-
 apps/job/services/workshop_pdf_service.py     |   34 +-
 apps/job/services/workshop_service.py         |    4 +-
 apps/job/tests/_pdf_golden_fixtures.py        |    8 +-
 apps/job/tests/fixtures/chat_test_data.json   |   10 +-
 apps/job/tests/test_chat_api_endpoints.py     |   26 +-
 apps/job/tests/test_chat_performance.py       |   14 +-
 apps/job/tests/test_chat_service.py           |   44 +-
 .../tests/test_costline_schema_validation.py  |    8 +-
 .../test_costline_time_rate_serialization.py  |   10 +-
 .../job/tests/test_delivery_docket_service.py |    8 +-
 apps/job/tests/test_duplicate_phones_view.py  |   12 +-
 apps/job/tests/test_event_deduplication.py    |   10 +-
 apps/job/tests/test_job_event_tracking.py     |   24 +-
 apps/job/tests/test_job_files_api.py          |    8 +-
 apps/job/tests/test_job_invoicing.py          |   10 +-
 apps/job/tests/test_job_latest_costsets.py    |   16 +-
 apps/job/tests/test_job_quote_chat_model.py   |   10 +-
 apps/job/tests/test_job_rest_service.py       |   16 +-
 .../job/tests/test_job_summary_pdf_service.py |   12 +-
 .../job/tests/test_kanban_reorder_priority.py |   10 +-
 apps/job/tests/test_kanban_search.py          |  130 +-
 apps/job/tests/test_kanban_service.py         |   22 +-
 apps/job/tests/test_labour_subtypes.py        |   22 +-
 apps/job/tests/test_mcp_tool_integration.py   |   28 +-
 apps/job/tests/test_modern_timesheet_views.py |   12 +-
 apps/job/tests/test_paid_flag_service.py      |   10 +-
 apps/job/tests/test_quote_modes.py            |   16 +-
 apps/job/tests/test_workshop_pdf_service.py   |   30 +-
 apps/job/tests/test_workshop_timesheet_api.py |    8 +-
 apps/job/utils.py                             |    2 +-
 apps/job/views/data_quality_report_views.py   |    6 +-
 apps/job/views/delivery_docket_view.py        |    2 +-
 apps/job/views/job_rest_views.py              |   10 +-
 apps/job/views/kanban_view_api.py             |    8 +-
 apps/job/views/modern_timesheet_views.py      |    6 +-
 apps/job/views/month_end_rest_view.py         |    4 +-
 apps/job/views/workshop_view.py               |    2 +-
 .../workshop_schedule_serializer.py           |    4 +-
 .../tests/test_scheduler_persistence.py       |   18 +-
 .../tests/test_scheduler_service.py           |   14 +-
 .../tests/test_workshop_schedule_api.py       |   16 +-
 .../views/workshop_schedule_view.py           |    8 +-
 apps/process/services/google_docs_service.py  |    4 +-
 apps/process/services/safety_ai_service.py    |    4 +-
 apps/process/tests/conftest.py                |   14 +-
 apps/process/tests/test_procedure_service.py  |   10 +-
 apps/purchasing/migrations/0001_baseline.py   |    6 +-
 apps/purchasing/models.py                     |    4 +-
 apps/purchasing/serializers.py                |   22 +-
 .../services/purchasing_rest_service.py       |    8 +-
 .../services/quote_to_po_service.py           |    6 +-
 .../services/supplier_search_service.py       |   50 +-
 .../tests/test_purchase_order_line_usage.py   |    2 +-
 .../tests/test_quote_to_po_service.py         |    4 +-
 apps/purchasing/tests/test_serializers.py     |   12 +-
 .../purchasing/tests/test_stock_fts_search.py |   22 +-
 .../tests/test_stock_metadata_tasks.py        |   10 +-
 apps/purchasing/tests/test_supplier_search.py |   20 +-
 .../purchasing/views/purchasing_rest_views.py |   16 +-
 .../views/stock_search_rest_view.py           |    2 +-
 apps/quoting/__init__.py                      |    2 +-
 apps/quoting/admin.py                         |   14 +-
 apps/quoting/mcp.py                           |    8 +-
 apps/quoting/migrations/0001_baseline.py      |   12 +-
 apps/quoting/models.py                        |   12 +-
 apps/quoting/services/pdf_data_validation.py  |    6 +-
 apps/quoting/services/pdf_import_service.py   |   38 +-
 .../quoting/tests/test_pdf_data_validation.py |    4 +-
 .../test_supplier_scraper_credentials.py      |    6 +-
 apps/quoting/tests_mcp.py                     |   18 +-
 apps/testing.py                               |    2 +-
 .../management/commands/create_special_job.py |    8 +-
 .../daily_timesheet_serializers.py            |    2 +-
 .../modern_timesheet_serializers.py           |   10 +-
 .../services/daily_timesheet_service.py       |    4 +-
 .../tests/test_daily_timesheet_service.py     |   28 +-
 apps/timesheet/tests/test_jobs_api_filter.py  |    8 +-
 .../tests/test_weekly_timesheet_service.py    |    8 +-
 apps/timesheet/views/api.py                   |   22 +-
 apps/workflow/accounting/provider.py          |    8 +-
 apps/workflow/accounting/types.py             |    4 +-
 apps/workflow/accounting/xero/provider.py     |   24 +-
 apps/workflow/api/reports/job_movement.py     |    6 +-
 apps/workflow/api/xero/__init__.py            |   36 +-
 apps/workflow/api/xero/push.py                |   92 +-
 apps/workflow/api/xero/reprocess_xero.py      |  145 +-
 apps/workflow/api/xero/seed.py                |   62 +-
 apps/workflow/api/xero/sync.py                |   14 +-
 apps/workflow/api/xero/transforms.py          |  140 +-
 apps/workflow/fixtures/company_defaults.json  |    6 +-
 .../fixtures/company_defaults_prospect.json   |    6 +-
 apps/workflow/fixtures/initial_data.json      |    2 +-
 .../management/commands/e2e_cleanup.py        |   50 +-
 .../management/commands/relabel_client_app.py |   84 +
 .../commands/seed_xero_from_database.py       |   98 +-
 apps/workflow/middleware.py                   |    8 +-
 apps/workflow/migrations/0001_baseline.py     |    4 +-
 .../0005_rename_shop_client_fields.py         |   20 +
 ...r_companydefaults_shop_company_and_more.py |   35 +
 apps/workflow/models/company_defaults.py      |   12 +-
 .../workflow/models/search_telemetry_event.py |    2 +-
 apps/workflow/models/settings_metadata.py     |    8 +-
 apps/workflow/serializers.py                  |    6 +-
 apps/workflow/services/db_scrubber.py         |   48 +-
 .../tests/test_api_schema_coverage.py         |    2 +-
 .../tests/test_company_defaults_api.py        |   14 +-
 .../workflow/tests/test_data_versions_view.py |   28 +-
 apps/workflow/tests/test_db_scrubber.py       |    2 +-
 apps/workflow/tests/test_dev_demo_export.py   |   36 +-
 .../tests/test_localdate_regression.py        |   42 +-
 apps/workflow/tests/test_push_contacts.py     |   50 +-
 .../workflow/tests/test_relabel_client_app.py |  163 +
 .../tests/test_seed_xero_from_database.py     |   10 +-
 apps/workflow/tests/test_sync_clients.py      |   86 +-
 .../tests/test_xero_document_raw_json.py      |   20 +-
 apps/workflow/tests/test_xero_po_manager.py   |    4 +-
 apps/workflow/tests/test_xero_quota_floor.py  |    8 +-
 .../test_xero_transform_contact_resolution.py |   44 +-
 apps/workflow/views/data_versions_view.py     |    6 +-
 apps/workflow/views/search_telemetry_view.py  |    2 +-
 apps/workflow/views/xero/xero_base_manager.py |   30 +-
 .../views/xero/xero_invoice_manager.py        |   30 +-
 apps/workflow/views/xero/xero_po_manager.py   |    6 +-
 .../workflow/views/xero/xero_quote_manager.py |   26 +-
 apps/workflow/views/xero/xero_view.py         |    8 +-
 docketworks/settings.py                       |    4 +-
 docketworks/urls.py                           |    2 +-
 docs/architecture.md                          |   10 +-
 docs/restore-prod-to-nonprod.md               |   24 +-
 docs/urls/company.md                          |   56 +
 frontend/schema.yml                           | 2054 ++++++------
 frontend/src/api/generated/api.ts             |  574 ++--
 mypy-baseline.txt                             | 2976 ++++++++---------
 scripts/analyze_client_contacts.py            |   20 +-
 scripts/fix_test_client.py                    |   34 -
 scripts/fix_test_company.py                   |   34 +
 scripts/geocode_addresses.py                  |    6 +-
 .../integration/verify_xero_batch_order.py    |    2 +-
 .../verify_xero_client_quote_contract.py      |   32 +-
 ...s_to_xero.py => push_companies_to_xero.py} |  114 +-
 scripts/restore_checks/check_django_orm.py    |    4 +-
 scripts/restore_checks/check_shop_client.py   |   22 -
 scripts/restore_checks/check_shop_company.py  |   22 +
 scripts/restore_checks/check_test_client.py   |   26 -
 scripts/restore_checks/check_test_company.py  |   26 +
 scripts/restore_checks/check_xero_seed.py     |    6 +-
 scripts/restore_checks/fix_shop_client.py     |   31 -
 scripts/restore_checks/fix_shop_company.py    |   31 +
 scripts/restore_checks/test_serializers.py    |   16 +-
 scripts/server/deploy.sh                      |    7 +
 scripts/test_full_quote_conversation.py       |    2 +-
 scripts/test_quote_import.py                  |   12 +-
 scripts/validate_restore_progress.py          |   20 +-
 237 files changed, 6957 insertions(+), 6205 deletions(-)
 create mode 100644 apps/accounting/migrations/0003_rename_client_company.py
 delete mode 100644 apps/client/management/commands/merge_clients.py
 delete mode 100644 apps/client/tests/test_client_jobs_queries.py
 delete mode 100644 apps/client/urls_rest.py
 rename apps/{client => company}/__init__.py (53%)
 rename apps/{client => company}/admin.py (100%)
 rename apps/{client => company}/apps.py (61%)
 create mode 100644 apps/company/management/commands/merge_companies.py
 rename apps/{client => company}/migrations/0001_baseline.py (98%)
 create mode 100644 apps/company/migrations/0002_rename_client_company.py
 create mode 100644 apps/company/migrations/0003_alter_clientcontact_company_and_more.py
 rename apps/{client => company}/migrations/__init__.py (100%)
 rename apps/{client => company}/models.py (79%)
 rename apps/{client => company}/serializers.py (74%)
 rename apps/{client => company}/services/__init__.py (83%)
 rename apps/{client/services/client_merge_service.py => company/services/company_merge_service.py} (69%)
 rename apps/{client/services/client_rest_service.py => company/services/company_rest_service.py} (56%)
 rename apps/{client => company}/services/duplicate_phone_report.py (76%)
 rename apps/{client => company}/services/geocoding_service.py (100%)
 rename apps/{client => company}/tests/__init__.py (100%)
 rename apps/{client/tests/test_client_fts_search.py => company/tests/test_company_fts_search.py} (57%)
 rename apps/{client/tests/test_client_invoice_summary.py => company/tests/test_company_invoice_summary.py} (63%)
 create mode 100644 apps/company/tests/test_company_jobs_queries.py
 rename apps/{client/tests/test_client_merge_service.py => company/tests/test_company_merge_service.py} (74%)
 rename apps/{client => company}/tests/test_contact_methods.py (71%)
 rename apps/{client => company}/tests/test_duplicate_phone_report.py (74%)
 rename apps/{client/tests/test_get_client_for_xero.py => company/tests/test_get_company_for_xero.py} (75%)
 create mode 100644 apps/company/urls_rest.py
 rename apps/{client => company}/utils.py (94%)
 rename apps/{client => company}/views/__init__.py (54%)
 rename apps/{client => company}/views/address_views.py (97%)
 rename apps/{client/views/client_rest_views.py => company/views/company_rest_views.py} (61%)
 rename apps/{client/views/client_contact_method_viewset.py => company/views/contact_method_viewset.py} (86%)
 rename apps/{client/views/client_contact_viewset.py => company/views/contact_viewset.py} (61%)
 rename apps/{client => company}/views/supplier_pickup_address_viewset.py (67%)
 rename apps/{client => company}/views/supplier_search_alias_views.py (83%)
 create mode 100644 apps/crm/migrations/0004_rename_client_company.py
 create mode 100644 apps/job/migrations/0003_rename_client_company.py
 create mode 100644 apps/workflow/management/commands/relabel_client_app.py
 create mode 100644 apps/workflow/migrations/0005_rename_shop_client_fields.py
 create mode 100644 apps/workflow/migrations/0006_alter_companydefaults_shop_company_and_more.py
 create mode 100644 apps/workflow/tests/test_relabel_client_app.py
 create mode 100644 docs/urls/company.md
 delete mode 100644 scripts/fix_test_client.py
 create mode 100644 scripts/fix_test_company.py
 rename scripts/{push_clients_to_xero.py => push_companies_to_xero.py} (56%)
 delete mode 100644 scripts/restore_checks/check_shop_client.py
 create mode 100644 scripts/restore_checks/check_shop_company.py
 delete mode 100644 scripts/restore_checks/check_test_client.py
 create mode 100644 scripts/restore_checks/check_test_company.py
 delete mode 100644 scripts/restore_checks/fix_shop_client.py
 create mode 100644 scripts/restore_checks/fix_shop_company.py

diff --git a/CLAUDE.md b/CLAUDE.md
index f3d534734..e1b51dfec 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -51,7 +51,7 @@ Django-based job/project management system for jobbing shops and custom work bus
 - **`workflow`** - Central hub, Xero integration, auth middleware
 - **`job`** - Job lifecycle, Kanban status tracking (Quoting → In Progress → Completed → Archived), audit trails
 - **`accounts`** - Custom Staff model extending AbstractBaseUser, authentication
-- **`client`** - Customer management, bidirectional Xero contact sync
+- **`company`** - Customer management, bidirectional Xero contact sync
 - **`timesheet`** - Time tracking, billable/non-billable, wage rates
 - **`purchasing`** - POs, stock management, Xero integration, links to CostLine via ext_refs
 - **`accounting`** - KPIs, financial reporting, invoice generation
@@ -65,7 +65,7 @@ Django-based job/project management system for jobbing shops and custom work bus
 Job → CostSet (1:many) → CostLine (1:many)
 PurchaseOrder → PurchaseOrderLine → Stock → CostLine
 Staff → CostLine (time entries)
-Client → Job (1:many)
+Company → Job (1:many)
 ```
 
 **Key Design Patterns:**
@@ -83,7 +83,7 @@ Client → Job (1:many)
 TIME entries (kind='time'):
 - staff_id (str, UUID): Reference to Staff member
 - date (str, ISO): Date work performed (legacy - use accounting_date field instead)
-- is_billable (bool): Whether billable to client
+- is_billable (bool): Whether billable to company
 - wage_rate_multiplier/rate_multiplier (float): Rate multiplier (e.g., 1.5 for overtime)
 - note (str): Optional notes
 - created_from_timesheet (bool): True if from modern timesheet UI
diff --git a/apps/accounting/migrations/0001_baseline.py b/apps/accounting/migrations/0001_baseline.py
index e08f412b8..08ecf0a4d 100644
--- a/apps/accounting/migrations/0001_baseline.py
+++ b/apps/accounting/migrations/0001_baseline.py
@@ -13,7 +13,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
     ]
 
     operations = [
@@ -414,7 +414,7 @@ class Migration(migrations.Migration):
                 (
                     "client",
                     models.ForeignKey(
-                        on_delete=django.db.models.deletion.PROTECT, to="client.client"
+                        on_delete=django.db.models.deletion.PROTECT, to="company.client"
                     ),
                 ),
             ],
diff --git a/apps/accounting/migrations/0002_baseline.py b/apps/accounting/migrations/0002_baseline.py
index c459575d3..14b78fbc6 100644
--- a/apps/accounting/migrations/0002_baseline.py
+++ b/apps/accounting/migrations/0002_baseline.py
@@ -10,7 +10,7 @@ class Migration(migrations.Migration):
 
     dependencies = [
         ("accounting", "0001_baseline"),
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         ("job", "0001_baseline"),
         ("workflow", "0001_baseline"),
     ]
@@ -39,7 +39,7 @@ class Migration(migrations.Migration):
             model_name="creditnote",
             name="client",
             field=models.ForeignKey(
-                on_delete=django.db.models.deletion.PROTECT, to="client.client"
+                on_delete=django.db.models.deletion.PROTECT, to="company.client"
             ),
         ),
         migrations.AddField(
@@ -65,7 +65,7 @@ class Migration(migrations.Migration):
             model_name="invoice",
             name="client",
             field=models.ForeignKey(
-                on_delete=django.db.models.deletion.PROTECT, to="client.client"
+                on_delete=django.db.models.deletion.PROTECT, to="company.client"
             ),
         ),
         migrations.AddField(
@@ -102,7 +102,7 @@ class Migration(migrations.Migration):
             model_name="quote",
             name="client",
             field=models.ForeignKey(
-                on_delete=django.db.models.deletion.PROTECT, to="client.client"
+                on_delete=django.db.models.deletion.PROTECT, to="company.client"
             ),
         ),
         migrations.AddField(
diff --git a/apps/accounting/migrations/0003_rename_client_company.py b/apps/accounting/migrations/0003_rename_client_company.py
new file mode 100644
index 000000000..15e6cc7be
--- /dev/null
+++ b/apps/accounting/migrations/0003_rename_client_company.py
@@ -0,0 +1,30 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("accounting", "0002_baseline"),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name="invoice",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.RenameField(
+            model_name="bill",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.RenameField(
+            model_name="creditnote",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.RenameField(
+            model_name="quote",
+            old_name="client",
+            new_name="company",
+        ),
+    ]
diff --git a/apps/accounting/models/invoice.py b/apps/accounting/models/invoice.py
index 0d0fa257d..cf6397fb5 100644
--- a/apps/accounting/models/invoice.py
+++ b/apps/accounting/models/invoice.py
@@ -6,7 +6,7 @@
 from django.utils import timezone
 
 if TYPE_CHECKING:
-    from apps.client.models import Client
+    from apps.company.models import Company
 
 from apps.accounting.enums import InvoiceStatus
 
@@ -23,7 +23,7 @@ class BaseXeroInvoiceDocument(models.Model):
         max_length=255, null=True, blank=True
     )  # For reference only - we are not fully multi-tenant yet
     number = models.CharField(max_length=255)
-    client = models.ForeignKey("client.Client", on_delete=models.PROTECT)
+    company = models.ForeignKey("company.Company", on_delete=models.PROTECT)
     date = models.DateField()
     due_date = models.DateField(null=True, blank=True)
     status = models.CharField(
@@ -43,7 +43,7 @@ class Meta:
         abstract = True
 
     def __str__(self) -> str:
-        return f"{self.number} - {self.client.name}"
+        return f"{self.number} - {self.company.name}"
 
     @property
     def total_amount(self) -> Decimal:
@@ -125,13 +125,13 @@ class Meta:
         ordering = ["-date", "number"]
 
     @property
-    def supplier(self) -> "Client":
-        """Return the client as 'supplier' for bills."""
-        return self.client
+    def supplier(self) -> "Company":
+        """Return the company as 'supplier' for bills."""
+        return self.company
 
     @supplier.setter
-    def supplier(self, value: "Client") -> None:
-        self.client = value
+    def supplier(self, value: "Company") -> None:
+        self.company = value
 
 
 class CreditNote(BaseXeroInvoiceDocument):
diff --git a/apps/accounting/models/quote.py b/apps/accounting/models/quote.py
index a99f2fa71..5379c17bd 100644
--- a/apps/accounting/models/quote.py
+++ b/apps/accounting/models/quote.py
@@ -15,7 +15,7 @@ class Quote(models.Model):
     job = models.OneToOneField(
         "job.Job", on_delete=models.PROTECT, related_name="quote", null=True, blank=True
     )
-    client = models.ForeignKey("client.Client", on_delete=models.PROTECT)
+    company = models.ForeignKey("company.Company", on_delete=models.PROTECT)
     date = models.DateField()
     status = models.CharField(
         max_length=50, choices=QuoteStatus.choices, default=QuoteStatus.DRAFT
diff --git a/apps/accounting/serializers/core.py b/apps/accounting/serializers/core.py
index 70e4c675d..dbc45890c 100644
--- a/apps/accounting/serializers/core.py
+++ b/apps/accounting/serializers/core.py
@@ -21,7 +21,7 @@ class KPIJobBreakdownSerializer(serializers.Serializer[Any]):
         serializers.CharField()
     )  # Changed to CharField to match frontend schema
     job_name = serializers.CharField()  # Changed from job_display_name
-    client_name = serializers.CharField()  # Added client_name field
+    company_name = serializers.CharField()  # Added company_name field
     billable_hours = serializers.FloatField()  # Added billable_hours field
     revenue = serializers.FloatField()
     cost = serializers.FloatField()
@@ -160,7 +160,7 @@ class JobAgingJobDataSerializer(serializers.Serializer[Any]):
     id = serializers.CharField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     status = serializers.CharField()
     status_display = serializers.CharField()
     financial_data = JobAgingFinancialDataSerializer()
@@ -208,7 +208,7 @@ class StaffPerformanceJobBreakdownSerializer(serializers.Serializer[Any]):
     job_id = serializers.CharField()
     job_number = serializers.IntegerField()
     job_name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     billable_hours = serializers.FloatField()
     non_billable_hours = serializers.FloatField()
     total_hours = serializers.FloatField()
diff --git a/apps/accounting/serializers/rdti_spend_serializers.py b/apps/accounting/serializers/rdti_spend_serializers.py
index e5fdc2fa3..5953fe968 100644
--- a/apps/accounting/serializers/rdti_spend_serializers.py
+++ b/apps/accounting/serializers/rdti_spend_serializers.py
@@ -36,7 +36,7 @@ class RDTISpendJobDetailSerializer(serializers.Serializer[Any]):
     job_id = serializers.CharField()
     job_number = serializers.IntegerField()
     job_name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     rdti_type = serializers.CharField()
     hours = serializers.FloatField()
     cost = serializers.FloatField()
diff --git a/apps/accounting/serializers/sales_pipeline_serializers.py b/apps/accounting/serializers/sales_pipeline_serializers.py
index 32a86322e..9c241d531 100644
--- a/apps/accounting/serializers/sales_pipeline_serializers.py
+++ b/apps/accounting/serializers/sales_pipeline_serializers.py
@@ -101,7 +101,7 @@ class SalesPipelineSnapshotJobSerializer(serializers.Serializer[Any]):
     id = serializers.CharField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client_name = serializers.CharField(allow_blank=True)
+    company_name = serializers.CharField(allow_blank=True)
     hours = serializers.FloatField()
     value = serializers.FloatField()
     days_in_stage = serializers.IntegerField()
diff --git a/apps/accounting/serializers/wip_serializers.py b/apps/accounting/serializers/wip_serializers.py
index e7f6c3e52..c7190a3de 100644
--- a/apps/accounting/serializers/wip_serializers.py
+++ b/apps/accounting/serializers/wip_serializers.py
@@ -22,7 +22,7 @@ class WIPJobSerializer(serializers.Serializer[Any]):
 
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client = serializers.CharField()
+    company = serializers.CharField()
     status = serializers.CharField()
     time_cost = serializers.FloatField()
     time_rev = serializers.FloatField()
diff --git a/apps/accounting/services/core.py b/apps/accounting/services/core.py
index 7d12c425c..a62a9fd84 100644
--- a/apps/accounting/services/core.py
+++ b/apps/accounting/services/core.py
@@ -153,7 +153,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
             List of job breakdowns with profit details
         """
         defaults = CompanyDefaults.get_solo()
-        shop_client_id = defaults.shop_client_id
+        shop_company_id = defaults.shop_company_id
         excluded_staff_ids = get_payroll_excluded_staff_ids()
 
         # Get cost lines for the target date from 'actual' cost sets
@@ -165,7 +165,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                 cost_set__kind="actual",
                 accounting_date=target_date,
             )
-            .select_related("cost_set__job__client")
+            .select_related("cost_set__job__company")
         )
 
         # For time entries, exclude staff that shouldn't be included
@@ -190,7 +190,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                     "job_id": str(job.id),
                     "job_number": job_number,
                     "job_display_name": job.job_display_name,
-                    "client_name": job.client.name,  # Add client name
+                    "company_name": job.company.name,  # Add company name
                     "labour_revenue": 0,
                     "labour_cost": 0,
                     "material_revenue": 0,
@@ -199,8 +199,8 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                     "adjustment_cost": 0,
                 }
 
-            # Only count billable time revenue if not shop client
-            if line.is_billable == "true" and job.client_id != shop_client_id:
+            # Only count billable time revenue if not shop company
+            if line.is_billable == "true" and job.company_id != shop_company_id:
                 job_data[job_number]["labour_revenue"] += float(line.total_rev)
 
             job_data[job_number]["labour_cost"] += float(line.total_cost)
@@ -215,7 +215,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                     "job_id": str(job.id),
                     "job_number": job_number,
                     "job_display_name": job.job_display_name,
-                    "client_name": job.client.name,  # Add client name
+                    "company_name": job.company.name,  # Add company name
                     "labour_revenue": 0,
                     "labour_cost": 0,
                     "material_revenue": 0,
@@ -237,7 +237,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                     "job_id": str(job.id),
                     "job_number": job_number,
                     "job_display_name": job.job_display_name,
-                    "client_name": job.client.name,  # Add client name
+                    "company_name": job.company.name,  # Add company name
                     "labour_revenue": 0,
                     "labour_cost": 0,
                     "material_revenue": 0,
@@ -263,7 +263,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                 if (
                     line.cost_set.job.job_number == job_number
                     and line.is_billable == "true"
-                    and line.cost_set.job.client_id != shop_client_id
+                    and line.cost_set.job.company_id != shop_company_id
                 ):
                     billable_hours += float(line.quantity)
 
@@ -282,7 +282,7 @@ def get_job_breakdown_for_date(cls, target_date: date) -> List[Dict[str, Any]]:
                     "job_id": data["job_id"],
                     "job_number": str(job_number),
                     "job_name": data["job_display_name"],
-                    "client_name": data["client_name"],
+                    "company_name": data["company_name"],
                     "billable_hours": billable_hours,
                     "revenue": total_revenue,
                     "cost": total_cost,
@@ -313,7 +313,7 @@ def get_calendar_data(cls, year: int, month: int) -> Dict[str, Any]:
         logger.info(f"Generating KPI calendar data for {year}-{month}")
 
         defaults = CompanyDefaults.get_solo()
-        shop_client_id = defaults.shop_client_id
+        shop_company_id = defaults.shop_company_id
         thresholds = cls.get_company_thresholds()
         logger.debug(
             f"Using thresholds: green={thresholds['kpi_daily_billable_hours_green']}, "
@@ -389,16 +389,16 @@ def get_calendar_data(cls, year: int, month: int) -> Dict[str, Any]:
             hours = line.quantity
             time_entries_by_date[line_date]["total_hours"] += hours
 
-            # Check if billable and not shop client
+            # Check if billable and not shop company
             if (
                 line.is_billable == "true"
-                and line.cost_set.job.client_id != shop_client_id
+                and line.cost_set.job.company_id != shop_company_id
             ):
                 time_entries_by_date[line_date]["billable_hours"] += hours
                 time_entries_by_date[line_date]["time_revenue"] += line.total_rev
 
             # Check if shop hours
-            if line.cost_set.job.client_id == shop_client_id:
+            if line.cost_set.job.company_id == shop_company_id:
                 time_entries_by_date[line_date]["shop_hours"] += hours
 
             time_entries_by_date[line_date]["staff_cost"] += line.total_cost
@@ -782,7 +782,7 @@ def get_job_aging_data(include_archived: bool = False) -> Dict[str, Any]:
 
         try:
             # Get active jobs (exclude archived unless requested)
-            jobs_query = Job.objects.select_related("client").prefetch_related(
+            jobs_query = Job.objects.select_related("company").prefetch_related(
                 "events", "cost_sets__cost_lines"
             )
 
@@ -799,7 +799,7 @@ def get_job_aging_data(include_archived: bool = False) -> Dict[str, Any]:
                 additional_context={
                     "operation": "fetch_jobs_for_aging_report",
                     "include_archived": include_archived,
-                    "query_filters": "active_jobs_with_client_and_cost_data",
+                    "query_filters": "active_jobs_with_company_and_cost_data",
                 },
             )
 
@@ -816,7 +816,7 @@ def get_job_aging_data(include_archived: bool = False) -> Dict[str, Any]:
                     "id": str(job.id),
                     "job_number": job.job_number,
                     "name": job.name,
-                    "client_name": job.client.name if job.client else "No Client",
+                    "company_name": job.company.name if job.company else "No Company",
                     "status": job.status,
                     "status_display": job.get_status_display(),
                     "price_cap": job.price_cap,
@@ -833,7 +833,7 @@ def get_job_aging_data(include_archived: bool = False) -> Dict[str, Any]:
                         "operation": "process_individual_job_for_aging",
                         "job_number": job.job_number,
                         "job_status": job.status,
-                        "client_name": job.client.name if job.client else None,
+                        "company_name": job.company.name if job.company else None,
                     },
                 )
                 # Continue processing other jobs
@@ -1189,7 +1189,7 @@ def get_staff_performance_data(
                     accounting_date__gte=start_date,
                     accounting_date__lte=end_date,
                 )
-                .select_related("cost_set__job__client")
+                .select_related("cost_set__job__company")
             )
 
             # Get all active staff
@@ -1201,7 +1201,7 @@ def get_staff_performance_data(
 
             staff_data = []
             include_job_breakdown = staff_id is not None
-            shop_client_id = CompanyDefaults.get_solo().shop_client_id
+            shop_company_id = CompanyDefaults.get_solo().shop_company_id
 
             lines_by_staff_id: Dict[str, List[CostLine]] = {}
             for line in cost_lines:
@@ -1216,7 +1216,7 @@ def get_staff_performance_data(
                     staff,
                     staff_cost_lines,
                     include_job_breakdown,
-                    shop_client_id,
+                    shop_company_id,
                 )
                 # Only include staff with recorded hours in the period
                 if staff_metrics["total_hours"] > 0:
@@ -1261,7 +1261,7 @@ def _calculate_staff_metrics(
         staff: Staff,
         cost_lines: List[CostLine],
         include_job_breakdown: bool = False,
-        shop_client_id: UUID | None = None,
+        shop_company_id: UUID | None = None,
     ) -> Dict[str, Any]:
         """
         Calculate performance metrics for a single staff member.
@@ -1275,15 +1275,15 @@ def _calculate_staff_metrics(
             Dict containing staff performance metrics
         """
         total_hours = float(sum(line.quantity for line in cost_lines))
-        if shop_client_id is None:
-            shop_client_id = CompanyDefaults.get_solo().shop_client_id
+        if shop_company_id is None:
+            shop_company_id = CompanyDefaults.get_solo().shop_company_id
 
         billable_hours = float(
             sum(
                 line.quantity
                 for line in cost_lines
                 if line.is_billable_meta == "true"
-                and line.cost_set.job.client_id != shop_client_id
+                and line.cost_set.job.company_id != shop_company_id
             )
         )
 
@@ -1320,7 +1320,7 @@ def _calculate_staff_metrics(
         if include_job_breakdown:
             job_breakdown = StaffPerformanceService._calculate_job_breakdown(
                 cost_lines,
-                shop_client_id,
+                shop_company_id,
             )
             staff_metrics["job_breakdown"] = job_breakdown
 
@@ -1329,7 +1329,7 @@ def _calculate_staff_metrics(
     @staticmethod
     def _calculate_job_breakdown(
         cost_lines: models.QuerySet,
-        shop_client_id: UUID | None = None,
+        shop_company_id: UUID | None = None,
     ) -> List[Dict[str, Any]]:
         """
         Calculate job-level breakdown for cost lines.
@@ -1341,8 +1341,8 @@ def _calculate_job_breakdown(
             List of job breakdown dictionaries
         """
         job_data = {}
-        if shop_client_id is None:
-            shop_client_id = CompanyDefaults.get_solo().shop_client_id
+        if shop_company_id is None:
+            shop_company_id = CompanyDefaults.get_solo().shop_company_id
 
         for line in cost_lines:
             job = line.cost_set.job
@@ -1353,7 +1353,7 @@ def _calculate_job_breakdown(
                     "job_id": job_id,
                     "job_number": job.job_number or "",
                     "job_name": job.name or "",
-                    "client_name": job.client.name if job.client else "",
+                    "company_name": job.company.name if job.company else "",
                     "billable_hours": 0.0,
                     "non_billable_hours": 0.0,
                     "revenue": 0.0,
@@ -1362,7 +1362,7 @@ def _calculate_job_breakdown(
 
             hours = float(line.quantity)
             # Shop jobs are always non-billable regardless of the is_billable flag
-            is_shop_job = line.cost_set.job.client_id == shop_client_id
+            is_shop_job = line.cost_set.job.company_id == shop_company_id
             is_billable = line.is_billable_meta == "true" and not is_shop_job
 
             if is_billable:
diff --git a/apps/accounting/services/invoice_calculation.py b/apps/accounting/services/invoice_calculation.py
index 8a5dcbf5e..ac783abf0 100644
--- a/apps/accounting/services/invoice_calculation.py
+++ b/apps/accounting/services/invoice_calculation.py
@@ -40,7 +40,7 @@ def get_prior_valid_invoice_total(job: Job) -> Decimal:
 
 
 def get_job_for_invoice_calculation(job_id: UUID) -> Job:
-    job = Job.objects.select_related("client", "latest_quote", "latest_actual").get(
+    job = Job.objects.select_related("company", "latest_quote", "latest_actual").get(
         id=job_id
     )
 
diff --git a/apps/accounting/services/rdti_spend_service.py b/apps/accounting/services/rdti_spend_service.py
index 9b681fd89..2b43e41b9 100644
--- a/apps/accounting/services/rdti_spend_service.py
+++ b/apps/accounting/services/rdti_spend_service.py
@@ -55,7 +55,7 @@ def _build_report(start_date: date, end_date: date) -> dict[str, Any]:
                 job_id=F("cost_set__job__id"),
                 job_number=F("cost_set__job__job_number"),
                 job_name=F("cost_set__job__name"),
-                client_name=F("cost_set__job__client__name"),
+                company_name=F("cost_set__job__company__name"),
                 rdti_type=Coalesce(
                     F("cost_set__job__rdti_type"), Value("unclassified")
                 ),
@@ -76,7 +76,7 @@ def _build_report(start_date: date, end_date: date) -> dict[str, Any]:
                     "job_id": str(row["job_id"]),
                     "job_number": row["job_number"],
                     "job_name": row["job_name"],
-                    "client_name": row["client_name"] or "",
+                    "company_name": row["company_name"] or "",
                     "rdti_type": row["rdti_type"],
                     "hours": float(row["hours"]),
                     "cost": float(row["cost"]),
diff --git a/apps/accounting/services/sales_pipeline_service.py b/apps/accounting/services/sales_pipeline_service.py
index 9439508a8..8934b6ccb 100644
--- a/apps/accounting/services/sales_pipeline_service.py
+++ b/apps/accounting/services/sales_pipeline_service.py
@@ -72,7 +72,7 @@
 FUNNEL_PATH_ESTIMATING = "estimating"
 
 # Cap on how many sample job records each warning bucket carries back to the
-# client. The full count is always reported.
+# company. The full count is always reported.
 WARNING_SAMPLE_CAP = 10
 
 # Warning codes (machine-readable).
@@ -283,7 +283,7 @@ def _fetch_jobs(job_ids: Iterable[Any]) -> dict[Any, Job]:
         if not ids:
             return {}
         jobs = Job.objects.filter(id__in=ids).select_related(
-            "latest_quote", "latest_estimate", "client"
+            "latest_quote", "latest_estimate", "company"
         )
         return {j.id: j for j in jobs}
 
@@ -731,7 +731,7 @@ def _build_snapshot(
                     "id": str(job.id),
                     "job_number": job.job_number,
                     "name": job.name,
-                    "client_name": job.client.name if job.client_id else "",
+                    "company_name": job.company.name if job.company_id else "",
                     "hours": hours,
                     "value": value or 0.0,
                     "days_in_stage": days_in_stage,
diff --git a/apps/accounting/services/wip_service.py b/apps/accounting/services/wip_service.py
index 07a6881a0..0f11e087a 100644
--- a/apps/accounting/services/wip_service.py
+++ b/apps/accounting/services/wip_service.py
@@ -60,7 +60,7 @@ def get_wip_data(report_date: date, method: str) -> dict[str, Any]:
                 Job.objects.filter(fully_invoiced=False, rejected_flag=False)
                 .exclude(status__in=NO_WORK_STATUSES)
                 .exclude(latest_actual__isnull=True)
-                .select_related("latest_actual", "client")
+                .select_related("latest_actual", "company")
                 .order_by("job_number")
             )
         except AlreadyLoggedException:
@@ -155,7 +155,7 @@ def _aggregate_job(
         return {
             "job_number": job.job_number,
             "name": job.name,
-            "client": str(job.client) if job.client else "N/A",
+            "company": str(job.company) if job.company else "N/A",
             "status": job.status,
             "time_cost": float(totals["time_cost"] or Decimal("0")),
             "time_rev": float(totals["time_rev"] or Decimal("0")),
diff --git a/apps/accounting/tests/test_core_nplusone.py b/apps/accounting/tests/test_core_nplusone.py
index 78b29ec78..3f0c3faaa 100644
--- a/apps/accounting/tests/test_core_nplusone.py
+++ b/apps/accounting/tests/test_core_nplusone.py
@@ -8,25 +8,25 @@
 
 from apps.accounting.services.core import KPIService, StaffPerformanceService
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, LabourSubtype
 from apps.testing import BaseTestCase
 from apps.workflow.models import XeroPayItem
 
 
 class AccountingCoreQueryTests(BaseTestCase):
-    """Accounting reports must not query job/client data once per row.
+    """Accounting reports must not query job/company data once per row.
 
     The reports loop over CostLine rows and grouped staff metrics. These tests
-    catch refactors that drop the preloaded job/client data by using multiple
+    catch refactors that drop the preloaded job/company data by using multiple
     rows and a fixed query budget for the report boundary.
     """
 
     def setUp(self):
         super().setUp()
         self.target_date = date(2026, 5, 22)
-        self.client = Client.objects.create(
-            name="Accounting Nplusone Client",
+        self.company = Company.objects.create(
+            name="Accounting Nplusone Company",
             email="accounting-nplusone@example.com",
             xero_last_modified=timezone.now(),
         )
@@ -47,7 +47,7 @@ def _create_job(self, job_number: int) -> Job:
         job = Job.objects.create(
             job_number=job_number,
             name=f"Accounting Job {job_number}",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.pay_item,
             staff=self.test_staff,
         )
@@ -76,11 +76,11 @@ def _create_time_line(self, job: Job, staff: Staff, hours: str = "2.000"):
         )
 
     def test_kpi_job_breakdown_preloads_job_client(self):
-        """Job breakdown must not fetch each job's client inside the loop.
+        """Job breakdown must not fetch each job's company inside the loop.
 
-        This catches removing ``select_related("cost_set__job__client")`` by
+        This catches removing ``select_related("cost_set__job__company")`` by
         asserting the report stays at fixed query overhead plus one query per
-        CostLine kind, even when it emits client names.
+        CostLine kind, even when it emits company names.
         """
         job = self._create_job(98801)
         CostLine.objects.create(
@@ -98,12 +98,12 @@ def test_kpi_job_breakdown_preloads_job_client(self):
         with self.assertNumQueries(5):
             breakdown = KPIService.get_job_breakdown_for_date(self.target_date)
 
-        self.assertEqual(breakdown[0]["client_name"], "Accounting Nplusone Client")
+        self.assertEqual(breakdown[0]["company_name"], "Accounting Nplusone Company")
 
     def test_staff_performance_groups_prefetched_cost_lines_by_staff(self):
         """Staff performance must group prefetched lines without per-staff queries.
 
-        This catches metric code that looks up CostLine/job/client data inside
+        This catches metric code that looks up CostLine/job/company data inside
         the staff loop by asserting two staff with separate jobs stay within a
         fixed query ceiling.
         """
diff --git a/apps/accounting/tests/test_invoice_calculation.py b/apps/accounting/tests/test_invoice_calculation.py
index aa365afe0..6cd80aff4 100644
--- a/apps/accounting/tests/test_invoice_calculation.py
+++ b/apps/accounting/tests/test_invoice_calculation.py
@@ -15,7 +15,7 @@
     get_job_for_invoice_calculation,
     get_prior_valid_invoice_total,
 )
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.models.costing import CostLine
 from apps.testing import BaseTestCase
@@ -25,14 +25,14 @@ class TestInvoiceCalculation(BaseTestCase):
     """Tests for calculate_invoice_amount()."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             xero_last_modified=timezone.now(),
         )
 
     def _create_job(self, pricing_methodology="time_materials"):
         job = Job(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Test Job",
             pricing_methodology=pricing_methodology,
         )
@@ -53,7 +53,7 @@ def _add_revenue_line(self, cost_set, revenue):
     def _create_invoice(self, job, amount, status="AUTHORISED"):
         return Invoice.objects.create(
             job=job,
-            client=self.client_obj,
+            company=self.client_obj,
             xero_id=uuid.uuid4(),
             number=f"INV-{uuid.uuid4().hex[:8]}",
             status=status,
diff --git a/apps/accounting/tests/test_invoice_models.py b/apps/accounting/tests/test_invoice_models.py
index b597fb5e7..349c49e11 100644
--- a/apps/accounting/tests/test_invoice_models.py
+++ b/apps/accounting/tests/test_invoice_models.py
@@ -5,7 +5,7 @@
 
 from apps.accounting.enums import InvoiceStatus
 from apps.accounting.models import Invoice, InvoiceLineItem
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.testing import BaseTestCase
 
 
@@ -15,15 +15,15 @@ def test_total_amount_sums_reverse_line_items(self):
         when line items are added or modified — a bug here silently corrupts
         invoice totals displayed to users and synced to Xero.
         """
-        client = Client.objects.create(
-            name="Invoice Model Client",
+        company = Company.objects.create(
+            name="Invoice Model Company",
             xero_last_modified=timezone.now(),
         )
         invoice = Invoice.objects.create(
             xero_id=uuid4(),
             xero_tenant_id="tenant-id",
             number="INV-001",
-            client=client,
+            company=company,
             date=timezone.localdate(),
             due_date=timezone.localdate(),
             status=InvoiceStatus.DRAFT,
diff --git a/apps/accounting/tests/test_sales_pipeline_service.py b/apps/accounting/tests/test_sales_pipeline_service.py
index df20ef5e9..f45f8e587 100644
--- a/apps/accounting/tests/test_sales_pipeline_service.py
+++ b/apps/accounting/tests/test_sales_pipeline_service.py
@@ -15,7 +15,7 @@
 from django.utils import timezone
 
 from apps.accounting.services import SalesPipelineService
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobEvent
 from apps.job.models.costing import CostSet
 from apps.testing import BaseTestCase
@@ -32,14 +32,14 @@ def _nz_dt(d: date, hour: int = 12) -> datetime:
 class SalesPipelineServiceFixturesMixin:
     """Shared fixture-builders. Use via multiple inheritance with BaseTestCase."""
 
-    def _make_client(self, name: str = "Acme Co") -> Client:
-        return Client.objects.create(
+    def _make_client(self, name: str = "Acme Co") -> Company:
+        return Company.objects.create(
             name=name,
             email=f"{name.lower().replace(' ', '_')}@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
-    def _make_job(self, *, name: str, client: Client, created_dt: datetime) -> Job:
+    def _make_job(self, *, name: str, company: Company, created_dt: datetime) -> Job:
         """Create a job with a deterministic ``job_created`` event at ``created_dt``.
 
         ``Job.save()`` itself does not emit ``job_created`` — that lives in
@@ -49,7 +49,7 @@ def _make_job(self, *, name: str, client: Client, created_dt: datetime) -> Job:
         pay_item = XeroPayItem.get_ordinary_time()
         job = Job(
             name=name,
-            client=client,
+            company=company,
             created_by=self.test_staff,
             default_xero_pay_item=pay_item,
         )
@@ -61,7 +61,7 @@ def _make_job(self, *, name: str, client: Client, created_dt: datetime) -> Job:
             staff=self.test_staff,
             detail={
                 "job_name": job.name,
-                "client_name": client.name if client else "Shop Job",
+                "company_name": company.name if company else "Shop Job",
                 "contact_name": None,
                 "initial_status": job.get_status_display(),
                 "pricing_methodology": job.get_pricing_methodology_display(),
@@ -144,7 +144,7 @@ def setUp(self) -> None:
 
     def test_status_changed_into_approved_counts(self):
         job = self._make_job(
-            name="J1", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
+            name="J1", company=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
         )
         self._attach_quote(job, hours=12.5)
         self._add_status_change(
@@ -162,7 +162,7 @@ def test_status_changed_into_approved_counts(self):
 
     def test_quote_accepted_counts(self):
         job = self._make_job(
-            name="J2", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
+            name="J2", company=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
         )
         self._attach_quote(job, hours=4.0)
         self._add_status_change(
@@ -176,7 +176,7 @@ def test_quote_accepted_counts(self):
 
     def test_direct_approved_counts_in_direct_bucket(self):
         job = self._make_job(
-            name="J3", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
+            name="J3", company=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
         )
         self._attach_quote(job, hours=6.0)
         # Straight from draft to approved — no awaiting and no quote_accepted.
@@ -191,7 +191,7 @@ def test_direct_approved_counts_in_direct_bucket(self):
 
     def test_dedupe_approved_then_in_progress_same_period(self):
         job = self._make_job(
-            name="J4", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
+            name="J4", company=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
         )
         self._attach_quote(job, hours=10.0)
         self._add_status_change(
@@ -221,7 +221,9 @@ def test_target_reflects_company_defaults(self):
 
     def test_missing_hours_summary_excludes_and_warns(self):
         job = self._make_job(
-            name="No hours", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 5))
+            name="No hours",
+            company=self.client_obj,
+            created_dt=_nz_dt(date(2026, 1, 5)),
         )
         # Remove hours from the default quote/estimate summaries so hours
         # resolution genuinely fails (Job.save() seeds both with hours=0.0).
@@ -250,7 +252,7 @@ def test_replays_to_historical_status_not_live(self):
         # the historical state is "awaiting_approval".
         job = self._make_job(
             name="Replay job",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2026, 1, 5)),
         )
         self._attach_quote(job, hours=7.0, rev=2100.0)
@@ -282,7 +284,7 @@ def test_days_in_stage_uses_most_recent_entry(self):
         # Created in awaiting_approval, bounced back to draft, then back to
         # awaiting_approval. Days-in-stage measured from the latest entry.
         job = self._make_job(
-            name="Bouncy", client=self.client_obj, created_dt=_nz_dt(date(2026, 1, 1))
+            name="Bouncy", company=self.client_obj, created_dt=_nz_dt(date(2026, 1, 1))
         )
         # Override creation status to awaiting_approval for this test so the
         # historical replay anchor starts there.
@@ -308,14 +310,14 @@ def test_days_in_stage_uses_most_recent_entry(self):
 
     def test_draft_uses_estimate_summary_awaiting_uses_quote(self):
         d_job = self._make_job(
-            name="DraftJ", client=self.client_obj, created_dt=_nz_dt(date(2026, 2, 1))
+            name="DraftJ", company=self.client_obj, created_dt=_nz_dt(date(2026, 2, 1))
         )
         self._attach_estimate(d_job, hours=2.5)
         # Quote also exists but draft must use estimate
         self._attach_quote(d_job, hours=99.9)
 
         a_job = self._make_job(
-            name="AwaitJ", client=self.client_obj, created_dt=_nz_dt(date(2026, 2, 1))
+            name="AwaitJ", company=self.client_obj, created_dt=_nz_dt(date(2026, 2, 1))
         )
         self._attach_estimate(a_job, hours=99.9)
         self._attach_quote(a_job, hours=4.5)
@@ -341,7 +343,7 @@ def test_narrowed_fetch_preserves_historical_replay(self):
         """
         job = self._make_job(
             name="LongHistory",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2023, 1, 15)),
         )
         self._attach_quote(job, hours=9.0, rev=1800.0)
@@ -372,7 +374,7 @@ def test_narrowed_fetch_applies_lower_bound_for_in_window_query(self):
         # (single queryset), not the in-window queryset.
         outside_job = self._make_job(
             name="Outside",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2022, 3, 1)),
         )
         self._attach_estimate(outside_job, hours=2.0)
@@ -413,7 +415,7 @@ def test_missing_creation_anchor_excludes_and_warns(self):
         # Build a job and then delete its job_created event.
         job = self._make_job(
             name="Anchorless",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2026, 2, 1)),
         )
         self._attach_quote(job, hours=5.0)
@@ -442,7 +444,7 @@ def test_median_p80_sample_size(self):
             created = date(2026, 2, 1)
             approved_dt = _nz_dt(date(2026, 2, 1) + timedelta(days=gap))
             j = self._make_job(
-                name=f"V{i}", client=self.client_obj, created_dt=_nz_dt(created)
+                name=f"V{i}", company=self.client_obj, created_dt=_nz_dt(created)
             )
             self._attach_quote(j, hours=1.0)
             self._add_status_change(
@@ -474,7 +476,7 @@ def test_pre_window_creation_resolved_for_in_window_approval(self):
         """
         job = self._make_job(
             name="OldCreatedNowArchived",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2024, 1, 15)),
         )
         self._attach_quote(job, hours=4.0)
@@ -521,7 +523,7 @@ def test_missing_creation_anchor_excludes_and_warns(self):
         job_created anchor must produce a warning, not silent exclusion."""
         job = self._make_job(
             name="VelAnchorless",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2026, 2, 1)),
         )
         self._attach_quote(job, hours=1.0)
@@ -557,7 +559,7 @@ def setUp(self) -> None:
     def test_categorization_is_mutually_exclusive(self):
         # Accepted via quote_accepted
         j_acc = self._make_job(
-            name="Acc", client=self.client_obj, created_dt=_nz_dt(date(2026, 3, 2))
+            name="Acc", company=self.client_obj, created_dt=_nz_dt(date(2026, 3, 2))
         )
         self._attach_quote(j_acc, hours=1.0)
         self._add_status_change(
@@ -567,7 +569,7 @@ def test_categorization_is_mutually_exclusive(self):
 
         # Rejected
         j_rej = self._make_job(
-            name="Rej", client=self.client_obj, created_dt=_nz_dt(date(2026, 3, 3))
+            name="Rej", company=self.client_obj, created_dt=_nz_dt(date(2026, 3, 3))
         )
         self._attach_quote(j_rej, hours=2.0)
         self._add_status_change(
@@ -577,7 +579,7 @@ def test_categorization_is_mutually_exclusive(self):
 
         # Waiting
         j_wait = self._make_job(
-            name="Wait", client=self.client_obj, created_dt=_nz_dt(date(2026, 3, 4))
+            name="Wait", company=self.client_obj, created_dt=_nz_dt(date(2026, 3, 4))
         )
         self._attach_quote(j_wait, hours=4.0)
         self._add_status_change(
@@ -586,7 +588,7 @@ def test_categorization_is_mutually_exclusive(self):
 
         # Direct
         j_dir = self._make_job(
-            name="Dir", client=self.client_obj, created_dt=_nz_dt(date(2026, 3, 5))
+            name="Dir", company=self.client_obj, created_dt=_nz_dt(date(2026, 3, 5))
         )
         self._attach_estimate(j_dir, hours=8.0)
         self._add_status_change(
@@ -595,7 +597,7 @@ def test_categorization_is_mutually_exclusive(self):
 
         # Still draft
         j_draft = self._make_job(
-            name="Drf", client=self.client_obj, created_dt=_nz_dt(date(2026, 3, 6))
+            name="Drf", company=self.client_obj, created_dt=_nz_dt(date(2026, 3, 6))
         )
         self._attach_estimate(j_draft, hours=16.0)
 
@@ -622,7 +624,7 @@ def test_missing_creation_anchor_excludes_and_warns(self):
         being silently dropped."""
         job = self._make_job(
             name="FunnelAnchorless",
-            client=self.client_obj,
+            company=self.client_obj,
             created_dt=_nz_dt(date(2026, 3, 5)),
         )
         self._attach_quote(job, hours=3.0)
@@ -661,7 +663,7 @@ def test_rolling_average_derived_from_weekly_series(self):
             approved_day = end_date - timedelta(weeks=2 - i, days=2)  # Friday-ish
             j = self._make_job(
                 name=f"T{i}",
-                client=self.client_obj,
+                company=self.client_obj,
                 created_dt=_nz_dt(approved_day - timedelta(days=10)),
             )
             self._attach_quote(j, hours=hours)
diff --git a/apps/accounting/views/sales_forecast_view.py b/apps/accounting/views/sales_forecast_view.py
index 5cf2e0cd7..23b36a990 100644
--- a/apps/accounting/views/sales_forecast_view.py
+++ b/apps/accounting/views/sales_forecast_view.py
@@ -211,7 +211,7 @@ class SalesForecastMonthDetailAPIView(APIView):
                             "type": "object",
                             "properties": {
                                 "date": {"type": "string", "format": "date"},
-                                "client_name": {"type": "string"},
+                                "company_name": {"type": "string"},
                                 "job_number": {"type": "integer", "nullable": True},
                                 "job_name": {"type": "string", "nullable": True},
                                 "invoice_numbers": {"type": "string", "nullable": True},
@@ -311,7 +311,7 @@ def _build_comparison_rows(self, year: int, month: int) -> List[Dict[str, Any]]:
             ~Q(status__in=["DRAFT", "DELETED", "VOIDED"]),
             date__year=year,
             date__month=month,
-        ).select_related("client", "job", "job__client")
+        ).select_related("company", "job", "job__company")
 
         # Get jobs with actual revenue in this month
         jobs_with_revenue = self._get_jobs_with_revenue(year, month)
@@ -331,7 +331,7 @@ def _build_comparison_rows(self, year: int, month: int) -> List[Dict[str, Any]]:
 
         def build_row(
             row_date: str,
-            client_name: str,
+            company_name: str,
             job_number: Optional[int],
             job_name: Optional[str],
             invoice_numbers: Optional[str],
@@ -348,7 +348,7 @@ def build_row(
                 variance_all_time = round(total_xero_all_time - total_jm_all_time, 2)
             return {
                 "date": row_date,
-                "client_name": client_name,
+                "company_name": company_name,
                 "job_number": job_number,
                 "job_name": job_name,
                 "invoice_numbers": invoice_numbers,
@@ -389,7 +389,7 @@ def get_job_note(job: Optional[Job], match_type: str) -> Optional[str]:
             rows.append(
                 build_row(
                     row_date=job_invoices[0].date.isoformat(),
-                    client_name=job.client.name,
+                    company_name=job.company.name,
                     job_number=job.job_number,
                     job_name=job.name,
                     invoice_numbers=", ".join(inv.number for inv in job_invoices),
@@ -410,7 +410,7 @@ def get_job_note(job: Optional[Job], match_type: str) -> Optional[str]:
             rows.append(
                 build_row(
                     row_date=invoice.date.isoformat(),
-                    client_name=invoice.client.name,
+                    company_name=invoice.company.name,
                     job_number=None,
                     job_name=None,
                     invoice_numbers=invoice.number,
@@ -425,7 +425,7 @@ def get_job_note(job: Optional[Job], match_type: str) -> Optional[str]:
         for job_id in jobs_with_revenue.keys():
             if job_id in jobs_with_invoices:
                 continue
-            job = Job.objects.select_related("client").get(id=job_id)
+            job = Job.objects.select_related("company").get(id=job_id)
             monthly_revenue = float(jobs_with_revenue[job_id])
             start_date = job.start_date
             completion = job.last_financial_activity_date
@@ -435,7 +435,7 @@ def get_job_note(job: Optional[Job], match_type: str) -> Optional[str]:
             rows.append(
                 build_row(
                     row_date=completion.isoformat() if completion else None,
-                    client_name=job.client.name,
+                    company_name=job.company.name,
                     job_number=job.job_number,
                     job_name=job.name,
                     invoice_numbers=None,
diff --git a/apps/client/management/commands/merge_clients.py b/apps/client/management/commands/merge_clients.py
deleted file mode 100644
index d8377caf0..000000000
--- a/apps/client/management/commands/merge_clients.py
+++ /dev/null
@@ -1,131 +0,0 @@
-from django.core.management.base import BaseCommand
-from django.db import transaction
-
-from apps.accounts.models import Staff
-from apps.client.models import Client
-from apps.client.services.client_merge_service import reassign_client_fk_records
-from apps.job.models import Job
-from apps.workflow.models import CompanyDefaults
-
-
-class Command(BaseCommand):
-    help = "Merge duplicate clients with the same name"
-
-    def add_arguments(self, parser):
-        parser.add_argument(
-            "--name",
-            type=str,
-            help="Client name to check for duplicates. If not provided, "
-            "then raise a value error",
-        )
-        parser.add_argument(
-            "--auto",
-            action="store_true",
-            help="Automatically merge without confirmation",
-        )
-
-    def handle(self, *args, **options):
-        # Determine which client name to look for
-        client_name = options.get("name")
-
-        if not client_name:
-            # Use the configured shop client from CompanyDefaults
-            company_defaults = CompanyDefaults.get_solo()
-            client_name = company_defaults.shop_client.name
-        else:
-            pass  # explicit client name provided by caller
-
-        self.stdout.write(f"Looking for duplicate clients with name: '{client_name}'")
-
-        # Find all clients with this name
-        duplicate_clients = Client.objects.filter(name=client_name).order_by(
-            "django_created_at"
-        )
-        count = duplicate_clients.count()
-
-        if count == 0:
-            self.stdout.write(
-                self.style.WARNING(f"No clients found with name '{client_name}'")
-            )
-            return
-        elif count == 1:
-            self.stdout.write(
-                self.style.SUCCESS(
-                    f"Only one client found with name '{client_name}' - "
-                    f"no duplicates to fix"
-                )
-            )
-            return
-
-        self.stdout.write(
-            self.style.WARNING(f"Found {count} clients with name '{client_name}':")
-        )
-
-        # Display information about each client
-        clients_with_job_counts = []
-        for i, client in enumerate(duplicate_clients):
-            job_count = Job.objects.filter(client=client).count()
-            clients_with_job_counts.append((client, job_count))
-
-            self.stdout.write(f"{i + 1}. Client ID: {client.pk}")
-            self.stdout.write(f"   Created: {client.django_created_at}")
-            self.stdout.write(f"   Jobs: {job_count}")
-            if client.xero_contact_id:
-                self.stdout.write(f"   Xero Contact ID: {client.xero_contact_id}")
-
-        # Sort by job count (descending) and then by creation date (ascending)
-        clients_with_job_counts.sort(key=lambda x: (-x[1], x[0].django_created_at))
-
-        primary_client = clients_with_job_counts[0][0]
-        self.stdout.write(
-            self.style.SUCCESS(
-                f"Recommended primary client: {primary_client.pk} "
-                f"(has {clients_with_job_counts[0][1]} jobs)"
-            )
-        )
-
-        # Ask for confirmation unless --auto flag is used
-        if not options["auto"]:
-            response = input(
-                "Do you want to merge all duplicates into this client? (yes/no): "
-            )
-            if response.lower() != "yes":
-                self.stdout.write(self.style.WARNING("Operation cancelled"))
-                return
-
-        # Merge duplicates
-        with transaction.atomic():
-            for client, job_count in clients_with_job_counts[1:]:
-                self.stdout.write(
-                    f"Merging client {client.pk} into {primary_client.pk}..."
-                )
-
-                # Reassign every client-FK record (Jobs, Invoices, Bills,
-                # Credit Notes, Quotes, POs, supplier references). The prior
-                # implementation only moved Jobs; the others ended up orphaned
-                # on the deleted client via the PROTECT constraint failure
-                # path — or silently lost on cascade with the old pointer.
-                counts = reassign_client_fk_records(
-                    client,
-                    primary_client,
-                    Staff.get_automation_user(),
-                    logger_prefix="[manual-merge] ",
-                )
-                self.stdout.write(f"  Reassigned records: {counts}")
-
-                # Delete the duplicate client — safe now that every PROTECTed
-                # FK has been moved onto the primary.
-                client.delete()
-                self.stdout.write(f"  Deleted duplicate client {client.pk}")
-
-        self.stdout.write(
-            self.style.SUCCESS(
-                f"Success! All duplicates merged into client {primary_client.pk}"
-            )
-        )
-        self.stdout.write(
-            self.style.SUCCESS(
-                f"Total jobs now associated with this client: "
-                f"{Job.objects.filter(client=primary_client).count()}"
-            )
-        )
diff --git a/apps/client/tests/test_client_jobs_queries.py b/apps/client/tests/test_client_jobs_queries.py
deleted file mode 100644
index 754d27f04..000000000
--- a/apps/client/tests/test_client_jobs_queries.py
+++ /dev/null
@@ -1,31 +0,0 @@
-from __future__ import annotations
-
-from django.db import connection
-from django.test.utils import CaptureQueriesContext
-
-from apps.client.models import Client
-from apps.client.services.client_rest_service import ClientRestService
-from apps.job.models import Job
-from apps.testing import BaseTestCase
-
-
-class ClientJobsQueryTests(BaseTestCase):
-    """get_client_jobs reads job.quoted per job; without select_related on
-    quote that lazy-loads once per job and the dev/E2E n+1 guard raises."""
-
-    def test_get_client_jobs_does_not_lazy_load_quotes(self) -> None:
-        client_obj = Client.objects.create(
-            name="Client Jobs Query Client",
-            email="client-jobs-queries@example.com",
-            xero_last_modified="2024-01-01T00:00:00Z",
-        )
-        for name in ("Client Jobs Query Job 1", "Client Jobs Query Job 2"):
-            job = Job(name=name, client=client_obj)
-            job.save(staff=self.test_staff)
-
-        with CaptureQueriesContext(connection) as ctx:
-            jobs = ClientRestService.get_client_jobs(client_obj.id)
-
-        self.assertEqual(len(jobs), 2)
-        # exists() guard + the jobs query (quote joined in, not lazy-loaded)
-        self.assertLessEqual(len(ctx.captured_queries), 2)
diff --git a/apps/client/urls_rest.py b/apps/client/urls_rest.py
deleted file mode 100644
index 3c14fc721..000000000
--- a/apps/client/urls_rest.py
+++ /dev/null
@@ -1,108 +0,0 @@
-"""
-Client REST URLs
-
-REST URLs for Client module following RESTful patterns:
-- Clearly defined endpoints
-- Appropriate HTTP verbs
-- Consistent structure with other REST modules
-"""
-
-from django.urls import include, path
-from rest_framework.routers import DefaultRouter
-
-from apps.client.views.address_views import AddressValidateView
-from apps.client.views.client_contact_method_viewset import ClientContactMethodViewSet
-from apps.client.views.client_contact_viewset import ClientContactViewSet
-from apps.client.views.client_rest_views import (
-    ClientCreateRestView,
-    ClientJobsRestView,
-    ClientListAllRestView,
-    ClientRetrieveRestView,
-    ClientSearchRestView,
-    ClientUpdateRestView,
-    JobContactRestView,
-)
-from apps.client.views.supplier_pickup_address_viewset import (
-    SupplierPickupAddressViewSet,
-)
-from apps.client.views.supplier_search_alias_views import (
-    ClientSupplierAliasListCreateView,
-    SupplierAliasDetailView,
-)
-
-app_name = "clients_rest"
-
-# Router for ViewSet-based endpoints
-router = DefaultRouter()
-router.register(
-    "contact-methods",
-    ClientContactMethodViewSet,
-    basename="client-contact-method",
-)
-router.register("contacts", ClientContactViewSet, basename="client-contact")
-router.register(
-    "pickup-addresses", SupplierPickupAddressViewSet, basename="supplier-pickup-address"
-)
-
-urlpatterns = [
-    # Client list all REST endpoint
-    path(
-        "all/",
-        ClientListAllRestView.as_view(),
-        name="client_list_all_rest",
-    ),
-    # Client creation REST endpoint
-    path(
-        "create/",
-        ClientCreateRestView.as_view(),
-        name="client_create_rest",
-    ),
-    # Client search REST endpoint
-    path(
-        "search/",
-        ClientSearchRestView.as_view(),
-        name="client_search_rest",
-    ),
-    # Client retrieve REST endpoint
-    path(
-        "<uuid:client_id>/",
-        ClientRetrieveRestView.as_view(),
-        name="client_retrieve_rest",
-    ),
-    # Client update REST endpoint
-    path(
-        "<uuid:client_id>/update/",
-        ClientUpdateRestView.as_view(),
-        name="client_update_rest",
-    ),
-    # Client jobs REST endpoint
-    path(
-        "<uuid:client_id>/jobs/",
-        ClientJobsRestView.as_view(),
-        name="client_jobs_rest",
-    ),
-    path(
-        "<uuid:client_id>/supplier-aliases/",
-        ClientSupplierAliasListCreateView.as_view(),
-        name="client_supplier_aliases_rest",
-    ),
-    path(
-        "supplier-aliases/<uuid:alias_id>/",
-        SupplierAliasDetailView.as_view(),
-        name="supplier_alias_detail_rest",
-    ),
-    # Job contact REST endpoint
-    path(
-        "jobs/<uuid:job_id>/contact/",
-        JobContactRestView.as_view(),
-        name="job_contact_rest",
-    ),
-    # Address validation endpoint
-    path(
-        "addresses/validate/",
-        AddressValidateView.as_view(),
-        name="address_validate",
-    ),
-    # ViewSet routes (contacts CRUD)
-    path("", include(router.urls)),
-]
diff --git a/apps/client/__init__.py b/apps/company/__init__.py
similarity index 53%
rename from apps/client/__init__.py
rename to apps/company/__init__.py
index 789a287a4..a78879f7c 100644
--- a/apps/client/__init__.py
+++ b/apps/company/__init__.py
@@ -1,6 +1,6 @@
 # This file is autogenerated by update_init.py script
 
-from .apps import ClientConfig
+from .apps import CompanyConfig
 from .utils import date_to_datetime
 
 # Conditional imports (only when Django is ready)
@@ -9,10 +9,10 @@
 
     if apps.ready:
         from .models import (
-            Client,
             ClientContact,
             ClientContactMethod,
-            ClientQuerySet,
+            Company,
+            CompanyQuerySet,
             PhoneAssignmentConflictError,
             Supplier,
             SupplierPickupAddress,
@@ -21,20 +21,20 @@
         from .serializers import (
             ClientContactMethodSerializer,
             ClientContactSerializer,
-            ClientCreateResponseSerializer,
-            ClientCreateSerializer,
-            ClientDetailResponseSerializer,
-            ClientDuplicateErrorResponseSerializer,
-            ClientErrorResponseSerializer,
-            ClientJobHeaderSerializer,
-            ClientJobsResponseSerializer,
-            ClientListResponseSerializer,
-            ClientNameOnlySerializer,
-            ClientSearchResponseSerializer,
-            ClientSearchResultSerializer,
-            ClientSerializer,
-            ClientUpdateResponseSerializer,
-            ClientUpdateSerializer,
+            CompanyCreateResponseSerializer,
+            CompanyCreateSerializer,
+            CompanyDetailResponseSerializer,
+            CompanyDuplicateErrorResponseSerializer,
+            CompanyErrorResponseSerializer,
+            CompanyJobHeaderSerializer,
+            CompanyJobsResponseSerializer,
+            CompanyListResponseSerializer,
+            CompanyNameOnlySerializer,
+            CompanySearchResponseSerializer,
+            CompanySearchResultSerializer,
+            CompanySerializer,
+            CompanyUpdateResponseSerializer,
+            CompanyUpdateSerializer,
             JobContactResponseSerializer,
             JobContactUpdateSerializer,
             StandardErrorSerializer,
@@ -47,27 +47,27 @@
     pass
 
 __all__ = [
-    "Client",
-    "ClientConfig",
     "ClientContact",
     "ClientContactMethod",
     "ClientContactMethodSerializer",
     "ClientContactSerializer",
-    "ClientCreateResponseSerializer",
-    "ClientCreateSerializer",
-    "ClientDetailResponseSerializer",
-    "ClientDuplicateErrorResponseSerializer",
-    "ClientErrorResponseSerializer",
-    "ClientJobHeaderSerializer",
-    "ClientJobsResponseSerializer",
-    "ClientListResponseSerializer",
-    "ClientNameOnlySerializer",
-    "ClientQuerySet",
-    "ClientSearchResponseSerializer",
-    "ClientSearchResultSerializer",
-    "ClientSerializer",
-    "ClientUpdateResponseSerializer",
-    "ClientUpdateSerializer",
+    "Company",
+    "CompanyConfig",
+    "CompanyCreateResponseSerializer",
+    "CompanyCreateSerializer",
+    "CompanyDetailResponseSerializer",
+    "CompanyDuplicateErrorResponseSerializer",
+    "CompanyErrorResponseSerializer",
+    "CompanyJobHeaderSerializer",
+    "CompanyJobsResponseSerializer",
+    "CompanyListResponseSerializer",
+    "CompanyNameOnlySerializer",
+    "CompanyQuerySet",
+    "CompanySearchResponseSerializer",
+    "CompanySearchResultSerializer",
+    "CompanySerializer",
+    "CompanyUpdateResponseSerializer",
+    "CompanyUpdateSerializer",
     "JobContactResponseSerializer",
     "JobContactUpdateSerializer",
     "PhoneAssignmentConflictError",
diff --git a/apps/client/admin.py b/apps/company/admin.py
similarity index 100%
rename from apps/client/admin.py
rename to apps/company/admin.py
diff --git a/apps/client/apps.py b/apps/company/apps.py
similarity index 61%
rename from apps/client/apps.py
rename to apps/company/apps.py
index c221d32c0..cd2ead460 100644
--- a/apps/client/apps.py
+++ b/apps/company/apps.py
@@ -1,6 +1,6 @@
 from django.apps import AppConfig
 
 
-class ClientConfig(AppConfig):
+class CompanyConfig(AppConfig):
     default_auto_field = "django.db.models.BigAutoField"
-    name = "apps.client"
+    name = "apps.company"
diff --git a/apps/company/management/commands/merge_companies.py b/apps/company/management/commands/merge_companies.py
new file mode 100644
index 000000000..467d77d83
--- /dev/null
+++ b/apps/company/management/commands/merge_companies.py
@@ -0,0 +1,133 @@
+from django.core.management.base import BaseCommand
+from django.db import transaction
+
+from apps.accounts.models import Staff
+from apps.company.models import Company
+from apps.company.services.company_merge_service import reassign_company_fk_records
+from apps.job.models import Job
+from apps.workflow.models import CompanyDefaults
+
+
+class Command(BaseCommand):
+    help = "Merge duplicate companies with the same name"
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--name",
+            type=str,
+            help="Company name to check for duplicates. If not provided, "
+            "then raise a value error",
+        )
+        parser.add_argument(
+            "--auto",
+            action="store_true",
+            help="Automatically merge without confirmation",
+        )
+
+    def handle(self, *args, **options):
+        # Determine which company name to look for
+        company_name = options.get("name")
+
+        if not company_name:
+            # Use the configured shop company from CompanyDefaults
+            company_defaults = CompanyDefaults.get_solo()
+            company_name = company_defaults.shop_company.name
+        else:
+            pass  # explicit company name provided by caller
+
+        self.stdout.write(
+            f"Looking for duplicate companies with name: '{company_name}'"
+        )
+
+        # Find all companies with this name
+        duplicate_companies = Company.objects.filter(name=company_name).order_by(
+            "django_created_at"
+        )
+        count = duplicate_companies.count()
+
+        if count == 0:
+            self.stdout.write(
+                self.style.WARNING(f"No companies found with name '{company_name}'")
+            )
+            return
+        elif count == 1:
+            self.stdout.write(
+                self.style.SUCCESS(
+                    f"Only one company found with name '{company_name}' - "
+                    f"no duplicates to fix"
+                )
+            )
+            return
+
+        self.stdout.write(
+            self.style.WARNING(f"Found {count} companies with name '{company_name}':")
+        )
+
+        # Display information about each company
+        companies_with_job_counts = []
+        for i, company in enumerate(duplicate_companies):
+            job_count = Job.objects.filter(company=company).count()
+            companies_with_job_counts.append((company, job_count))
+
+            self.stdout.write(f"{i + 1}. Company ID: {company.pk}")
+            self.stdout.write(f"   Created: {company.django_created_at}")
+            self.stdout.write(f"   Jobs: {job_count}")
+            if company.xero_contact_id:
+                self.stdout.write(f"   Xero Contact ID: {company.xero_contact_id}")
+
+        # Sort by job count (descending) and then by creation date (ascending)
+        companies_with_job_counts.sort(key=lambda x: (-x[1], x[0].django_created_at))
+
+        primary_company = companies_with_job_counts[0][0]
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Recommended primary company: {primary_company.pk} "
+                f"(has {companies_with_job_counts[0][1]} jobs)"
+            )
+        )
+
+        # Ask for confirmation unless --auto flag is used
+        if not options["auto"]:
+            response = input(
+                "Do you want to merge all duplicates into this company? (yes/no): "
+            )
+            if response.lower() != "yes":
+                self.stdout.write(self.style.WARNING("Operation cancelled"))
+                return
+
+        # Merge duplicates
+        with transaction.atomic():
+            for company, job_count in companies_with_job_counts[1:]:
+                self.stdout.write(
+                    f"Merging company {company.pk} into {primary_company.pk}..."
+                )
+
+                # Reassign every company-FK record (Jobs, Invoices, Bills,
+                # Credit Notes, Quotes, POs, supplier references). The prior
+                # implementation only moved Jobs; the others ended up orphaned
+                # on the deleted company via the PROTECT constraint failure
+                # path — or silently lost on cascade with the old pointer.
+                counts = reassign_company_fk_records(
+                    company,
+                    primary_company,
+                    Staff.get_automation_user(),
+                    logger_prefix="[manual-merge] ",
+                )
+                self.stdout.write(f"  Reassigned records: {counts}")
+
+                # Delete the duplicate company — safe now that every PROTECTed
+                # FK has been moved onto the primary.
+                company.delete()
+                self.stdout.write(f"  Deleted duplicate company {company.pk}")
+
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Success! All duplicates merged into company {primary_company.pk}"
+            )
+        )
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Total jobs now associated with this company: "
+                f"{Job.objects.filter(company=primary_company).count()}"
+            )
+        )
diff --git a/apps/client/migrations/0001_baseline.py b/apps/company/migrations/0001_baseline.py
similarity index 98%
rename from apps/client/migrations/0001_baseline.py
rename to apps/company/migrations/0001_baseline.py
index eff64690a..4746dd232 100644
--- a/apps/client/migrations/0001_baseline.py
+++ b/apps/company/migrations/0001_baseline.py
@@ -99,7 +99,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.SET_NULL,
                         related_name="merged_from_clients",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -116,7 +116,7 @@ class Migration(migrations.Migration):
                 "indexes": [],
                 "constraints": [],
             },
-            bases=("client.client",),
+            bases=("company.client",),
         ),
         migrations.CreateModel(
             name="ClientContact",
@@ -184,7 +184,7 @@ class Migration(migrations.Migration):
                         help_text="The client this contact belongs to",
                         on_delete=django.db.models.deletion.CASCADE,
                         related_name="contacts",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -233,7 +233,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.CASCADE,
                         related_name="contact_methods",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
                 (
@@ -243,7 +243,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.CASCADE,
                         related_name="contact_methods",
-                        to="client.clientcontact",
+                        to="company.clientcontact",
                     ),
                 ),
             ],
@@ -377,7 +377,7 @@ class Migration(migrations.Migration):
                         help_text="The supplier this pickup address belongs to",
                         on_delete=django.db.models.deletion.CASCADE,
                         related_name="pickup_addresses",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -408,7 +408,7 @@ class Migration(migrations.Migration):
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.CASCADE,
                         related_name="supplier_search_aliases",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
diff --git a/apps/company/migrations/0002_rename_client_company.py b/apps/company/migrations/0002_rename_client_company.py
new file mode 100644
index 000000000..345162bcc
--- /dev/null
+++ b/apps/company/migrations/0002_rename_client_company.py
@@ -0,0 +1,202 @@
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("company", "0001_baseline"),
+        # Every app below has a baseline migration with a lazy FK reference
+        # to "company.client" (the pre-rename model name). RenameModel only
+        # repoints references already present in the in-memory state at the
+        # moment it runs; without these edges the topological sort is free to
+        # schedule this migration before those apps' baselines are replayed,
+        # leaving their FKs pointing at a model name that no longer resolves.
+        ("accounting", "0002_baseline"),
+        ("crm", "0001_baseline"),
+        ("job", "0001_baseline"),
+        ("purchasing", "0001_baseline"),
+        ("quoting", "0001_baseline"),
+        ("workflow", "0001_baseline"),
+    ]
+
+    operations = [
+        # RenameModel repoints FK/M2M references to the renamed model but does
+        # not rewrite the `bases` tuple of proxy models that inherit from it
+        # (Supplier(Client) -> would still record bases=("company.client",)
+        # after the rename, which no longer resolves). Worse, the contenttypes
+        # app injects a RenameContentType operation IMMEDIATELY after every
+        # RenameModel at migrate time, and that operation renders the full
+        # project state right there. So the proxy must be gone from state
+        # BEFORE the rename and recreated on the new base AFTER it. A proxy
+        # has no physical table (allow_migrate_model is False), so the
+        # Delete+Create pair is a state-only no-op against the database.
+        migrations.DeleteModel(name="Supplier"),
+        migrations.RenameModel(old_name="Client", new_name="Company"),
+        migrations.CreateModel(
+            name="Supplier",
+            fields=[],
+            options={
+                "proxy": True,
+                "indexes": [],
+                "constraints": [],
+            },
+            bases=("company.company",),
+        ),
+        migrations.RenameIndex(
+            model_name="company",
+            old_name="client_name_fts_idx",
+            new_name="company_name_fts_idx",
+        ),
+        migrations.RenameIndex(
+            model_name="company",
+            old_name="client_name_trgm_idx",
+            new_name="company_name_trgm_idx",
+        ),
+        migrations.AlterField(
+            model_name="company",
+            name="merged_into",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="The company this was merged into",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="merged_from_companies",
+                to="company.company",
+            ),
+        ),
+        # Constraints referencing a field must be removed (using the old field
+        # name they were defined with) BEFORE the field is renamed, and any
+        # replacement added AFTER: RenameField does not rewrite field names
+        # embedded in Q() conditions on other constraints, so removing a
+        # conditioned constraint after the rename fails to resolve the old
+        # field name against the post-rename model state.
+        migrations.RemoveConstraint(
+            model_name="clientcontact",
+            name="unique_client_contact_name",
+        ),
+        migrations.RenameField(
+            model_name="clientcontact",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontact",
+            constraint=models.UniqueConstraint(
+                fields=("company", "name"), name="unique_company_contact_name"
+            ),
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="client_contact_method_one_owner",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_client_contact_method_value",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_client_primary_contact_method",
+        ),
+        # These two constraints keep their names across the rename (they were
+        # never named after "client"), but their conditions embed the old
+        # field name too, so they need the same remove-before/add-after
+        # treatment as the constraints above.
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_contact_contact_method_value",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_contact_primary_contact_method",
+        ),
+        migrations.RenameField(
+            model_name="clientcontactmethod",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontactmethod",
+            constraint=models.CheckConstraint(
+                condition=(
+                    models.Q(("company__isnull", False), ("contact__isnull", True))
+                    | models.Q(("company__isnull", True), ("contact__isnull", False))
+                ),
+                name="contact_method_one_owner",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(
+                    ("company__isnull", False), ("contact__isnull", True)
+                ),
+                fields=("company", "method_type", "normalized_value"),
+                name="unique_company_contact_method_value",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(
+                    ("company__isnull", False),
+                    ("contact__isnull", True),
+                    ("is_primary", True),
+                ),
+                fields=("company", "method_type"),
+                name="unique_company_primary_contact_method",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(
+                    ("company__isnull", True), ("contact__isnull", False)
+                ),
+                fields=("contact", "method_type", "normalized_value"),
+                name="unique_contact_contact_method_value",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="clientcontactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(
+                    ("company__isnull", True),
+                    ("contact__isnull", False),
+                    ("is_primary", True),
+                ),
+                fields=("contact", "method_type"),
+                name="unique_contact_primary_contact_method",
+            ),
+        ),
+        migrations.RemoveConstraint(
+            model_name="suppliersearchalias",
+            name="unique_supplier_search_alias_per_client",
+        ),
+        migrations.RenameField(
+            model_name="suppliersearchalias",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.AddConstraint(
+            model_name="suppliersearchalias",
+            constraint=models.UniqueConstraint(
+                fields=("company", "alias"),
+                name="unique_supplier_search_alias_per_company",
+            ),
+        ),
+        migrations.RemoveConstraint(
+            model_name="supplierpickupaddress",
+            name="unique_supplier_pickup_address_name",
+        ),
+        migrations.RenameField(
+            model_name="supplierpickupaddress",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.AddConstraint(
+            model_name="supplierpickupaddress",
+            constraint=models.UniqueConstraint(
+                fields=("company", "name"), name="unique_supplier_pickup_address_name"
+            ),
+        ),
+    ]
diff --git a/apps/company/migrations/0003_alter_clientcontact_company_and_more.py b/apps/company/migrations/0003_alter_clientcontact_company_and_more.py
new file mode 100644
index 000000000..8054de51a
--- /dev/null
+++ b/apps/company/migrations/0003_alter_clientcontact_company_and_more.py
@@ -0,0 +1,58 @@
+# Generated by Django 6.0.4 on 2026-07-06 10:20
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0002_rename_client_company"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="clientcontact",
+            name="company",
+            field=models.ForeignKey(
+                help_text="The company this contact belongs to",
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="contacts",
+                to="company.company",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="clientcontact",
+            name="is_primary",
+            field=models.BooleanField(
+                default=False,
+                help_text="Indicates if this is the primary contact for the company",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="company",
+            name="allow_jobs",
+            field=models.BooleanField(
+                default=True,
+                help_text="If False, this company cannot be selected as the company on a Job. Use for Xero contacts that must exist (tax authorities, internal accounts, etc.) but should never appear on a job. Automatically set to False when a company is archived or merged in Xero.",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="company",
+            name="xero_archived",
+            field=models.BooleanField(
+                default=False,
+                help_text="Indicates if this company has been archived/merged in Xero",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="company",
+            name="xero_merged_into_id",
+            field=models.CharField(
+                blank=True,
+                help_text="The Xero contact ID this company was merged into (temporary storage)",
+                max_length=255,
+                null=True,
+            ),
+        ),
+    ]
diff --git a/apps/client/migrations/__init__.py b/apps/company/migrations/__init__.py
similarity index 100%
rename from apps/client/migrations/__init__.py
rename to apps/company/migrations/__init__.py
diff --git a/apps/client/models.py b/apps/company/models.py
similarity index 79%
rename from apps/client/models.py
rename to apps/company/models.py
index 80fa138ee..567cb4f71 100644
--- a/apps/client/models.py
+++ b/apps/company/models.py
@@ -42,8 +42,8 @@ def _augment_update_fields(
     return names
 
 
-class ClientQuerySet(models.QuerySet):
-    """Custom queryset for Client with precomputed invoice aggregates."""
+class CompanyQuerySet(models.QuerySet):
+    """Custom queryset for Company with precomputed invoice aggregates."""
 
     def with_invoice_summary(self):
         output = models.DecimalField(max_digits=12, decimal_places=2)
@@ -57,21 +57,21 @@ def with_invoice_summary(self):
         )
 
 
-class Client(models.Model):
-    # CHECKLIST - when adding a new field or property to Client, check these locations:
-    #   1. CLIENT_DIRECT_FIELDS below (if it's a model field)
-    #   2. _format_client_detail() in apps/client/services/client_rest_service.py
-    #   3. _format_client_summary() in apps/client/services/client_rest_service.py (subset for lists)
-    #   4. get_client_for_xero() in this file (Xero API format)
-    #   5. update_client_from_raw_json() in apps/workflow/api/xero/reprocess_xero.py (Xero-sourced fields only)
-    #   6. _update_client_in_xero() in apps/client/services/client_rest_service.py (Xero API format)
-    #   7. ClientDetailResponseSerializer in apps/client/serializers.py
-    #   8. ClientSearchResultSerializer in apps/client/serializers.py (subset for lists)
+class Company(models.Model):
+    # CHECKLIST - when adding a new field or property to Company, check these locations:
+    #   1. COMPANY_DIRECT_FIELDS below (if it's a model field)
+    #   2. _format_company_detail() in apps/company/services/company_rest_service.py
+    #   3. _format_company_summary() in apps/company/services/company_rest_service.py (subset for lists)
+    #   4. get_company_for_xero() in this file (Xero API format)
+    #   5. update_company_from_raw_json() in apps/workflow/api/xero/reprocess_xero.py (Xero-sourced fields only)
+    #   6. _update_company_in_xero() in apps/company/services/company_rest_service.py (Xero API format)
+    #   7. CompanyDetailResponseSerializer in apps/company/serializers.py
+    #   8. CompanySearchResultSerializer in apps/company/serializers.py (subset for lists)
 
-    objects = ClientQuerySet.as_manager()
+    objects = CompanyQuerySet.as_manager()
 
     # Direct scalar model fields (not related objects, not properties).
-    CLIENT_DIRECT_FIELDS = [
+    COMPANY_DIRECT_FIELDS = [
         "name",
         "email",
         "address",
@@ -107,14 +107,14 @@ class Client(models.Model):
     )  # Account vs cash customer flag
     is_supplier = models.BooleanField(
         default=False
-    )  # Indicates if this client is also a supplier
+    )  # Indicates if this company is also a supplier
     allow_jobs = models.BooleanField(
         default=True,
         help_text=(
-            "If False, this client cannot be selected as the client on a Job. "
+            "If False, this company cannot be selected as the company on a Job. "
             "Use for Xero contacts that must exist (tax authorities, internal "
             "accounts, etc.) but should never appear on a job. Automatically "
-            "set to False when a client is archived or merged in Xero."
+            "set to False when a company is archived or merged in Xero."
         ),
     )
     xero_last_modified = models.DateTimeField(null=False, blank=False)
@@ -135,24 +135,24 @@ class Client(models.Model):
 
     xero_last_synced = models.DateTimeField(null=True, blank=True, default=timezone.now)
 
-    # Fields to track merged clients in Xero
+    # Fields to track merged companies in Xero
     xero_archived = models.BooleanField(
         default=False,
-        help_text="Indicates if this client has been archived/merged in Xero",
+        help_text="Indicates if this company has been archived/merged in Xero",
     )
     xero_merged_into_id = models.CharField(
         max_length=255,
         null=True,
         blank=True,
-        help_text="The Xero contact ID this client was merged into (temporary storage)",
+        help_text="The Xero contact ID this company was merged into (temporary storage)",
     )
     merged_into = models.ForeignKey(
         "self",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
-        related_name="merged_from_clients",
-        help_text="The client this was merged into",
+        related_name="merged_from_companies",
+        help_text="The company this was merged into",
     )
 
     class Meta:
@@ -160,11 +160,11 @@ class Meta:
         indexes = [
             GinIndex(
                 SearchVector("name", config="english"),
-                name="client_name_fts_idx",
+                name="company_name_fts_idx",
             ),
             GinIndex(
                 fields=["name"],
-                name="client_name_trgm_idx",
+                name="company_name_trgm_idx",
                 opclasses=["gin_trgm_ops"],
             ),
         ]
@@ -178,11 +178,11 @@ def save(self, *args, **kwargs):
 
     def validate_for_xero(self):
         """
-        Validate if the client data is sufficient to sync to Xero.
+        Validate if the company data is sufficient to sync to Xero.
         Only name is required by Xero.
         """
         if not self.name:
-            logger.error(f"Client {self.id} does not have a valid name.")
+            logger.error(f"Company {self.id} does not have a valid name.")
             return False
         return True
 
@@ -190,8 +190,8 @@ def validate_for_xero(self):
     def last_invoice_date(self):
         if "_last_invoice_date" not in self.__dict__:
             raise RuntimeError(
-                "Client.last_invoice_date requires "
-                "Client.objects.with_invoice_summary()."
+                "Company.last_invoice_date requires "
+                "Company.objects.with_invoice_summary()."
             )
         return self.__dict__["_last_invoice_date"]
 
@@ -203,7 +203,7 @@ def last_invoice_date(self, value):
     def total_spend(self):
         if "_total_spend" not in self.__dict__:
             raise RuntimeError(
-                "Client.total_spend requires Client.objects.with_invoice_summary()."
+                "Company.total_spend requires Company.objects.with_invoice_summary()."
             )
         return self.__dict__["_total_spend"]
 
@@ -211,7 +211,7 @@ def total_spend(self):
     def total_spend(self, value):
         self.__dict__["_total_spend"] = value
 
-    def get_client_for_xero(self):
+    def get_company_for_xero(self):
         """
         Build a xero_python.accounting.models.Contact for syncing to Xero.
 
@@ -221,7 +221,7 @@ def get_client_for_xero(self):
         """
         if not self.name:
             raise ValueError(
-                f"Client {self.id} is missing a name, which is required for Xero."
+                f"Company {self.id} is missing a name, which is required for Xero."
             )
 
         primary_phone = self.primary_phone_value()
@@ -247,7 +247,7 @@ def get_client_for_xero(self):
         )
 
     def primary_phone_value(self) -> str:
-        """The client's own primary phone number, or "" when it has none.
+        """The company's own primary phone number, or "" when it has none.
 
         Uses the same ordering as every other primary-phone consumer:
         primary first, then label/value as a stable tie-break.
@@ -261,10 +261,10 @@ def primary_phone_value(self) -> str:
         )
         return method.value if method else ""
 
-    def get_final_client(self):
+    def get_final_company(self):
         """
-        Follow the merge chain to get the final client.
-        If this client was merged into another, return that client
+        Follow the merge chain to get the final company.
+        If this company was merged into another, return that company
         (following the chain).
         Otherwise return self.
         """
@@ -273,7 +273,7 @@ def get_final_client(self):
 
         while current.merged_into:
             if current.merged_into.id in seen:
-                logger.warning(f"Circular merge chain detected for client {self.id}")
+                logger.warning(f"Circular merge chain detected for company {self.id}")
                 break
             seen.add(current.merged_into.id)
             current = current.merged_into
@@ -283,24 +283,24 @@ def get_final_client(self):
 
 class ClientContact(models.Model):
     """
-    Represents a contact person for a client.
+    Represents a contact person for a company.
     This model stores contact information that was previously synced with Xero
     but is now managed entirely within our application.
     """
 
     # CHECKLIST - when adding a new field or property to ClientContact, check these locations:
     #   1. CLIENTCONTACT_API_FIELDS or CLIENTCONTACT_INTERNAL_FIELDS below (if it's a model field)
-    #   2. ClientContactSerializer in apps/client/serializers.py (uses CLIENTCONTACT_API_FIELDS)
+    #   2. ClientContactSerializer in apps/company/serializers.py (uses CLIENTCONTACT_API_FIELDS)
     #   3. ClientContactSerializer.to_internal_value() nullable_fields list (converts "" → None)
-    #   4. JobContactResponseSerializer in apps/client/serializers.py (subset for job context)
-    #   5. ClientContactViewSet in apps/client/views/client_contact_viewset.py (CRUD operations)
+    #   4. JobContactResponseSerializer in apps/company/serializers.py (subset for job context)
+    #   5. ClientContactViewSet in apps/company/views/contact_viewset.py (CRUD operations)
     #   6. Job.contact FK in apps/job/models/job.py (relationship to ClientContact)
     #   7. reprocess_xero.py in apps/workflow/api/xero/ (Xero sync creates contacts)
     #
     # Database fields exposed via API serializers
     CLIENTCONTACT_API_FIELDS = [
         "id",
-        "client",
+        "company",
         "name",
         "email",
         "position",
@@ -318,11 +318,11 @@ class ClientContact(models.Model):
     CLIENTCONTACT_ALL_FIELDS = CLIENTCONTACT_API_FIELDS + CLIENTCONTACT_INTERNAL_FIELDS
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    client = models.ForeignKey(
-        Client,
+    company = models.ForeignKey(
+        Company,
         on_delete=models.CASCADE,
         related_name="contacts",
-        help_text="The client this contact belongs to",
+        help_text="The company this contact belongs to",
     )
     name = models.CharField(max_length=255, help_text="Full name of the contact person")
     email = models.EmailField(
@@ -336,7 +336,7 @@ class ClientContact(models.Model):
     )
     is_primary = models.BooleanField(
         default=False,
-        help_text="Indicates if this is the primary contact for the client",
+        help_text="Indicates if this is the primary contact for the company",
     )
     notes = models.TextField(
         null=True, blank=True, help_text="Additional notes about this contact"
@@ -354,13 +354,13 @@ class Meta:
         verbose_name_plural = "Client Contacts"
         constraints = [
             models.UniqueConstraint(
-                fields=["client", "name"],
-                name="unique_client_contact_name",
+                fields=["company", "name"],
+                name="unique_company_contact_name",
             ),
         ]
 
     def __str__(self):
-        return f"{self.name} ({self.client.name})"
+        return f"{self.name} ({self.company.name})"
 
     def save(
         self,
@@ -373,9 +373,9 @@ def save(
         update_fields = _augment_update_fields(update_fields, "updated_at")
 
         # If this contact is being set as primary, ensure no other contacts
-        # for this client are marked as primary
+        # for this company are marked as primary
         if self.is_primary:
-            ClientContact.objects.filter(client=self.client, is_primary=True).exclude(
+            ClientContact.objects.filter(company=self.company, is_primary=True).exclude(
                 id=self.id
             ).update(is_primary=False)
         super().save(
@@ -387,10 +387,10 @@ def save(
 
 
 class PhoneAssignmentConflictError(Exception):
-    """A phone number cannot be assigned to the proposed client/contact owner.
+    """A phone number cannot be assigned to the proposed company/contact owner.
 
     ``conflict`` is the existing :class:`ClientContactMethod` owned by a
-    different effective client, or ``None`` when the number is an active
+    different effective company, or ``None`` when the number is an active
     internal :class:`~apps.crm.models.PhoneEndpoint`.
     """
 
@@ -404,7 +404,7 @@ def __init__(self, conflict: "ClientContactMethod | None") -> None:
 
 
 class ClientContactMethod(models.Model):
-    """Phone or email address owned by a client or one of its contacts."""
+    """Phone or email address owned by a company or one of its contacts."""
 
     class MethodType(models.TextChoices):
         PHONE = "phone", "Phone"
@@ -415,8 +415,8 @@ class Source(models.TextChoices):
         LOCAL = "local", "Local"
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    client = models.ForeignKey(
-        Client,
+    company = models.ForeignKey(
+        Company,
         on_delete=models.CASCADE,
         null=True,
         blank=True,
@@ -449,34 +449,34 @@ class Meta:
         constraints = [
             models.CheckConstraint(
                 condition=(
-                    models.Q(client__isnull=False, contact__isnull=True)
-                    | models.Q(client__isnull=True, contact__isnull=False)
+                    models.Q(company__isnull=False, contact__isnull=True)
+                    | models.Q(company__isnull=True, contact__isnull=False)
                 ),
-                name="client_contact_method_one_owner",
+                name="contact_method_one_owner",
             ),
             models.UniqueConstraint(
-                fields=["client", "method_type", "normalized_value"],
-                condition=models.Q(client__isnull=False, contact__isnull=True),
-                name="unique_client_contact_method_value",
+                fields=["company", "method_type", "normalized_value"],
+                condition=models.Q(company__isnull=False, contact__isnull=True),
+                name="unique_company_contact_method_value",
             ),
             models.UniqueConstraint(
                 fields=["contact", "method_type", "normalized_value"],
-                condition=models.Q(client__isnull=True, contact__isnull=False),
+                condition=models.Q(company__isnull=True, contact__isnull=False),
                 name="unique_contact_contact_method_value",
             ),
             models.UniqueConstraint(
-                fields=["client", "method_type"],
+                fields=["company", "method_type"],
                 condition=models.Q(
-                    client__isnull=False,
+                    company__isnull=False,
                     contact__isnull=True,
                     is_primary=True,
                 ),
-                name="unique_client_primary_contact_method",
+                name="unique_company_primary_contact_method",
             ),
             models.UniqueConstraint(
                 fields=["contact", "method_type"],
                 condition=models.Q(
-                    client__isnull=True,
+                    company__isnull=True,
                     contact__isnull=False,
                     is_primary=True,
                 ),
@@ -485,7 +485,7 @@ class Meta:
         ]
 
     def __str__(self) -> str:
-        owner = self.contact or self.client
+        owner = self.contact or self.company
         return f"{self.method_type}: {self.value} ({owner})"
 
     def save(
@@ -509,7 +509,7 @@ def save(
             try:
                 type(self).check_phone_assignment(
                     self.normalized_value,
-                    client_id=self.client_id,
+                    company_id=self.company_id,
                     contact=self.contact,
                     instance=self,
                     using=db,
@@ -518,7 +518,7 @@ def save(
                 if exc.conflict is None:
                     raise ValidationError(
                         "internal phone endpoint cannot be saved as a "
-                        "client contact method"
+                        "company contact method"
                     ) from exc
                 raise ValidationError(
                     "phone number already belongs to "
@@ -538,7 +538,7 @@ def save(
                 queryset = queryset.filter(contact_id=self.contact_id)
             else:
                 queryset = queryset.filter(
-                    client_id=self.client_id, contact__isnull=True
+                    company_id=self.company_id, contact__isnull=True
                 )
             queryset.update(is_primary=False)
 
@@ -568,31 +568,31 @@ def normalize_phone(value: str | None) -> str:
             return f"+64{digits[1:]}"
         return f"+{digits}"
 
-    def owner_client_id(self) -> uuid.UUID | None:
-        """The effective client that owns this method (directly or via its contact)."""
-        if self.client_id:
-            return self.client_id
+    def owner_company_id(self) -> uuid.UUID | None:
+        """The effective company that owns this method (directly or via its contact)."""
+        if self.company_id:
+            return self.company_id
         if self.contact is not None:
-            return self.contact.client_id
+            return self.contact.company_id
         return None
 
     @classmethod
-    def conflicting_client(
+    def conflicting_company(
         cls,
         normalized_value: str,
-        effective_client_id: uuid.UUID | None,
+        effective_company_id: uuid.UUID | None,
         exclude_id: uuid.UUID | None = None,
         using: str = DEFAULT_DB_ALIAS,
     ) -> "ClientContactMethod | None":
-        """A phone method for this number owned by a *different* effective client.
+        """A phone method for this number owned by a *different* effective company.
 
-        The single source of truth for the "one number, one client" rule, shared by
+        The single source of truth for the "one number, one company" rule, shared by
         the save() guard, the serializer, assign_phone_number, and the Data Quality
         report. Phones only; emails are unaffected.
         """
         queryset = (
             cls.objects.using(using)
-            .select_related("client", "contact")
+            .select_related("company", "contact")
             .filter(
                 method_type=cls.MethodType.PHONE,
                 normalized_value=normalized_value,
@@ -604,7 +604,7 @@ def conflicting_client(
             (
                 other
                 for other in queryset
-                if other.owner_client_id() != effective_client_id
+                if other.owner_company_id() != effective_company_id
             ),
             None,
         )
@@ -614,23 +614,23 @@ def check_phone_assignment(
         cls,
         normalized_value: str,
         *,
-        client_id: uuid.UUID | None,
+        company_id: uuid.UUID | None,
         contact: "ClientContact | None",
         instance: "ClientContactMethod | None" = None,
         using: str = DEFAULT_DB_ALIAS,
     ) -> None:
-        """Enforce the one-number-one-client rule for a proposed phone owner.
+        """Enforce the one-number-one-company rule for a proposed phone owner.
 
         Shared by :meth:`save` and the API serializer so both surfaces apply
         identical semantics:
 
         - Grandfathering: when ``instance`` is an existing row whose stored
           number and owner match the proposal, no check runs, so legacy
-          cross-client numbers can be re-saved (label/primary edits, re-sync)
+          cross-company numbers can be re-saved (label/primary edits, re-sync)
           without raising.
         - An active internal :class:`~apps.crm.models.PhoneEndpoint` can never
-          be a client number.
-        - A number owned by a different effective client is rejected.
+          be a company number.
+        - A number owned by a different effective company is rejected.
 
         Raises:
             PhoneAssignmentConflictError: carrying the conflicting method, or
@@ -641,13 +641,13 @@ def check_phone_assignment(
             stored = (
                 cls.objects.using(using)
                 .filter(pk=instance.pk)
-                .values("normalized_value", "client_id", "contact_id")
+                .values("normalized_value", "company_id", "contact_id")
                 .first()
             )
             if (
                 stored is not None
                 and stored["normalized_value"] == normalized_value
-                and stored["client_id"] == client_id
+                and stored["company_id"] == company_id
                 and stored["contact_id"] == contact_id
             ):
                 return  # unchanged association -> grandfathered
@@ -661,15 +661,15 @@ def check_phone_assignment(
         ):
             raise PhoneAssignmentConflictError(None)
 
-        if client_id is not None:
-            effective_client_id = client_id
+        if company_id is not None:
+            effective_company_id = company_id
         elif contact is not None:
-            effective_client_id = contact.client_id
+            effective_company_id = contact.company_id
         else:
-            effective_client_id = None
-        conflict = cls.conflicting_client(
+            effective_company_id = None
+        conflict = cls.conflicting_company(
             normalized_value,
-            effective_client_id,
+            effective_company_id,
             exclude_id=instance.pk if instance is not None else None,
             using=using,
         )
@@ -678,28 +678,27 @@ def check_phone_assignment(
 
     def owner_display_name(self) -> str:
         if self.contact:
-            return f"contact {self.contact.name} at {self.contact.client.name}"
-        if self.client:
-            return f"client {self.client.name}"
+            return f"contact {self.contact.name} at {self.contact.company.name}"
+        if self.company:
+            return f"company {self.company.name}"
         return "another CRM owner"
 
 
-class Supplier(Client):
+class Supplier(Company):
     """
-    A Supplier is simply a Client with additional semantics.
+    A Supplier is simply a Company with additional semantics.
     """
 
     class Meta:
         proxy = True
-        db_table = "client_client"
 
 
 class SupplierSearchAlias(models.Model):
-    """Editable search alias attached to a client/supplier contact."""
+    """Editable search alias attached to a company/supplier contact."""
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    client = models.ForeignKey(
-        Client,
+    company = models.ForeignKey(
+        Company,
         on_delete=models.CASCADE,
         related_name="supplier_search_aliases",
     )
@@ -712,20 +711,20 @@ class Meta:
         ordering = ["alias"]
         constraints = [
             models.UniqueConstraint(
-                fields=["client", "alias"],
-                name="unique_supplier_search_alias_per_client",
+                fields=["company", "alias"],
+                name="unique_supplier_search_alias_per_company",
             ),
         ]
 
     def __str__(self):
-        return f"{self.alias} ({self.client.name})"
+        return f"{self.alias} ({self.company.name})"
 
 
 class SupplierPickupAddress(models.Model):
     """
-    Represents a pickup/delivery address for a supplier or client.
+    Represents a pickup/delivery address for a supplier or company.
 
-    Despite the name, this model can be used for any Client - not just those
+    Despite the name, this model can be used for any Company - not just those
     marked as suppliers. Suppliers can have multiple pickup addresses, with
     one marked as primary. Useful for tracking warehouse locations, branch
     offices, or delivery points.
@@ -733,9 +732,9 @@ class SupplierPickupAddress(models.Model):
 
     # CHECKLIST - when adding a new field or property to SupplierPickupAddress, check:
     #   1. SUPPLIERPICKUPADDRESS_API_FIELDS below (if it's a model field)
-    #   2. SupplierPickupAddressSerializer in apps/client/serializers.py
+    #   2. SupplierPickupAddressSerializer in apps/company/serializers.py
     #   3. SupplierPickupAddressSerializer.to_internal_value() nullable_fields list
-    #   4. SupplierPickupAddressViewSet in apps/client/views/supplier_pickup_address_viewset.py
+    #   4. SupplierPickupAddressViewSet in apps/company/views/supplier_pickup_address_viewset.py
     #   5. PurchaseOrder.pickup_address FK in apps/purchasing/models.py
     #   6. PurchaseOrderDetailSerializer in apps/purchasing/serializers.py
     #   7. PurchaseOrderPDFGenerator in apps/purchasing/services/purchase_order_pdf_service.py
@@ -743,7 +742,7 @@ class SupplierPickupAddress(models.Model):
     # Database fields exposed via API serializers
     SUPPLIERPICKUPADDRESS_API_FIELDS = [
         "id",
-        "client",
+        "company",
         "name",
         "street",
         "suburb",
@@ -770,8 +769,8 @@ class SupplierPickupAddress(models.Model):
     )
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
-    client = models.ForeignKey(
-        Client,
+    company = models.ForeignKey(
+        Company,
         on_delete=models.CASCADE,
         related_name="pickup_addresses",
         help_text="The supplier this pickup address belongs to",
@@ -852,13 +851,13 @@ class Meta:
         verbose_name_plural = "Supplier Pickup Addresses"
         constraints = [
             models.UniqueConstraint(
-                fields=["client", "name"],
+                fields=["company", "name"],
                 name="unique_supplier_pickup_address_name",
             ),
         ]
 
     def __str__(self):
-        return f"{self.name} - {self.city} ({self.client.name})"
+        return f"{self.name} - {self.city} ({self.company.name})"
 
     @property
     def formatted_address(self) -> str:
@@ -877,13 +876,9 @@ def formatted_address(self) -> str:
 
     def save(self, *args, **kwargs):
         # If this address is being set as primary, ensure no other addresses
-        # for this client are marked as primary
+        # for this company are marked as primary
         if self.is_primary:
             SupplierPickupAddress.objects.filter(
-                client=self.client, is_primary=True
+                company=self.company, is_primary=True
             ).exclude(id=self.id).update(is_primary=False)
         super().save(*args, **kwargs)
-
-
-# Alias for SupplierPickupAddress - can be used for any client, not just suppliers
-ClientDeliveryAddress = SupplierPickupAddress
diff --git a/apps/client/serializers.py b/apps/company/serializers.py
similarity index 74%
rename from apps/client/serializers.py
rename to apps/company/serializers.py
index 4f71f7310..d1de36d92 100644
--- a/apps/client/serializers.py
+++ b/apps/company/serializers.py
@@ -1,9 +1,9 @@
 from rest_framework import serializers
 
-from apps.client.models import (
-    Client,
+from apps.company.models import (
     ClientContact,
     ClientContactMethod,
+    Company,
     PhoneAssignmentConflictError,
     SupplierPickupAddress,
     SupplierSearchAlias,
@@ -31,19 +31,19 @@ def to_internal_value(self, data):
 
 
 class ClientContactMethodSerializer(serializers.ModelSerializer):
-    """Serializer for canonical client/contact phone and email methods."""
+    """Serializer for canonical company/contact phone and email methods."""
 
-    owner_client = serializers.SerializerMethodField()
-    client_name = serializers.SerializerMethodField()
+    owner_company = serializers.SerializerMethodField()
+    company_name = serializers.SerializerMethodField()
     contact_name = serializers.SerializerMethodField()
 
     class Meta:
         model = ClientContactMethod
         fields = [
             "id",
-            "client",
-            "owner_client",
-            "client_name",
+            "company",
+            "owner_company",
+            "company_name",
             "contact",
             "contact_name",
             "method_type",
@@ -57,33 +57,33 @@ class Meta:
         ]
         read_only_fields = [
             "id",
-            "owner_client",
-            "client_name",
+            "owner_company",
+            "company_name",
             "contact_name",
             "normalized_value",
             "created_at",
             "updated_at",
         ]
 
-    def get_owner_client(self, obj: ClientContactMethod) -> str:
-        if obj.client_id:
-            return str(obj.client_id)
-        return str(obj.contact.client_id) if obj.contact else ""
+    def get_owner_company(self, obj: ClientContactMethod) -> str:
+        if obj.company_id:
+            return str(obj.company_id)
+        return str(obj.contact.company_id) if obj.contact else ""
 
-    def get_client_name(self, obj: ClientContactMethod) -> str:
-        if obj.client:
-            return obj.client.name
-        return obj.contact.client.name if obj.contact else ""
+    def get_company_name(self, obj: ClientContactMethod) -> str:
+        if obj.company:
+            return obj.company.name
+        return obj.contact.company.name if obj.contact else ""
 
     def get_contact_name(self, obj: ClientContactMethod) -> str:
         return obj.contact.name if obj.contact else ""
 
     def validate(self, attrs):
-        client = attrs.get("client", getattr(self.instance, "client", None))
+        company = attrs.get("company", getattr(self.instance, "company", None))
         contact = attrs.get("contact", getattr(self.instance, "contact", None))
-        if bool(client) == bool(contact):
+        if bool(company) == bool(contact):
             raise serializers.ValidationError(
-                "Exactly one of client or contact is required"
+                "Exactly one of company or contact is required"
             )
         method_type = attrs.get(
             "method_type", getattr(self.instance, "method_type", None)
@@ -94,7 +94,7 @@ def validate(self, attrs):
             try:
                 ClientContactMethod.check_phone_assignment(
                     normalized,
-                    client_id=client.id if client else None,
+                    company_id=company.id if company else None,
                     contact=contact,
                     instance=self.instance,
                 )
@@ -103,7 +103,7 @@ def validate(self, attrs):
                     raise serializers.ValidationError(
                         {
                             "value": "Internal phone endpoint cannot be assigned "
-                            "to a client."
+                            "to a company."
                         }
                     ) from exc
                 raise serializers.ValidationError(
@@ -154,16 +154,16 @@ def to_internal_value(self, data):
         return super().to_internal_value(data)
 
 
-class ClientSerializer(serializers.ModelSerializer):
+class CompanySerializer(serializers.ModelSerializer):
     contacts = ClientContactSerializer(many=True, read_only=True)
 
     class Meta:
-        model = Client
+        model = Company
         fields = (
             ["id"]
-            + Client.CLIENT_DIRECT_FIELDS
+            + Company.COMPANY_DIRECT_FIELDS
             + [
-                # Excluded from CLIENT_DIRECT_FIELDS:
+                # Excluded from COMPANY_DIRECT_FIELDS:
                 "raw_json",  # debugging blob, not business data
                 "django_created_at",  # auto timestamp
                 "django_updated_at",  # auto timestamp
@@ -173,9 +173,9 @@ class Meta:
         )
 
 
-class ClientNameOnlySerializer(serializers.ModelSerializer):
+class CompanyNameOnlySerializer(serializers.ModelSerializer):
     class Meta:
-        model = Client
+        model = Company
         fields = ["id", "name"]
         read_only_fields = ["id", "name"]
 
@@ -187,15 +187,15 @@ class StandardErrorSerializer(serializers.Serializer):
     details = serializers.JSONField(required=False)
 
 
-class ClientListResponseSerializer(serializers.Serializer):
-    """Serializer for client list response"""
+class CompanyListResponseSerializer(serializers.Serializer):
+    """Serializer for company list response"""
 
     id = serializers.CharField()
     name = serializers.CharField()
 
 
-class ClientSearchResultSerializer(serializers.Serializer):
-    """Serializer for individual client search result"""
+class CompanySearchResultSerializer(serializers.Serializer):
+    """Serializer for individual company search result"""
 
     id = serializers.CharField()
     name = serializers.CharField()
@@ -209,10 +209,10 @@ class ClientSearchResultSerializer(serializers.Serializer):
     total_spend = serializers.CharField()
 
 
-class ClientSearchResponseSerializer(serializers.Serializer):
-    """Serializer for paginated client search response"""
+class CompanySearchResponseSerializer(serializers.Serializer):
+    """Serializer for paginated company search response"""
 
-    results = ClientSearchResultSerializer(many=True)
+    results = CompanySearchResultSerializer(many=True)
     count = serializers.IntegerField()
     page = serializers.IntegerField()
     page_size = serializers.IntegerField()
@@ -220,12 +220,12 @@ class ClientSearchResponseSerializer(serializers.Serializer):
 
 
 class SupplierSearchAliasSerializer(serializers.ModelSerializer):
-    """Supplier search alias attached to a client/contact."""
+    """Supplier search alias attached to a company/contact."""
 
     class Meta:
         model = SupplierSearchAlias
-        fields = ["id", "client", "alias", "is_active", "created_at", "updated_at"]
-        read_only_fields = ["id", "client", "is_active", "created_at", "updated_at"]
+        fields = ["id", "company", "alias", "is_active", "created_at", "updated_at"]
+        read_only_fields = ["id", "company", "is_active", "created_at", "updated_at"]
 
 
 class SupplierSearchAliasCreateSerializer(serializers.Serializer):
@@ -240,8 +240,8 @@ def validate_alias(self, value: str) -> str:
         return alias
 
 
-class ClientCreateSerializer(serializers.Serializer):
-    """Serializer for client creation request"""
+class CompanyCreateSerializer(serializers.Serializer):
+    """Serializer for company creation request"""
 
     name = serializers.CharField(max_length=255)
     email = serializers.EmailField(required=False, allow_blank=True, allow_null=True)
@@ -250,32 +250,32 @@ class ClientCreateSerializer(serializers.Serializer):
     allow_jobs = serializers.BooleanField(default=True)
 
 
-class ClientCreateResponseSerializer(serializers.Serializer):
-    """Serializer for client creation response"""
+class CompanyCreateResponseSerializer(serializers.Serializer):
+    """Serializer for company creation response"""
 
     success = serializers.BooleanField()
-    client = ClientSearchResultSerializer()
+    company = CompanySearchResultSerializer()
     message = serializers.CharField()
 
 
-class ClientErrorResponseSerializer(serializers.Serializer):
-    """Serializer for client error responses"""
+class CompanyErrorResponseSerializer(serializers.Serializer):
+    """Serializer for company error responses"""
 
     success = serializers.BooleanField(default=False)
     error = serializers.CharField()
     details = serializers.CharField(required=False)
 
 
-class ClientDuplicateErrorResponseSerializer(serializers.Serializer):
-    """Serializer for client duplicate error response"""
+class CompanyDuplicateErrorResponseSerializer(serializers.Serializer):
+    """Serializer for company duplicate error response"""
 
     success = serializers.BooleanField(default=False)
     error = serializers.CharField()
-    existing_client = serializers.DictField()
+    existing_company = serializers.DictField()
 
 
-class ClientDetailResponseSerializer(serializers.Serializer):
-    """Serializer for client detail response"""
+class CompanyDetailResponseSerializer(serializers.Serializer):
+    """Serializer for company detail response"""
 
     id = serializers.CharField()
     name = serializers.CharField()
@@ -300,8 +300,8 @@ class ClientDetailResponseSerializer(serializers.Serializer):
     total_spend = serializers.CharField()
 
 
-class ClientUpdateSerializer(serializers.Serializer):
-    """Serializer for client update request"""
+class CompanyUpdateSerializer(serializers.Serializer):
+    """Serializer for company update request"""
 
     name = serializers.CharField(max_length=255, required=False)
     email = serializers.EmailField(required=False, allow_blank=True)
@@ -310,11 +310,11 @@ class ClientUpdateSerializer(serializers.Serializer):
     allow_jobs = serializers.BooleanField(required=False)
 
 
-class ClientUpdateResponseSerializer(serializers.Serializer):
-    """Serializer for client update response"""
+class CompanyUpdateResponseSerializer(serializers.Serializer):
+    """Serializer for company update response"""
 
     success = serializers.BooleanField()
-    client = ClientDetailResponseSerializer()
+    company = CompanyDetailResponseSerializer()
     message = serializers.CharField()
 
 
@@ -333,13 +333,13 @@ class JobContactUpdateSerializer(JobContactResponseSerializer):
     """Serializer for job contact update request"""
 
 
-class ClientJobHeaderSerializer(serializers.Serializer):
-    """Serializer for job header in client jobs list."""
+class CompanyJobHeaderSerializer(serializers.Serializer):
+    """Serializer for job header in company jobs list."""
 
     job_id = serializers.UUIDField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client = serializers.DictField(allow_null=True)
+    company = serializers.DictField(allow_null=True)
     status = serializers.CharField()
     pricing_methodology = serializers.CharField(allow_null=True)
     speed_quality_tradeoff = serializers.CharField()
@@ -353,7 +353,7 @@ class ClientJobHeaderSerializer(serializers.Serializer):
     max_people = serializers.IntegerField()
 
 
-class ClientJobsResponseSerializer(serializers.Serializer):
-    """Serializer for client jobs list response"""
+class CompanyJobsResponseSerializer(serializers.Serializer):
+    """Serializer for company jobs list response"""
 
-    results = ClientJobHeaderSerializer(many=True)
+    results = CompanyJobHeaderSerializer(many=True)
diff --git a/apps/client/services/__init__.py b/apps/company/services/__init__.py
similarity index 83%
rename from apps/client/services/__init__.py
rename to apps/company/services/__init__.py
index 71d83f928..27b868e89 100644
--- a/apps/client/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -5,8 +5,8 @@
     from django.apps import apps
 
     if apps.ready:
-        from .client_merge_service import reassign_client_fk_records
-        from .client_rest_service import ClientRestService
+        from .company_merge_service import reassign_company_fk_records
+        from .company_rest_service import CompanyRestService
         from .duplicate_phone_report import (
             DuplicatePhoneIssue,
             DuplicatePhoneOwner,
@@ -26,7 +26,7 @@
     pass
 
 __all__ = [
-    "ClientRestService",
+    "CompanyRestService",
     "DuplicatePhoneIssue",
     "DuplicatePhoneOwner",
     "DuplicatePhoneReportService",
@@ -37,5 +37,5 @@
     "GeocodingResult",
     "geocode_address",
     "get_api_key",
-    "reassign_client_fk_records",
+    "reassign_company_fk_records",
 ]
diff --git a/apps/client/services/client_merge_service.py b/apps/company/services/company_merge_service.py
similarity index 69%
rename from apps/client/services/client_merge_service.py
rename to apps/company/services/company_merge_service.py
index c98d782ed..bff80d6ca 100644
--- a/apps/client/services/client_merge_service.py
+++ b/apps/company/services/company_merge_service.py
@@ -1,15 +1,15 @@
 """
-Reassign FK records from one Client (source) to another (destination).
+Reassign FK records from one Company (source) to another (destination).
 
-The Client.merged_into pointer alone leaves historical records stranded on
-the merged-from row — queries filtered by the merged-into client miss the
-absorbed history. This service moves the 8 client-referencing FK fields in
+The Company.merged_into pointer alone leaves historical records stranded on
+the merged-from row — queries filtered by the merged-into company miss the
+absorbed history. This service moves the 8 company-referencing FK fields in
 a single atomic block.
 
 Callers pick the destination explicitly:
-- Xero sync paths typically pass ``source.get_final_client()`` so absorbed
-  history lands on the terminal client in a merge chain (A -> B -> C).
-- The local dedup command passes a hand-picked primary client.
+- Xero sync paths typically pass ``source.get_final_company()`` so absorbed
+  history lands on the terminal company in a merge chain (A -> B -> C).
+- The local dedup command passes a hand-picked primary company.
 """
 
 import logging
@@ -17,7 +17,7 @@
 from django.db import transaction
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.workflow.services.error_persistence import persist_app_error
 
 logger = logging.getLogger("xero")
@@ -26,17 +26,17 @@
 def _move_contact_methods(
     *,
     source_contact: ClientContact | None,
-    source_client: Client | None,
+    source_company: Company | None,
     destination_contact: ClientContact | None,
-    destination_client: Client | None,
+    destination_company: Company | None,
 ) -> int:
     if source_contact is None:
         source_queryset = ClientContactMethod.objects.filter(
-            client=source_client,
+            company=source_company,
             contact__isnull=True,
         )
         destination_queryset = ClientContactMethod.objects.filter(
-            client=destination_client,
+            company=destination_company,
             contact__isnull=True,
         )
     else:
@@ -77,30 +77,30 @@ def _move_contact_methods(
         ).update(is_primary=False)
 
     # queryset.update() bypasses ClientContactMethod.save()'s
-    # one-number-one-client guard DELIBERATELY: a merge moves ALL of the
-    # source's methods to the destination, so any cross-client sharing the
-    # guard would flag (e.g. the client-level/contact-level twins migration
+    # one-number-one-company guard DELIBERATELY: a merge moves ALL of the
+    # source's methods to the destination, so any cross-company sharing the
+    # guard would flag (e.g. the company-level/contact-level twins migration
     # 0023 created) already existed before the merge — the move creates no
     # new conflicting ownership.
     if destination_contact is None:
         affected += source_queryset.update(
-            client=destination_client,
+            company=destination_company,
             contact=None,
             updated_at=timezone.now(),
         )
     else:
         affected += source_queryset.update(
-            client=None,
+            company=None,
             contact=destination_contact,
             updated_at=timezone.now(),
         )
     return affected
 
 
-def _move_client_contacts_and_methods(
-    source: Client, destination: Client
+def _move_company_contacts_and_methods(
+    source: Company, destination: Company
 ) -> dict[str, int]:
-    """Move CRM contact ownership before the source client is deleted."""
+    """Move CRM contact ownership before the source company is deleted."""
 
     from apps.crm.models import PhoneCallRecord
 
@@ -112,53 +112,53 @@ def _move_client_contacts_and_methods(
 
     counts["contact_methods"] += _move_contact_methods(
         source_contact=None,
-        source_client=source,
+        source_company=source,
         destination_contact=None,
-        destination_client=destination,
+        destination_company=destination,
     )
 
     destination_contacts_by_name = {
         existing.name: existing
-        for existing in ClientContact.objects.filter(client=destination)
+        for existing in ClientContact.objects.filter(company=destination)
     }
-    for contact in ClientContact.objects.filter(client=source).iterator():
+    for contact in ClientContact.objects.filter(company=source).iterator():
         destination_contact = destination_contacts_by_name.get(contact.name)
         if destination_contact is None:
-            contact.client = destination
-            contact.save(update_fields=["client", "updated_at"])
+            contact.company = destination
+            contact.save(update_fields=["company", "updated_at"])
             destination_contact = contact
         else:
             counts["contact_methods"] += _move_contact_methods(
                 source_contact=contact,
-                source_client=None,
+                source_company=None,
                 destination_contact=destination_contact,
-                destination_client=None,
+                destination_company=None,
             )
             counts["phone_calls"] += PhoneCallRecord.objects.filter(
                 contact=contact
             ).update(
-                client=destination,
+                company=destination,
                 contact=destination_contact,
             )
             contact.delete()
 
         counts["contacts"] += 1
 
-    counts["phone_calls"] += PhoneCallRecord.objects.filter(client=source).update(
-        client=destination
+    counts["phone_calls"] += PhoneCallRecord.objects.filter(company=source).update(
+        company=destination
     )
     return counts
 
 
-def reassign_client_fk_records(
-    source: Client,
-    destination: Client,
+def reassign_company_fk_records(
+    source: Company,
+    destination: Company,
     staff,
     *,
     logger_prefix: str = "",
 ) -> dict[str, int]:
     """
-    Move every client-referencing FK record from ``source`` to ``destination``.
+    Move every company-referencing FK record from ``source`` to ``destination``.
 
     Returns a dict of per-model rowcounts, e.g. ``{"jobs": 3, ...}``.
 
@@ -176,8 +176,8 @@ def reassign_client_fk_records(
     """
     if destination.id == source.id:
         raise ValueError(
-            f"reassign_client_fk_records: source and destination are the "
-            f"same client ({source.id}); refusing to run"
+            f"reassign_company_fk_records: source and destination are the "
+            f"same company ({source.id}); refusing to run"
         )
 
     # Late imports to avoid circular-import at Django app-loading time.
@@ -189,26 +189,28 @@ def reassign_client_fk_records(
     try:
         with transaction.atomic():
             jobs_moved = 0
-            for job in Job.objects.filter(client=source):
-                job.client = destination
-                job.save(staff=staff, update_fields=["client"])
+            for job in Job.objects.filter(company=source):
+                job.company = destination
+                job.save(staff=staff, update_fields=["company"])
                 jobs_moved += 1
 
-            crm_counts = _move_client_contacts_and_methods(source, destination)
+            crm_counts = _move_company_contacts_and_methods(source, destination)
             counts = {
                 "jobs": jobs_moved,
                 "contacts": crm_counts["contacts"],
                 "contact_methods": crm_counts["contact_methods"],
                 "phone_calls": crm_counts["phone_calls"],
-                "invoices": Invoice.objects.filter(client=source).update(
-                    client=destination
+                "invoices": Invoice.objects.filter(company=source).update(
+                    company=destination
                 ),
-                "bills": Bill.objects.filter(client=source).update(client=destination),
-                "credit_notes": CreditNote.objects.filter(client=source).update(
-                    client=destination
+                "bills": Bill.objects.filter(company=source).update(
+                    company=destination
                 ),
-                "quotes": Quote.objects.filter(client=source).update(
-                    client=destination
+                "credit_notes": CreditNote.objects.filter(company=source).update(
+                    company=destination
+                ),
+                "quotes": Quote.objects.filter(company=source).update(
+                    company=destination
                 ),
                 "purchase_orders": PurchaseOrder.objects.filter(supplier=source).update(
                     supplier=destination
@@ -225,7 +227,7 @@ def reassign_client_fk_records(
             }
 
         logger.info(
-            "%sReassigned client %s -> %s: jobs=%d contacts=%d "
+            "%sReassigned company %s -> %s: jobs=%d contacts=%d "
             "contact_methods=%d phone_calls=%d invoices=%d bills=%d "
             "credit_notes=%d quotes=%d purchase_orders=%d supplier_products=%d "
             "supplier_price_lists=%d scrape_jobs=%d",
diff --git a/apps/client/services/client_rest_service.py b/apps/company/services/company_rest_service.py
similarity index 56%
rename from apps/client/services/client_rest_service.py
rename to apps/company/services/company_rest_service.py
index deae39594..3d848dac9 100644
--- a/apps/client/services/client_rest_service.py
+++ b/apps/company/services/company_rest_service.py
@@ -1,8 +1,8 @@
 """
-Client REST Service Layer
+Company REST Service Layer
 
 Following SRP (Single Responsibility Principle) and clean code guidelines.
-All business logic for Client REST operations should be implemented here.
+All business logic for Company REST operations should be implemented here.
 """
 
 import json
@@ -20,9 +20,9 @@
 from django.shortcuts import get_object_or_404
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact
-from apps.client.serializers import ClientCreateSerializer, ClientUpdateSerializer
-from apps.client.utils import date_to_datetime
+from apps.company.models import ClientContact, Company
+from apps.company.serializers import CompanyCreateSerializer, CompanyUpdateSerializer
+from apps.company.utils import date_to_datetime
 from apps.workflow.accounting.registry import get_provider
 from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.error_persistence import (
@@ -31,34 +31,34 @@
 )
 from apps.workflow.services.search_telemetry import SearchTelemetryService
 
-CLIENT_SEARCH_TOKEN_RE = re.compile(r"[a-z0-9]+")
+COMPANY_SEARCH_TOKEN_RE = re.compile(r"[a-z0-9]+")
 
 logger = logging.getLogger(__name__)
-client_search_logger = logging.getLogger("client_search")
+company_search_logger = logging.getLogger("company_search")
 
 
-class ClientRestService:
+class CompanyRestService:
     """
-    Service layer for Client REST operations.
-    Implements all business rules related to Client manipulation via REST API.
+    Service layer for Company REST operations.
+    Implements all business rules related to Company manipulation via REST API.
     """
 
     @staticmethod
-    def get_all_clients() -> List[Dict[str, Any]]:
+    def get_all_companies() -> List[Dict[str, Any]]:
         """
-        Retrieves all clients with basic information for dropdowns.
+        Retrieves all companies with basic information for dropdowns.
 
         Returns:
-            List of client dictionaries with id and name
+            List of company dictionaries with id and name
         """
         try:
-            clients = Client.objects.all().order_by("name")
+            companies = Company.objects.all().order_by("name")
             return [
                 {
-                    "id": str(client.id),
-                    "name": client.name,
+                    "id": str(company.id),
+                    "name": company.name,
                 }
-                for client in clients
+                for company in companies
             ]
         except AlreadyLoggedException:
             raise
@@ -66,16 +66,16 @@ def get_all_clients() -> List[Dict[str, Any]]:
             persist_and_raise(exc)
 
     @staticmethod
-    def search_clients(query: str, limit: int = 10) -> List[Dict[str, Any]]:
+    def search_companies(query: str, limit: int = 10) -> List[Dict[str, Any]]:
         """
-        Searches clients by name with enhanced data.
+        Searches companies by name with enhanced data.
 
         Args:
             query: Search query (minimum 3 characters)
             limit: Maximum results to return (capped at 50)
 
         Returns:
-            List of client dictionaries with detailed information
+            List of company dictionaries with detailed information
 
         Raises:
             ValueError: If query is too short
@@ -90,8 +90,8 @@ def search_clients(query: str, limit: int = 10) -> List[Dict[str, Any]]:
             limit = max(1, min(limit, 50))
 
             # Execute optimized search
-            clients = ClientRestService._execute_client_search(query, limit)
-            return ClientRestService._format_client_search_results(clients)
+            companies = CompanyRestService._execute_company_search(query, limit)
+            return CompanyRestService._format_company_search_results(companies)
 
         except AlreadyLoggedException:
             raise
@@ -99,7 +99,7 @@ def search_clients(query: str, limit: int = 10) -> List[Dict[str, Any]]:
             persist_and_raise(exc, additional_context={"query": query, "limit": limit})
 
     @staticmethod
-    def list_clients(
+    def list_companies(
         query: str | None = None,
         page: int = 1,
         page_size: int = 50,
@@ -107,7 +107,7 @@ def list_clients(
         sort_dir: str = "asc",
     ) -> Dict[str, Any]:
         """
-        Lists clients with pagination, sorting, and optional search.
+        Lists companies with pagination, sorting, and optional search.
 
         Args:
             query: Optional search query (min 3 chars for filtering)
@@ -135,17 +135,17 @@ def list_clients(
                 sort_field = f"-{sort_field}"
 
             # Annotate computed fields for sorting capability
-            queryset = Client.objects.with_invoice_summary().defer("raw_json")
+            queryset = Company.objects.with_invoice_summary().defer("raw_json")
 
             # Apply search filter if query provided
             if query:
-                ranked_ids = ClientRestService._rank_matching_client_ids(
-                    Client.objects.all(), query
+                ranked_ids = CompanyRestService._rank_matching_company_ids(
+                    Company.objects.all(), query
                 )
                 total_count = len(ranked_ids)
                 offset = (page - 1) * page_size
                 page_ids = ranked_ids[offset : offset + page_size]
-                clients = ClientRestService._hydrate_client_search_results(page_ids)
+                companies = CompanyRestService._hydrate_company_search_results(page_ids)
             else:
                 ordering = (sort_field,)
                 # Get total count before pagination
@@ -153,13 +153,13 @@ def list_clients(
 
                 # Apply sorting and pagination
                 offset = (page - 1) * page_size
-                clients = queryset.order_by(*ordering)[offset : offset + page_size]
+                companies = queryset.order_by(*ordering)[offset : offset + page_size]
 
             # Calculate total pages
             total_pages = (total_count + page_size - 1) // page_size
 
             return {
-                "results": ClientRestService._format_client_search_results(clients),
+                "results": CompanyRestService._format_company_search_results(companies),
                 "count": total_count,
                 "page": page,
                 "page_size": page_size,
@@ -179,52 +179,52 @@ def list_clients(
             )
 
     @staticmethod
-    def get_client_by_id(client_id: UUID) -> Dict[str, Any]:
+    def get_company_by_id(company_id: UUID) -> Dict[str, Any]:
         """
-        Retrieves a specific client by ID with full details.
+        Retrieves a specific company by ID with full details.
 
         Args:
-            client_id: Client UUID
+            company_id: Company UUID
 
         Returns:
-            Dict with complete client information
+            Dict with complete company information
 
         Raises:
-            ValueError: If client not found
+            ValueError: If company not found
         """
         try:
-            client = Client.objects.with_invoice_summary().get(id=client_id)
-            return ClientRestService._format_client_detail(client)
-        except Client.DoesNotExist:
-            raise ValueError(f"Client with id {client_id} not found")
+            company = Company.objects.with_invoice_summary().get(id=company_id)
+            return CompanyRestService._format_company_detail(company)
+        except Company.DoesNotExist:
+            raise ValueError(f"Company with id {company_id} not found")
         except AlreadyLoggedException:
             raise
         except Exception as exc:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "get_client_by_id",
-                    "client_id": str(client_id),
+                    "operation": "get_company_by_id",
+                    "company_id": str(company_id),
                 },
             )
 
     @staticmethod
-    def create_client(data: Dict[str, Any]) -> Client:
+    def create_company(data: Dict[str, Any]) -> Company:
         """
-        Creates a new client locally and in the accounting provider.
+        Creates a new company locally and in the accounting provider.
 
         Args:
-            data: Client creation data
+            data: Company creation data
 
         Returns:
-            Created Client instance
+            Created Company instance
 
         Raises:
             ValueError: If validation fails or accounting provider sync fails
         """
         try:
             # Validate using DRF serializer
-            serializer = ClientCreateSerializer(data=data)
+            serializer = CompanyCreateSerializer(data=data)
             if not serializer.is_valid():
                 error_messages = []
                 for field, errors in serializer.errors.items():
@@ -238,8 +238,10 @@ def create_client(data: Dict[str, Any]) -> Client:
                 raise ValueError("Accounting provider authentication required")
 
             # Create in Xero first
-            client = ClientRestService._create_client_in_xero(serializer.validated_data)
-            return client
+            company = CompanyRestService._create_company_in_xero(
+                serializer.validated_data
+            )
+            return company
 
         except AlreadyLoggedException:
             raise
@@ -247,35 +249,35 @@ def create_client(data: Dict[str, Any]) -> Client:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "create_client",
+                    "operation": "create_company",
                     "payload_keys": list(data.keys()),
                 },
             )
 
     @staticmethod
-    def update_client(client_id: UUID, data: Dict[str, Any]) -> Client:
+    def update_company(company_id: UUID, data: Dict[str, Any]) -> Company:
         """
-        Updates an existing client.
-        If client is synced with Xero, updates Xero first then syncs locally.
+        Updates an existing company.
+        If company is synced with Xero, updates Xero first then syncs locally.
 
         Args:
-            client_id: Client UUID
-            data: Updated client data
+            company_id: Company UUID
+            data: Updated company data
 
         Returns:
-            Updated Client instance
+            Updated Company instance
 
         Raises:
-            ValueError: If client not found or validation fails
+            ValueError: If company not found or validation fails
         """
         try:
-            client = get_object_or_404(Client, id=client_id)
+            company = get_object_or_404(Company, id=company_id)
 
             # Store xero_contact_id before validation
-            original_xero_contact_id = client.xero_contact_id
+            original_xero_contact_id = company.xero_contact_id
 
             # Validate using DRF serializer
-            serializer = ClientUpdateSerializer(data=data)
+            serializer = CompanyUpdateSerializer(data=data)
             if not serializer.is_valid():
                 error_messages = []
                 for field, errors in serializer.errors.items():
@@ -285,51 +287,53 @@ def update_client(client_id: UUID, data: Dict[str, Any]) -> Client:
             validated_data = serializer.validated_data
 
             # Guard clause - validate required fields
-            if not validated_data.get("name") and not client.name:
-                raise ValueError("Client name is required")
+            if not validated_data.get("name") and not company.name:
+                raise ValueError("Company name is required")
 
-            # DEBUG: Log client state after validation
+            # DEBUG: Log company state after validation
             logger.info(
-                f"Client data after validation: xero_contact_id={original_xero_contact_id}",
+                f"Company data after validation: xero_contact_id={original_xero_contact_id}",
                 extra={
-                    "client_id": str(client.id),
+                    "company_id": str(company.id),
                     "original_xero_contact_id": original_xero_contact_id,
-                    "operation": "update_client_debug_after_validation",
+                    "operation": "update_company_debug_after_validation",
                 },
             )
 
-            # Check if client is synced with Xero
+            # Check if company is synced with Xero
             if original_xero_contact_id:
                 # Update in Xero first, then sync locally
-                updated_client = ClientRestService._update_client_in_xero(client, data)
+                updated_company = CompanyRestService._update_company_in_xero(
+                    company, data
+                )
                 logger.info(
-                    f"Client {updated_client.id} updated in Xero and synced locally",
+                    f"Company {updated_company.id} updated in Xero and synced locally",
                     extra={
-                        "client_id": str(updated_client.id),
-                        "client_name": updated_client.name,
-                        "xero_contact_id": updated_client.xero_contact_id,
-                        "operation": "update_client_xero_sync",
+                        "company_id": str(updated_company.id),
+                        "company_name": updated_company.name,
+                        "xero_contact_id": updated_company.xero_contact_id,
+                        "operation": "update_company_xero_sync",
                     },
                 )
-                return updated_client
+                return updated_company
             else:
-                # Local-only update for clients not synced with Xero
+                # Local-only update for companies not synced with Xero
                 with transaction.atomic():
                     for field, value in validated_data.items():
-                        setattr(client, field, value)
-                    client.xero_last_modified = timezone.now()
-                    client.save()
+                        setattr(company, field, value)
+                    company.xero_last_modified = timezone.now()
+                    company.save()
 
                     logger.info(
-                        f"Client {client.id} updated locally (no Xero sync)",
+                        f"Company {company.id} updated locally (no Xero sync)",
                         extra={
-                            "client_id": str(client.id),
-                            "client_name": client.name,
-                            "operation": "update_client_local_only",
+                            "company_id": str(company.id),
+                            "company_name": company.name,
+                            "operation": "update_company_local_only",
                         },
                     )
 
-                return client
+                return company
 
         except AlreadyLoggedException:
             raise
@@ -337,29 +341,29 @@ def update_client(client_id: UUID, data: Dict[str, Any]) -> Client:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "update_client",
-                    "client_id": str(client_id),
+                    "operation": "update_company",
+                    "company_id": str(company_id),
                     "payload_keys": list(data.keys()),
                 },
             )
 
     @staticmethod
-    def get_client_contacts(client_id: UUID) -> List[Dict[str, Any]]:
+    def get_company_contacts(company_id: UUID) -> List[Dict[str, Any]]:
         """
-        Retrieves all contacts for a specific client.
+        Retrieves all contacts for a specific company.
 
         Args:
-            client_id: Client UUID
+            company_id: Company UUID
 
         Returns:
             List of contact dictionaries
 
         Raises:
-            ValueError: If client not found
+            ValueError: If company not found
         """
         try:
-            client = get_object_or_404(Client, id=client_id)
-            contacts = client.contacts.all().order_by("name")
+            company = get_object_or_404(Company, id=company_id)
+            contacts = company.contacts.all().order_by("name")
 
             return [
                 {
@@ -378,8 +382,8 @@ def get_client_contacts(client_id: UUID) -> List[Dict[str, Any]]:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "get_client_contacts",
-                    "client_id": str(client_id),
+                    "operation": "get_company_contacts",
+                    "company_id": str(company_id),
                 },
             )
 
@@ -463,11 +467,11 @@ def update_job_contact(
             from apps.job.models import Job
 
             try:
-                job = Job.objects.select_related("client", "contact").get(id=job_id)
+                job = Job.objects.select_related("company", "contact").get(id=job_id)
             except Job.DoesNotExist:
                 raise ValueError(f"Job with id {job_id} not found")
 
-            # Validate contact exists and belongs to the same client
+            # Validate contact exists and belongs to the same company
             contact_id = contact_data.get("id")
             if not contact_id:
                 raise ValueError("Contact ID is required")
@@ -477,9 +481,9 @@ def update_job_contact(
             except ClientContact.DoesNotExist:
                 raise ValueError(f"Contact with id {contact_id} not found")
 
-            # Validate contact belongs to the job's client
-            if contact.client_id != job.client_id:
-                raise ValueError("Contact does not belong to the job's client")
+            # Validate contact belongs to the job's company
+            if contact.company_id != job.company_id:
+                raise ValueError("Contact does not belong to the job's company")
 
             # Update job's contact
             job.contact = contact
@@ -490,7 +494,7 @@ def update_job_contact(
                 extra={
                     "job_id": str(job_id),
                     "contact_id": str(contact_id),
-                    "client_id": str(job.client_id),
+                    "company_id": str(job.company_id),
                     "operation": "update_job_contact",
                 },
             )
@@ -517,29 +521,29 @@ def update_job_contact(
             )
 
     @staticmethod
-    def _execute_client_search(query: str, limit: int):
+    def _execute_company_search(query: str, limit: int):
         """
-        Executes client search with appropriate filters and annotations.
+        Executes company search with appropriate filters and annotations.
         """
-        ranked_ids = ClientRestService._rank_matching_client_ids(
-            Client.objects.filter(allow_jobs=True), query
+        ranked_ids = CompanyRestService._rank_matching_company_ids(
+            Company.objects.filter(allow_jobs=True), query
         )
-        return ClientRestService._hydrate_client_search_results(ranked_ids[:limit])
+        return CompanyRestService._hydrate_company_search_results(ranked_ids[:limit])
 
     @staticmethod
-    def _hydrate_client_search_results(client_ids):
-        if not client_ids:
+    def _hydrate_company_search_results(company_ids):
+        if not company_ids:
             return []
 
         ordering = Case(
             *[
-                When(id=client_id, then=position)
-                for position, client_id in enumerate(client_ids)
+                When(id=company_id, then=position)
+                for position, company_id in enumerate(company_ids)
             ],
             output_field=IntegerField(),
         )
         return list(
-            Client.objects.with_invoice_summary()
+            Company.objects.with_invoice_summary()
             .defer("raw_json")  # Not needed for search results
             .only(
                 "id",
@@ -551,58 +555,58 @@ def _hydrate_client_search_results(client_ids):
                 "allow_jobs",
                 "xero_contact_id",
             )
-            .filter(id__in=client_ids)
+            .filter(id__in=company_ids)
             .order_by(ordering)
         )
 
     @staticmethod
-    def _rank_matching_client_ids(queryset, query: str):
-        tokens = ClientRestService._client_search_tokens(query)
+    def _rank_matching_company_ids(queryset, query: str):
+        tokens = CompanyRestService._company_search_tokens(query)
         if not tokens:
             return []
 
-        candidate_filter = ClientRestService._client_name_candidate_filter(tokens)
+        candidate_filter = CompanyRestService._company_name_candidate_filter(tokens)
         candidates = queryset.filter(candidate_filter).values_list("id", "name")
 
         ranked = [
             (
-                ClientRestService._client_name_score(name, query, tokens),
-                client_id,
+                CompanyRestService._company_name_score(name, query, tokens),
+                company_id,
             )
-            for client_id, name in candidates.iterator()
-            if ClientRestService._client_name_matches(name, tokens)
+            for company_id, name in candidates.iterator()
+            if CompanyRestService._company_name_matches(name, tokens)
         ]
         ranked.sort(key=lambda item: item[0])
-        return [client_id for _, client_id in ranked]
+        return [company_id for _, company_id in ranked]
 
     @staticmethod
-    def _client_search_tokens(query: str) -> list[str]:
-        return CLIENT_SEARCH_TOKEN_RE.findall(query.lower())
+    def _company_search_tokens(query: str) -> list[str]:
+        return COMPANY_SEARCH_TOKEN_RE.findall(query.lower())
 
     @staticmethod
-    def _normalized_client_search_text(value: str) -> str:
-        return " ".join(CLIENT_SEARCH_TOKEN_RE.findall(value.lower()))
+    def _normalized_company_search_text(value: str) -> str:
+        return " ".join(COMPANY_SEARCH_TOKEN_RE.findall(value.lower()))
 
     @staticmethod
-    def _client_name_candidate_filter(tokens: list[str]):
+    def _company_name_candidate_filter(tokens: list[str]):
         candidate_filter = Q()
         for token in tokens:
             candidate_filter &= Q(name__icontains=token)
         return candidate_filter
 
     @staticmethod
-    def _client_name_matches(name: str, tokens: list[str]) -> bool:
-        name_tokens = ClientRestService._client_search_tokens(name)
+    def _company_name_matches(name: str, tokens: list[str]) -> bool:
+        name_tokens = CompanyRestService._company_search_tokens(name)
         return all(
             any(name_token.startswith(query_token) for name_token in name_tokens)
             for query_token in tokens
         )
 
     @staticmethod
-    def _client_name_score(name: str, query: str, tokens: list[str]):
-        normalized_name = ClientRestService._normalized_client_search_text(name)
-        normalized_query = ClientRestService._normalized_client_search_text(query)
-        name_tokens = ClientRestService._client_search_tokens(name)
+    def _company_name_score(name: str, query: str, tokens: list[str]):
+        normalized_name = CompanyRestService._normalized_company_search_text(name)
+        normalized_query = CompanyRestService._normalized_company_search_text(query)
+        name_tokens = CompanyRestService._company_search_tokens(name)
 
         if normalized_name == normalized_query:
             tier = 0
@@ -614,7 +618,7 @@ def _client_name_score(name: str, query: str, tokens: list[str]):
             tier = 3
 
         token_scores = [
-            ClientRestService._client_token_match_score(token, name_tokens)
+            CompanyRestService._company_token_match_score(token, name_tokens)
             for token in tokens
         ]
         positions = [normalized_name.find(token) for token in tokens]
@@ -630,7 +634,7 @@ def _client_name_score(name: str, query: str, tokens: list[str]):
         )
 
     @staticmethod
-    def _client_token_match_score(query_token: str, name_tokens: list[str]) -> int:
+    def _company_token_match_score(query_token: str, name_tokens: list[str]) -> int:
         if query_token in name_tokens:
             return 0
         if any(token.startswith(query_token) for token in name_tokens):
@@ -638,38 +642,40 @@ def _client_token_match_score(query_token: str, name_tokens: list[str]) -> int:
         return 99
 
     @staticmethod
-    def explain_client_search(query: str, limit: int = 20) -> List[Dict[str, Any]]:
-        ranked_ids = ClientRestService._rank_matching_client_ids(
-            Client.objects.all(), query
+    def explain_company_search(query: str, limit: int = 20) -> List[Dict[str, Any]]:
+        ranked_ids = CompanyRestService._rank_matching_company_ids(
+            Company.objects.all(), query
+        )
+        companies = CompanyRestService._hydrate_company_search_results(
+            ranked_ids[:limit]
         )
-        clients = ClientRestService._hydrate_client_search_results(ranked_ids[:limit])
-        tokens = ClientRestService._client_search_tokens(query)
+        tokens = CompanyRestService._company_search_tokens(query)
         return [
-            ClientRestService._client_search_log_result(
+            CompanyRestService._company_search_log_result(
                 rank=index + 1,
-                result=client,
+                result=company,
                 query=query,
                 tokens=tokens,
             )
-            for index, client in enumerate(clients)
+            for index, company in enumerate(companies)
         ]
 
     @staticmethod
-    def log_client_search_results(
+    def log_company_search_results(
         *,
         request: Optional[HttpRequest],
         source: str,
         query: str,
-        clients,
+        companies,
         total_count: int,
     ) -> None:
         if len(query.strip()) < 3:
             return
 
-        tokens = ClientRestService._client_search_tokens(query)
+        tokens = CompanyRestService._company_search_tokens(query)
         user = getattr(request, "user", None) if request else None
         payload = {
-            "event": "client_search_results",
+            "event": "company_search_results",
             "search_id": str(uuid4()),
             "source": source,
             "query": query,
@@ -680,18 +686,18 @@ def log_client_search_results(
             "user_id": str(getattr(user, "id", "")) if user else None,
             "user_email": getattr(user, "email", None) if user else None,
             "result_count": total_count,
-            "returned_count": len(clients),
+            "returned_count": len(companies),
             "results": [
-                ClientRestService._client_search_log_result(
+                CompanyRestService._company_search_log_result(
                     rank=index + 1,
-                    result=client,
+                    result=company,
                     query=query,
                     tokens=tokens,
                 )
-                for index, client in enumerate(clients)
+                for index, company in enumerate(companies)
             ],
         }
-        client_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
+        company_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
         SearchTelemetryService.log_search(
             request=request,
             domain="client",
@@ -700,24 +706,24 @@ def log_client_search_results(
             result_count=total_count,
             returned_result_ids=[
                 result["id"] if isinstance(result, dict) else result.id
-                for result in clients
+                for result in companies
             ],
             metadata={"results": payload["results"][:100]},
         )
 
     @staticmethod
-    def log_client_search_click(
+    def log_company_search_click(
         *,
         request: Optional[HttpRequest],
         source: str,
         query: str,
-        client_id,
+        company_id,
         rank: Optional[int],
     ) -> None:
-        client = Client.objects.only("id", "name").get(id=client_id)
+        company = Company.objects.only("id", "name").get(id=company_id)
         user = getattr(request, "user", None) if request else None
         payload = {
-            "event": "client_search_click",
+            "event": "company_search_click",
             "search_id": str(uuid4()),
             "source": source,
             "query": query,
@@ -727,52 +733,52 @@ def log_client_search_click(
             ),
             "user_id": str(getattr(user, "id", "")) if user else None,
             "user_email": getattr(user, "email", None) if user else None,
-            "client_id": str(client.id),
-            "client_name": client.name,
+            "company_id": str(company.id),
+            "company_name": company.name,
             "rank": rank,
         }
-        client_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
+        company_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
         SearchTelemetryService.log_click(
             request=request,
             domain="client",
             source=source,
             query=query,
-            selected_result_id=str(client.id),
-            selected_label=client.name,
+            selected_result_id=str(company.id),
+            selected_label=company.name,
             selected_rank=rank,
-            metadata={"client_name": client.name},
+            metadata={"company_name": company.name},
         )
 
     @staticmethod
-    def _client_search_log_result(
+    def _company_search_log_result(
         *,
         rank: int,
-        result: Client | Dict[str, Any],
+        result: Company | Dict[str, Any],
         query: str,
         tokens: list[str],
     ) -> Dict[str, Any]:
         if isinstance(result, dict):
-            client_id = result["id"]
-            client_name = result["name"]
+            company_id = result["id"]
+            company_name = result["name"]
         else:
-            client_id = str(result.id)
-            client_name = result.name
+            company_id = str(result.id)
+            company_name = result.name
 
-        name_tokens = ClientRestService._client_search_tokens(client_name)
+        name_tokens = CompanyRestService._company_search_tokens(company_name)
         return {
             "rank": rank,
-            "client_id": client_id,
-            "client_name": client_name,
-            "search_score": ClientRestService._client_name_score(
-                client_name, query, tokens
+            "company_id": company_id,
+            "company_name": company_name,
+            "search_score": CompanyRestService._company_name_score(
+                company_name, query, tokens
             ),
             "search_reasons": [
                 {
                     "token": token,
-                    "reason": ClientRestService._client_token_match_reason(
+                    "reason": CompanyRestService._company_token_match_reason(
                         token, name_tokens
                     ),
-                    "score": ClientRestService._client_token_match_score(
+                    "score": CompanyRestService._company_token_match_score(
                         token, name_tokens
                     ),
                 }
@@ -781,7 +787,7 @@ def _client_search_log_result(
         }
 
     @staticmethod
-    def _client_token_match_reason(query_token: str, name_tokens: list[str]) -> str:
+    def _company_token_match_reason(query_token: str, name_tokens: list[str]) -> str:
         if query_token in name_tokens:
             return "token_exact"
         if any(token.startswith(query_token) for token in name_tokens):
@@ -789,118 +795,120 @@ def _client_token_match_reason(query_token: str, name_tokens: list[str]) -> str:
         return "no_match"
 
     @staticmethod
-    def _format_client_summary(client: Client) -> Dict[str, Any]:
+    def _format_company_summary(company: Company) -> Dict[str, Any]:
         """
-        Formats a single client summary for list/search responses.
+        Formats a single company summary for list/search responses.
         """
         return {
-            "id": str(client.id),
-            "name": client.name,
-            "email": client.email or "",
-            "address": client.address or "",
-            "is_account_customer": client.is_account_customer,
-            "is_supplier": client.is_supplier,
-            "allow_jobs": client.allow_jobs,
-            "xero_contact_id": client.xero_contact_id or "",
-            "last_invoice_date": date_to_datetime(client.last_invoice_date),
-            "total_spend": f"${client.total_spend:,.2f}",
+            "id": str(company.id),
+            "name": company.name,
+            "email": company.email or "",
+            "address": company.address or "",
+            "is_account_customer": company.is_account_customer,
+            "is_supplier": company.is_supplier,
+            "allow_jobs": company.allow_jobs,
+            "xero_contact_id": company.xero_contact_id or "",
+            "last_invoice_date": date_to_datetime(company.last_invoice_date),
+            "total_spend": f"${company.total_spend:,.2f}",
         }
 
     @staticmethod
-    def _format_client_search_results(clients) -> List[Dict[str, Any]]:
+    def _format_company_search_results(companies) -> List[Dict[str, Any]]:
         """
-        Formats client search results for API response.
+        Formats company search results for API response.
         """
-        return [ClientRestService._format_client_summary(client) for client in clients]
+        return [
+            CompanyRestService._format_company_summary(company) for company in companies
+        ]
 
     @staticmethod
-    def _format_client_detail(client: Client) -> Dict[str, Any]:
+    def _format_company_detail(company: Company) -> Dict[str, Any]:
         """
-        Formats complete client details for API response.
+        Formats complete company details for API response.
         """
         return {
-            "id": str(client.id),
-            "name": client.name,
-            "email": client.email or "",
-            "address": client.address or "",
-            "is_account_customer": client.is_account_customer,
-            "is_supplier": client.is_supplier,
-            "allow_jobs": client.allow_jobs,
-            "xero_contact_id": client.xero_contact_id or "",
-            "xero_tenant_id": client.xero_tenant_id or "",
-            "primary_contact_name": client.primary_contact_name or "",
-            "primary_contact_email": client.primary_contact_email or "",
-            "additional_contact_persons": client.additional_contact_persons or [],
-            "xero_last_modified": client.xero_last_modified,
-            "xero_last_synced": client.xero_last_synced,
-            "xero_archived": client.xero_archived,
-            "xero_merged_into_id": client.xero_merged_into_id or "",
-            "merged_into": str(client.merged_into.id) if client.merged_into else None,
-            "django_created_at": client.django_created_at,
-            "django_updated_at": client.django_updated_at,
-            "last_invoice_date": date_to_datetime(client.last_invoice_date),
-            "total_spend": f"${client.total_spend:,.2f}",
+            "id": str(company.id),
+            "name": company.name,
+            "email": company.email or "",
+            "address": company.address or "",
+            "is_account_customer": company.is_account_customer,
+            "is_supplier": company.is_supplier,
+            "allow_jobs": company.allow_jobs,
+            "xero_contact_id": company.xero_contact_id or "",
+            "xero_tenant_id": company.xero_tenant_id or "",
+            "primary_contact_name": company.primary_contact_name or "",
+            "primary_contact_email": company.primary_contact_email or "",
+            "additional_contact_persons": company.additional_contact_persons or [],
+            "xero_last_modified": company.xero_last_modified,
+            "xero_last_synced": company.xero_last_synced,
+            "xero_archived": company.xero_archived,
+            "xero_merged_into_id": company.xero_merged_into_id or "",
+            "merged_into": str(company.merged_into.id) if company.merged_into else None,
+            "django_created_at": company.django_created_at,
+            "django_updated_at": company.django_updated_at,
+            "last_invoice_date": date_to_datetime(company.last_invoice_date),
+            "total_spend": f"${company.total_spend:,.2f}",
         }
 
     @staticmethod
-    def _create_client_in_xero(client_data: Dict[str, Any]) -> Client:
+    def _create_company_in_xero(company_data: Dict[str, Any]) -> Company:
         """
-        Creates client in the accounting provider and locally.
+        Creates company in the accounting provider and locally.
         """
         provider = get_provider()
-        name = client_data["name"]
+        name = company_data["name"]
 
         # Check for duplicates in accounting provider
         existing = provider.search_contact_by_name(name)
         if existing is not None:
             raise ValueError(
-                f"Client '{name}' already exists in {provider.provider_name}"
+                f"Company '{name}' already exists in {provider.provider_name}"
                 f" with ID: {existing.external_id}"
             )
 
-        # Create local client first
+        # Create local company first
         with transaction.atomic():
-            client = Client.objects.create(
+            company = Company.objects.create(
                 name=name,
-                email=client_data.get("email") or "",
-                address=client_data.get("address") or "",
-                is_account_customer=client_data.get("is_account_customer", True),
+                email=company_data.get("email") or "",
+                address=company_data.get("address") or "",
+                is_account_customer=company_data.get("is_account_customer", True),
                 xero_last_modified=timezone.now(),
             )
 
-        # Push to accounting provider (persists xero_contact_id on the client object)
-        result = provider.create_contact(client)
+        # Push to accounting provider (persists xero_contact_id on the company object)
+        result = provider.create_contact(company)
         if not result.success:
-            client_id = client.id
-            client.delete()
+            company_id = company.id
+            company.delete()
             logger.warning(
-                "Deleted local client after accounting provider create failure",
+                "Deleted local company after accounting provider create failure",
                 extra={
-                    "client_id": str(client_id),
-                    "client_name": name,
+                    "company_id": str(company_id),
+                    "company_name": name,
                     "provider": provider.provider_name,
-                    "operation": "create_client_in_xero_cleanup",
+                    "operation": "create_company_in_xero_cleanup",
                 },
             )
             raise ValueError(
-                f"Failed to create client in {provider.provider_name}: {result.error}"
+                f"Failed to create company in {provider.provider_name}: {result.error}"
             )
 
         logger.info(
-            f"Client {client.id} created locally and in {provider.provider_name}",
+            f"Company {company.id} created locally and in {provider.provider_name}",
             extra={
-                "client_id": str(client.id),
-                "client_name": client.name,
-                "xero_contact_id": client.xero_contact_id,
-                "operation": "create_client_in_xero",
+                "company_id": str(company.id),
+                "company_name": company.name,
+                "xero_contact_id": company.xero_contact_id,
+                "operation": "create_company_in_xero",
             },
         )
-        return client
+        return company
 
     @staticmethod
-    def _update_client_in_xero(client: Client, data: Dict[str, Any]) -> Client:
+    def _update_company_in_xero(company: Company, data: Dict[str, Any]) -> Company:
         """
-        Updates client locally and in the accounting provider.
+        Updates company locally and in the accounting provider.
         """
         provider = get_provider()
 
@@ -911,16 +919,16 @@ def _update_client_in_xero(client: Client, data: Dict[str, Any]) -> Client:
 
         # Update local fields first
         with transaction.atomic():
-            client.name = data.get("name", client.name)
-            client.email = data.get("email", client.email)
-            client.address = data.get("address", client.address)
-            client.is_account_customer = data.get(
-                "is_account_customer", client.is_account_customer
+            company.name = data.get("name", company.name)
+            company.email = data.get("email", company.email)
+            company.address = data.get("address", company.address)
+            company.is_account_customer = data.get(
+                "is_account_customer", company.is_account_customer
             )
             if "allow_jobs" in data:
-                client.allow_jobs = data["allow_jobs"]
-            client.xero_last_modified = timezone.now()
-            client.save()
+                company.allow_jobs = data["allow_jobs"]
+            company.xero_last_modified = timezone.now()
+            company.save()
 
         # FIXME: `allow_jobs` is a local-only field (not synced to Xero) but
         # toggling it still routes through this method, which unconditionally
@@ -928,56 +936,56 @@ def _update_client_in_xero(client: Client, data: Dict[str, Any]) -> Client:
         # Xero API quota and -- more concerning -- can fool the next sync
         # into thinking local state is newer than remote, potentially
         # clobbering a genuine Xero-side change. Fix: either split into a
-        # local-only `_update_client_locally` path for flags like
+        # local-only `_update_company_locally` path for flags like
         # `allow_jobs`, or detect when `data` contains only local-only keys
         # and skip the push + timestamp bump.
-        # Push updated client to accounting provider
-        result = provider.update_contact(client)
+        # Push updated company to accounting provider
+        result = provider.update_contact(company)
         if not result.success:
             raise ValueError(
-                f"Failed to update client in {provider.provider_name}: {result.error}"
+                f"Failed to update company in {provider.provider_name}: {result.error}"
             )
 
         logger.info(
-            f"Client {client.id} updated locally and in {provider.provider_name}",
+            f"Company {company.id} updated locally and in {provider.provider_name}",
             extra={
-                "client_id": str(client.id),
-                "client_name": client.name,
-                "xero_contact_id": client.xero_contact_id,
-                "operation": "_update_client_in_xero",
+                "company_id": str(company.id),
+                "company_name": company.name,
+                "xero_contact_id": company.xero_contact_id,
+                "operation": "_update_company_in_xero",
             },
         )
 
-        return client
+        return company
 
     @staticmethod
-    def get_client_jobs(client_id: UUID) -> List[Dict[str, Any]]:
+    def get_company_jobs(company_id: UUID) -> List[Dict[str, Any]]:
         """
-        Retrieves all jobs for a specific client.
+        Retrieves all jobs for a specific company.
 
         Args:
-            client_id: Client UUID
+            company_id: Company UUID
 
         Returns:
             List of job header dictionaries
 
         Raises:
-            ValueError: If client not found
+            ValueError: If company not found
         """
         try:
-            # Guard clause - verify client exists
-            if not Client.objects.filter(id=client_id).exists():
-                raise ValueError(f"Client with id {client_id} not found")
+            # Guard clause - verify company exists
+            if not Company.objects.filter(id=company_id).exists():
+                raise ValueError(f"Company with id {company_id} not found")
 
             # Import here to avoid circular imports
             from apps.job.models import Job
 
-            # Get all jobs for this client using JOB_DIRECT_FIELDS as source of truth
-            query_fields = ["id", "client_id"] + Job.JOB_DIRECT_FIELDS
+            # Get all jobs for this company using JOB_DIRECT_FIELDS as source of truth
+            query_fields = ["id", "company_id"] + Job.JOB_DIRECT_FIELDS
             jobs = (
-                Job.objects.filter(client_id=client_id)
+                Job.objects.filter(company_id=company_id)
                 # quote joined in because job.quoted reads it per job below
-                .select_related("client", "quote")
+                .select_related("company", "quote")
                 .only(*query_fields, "quote__id")
                 .order_by("-job_number")
             )
@@ -988,9 +996,9 @@ def get_client_jobs(client_id: UUID) -> List[Dict[str, Any]]:
                     "job_id": str(job.id),
                     "job_number": job.job_number,
                     "name": job.name,
-                    "client": (
-                        {"id": str(job.client.id), "name": job.client.name}
-                        if job.client
+                    "company": (
+                        {"id": str(job.company.id), "name": job.company.name}
+                        if job.company
                         else None
                     ),
                     "status": job.status,
diff --git a/apps/client/services/duplicate_phone_report.py b/apps/company/services/duplicate_phone_report.py
similarity index 76%
rename from apps/client/services/duplicate_phone_report.py
rename to apps/company/services/duplicate_phone_report.py
index 656cde169..71af7d791 100644
--- a/apps/client/services/duplicate_phone_report.py
+++ b/apps/company/services/duplicate_phone_report.py
@@ -1,9 +1,9 @@
-"""Data Quality report: phone numbers that break the one-number-one-client rule.
+"""Data Quality report: phone numbers that break the one-number-one-company rule.
 
 Surfaces the two ways a phone number can be mis-owned, for manual clean-up:
-- ``cross_client`` — a number whose effective clients (``COALESCE(client_id,
-  contact.client_id)``) number more than one (the grandfathered pre-existing links).
-- ``internal_line`` — a client/contact phone method whose number is one of the
+- ``cross_client`` — a number whose effective companies (``COALESCE(company_id,
+  contact.company_id)``) number more than one (the grandfathered pre-existing links).
+- ``internal_line`` — a company/contact phone method whose number is one of the
   company's own internal ``PhoneEndpoint`` lines (e.g. a staff line mis-filed as a
   customer contact).
 """
@@ -15,7 +15,7 @@
 from django.db.models.functions import Coalesce
 from django.utils import timezone
 
-from apps.client.models import ClientContactMethod
+from apps.company.models import ClientContactMethod
 from apps.crm.models import PhoneEndpoint
 
 
@@ -48,18 +48,18 @@ class DuplicatePhoneReportService:
     """Builds the "Duplicate phones" data-quality report."""
 
     def get_report(self) -> DuplicatePhonesReport:
-        cross_client = self._cross_client_conflicts()
+        cross_company = self._cross_company_conflicts()
         internal_line = self._internal_line_collisions()
         return {
-            "duplicate_phones": cross_client + internal_line,
+            "duplicate_phones": cross_company + internal_line,
             "summary": {
-                "cross_client": len(cross_client),
+                "cross_client": len(cross_company),
                 "internal_line": len(internal_line),
             },
             "checked_at": timezone.now(),
         }
 
-    def _cross_client_conflicts(self) -> list[DuplicatePhoneIssue]:
+    def _cross_company_conflicts(self) -> list[DuplicatePhoneIssue]:
         phones = ClientContactMethod.objects.filter(
             method_type=ClientContactMethod.MethodType.PHONE
         )
@@ -67,18 +67,18 @@ def _cross_client_conflicts(self) -> list[DuplicatePhoneIssue]:
             row["normalized_value"]
             for row in phones.values("normalized_value")
             .annotate(
-                clients=Count(
-                    Coalesce("client_id", "contact__client_id"), distinct=True
+                companies=Count(
+                    Coalesce("company_id", "contact__company_id"), distinct=True
                 )
             )
-            .filter(clients__gt=1)
+            .filter(companies__gt=1)
         ]
         if not conflict_numbers:
             return []
         grouped: dict[str, list[DuplicatePhoneOwner]] = {}
         for method in (
             phones.filter(normalized_value__in=conflict_numbers)
-            .select_related("client", "contact", "contact__client")
+            .select_related("company", "contact", "contact__company")
             .order_by("normalized_value", "id")
         ):
             grouped.setdefault(method.normalized_value, []).append(self._owner(method))
@@ -112,19 +112,19 @@ def _internal_line_collisions(self) -> list[DuplicatePhoneIssue]:
                     method_type=ClientContactMethod.MethodType.PHONE,
                     normalized_value__in=list(endpoint_labels),
                 )
-                .select_related("client", "contact", "contact__client")
+                .select_related("company", "contact", "contact__company")
                 .order_by("normalized_value", "id")
             )
         ]
 
     @staticmethod
     def _owner(method: ClientContactMethod) -> DuplicatePhoneOwner:
-        effective_client_id = method.owner_client_id()
+        effective_company_id = method.owner_company_id()
         return {
             "method_id": str(method.id),
-            "owner_kind": "client" if method.client_id else "contact",
+            "owner_kind": "company" if method.company_id else "contact",
             "owner_name": method.owner_display_name(),
             "effective_client_id": (
-                str(effective_client_id) if effective_client_id else None
+                str(effective_company_id) if effective_company_id else None
             ),
         }
diff --git a/apps/client/services/geocoding_service.py b/apps/company/services/geocoding_service.py
similarity index 100%
rename from apps/client/services/geocoding_service.py
rename to apps/company/services/geocoding_service.py
diff --git a/apps/client/tests/__init__.py b/apps/company/tests/__init__.py
similarity index 100%
rename from apps/client/tests/__init__.py
rename to apps/company/tests/__init__.py
diff --git a/apps/client/tests/test_client_fts_search.py b/apps/company/tests/test_company_fts_search.py
similarity index 57%
rename from apps/client/tests/test_client_fts_search.py
rename to apps/company/tests/test_company_fts_search.py
index 1abb00afc..2a0d08fdd 100644
--- a/apps/client/tests/test_client_fts_search.py
+++ b/apps/company/tests/test_company_fts_search.py
@@ -1,4 +1,4 @@
-"""Python-owned client-name search regression coverage.
+"""Python-owned company-name search regression coverage.
 
 Postgres may narrow candidates for performance, but Python owns final matching
 and ordering. These tests pin the user-facing behavior, including prefix
@@ -12,80 +12,82 @@
 from django.test import RequestFactory
 from django.utils import timezone
 
-from apps.client.models import Client
-from apps.client.services.client_rest_service import ClientRestService
+from apps.company.models import Company
+from apps.company.services.company_rest_service import CompanyRestService
 from apps.workflow.models import SearchTelemetryEvent
 
 
-def _make_client(name: str, **overrides):
+def _make_company(name: str, **overrides):
     defaults = {
         "name": name,
         "xero_last_modified": timezone.now(),
         "allow_jobs": True,
     }
     defaults.update(overrides)
-    return Client.objects.create(**defaults)
+    return Company.objects.create(**defaults)
 
 
-def _make_search_noise_clients(count: int = 2000):
+def _make_search_noise_companies(count: int = 2000):
     """
-    Client search bugs hide in tiny fixtures: a candidate filter that admits
+    Company search bugs hide in tiny fixtures: a candidate filter that admits
     substring false positives can still look correct until real matches are
     buried under production-sized noise.
     """
     now = timezone.now()
-    clients = []
+    companies = []
     for index in range(count):
         if index % 5 == 0:
-            name = f"AlphaFume Noise Client {index:04d}"
+            name = f"AlphaFume Noise Company {index:04d}"
         elif index % 5 == 1:
-            name = f"Smartin Redwood Client {index:04d}"
+            name = f"Smartin Redwood Company {index:04d}"
         else:
-            name = f"Noise Client {index:04d}"
+            name = f"Noise Company {index:04d}"
 
-        clients.append(
-            Client(
+        companies.append(
+            Company(
                 name=name,
                 xero_last_modified=now,
                 allow_jobs=True,
             )
         )
 
-    Client.objects.bulk_create(clients)
+    Company.objects.bulk_create(companies)
 
 
 @pytest.fixture
 def hynds(db):
-    return _make_client("Hynds Pipe Systems")
+    return _make_company("Hynds Pipe Systems")
 
 
 @pytest.fixture
 def dog_food(db):
-    return _make_client("Acme Dog Food Ltd")
+    return _make_company("Acme Dog Food Ltd")
 
 
 @pytest.fixture
 def food_dog(db):
-    return _make_client("Food Dog Imports")
+    return _make_company("Food Dog Imports")
 
 
 def test_multi_token_query_matches_in_any_order(hynds):
     """The Hynds-Pipe-Systems case: tokens in any order must match."""
-    result = ClientRestService.list_clients(query="Hynds Systems", page=1, page_size=10)
+    result = CompanyRestService.list_companies(
+        query="Hynds Systems", page=1, page_size=10
+    )
     names = [c["name"] for c in result["results"]]
     assert "Hynds Pipe Systems" in names
 
 
 def test_quoted_phrase_outranks_scattered_tokens(dog_food, food_dog):
     """Quoted "Dog Food" must rank the contiguous-phrase row first."""
-    result = ClientRestService.list_clients(query='"Dog Food"', page=1, page_size=10)
+    result = CompanyRestService.list_companies(query='"Dog Food"', page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
     assert names[0] == "Acme Dog Food Ltd"
 
 
 def test_unquoted_tokens_match_both_orders(dog_food, food_dog):
     """Unquoted `dog food` matches both orderings (AND semantics)."""
-    result = ClientRestService.list_clients(query="dog food", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="dog food", page=1, page_size=10)
     names = {c["name"] for c in result["results"]}
     assert names == {"Acme Dog Food Ltd", "Food Dog Imports"}
 
@@ -95,18 +97,18 @@ def test_single_token_query_matches(hynds):
     one word into the search box) silently returns nothing — every user
     experiences a broken search.
     """
-    result = ClientRestService.list_clients(query="Hynds", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="Hynds", page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
     assert "Hynds Pipe Systems" in names
 
 
 def test_partial_name_query_matches_business_name_prefix(db):
     """Production regression: `FUME` must find `Fumecare Ltd`."""
-    _make_search_noise_clients()
-    _make_client("Fumecare Ltd")
-    _make_client("Acme Co")
+    _make_search_noise_companies()
+    _make_company("Fumecare Ltd")
+    _make_company("Acme Co")
 
-    result = ClientRestService.list_clients(query="FUME", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="FUME", page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
 
     assert names == ["Fumecare Ltd"]
@@ -115,9 +117,9 @@ def test_partial_name_query_matches_business_name_prefix(db):
 
 def test_full_name_token_query_still_matches_business_name(db):
     """Catches the direct-name branch breaking normal full-token lookup."""
-    _make_client("Fumecare Ltd")
+    _make_company("Fumecare Ltd")
 
-    result = ClientRestService.list_clients(query="Fumecare", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="Fumecare", page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
 
     assert names == ["Fumecare Ltd"]
@@ -125,21 +127,21 @@ def test_full_name_token_query_still_matches_business_name(db):
 
 def test_prefix_token_score_beats_internal_substring_score(db):
     """`FUME` is a stronger signal for Fumecare than internal `umec`."""
-    tokens = ClientRestService._client_search_tokens("FUME")
-    internal_tokens = ClientRestService._client_search_tokens("umec")
+    tokens = CompanyRestService._company_search_tokens("FUME")
+    internal_tokens = CompanyRestService._company_search_tokens("umec")
 
-    assert ClientRestService._client_name_score(
+    assert CompanyRestService._company_name_score(
         "Fumecare Ltd", "FUME", tokens
-    ) < ClientRestService._client_name_score("Fumecare Ltd", "umec", internal_tokens)
+    ) < CompanyRestService._company_name_score("Fumecare Ltd", "umec", internal_tokens)
 
 
 def test_prefix_name_match_ranks_above_internal_substring_match(db):
     """A name-leading token prefix outranks a later token prefix."""
-    _make_client("Fumecare Ltd")
-    _make_client("Safe Fume Handling")
-    _make_client("Acme Co")
+    _make_company("Fumecare Ltd")
+    _make_company("Safe Fume Handling")
+    _make_company("Acme Co")
 
-    result = ClientRestService.list_clients(query="FUME", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="FUME", page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
 
     assert names == ["Fumecare Ltd", "Safe Fume Handling"]
@@ -147,10 +149,10 @@ def test_prefix_name_match_ranks_above_internal_substring_match(db):
 
 def test_internal_substring_does_not_match_business_name(db):
     """`car` inside `Fumecare` is not a token-prefix business-name match."""
-    _make_client("Fumecare Ltd")
-    _make_client("Carters Tools")
+    _make_company("Fumecare Ltd")
+    _make_company("Carters Tools")
 
-    result = ClientRestService.list_clients(query="car", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="car", page=1, page_size=10)
     names = [c["name"] for c in result["results"]]
 
     assert names == ["Carters Tools"]
@@ -158,9 +160,9 @@ def test_internal_substring_does_not_match_business_name(db):
 
 def test_internal_fumecare_substring_does_not_match(db):
     """`umec` should score worse than `FUME` and should not be included."""
-    _make_client("Fumecare Ltd")
+    _make_company("Fumecare Ltd")
 
-    result = ClientRestService.list_clients(query="umec", page=1, page_size=10)
+    result = CompanyRestService.list_companies(query="umec", page=1, page_size=10)
 
     assert result["results"] == []
     assert result["count"] == 0
@@ -175,8 +177,8 @@ def test_no_match_returns_empty(db):
     but corrupts ranking in production by burying real matches under
     thousands of fake ones.
     """
-    _make_client("Acme Co")
-    result = ClientRestService.list_clients(
+    _make_company("Acme Co")
+    result = CompanyRestService.list_companies(
         query="zzzqqxnonsense", page=1, page_size=10
     )
     assert result["results"] == []
@@ -192,13 +194,15 @@ def test_martin_wood_against_compound_name(db):
     `search_rank__gt=0` filter is reintroduced (because junk-rank rows
     sort above genuine matches once results are paginated).
     """
-    _make_search_noise_clients()
-    _make_client("Martin, Price and Wood")
-    _make_client("Wood, Martin and Calhoun")
-    _make_client("Smith Co")
-    _make_client("Walton and Sons")
-
-    result = ClientRestService.list_clients(query="Martin Wood", page=1, page_size=10)
+    _make_search_noise_companies()
+    _make_company("Martin, Price and Wood")
+    _make_company("Wood, Martin and Calhoun")
+    _make_company("Smith Co")
+    _make_company("Walton and Sons")
+
+    result = CompanyRestService.list_companies(
+        query="Martin Wood", page=1, page_size=10
+    )
     names = [c["name"] for c in result["results"]]
     assert "Martin, Price and Wood" in names
     assert "Wood, Martin and Calhoun" in names
@@ -206,23 +210,23 @@ def test_martin_wood_against_compound_name(db):
     assert "Walton and Sons" not in names
 
 
-def test_search_clients_top_n_respects_allow_jobs(db):
-    """search_clients() requires allow_jobs=True (job-eligible only)."""
-    _make_client("Acme Foo", allow_jobs=True)
-    _make_client("Acme Bar", allow_jobs=False)
+def test_search_companies_top_n_respects_allow_jobs(db):
+    """search_companies() requires allow_jobs=True (job-eligible only)."""
+    _make_company("Acme Foo", allow_jobs=True)
+    _make_company("Acme Bar", allow_jobs=False)
 
-    results = ClientRestService.search_clients("Acme", limit=10)
+    results = CompanyRestService.search_companies("Acme", limit=10)
     names = [r["name"] for r in results]
     assert "Acme Foo" in names
     assert "Acme Bar" not in names
 
 
-def test_search_clients_matches_partial_business_name(db):
-    """Top-N client lookup uses the same Python-owned name search."""
-    _make_client("Fumecare Ltd")
-    _make_client("Acme Co")
+def test_search_companies_matches_partial_business_name(db):
+    """Top-N company lookup uses the same Python-owned name search."""
+    _make_company("Fumecare Ltd")
+    _make_company("Acme Co")
 
-    results = ClientRestService.search_clients("FUME", limit=10)
+    results = CompanyRestService.search_companies("FUME", limit=10)
     names = [r["name"] for r in results]
 
     assert names == ["Fumecare Ltd"]
@@ -230,57 +234,57 @@ def test_search_clients_matches_partial_business_name(db):
 
 def test_candidate_filter_is_superset_of_python_name_matching(db):
     """Postgres candidate filtering must not decide final search semantics."""
-    clients = [
-        _make_client("Fumecare Ltd"),
-        _make_client("Hynds Pipe Systems"),
-        _make_client("Pipe Hynds Systems"),
-        _make_client("Acme Co"),
+    companies = [
+        _make_company("Fumecare Ltd"),
+        _make_company("Hynds Pipe Systems"),
+        _make_company("Pipe Hynds Systems"),
+        _make_company("Acme Co"),
     ]
-    tokens = ClientRestService._client_search_tokens("Hynds Systems")
+    tokens = CompanyRestService._company_search_tokens("Hynds Systems")
 
     candidate_ids = set(
-        Client.objects.filter(
-            ClientRestService._client_name_candidate_filter(tokens)
+        Company.objects.filter(
+            CompanyRestService._company_name_candidate_filter(tokens)
         ).values_list("id", flat=True)
     )
     python_ids = {
-        client.id
-        for client in clients
-        if ClientRestService._client_name_matches(client.name, tokens)
+        company.id
+        for company in companies
+        if CompanyRestService._company_name_matches(company.name, tokens)
     }
 
     assert python_ids <= candidate_ids
 
 
-def test_client_search_logging_emits_structured_json(db, caplog):
+def test_company_search_logging_emits_structured_json(db, caplog):
     """Catches search telemetry drifting from the Kanban logging style."""
-    client = _make_client("Fumecare Ltd")
-    result = ClientRestService.list_clients(query="FUME", page=1, page_size=10)
-    request = RequestFactory().get("/api/clients/search/", {"q": "FUME"})
+    company = _make_company("Fumecare Ltd")
+    result = CompanyRestService.list_companies(query="FUME", page=1, page_size=10)
+    request = RequestFactory().get("/api/companies/search/", {"q": "FUME"})
     request.user = None
 
     assert result["count"] == 1
-    assert result["results"][0]["id"] == str(client.id)
+    assert result["results"][0]["id"] == str(company.id)
 
-    with caplog.at_level(logging.INFO, logger="client_search"):
-        ClientRestService.log_client_search_results(
+    with caplog.at_level(logging.INFO, logger="company_search"):
+        CompanyRestService.log_company_search_results(
             request=request,
-            source="client_search",
+            source="company_search",
             query="FUME",
-            clients=result["results"],
+            companies=result["results"],
             total_count=result["count"],
         )
 
     payload = json.loads(caplog.records[0].message)
 
-    assert payload["event"] == "client_search_results"
+    assert payload["event"] == "company_search_results"
     assert payload["query"] == "FUME"
     assert payload["query_string"] == "q=FUME"
     assert payload["result_count"] == 1
     assert payload["returned_count"] == 1
     assert payload["results"][0]["rank"] == 1
-    assert payload["results"][0]["client_id"] == str(client.id)
-    assert payload["results"][0]["client_name"] == "Fumecare Ltd"
+    assert payload["results"][0]["company_id"] == str(company.id)
+    assert payload["results"][0]["company_name"] == "Fumecare Ltd"
     assert payload["results"][0]["search_reasons"][0]["reason"] == "token_prefix"
 
     event = SearchTelemetryEvent.objects.get(
@@ -290,10 +294,10 @@ def test_client_search_logging_emits_structured_json(db, caplog):
     assert event.query == "FUME"
     assert event.normalized_query == "fume"
     assert event.result_count == 1
-    assert event.returned_result_ids == [str(client.id)]
+    assert event.returned_result_ids == [str(company.id)]
 
 
-def test_search_clients_short_query_is_rejected(db):
+def test_search_companies_short_query_is_rejected(db):
     """The 3-character minimum-query guard returns [] without raising."""
-    assert ClientRestService.search_clients("ab", limit=10) == []
-    assert ClientRestService.search_clients("", limit=10) == []
+    assert CompanyRestService.search_companies("ab", limit=10) == []
+    assert CompanyRestService.search_companies("", limit=10) == []
diff --git a/apps/client/tests/test_client_invoice_summary.py b/apps/company/tests/test_company_invoice_summary.py
similarity index 63%
rename from apps/client/tests/test_client_invoice_summary.py
rename to apps/company/tests/test_company_invoice_summary.py
index 3e4dbe6ec..c91e2b055 100644
--- a/apps/client/tests/test_client_invoice_summary.py
+++ b/apps/company/tests/test_company_invoice_summary.py
@@ -10,24 +10,24 @@
 from rest_framework.test import APIRequestFactory, force_authenticate
 
 from apps.accounting.models import Invoice
-from apps.client.models import Client
-from apps.client.services.client_rest_service import ClientRestService
-from apps.client.utils import date_to_datetime
-from apps.client.views.client_rest_views import ClientCreateRestView
+from apps.company.models import Company
+from apps.company.services.company_rest_service import CompanyRestService
+from apps.company.utils import date_to_datetime
+from apps.company.views.company_rest_views import CompanyCreateRestView
 from apps.testing import BaseTestCase
 from apps.workflow.accounting.types import ContactResult
 from apps.workflow.exceptions import AlreadyLoggedException
 
 
-def _make_client(name: str) -> Client:
-    return Client.objects.create(name=name, xero_last_modified=timezone.now())
+def _make_company(name: str) -> Company:
+    return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
 
-def _make_invoice(client: Client, invoice_date: date, amount: Decimal) -> Invoice:
+def _make_invoice(company: Company, invoice_date: date, amount: Decimal) -> Invoice:
     return Invoice.objects.create(
         xero_id=uuid.uuid4(),
         number=f"INV-{uuid.uuid4().hex[:8]}",
-        client=client,
+        company=company,
         date=invoice_date,
         total_excl_tax=amount,
         tax=Decimal("0.00"),
@@ -39,30 +39,30 @@ def _make_invoice(client: Client, invoice_date: date, amount: Decimal) -> Invoic
 
 
 def test_with_invoice_summary_sets_latest_invoice_date_and_total_spend(db):
-    """Client search can mislead credit decisions if invoice rollups drift.
+    """Company search can mislead credit decisions if invoice rollups drift.
 
     This catches aggregation changes that sum only one invoice or choose the
     wrong date by using two invoices where the latest date and total differ.
     """
-    client = _make_client("Acme")
-    _make_invoice(client, date(2024, 1, 10), Decimal("100.00"))
-    _make_invoice(client, date(2024, 2, 20), Decimal("25.50"))
+    company = _make_company("Acme")
+    _make_invoice(company, date(2024, 1, 10), Decimal("100.00"))
+    _make_invoice(company, date(2024, 2, 20), Decimal("25.50"))
 
-    annotated = Client.objects.with_invoice_summary().get(id=client.id)
+    annotated = Company.objects.with_invoice_summary().get(id=company.id)
 
     assert annotated.last_invoice_date == date(2024, 2, 20)
     assert annotated.total_spend == Decimal("125.50")
 
 
-def test_with_invoice_summary_handles_clients_without_invoices(db):
-    """New clients must render as zero-spend, not error or stale data.
+def test_with_invoice_summary_handles_companies_without_invoices(db):
+    """New companies must render as zero-spend, not error or stale data.
 
     This catches annotation changes that leave null totals for the frontend to
-    format or accidentally join another client's invoice summary.
+    format or accidentally join another company's invoice summary.
     """
-    client = _make_client("No Invoices")
+    company = _make_company("No Invoices")
 
-    annotated = Client.objects.with_invoice_summary().get(id=client.id)
+    annotated = Company.objects.with_invoice_summary().get(id=company.id)
 
     assert annotated.last_invoice_date is None
     assert annotated.total_spend == Decimal("0.00")
@@ -72,36 +72,36 @@ def test_invoice_summary_properties_require_annotation(db):
     """Unannotated access must fail loudly instead of issuing hidden queries.
 
     This catches callers bypassing ``with_invoice_summary`` and reintroducing
-    per-client invoice lookups in list/search responses.
+    per-company invoice lookups in list/search responses.
     """
-    client = _make_client("Unannotated")
+    company = _make_company("Unannotated")
 
     with pytest.raises(RuntimeError, match="with_invoice_summary"):
-        _ = client.last_invoice_date
+        _ = company.last_invoice_date
 
     with pytest.raises(RuntimeError, match="with_invoice_summary"):
-        _ = client.total_spend
+        _ = company.total_spend
 
 
-def test_formatting_annotated_clients_does_not_query_invoice_metrics(db):
+def test_formatting_annotated_companies_does_not_query_invoice_metrics(db):
     """Formatting search results must not reintroduce invoice N+1 queries.
 
     This catches a formatter refactor that reads invoice relations/properties
     per row by asserting all invoice-derived values come from annotations.
     """
-    with_invoices = _make_client("With Invoices")
-    without_invoices = _make_client("Without Invoices")
+    with_invoices = _make_company("With Invoices")
+    without_invoices = _make_company("Without Invoices")
     _make_invoice(with_invoices, date(2024, 1, 1), Decimal("10.00"))
     _make_invoice(with_invoices, date(2024, 1, 2), Decimal("5.25"))
 
-    clients = list(
-        Client.objects.with_invoice_summary()
+    companies = list(
+        Company.objects.with_invoice_summary()
         .filter(id__in=[with_invoices.id, without_invoices.id])
         .order_by("name")
     )
 
     with CaptureQueriesContext(connection) as captured:
-        formatted = ClientRestService._format_client_search_results(clients)
+        formatted = CompanyRestService._format_company_search_results(companies)
 
     assert len(captured) == 0
     assert formatted == [
@@ -132,12 +132,12 @@ def test_formatting_annotated_clients_does_not_query_invoice_metrics(db):
     ]
 
 
-class ClientCreateInvoiceSummaryTests(BaseTestCase):
-    def test_create_client_response_formats_annotated_invoice_summary(self):
-        """Create responses must match the client-search summary contract.
+class CompanyCreateInvoiceSummaryTests(BaseTestCase):
+    def test_create_company_response_formats_annotated_invoice_summary(self):
+        """Create responses must match the company-search summary contract.
 
-        This catches a view refactor that returns a raw Client payload without
-        annotated invoice defaults, which would break newly-created client rows
+        This catches a view refactor that returns a raw Company payload without
+        annotated invoice defaults, which would break newly-created company rows
         in the frontend.
         """
         provider = MagicMock()
@@ -146,13 +146,13 @@ def test_create_client_response_formats_annotated_invoice_summary(self):
         provider.create_contact.return_value = ContactResult(
             success=True,
             external_id="xero-contact-id",
-            name="New Client",
+            name="New Company",
         )
 
         request = APIRequestFactory().post(
-            "/api/clients/create/",
+            "/api/companies/create/",
             {
-                "name": "New Client",
+                "name": "New Company",
                 "email": "new@example.test",
                 "address": "",
                 "is_account_customer": True,
@@ -162,18 +162,18 @@ def test_create_client_response_formats_annotated_invoice_summary(self):
         force_authenticate(request, user=self.test_staff)
 
         with patch(
-            "apps.client.services.client_rest_service.get_provider",
+            "apps.company.services.company_rest_service.get_provider",
             return_value=provider,
         ):
-            response = ClientCreateRestView.as_view()(request)
+            response = CompanyCreateRestView.as_view()(request)
 
         assert response.status_code == 201
-        assert response.data["client"]["name"] == "New Client"
-        assert response.data["client"]["last_invoice_date"] is None
-        assert response.data["client"]["total_spend"] == "$0.00"
+        assert response.data["company"]["name"] == "New Company"
+        assert response.data["company"]["last_invoice_date"] is None
+        assert response.data["company"]["total_spend"] == "$0.00"
 
-    def test_create_client_cleans_up_local_row_when_xero_create_fails(self):
-        """Failed Xero contact creation must not leave a half-created client."""
+    def test_create_company_cleans_up_local_row_when_xero_create_fails(self):
+        """Failed Xero contact creation must not leave a half-created company."""
         provider = MagicMock()
         provider.provider_name = "Xero"
         provider.get_valid_token.return_value = {"access_token": "token"}
@@ -184,17 +184,17 @@ def test_create_client_cleans_up_local_row_when_xero_create_fails(self):
         )
 
         with patch(
-            "apps.client.services.client_rest_service.get_provider",
+            "apps.company.services.company_rest_service.get_provider",
             return_value=provider,
         ):
             with pytest.raises(AlreadyLoggedException, match="RemoteDisconnected"):
-                ClientRestService.create_client(
+                CompanyRestService.create_company(
                     {
-                        "name": "Failed Xero Client",
+                        "name": "Failed Xero Company",
                         "email": "failed@example.test",
                         "address": "",
                         "is_account_customer": True,
                     }
                 )
 
-        assert not Client.objects.filter(name="Failed Xero Client").exists()
+        assert not Company.objects.filter(name="Failed Xero Company").exists()
diff --git a/apps/company/tests/test_company_jobs_queries.py b/apps/company/tests/test_company_jobs_queries.py
new file mode 100644
index 000000000..97903e545
--- /dev/null
+++ b/apps/company/tests/test_company_jobs_queries.py
@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from django.db import connection
+from django.test.utils import CaptureQueriesContext
+
+from apps.company.models import Company
+from apps.company.services.company_rest_service import CompanyRestService
+from apps.job.models import Job
+from apps.testing import BaseTestCase
+
+
+class CompanyJobsQueryTests(BaseTestCase):
+    """get_company_jobs reads job.quoted per job; without select_related on
+    quote that lazy-loads once per job and the dev/E2E n+1 guard raises."""
+
+    def test_get_company_jobs_does_not_lazy_load_quotes(self) -> None:
+        company_obj = Company.objects.create(
+            name="Company Jobs Query Company",
+            email="company-jobs-queries@example.com",
+            xero_last_modified="2024-01-01T00:00:00Z",
+        )
+        for name in ("Company Jobs Query Job 1", "Company Jobs Query Job 2"):
+            job = Job(name=name, company=company_obj)
+            job.save(staff=self.test_staff)
+
+        with CaptureQueriesContext(connection) as ctx:
+            jobs = CompanyRestService.get_company_jobs(company_obj.id)
+
+        self.assertEqual(len(jobs), 2)
+        # exists() guard + the jobs query (quote joined in, not lazy-loaded)
+        self.assertLessEqual(len(ctx.captured_queries), 2)
diff --git a/apps/client/tests/test_client_merge_service.py b/apps/company/tests/test_company_merge_service.py
similarity index 74%
rename from apps/client/tests/test_client_merge_service.py
rename to apps/company/tests/test_company_merge_service.py
index 4035412de..413af31b5 100644
--- a/apps/client/tests/test_client_merge_service.py
+++ b/apps/company/tests/test_company_merge_service.py
@@ -1,7 +1,7 @@
 """
-Tests for apps.client.services.client_merge_service.
+Tests for apps.company.services.company_merge_service.
 
-Covers the 8 FK fields that point at Client, plus chain walking, circular
+Covers the 8 FK fields that point at Company, plus chain walking, circular
 chains, idempotency, the source==destination guard, atomic rollback on
 failure, and the JobEvent audit trail on Job reassignment.
 """
@@ -15,8 +15,8 @@
 from django.utils import timezone
 
 from apps.accounting.models import Bill, CreditNote, Invoice, Quote
-from apps.client.models import Client, ClientContact, ClientContactMethod
-from apps.client.services.client_merge_service import reassign_client_fk_records
+from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.services.company_merge_service import reassign_company_fk_records
 from apps.crm.models import PhoneCallRecord
 from apps.job.models import Job, JobEvent
 from apps.purchasing.models import PurchaseOrder
@@ -28,8 +28,8 @@
 # ---------------------------------------------------------------------------
 
 
-def make_client(name: str) -> Client:
-    return Client.objects.create(
+def make_company(name: str) -> Company:
+    return Company.objects.create(
         name=name,
         xero_last_modified=timezone.now(),
     )
@@ -38,22 +38,22 @@ def make_client(name: str) -> Client:
 _next_job_number = {"n": 90000}
 
 
-def make_job(client: Client, staff, *, name: str = "Test Job") -> Job:
+def make_job(company: Company, staff, *, name: str = "Test Job") -> Job:
     _next_job_number["n"] += 1
     job = Job(
         name=name,
         job_number=_next_job_number["n"],
-        client=client,
+        company=company,
     )
     job.save(staff=staff)
     return job
 
 
-def _invoice_fields(client: Client) -> dict:
+def _invoice_fields(company: Company) -> dict:
     return {
         "xero_id": uuid.uuid4(),
         "number": f"TEST-{uuid.uuid4().hex[:8]}",
-        "client": client,
+        "company": company,
         "date": date.today(),
         "total_excl_tax": Decimal("100.00"),
         "tax": Decimal("15.00"),
@@ -64,36 +64,36 @@ def _invoice_fields(client: Client) -> dict:
     }
 
 
-def make_invoice(client: Client) -> Invoice:
-    return Invoice.objects.create(**_invoice_fields(client))
+def make_invoice(company: Company) -> Invoice:
+    return Invoice.objects.create(**_invoice_fields(company))
 
 
-def make_bill(client: Client) -> Bill:
-    return Bill.objects.create(**_invoice_fields(client))
+def make_bill(company: Company) -> Bill:
+    return Bill.objects.create(**_invoice_fields(company))
 
 
-def make_credit_note(client: Client) -> CreditNote:
-    return CreditNote.objects.create(**_invoice_fields(client))
+def make_credit_note(company: Company) -> CreditNote:
+    return CreditNote.objects.create(**_invoice_fields(company))
 
 
-def make_quote(client: Client) -> Quote:
+def make_quote(company: Company) -> Quote:
     return Quote.objects.create(
         xero_id=uuid.uuid4(),
-        client=client,
+        company=company,
         date=date.today(),
         total_excl_tax=Decimal("100.00"),
         total_incl_tax=Decimal("115.00"),
     )
 
 
-def make_purchase_order(supplier: Client) -> PurchaseOrder:
+def make_purchase_order(supplier: Company) -> PurchaseOrder:
     return PurchaseOrder.objects.create(
         supplier=supplier,
         po_number=f"PO-{uuid.uuid4().hex[:8]}",
     )
 
 
-def make_supplier_price_list(supplier: Client) -> SupplierPriceList:
+def make_supplier_price_list(supplier: Company) -> SupplierPriceList:
     return SupplierPriceList.objects.create(
         supplier=supplier,
         file_name="test.csv",
@@ -101,7 +101,7 @@ def make_supplier_price_list(supplier: Client) -> SupplierPriceList:
 
 
 def make_supplier_product(
-    supplier: Client, price_list: SupplierPriceList
+    supplier: Company, price_list: SupplierPriceList
 ) -> SupplierProduct:
     return SupplierProduct.objects.create(
         supplier=supplier,
@@ -113,12 +113,12 @@ def make_supplier_product(
     )
 
 
-def make_scrape_job(supplier: Client) -> ScrapeJob:
+def make_scrape_job(supplier: Company) -> ScrapeJob:
     return ScrapeJob.objects.create(supplier=supplier)
 
 
 def make_phone_call(
-    client: Client, *, contact: ClientContact | None = None
+    company: Company, *, contact: ClientContact | None = None
 ) -> PhoneCallRecord:
     call_datetime = timezone.now()
     return PhoneCallRecord.objects.create(
@@ -129,7 +129,7 @@ def make_phone_call(
         call_time=call_datetime.time(),
         origin="+6421555123",
         destination="+6496365131",
-        client=client,
+        company=company,
         contact=contact,
         raw_json={},
     )
@@ -144,20 +144,20 @@ def make_phone_call(
 class ReassignFKBaseCase(BaseTestCase):
     def setUp(self) -> None:
         super().setUp()
-        self.source = make_client("Source Client")
-        self.destination = make_client("Destination Client")
+        self.source = make_company("Source Company")
+        self.destination = make_company("Destination Company")
 
 
 class ReassignJobTests(ReassignFKBaseCase):
     def test_job_moves_to_destination(self) -> None:
         job = make_job(self.source, self.test_staff)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         job.refresh_from_db()
-        self.assertEqual(job.client_id, self.destination.id)
+        self.assertEqual(job.company_id, self.destination.id)
         self.assertEqual(counts["jobs"], 1)
 
 
@@ -165,12 +165,12 @@ class ReassignInvoiceTests(ReassignFKBaseCase):
     def test_invoice_moves_to_destination(self) -> None:
         invoice = make_invoice(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         invoice.refresh_from_db()
-        self.assertEqual(invoice.client_id, self.destination.id)
+        self.assertEqual(invoice.company_id, self.destination.id)
         self.assertEqual(counts["invoices"], 1)
 
 
@@ -178,12 +178,12 @@ class ReassignBillTests(ReassignFKBaseCase):
     def test_bill_moves_to_destination(self) -> None:
         bill = make_bill(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         bill.refresh_from_db()
-        self.assertEqual(bill.client_id, self.destination.id)
+        self.assertEqual(bill.company_id, self.destination.id)
         self.assertEqual(counts["bills"], 1)
 
 
@@ -191,12 +191,12 @@ class ReassignCreditNoteTests(ReassignFKBaseCase):
     def test_credit_note_moves_to_destination(self) -> None:
         cn = make_credit_note(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         cn.refresh_from_db()
-        self.assertEqual(cn.client_id, self.destination.id)
+        self.assertEqual(cn.company_id, self.destination.id)
         self.assertEqual(counts["credit_notes"], 1)
 
 
@@ -204,12 +204,12 @@ class ReassignQuoteTests(ReassignFKBaseCase):
     def test_quote_moves_to_destination(self) -> None:
         quote = make_quote(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         quote.refresh_from_db()
-        self.assertEqual(quote.client_id, self.destination.id)
+        self.assertEqual(quote.company_id, self.destination.id)
         self.assertEqual(counts["quotes"], 1)
 
 
@@ -217,7 +217,7 @@ class ReassignPurchaseOrderTests(ReassignFKBaseCase):
     def test_purchase_order_supplier_moves_to_destination(self) -> None:
         po = make_purchase_order(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -231,7 +231,7 @@ def test_supplier_product_moves_to_destination(self) -> None:
         price_list = make_supplier_price_list(self.source)
         product = make_supplier_product(self.source, price_list)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -244,7 +244,7 @@ class ReassignSupplierPriceListTests(ReassignFKBaseCase):
     def test_supplier_price_list_moves_to_destination(self) -> None:
         price_list = make_supplier_price_list(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -257,7 +257,7 @@ class ReassignScrapeJobTests(ReassignFKBaseCase):
     def test_scrape_job_moves_to_destination(self) -> None:
         scrape = make_scrape_job(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -283,7 +283,7 @@ def test_all_fk_types_move_in_one_call(self) -> None:
         product = make_supplier_product(self.source, price_list)
         scrape = make_scrape_job(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -297,11 +297,11 @@ def test_all_fk_types_move_in_one_call(self) -> None:
         product.refresh_from_db()
         scrape.refresh_from_db()
 
-        self.assertEqual(job.client_id, self.destination.id)
-        self.assertEqual(invoice.client_id, self.destination.id)
-        self.assertEqual(bill.client_id, self.destination.id)
-        self.assertEqual(cn.client_id, self.destination.id)
-        self.assertEqual(quote.client_id, self.destination.id)
+        self.assertEqual(job.company_id, self.destination.id)
+        self.assertEqual(invoice.company_id, self.destination.id)
+        self.assertEqual(bill.company_id, self.destination.id)
+        self.assertEqual(cn.company_id, self.destination.id)
+        self.assertEqual(quote.company_id, self.destination.id)
         self.assertEqual(po.supplier_id, self.destination.id)
         self.assertEqual(price_list.supplier_id, self.destination.id)
         self.assertEqual(product.supplier_id, self.destination.id)
@@ -328,21 +328,21 @@ def test_all_fk_types_move_in_one_call(self) -> None:
 
 class ReassignCrmHistoryTests(ReassignFKBaseCase):
     def test_contact_methods_and_phone_calls_move_to_destination(self) -> None:
-        contact = ClientContact.objects.create(client=self.source, name="Jane Smith")
+        contact = ClientContact.objects.create(company=self.source, name="Jane Smith")
         method = ClientContactMethod.objects.create(
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        client_method = ClientContactMethod.objects.create(
-            client=self.source,
+        company_method = ClientContactMethod.objects.create(
+            company=self.source,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 124",
         )
         contact_call = make_phone_call(self.source, contact=contact)
-        client_call = make_phone_call(self.source)
+        company_call = make_phone_call(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source,
             self.destination,
             self.test_staff,
@@ -350,27 +350,27 @@ def test_contact_methods_and_phone_calls_move_to_destination(self) -> None:
 
         contact.refresh_from_db()
         method.refresh_from_db()
-        client_method.refresh_from_db()
+        company_method.refresh_from_db()
         contact_call.refresh_from_db()
-        client_call.refresh_from_db()
+        company_call.refresh_from_db()
 
-        self.assertEqual(contact.client_id, self.destination.id)
+        self.assertEqual(contact.company_id, self.destination.id)
         self.assertEqual(method.contact_id, contact.id)
-        self.assertEqual(client_method.client_id, self.destination.id)
-        self.assertEqual(contact_call.client_id, self.destination.id)
+        self.assertEqual(company_method.company_id, self.destination.id)
+        self.assertEqual(contact_call.company_id, self.destination.id)
         self.assertEqual(contact_call.contact_id, contact.id)
-        self.assertEqual(client_call.client_id, self.destination.id)
+        self.assertEqual(company_call.company_id, self.destination.id)
         self.assertEqual(counts["contacts"], 1)
         self.assertEqual(counts["contact_methods"], 1)
         self.assertEqual(counts["phone_calls"], 2)
 
     def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
         source_contact = ClientContact.objects.create(
-            client=self.source,
+            company=self.source,
             name="Jane Smith",
         )
         destination_contact = ClientContact.objects.create(
-            client=self.destination,
+            company=self.destination,
             name="Jane Smith",
         )
         method = ClientContactMethod.objects.create(
@@ -380,7 +380,7 @@ def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
         )
         call = make_phone_call(self.source, contact=source_contact)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source,
             self.destination,
             self.test_staff,
@@ -391,7 +391,7 @@ def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
 
         self.assertFalse(ClientContact.objects.filter(id=source_contact.id).exists())
         self.assertEqual(method.contact_id, destination_contact.id)
-        self.assertEqual(call.client_id, self.destination.id)
+        self.assertEqual(call.company_id, self.destination.id)
         self.assertEqual(call.contact_id, destination_contact.id)
         self.assertEqual(counts["contacts"], 1)
         self.assertEqual(counts["contact_methods"], 1)
@@ -399,7 +399,7 @@ def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
 
 
 class ContactMethodMergeGuardTests(ReassignFKBaseCase):
-    """Merges must never trip the one-number-one-client save() guard.
+    """Merges must never trip the one-number-one-company save() guard.
 
     Merging is the documented remedy the Duplicate Phones report points users
     at, so it has to succeed for exactly the data shapes the guard flags.
@@ -407,11 +407,11 @@ class ContactMethodMergeGuardTests(ReassignFKBaseCase):
 
     NUMBER = "021 555 123"
 
-    def _grandfathered_method(self, client: Client) -> ClientContactMethod:
-        """Insert a cross-client duplicate bypassing the save() guard,
+    def _grandfathered_method(self, company: Company) -> ClientContactMethod:
+        """Insert a cross-company duplicate bypassing the save() guard,
         exactly as pre-guard legacy rows (and migration 0023 twins) exist."""
         legacy = ClientContactMethod(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
@@ -419,12 +419,12 @@ def _grandfathered_method(self, client: Client) -> ClientContactMethod:
         ClientContactMethod.objects.bulk_create([legacy])
         return legacy
 
-    def test_same_number_on_client_and_own_contact_both_move(self) -> None:
-        """Migration 0023 creates client-level + contact-level twins; a merge
+    def test_same_number_on_company_and_own_contact_both_move(self) -> None:
+        """Migration 0023 creates company-level + contact-level twins; a merge
         must move both without the guard rejecting the not-yet-moved sibling."""
-        contact = ClientContact.objects.create(client=self.source, name="Jane Smith")
-        client_method = ClientContactMethod.objects.create(
-            client=self.source,
+        contact = ClientContact.objects.create(company=self.source, name="Jane Smith")
+        company_method = ClientContactMethod.objects.create(
+            company=self.source,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
@@ -434,47 +434,47 @@ def test_same_number_on_client_and_own_contact_both_move(self) -> None:
             value=self.NUMBER,
         )
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
-        client_method.refresh_from_db()
+        company_method.refresh_from_db()
         contact_method.refresh_from_db()
         contact.refresh_from_db()
-        self.assertEqual(client_method.client_id, self.destination.id)
-        self.assertEqual(contact.client_id, self.destination.id)
+        self.assertEqual(company_method.company_id, self.destination.id)
+        self.assertEqual(contact.company_id, self.destination.id)
         self.assertEqual(contact_method.contact_id, contact.id)
         self.assertEqual(counts["contact_methods"], 1)
         self.assertEqual(counts["contacts"], 1)
 
-    def test_merge_succeeds_when_third_client_owns_same_number(self) -> None:
-        """A grandfathered duplicate on an unrelated client must not block
+    def test_merge_succeeds_when_third_company_owns_same_number(self) -> None:
+        """A grandfathered duplicate on an unrelated company must not block
         merging A into B."""
         source_method = ClientContactMethod.objects.create(
-            client=self.source,
+            company=self.source,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
-        third = make_client("Third Client")
+        third = make_company("Third Company")
         self._grandfathered_method(third)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
         source_method.refresh_from_db()
-        self.assertEqual(source_method.client_id, self.destination.id)
+        self.assertEqual(source_method.company_id, self.destination.id)
         self.assertEqual(counts["contact_methods"], 1)
 
     def test_duplicate_of_destination_number_is_dropped_not_duplicated(self) -> None:
         destination_method = ClientContactMethod.objects.create(
-            client=self.destination,
+            company=self.destination,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
         source_method = self._grandfathered_method(self.source)
 
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -492,23 +492,23 @@ def test_moving_primary_method_demotes_destination_primary(self) -> None:
         """The bulk move must not violate the single-primary-per-owner
         constraint when both sides have a primary phone."""
         destination_primary = ClientContactMethod.objects.create(
-            client=self.destination,
+            company=self.destination,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 999",
             is_primary=True,
         )
         source_primary = ClientContactMethod.objects.create(
-            client=self.source,
+            company=self.source,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=self.NUMBER,
             is_primary=True,
         )
 
-        reassign_client_fk_records(self.source, self.destination, self.test_staff)
+        reassign_company_fk_records(self.source, self.destination, self.test_staff)
 
         destination_primary.refresh_from_db()
         source_primary.refresh_from_db()
-        self.assertEqual(source_primary.client_id, self.destination.id)
+        self.assertEqual(source_primary.company_id, self.destination.id)
         self.assertTrue(source_primary.is_primary)
         self.assertFalse(destination_primary.is_primary)
 
@@ -520,10 +520,10 @@ def test_moving_primary_method_demotes_destination_primary(self) -> None:
 
 class SourceEqualsDestinationGuardTests(BaseTestCase):
     def test_raises_value_error_when_source_equals_destination(self) -> None:
-        client = make_client("Only Client")
+        company = make_company("Only Company")
 
         with self.assertRaises(ValueError):
-            reassign_client_fk_records(client, client, self.test_staff)
+            reassign_company_fk_records(company, company, self.test_staff)
 
 
 class IdempotencyTests(ReassignFKBaseCase):
@@ -531,10 +531,10 @@ def test_second_call_returns_all_zero_counts(self) -> None:
         make_job(self.source, self.test_staff)
         make_invoice(self.source)
 
-        first_counts = reassign_client_fk_records(
+        first_counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
-        second_counts = reassign_client_fk_records(
+        second_counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
 
@@ -545,11 +545,11 @@ def test_second_call_returns_all_zero_counts(self) -> None:
 
 
 class JobEventTests(ReassignFKBaseCase):
-    def test_job_reassignment_creates_client_changed_event(self) -> None:
+    def test_job_reassignment_creates_company_changed_event(self) -> None:
         job = make_job(self.source, self.test_staff)
         events_before = JobEvent.objects.filter(job=job).count()
 
-        reassign_client_fk_records(self.source, self.destination, self.test_staff)
+        reassign_company_fk_records(self.source, self.destination, self.test_staff)
 
         job.refresh_from_db()
         events_after = JobEvent.objects.filter(job=job).count()
@@ -560,7 +560,7 @@ def test_job_reassignment_creates_client_changed_event(self) -> None:
         )
         latest = JobEvent.objects.filter(job=job).latest("timestamp")
         self.assertEqual(latest.event_type, "client_changed")
-        self.assertEqual(latest.delta_after["client_id"], str(self.destination.id))
+        self.assertEqual(latest.delta_after["company_id"], str(self.destination.id))
 
 
 # ---------------------------------------------------------------------------
@@ -570,45 +570,45 @@ def test_job_reassignment_creates_client_changed_event(self) -> None:
 
 class ChainWalkingTests(BaseTestCase):
     def test_caller_can_pass_terminal_of_chain_as_destination(self) -> None:
-        """A -> B -> C. Caller picks C (via get_final_client) as destination.
+        """A -> B -> C. Caller picks C (via get_final_company) as destination.
         Jobs originally on A should land on C."""
-        c = make_client("C")
-        b = make_client("B")
-        a = make_client("A")
+        c = make_company("C")
+        b = make_company("B")
+        a = make_company("A")
         b.merged_into = c
         b.save()
         a.merged_into = b
         a.save()
 
-        self.assertEqual(a.get_final_client().id, c.id)
+        self.assertEqual(a.get_final_company().id, c.id)
 
         job = make_job(a, self.test_staff)
 
-        reassign_client_fk_records(a, a.get_final_client(), self.test_staff)
+        reassign_company_fk_records(a, a.get_final_company(), self.test_staff)
 
         job.refresh_from_db()
-        self.assertEqual(job.client_id, c.id)
+        self.assertEqual(job.company_id, c.id)
 
-    def test_circular_chain_terminates_at_precycle_client(self) -> None:
-        """A -> B -> A (circular). get_final_client() stops at pre-cycle
+    def test_circular_chain_terminates_at_precycle_company(self) -> None:
+        """A -> B -> A (circular). get_final_company() stops at pre-cycle
         terminal (A itself here). Caller guards with source != destination —
         we confirm that path raises rather than loops forever."""
-        a = make_client("A")
-        b = make_client("B")
+        a = make_company("A")
+        b = make_company("B")
         b.merged_into = a
         b.save()
         a.merged_into = b
         a.save()
 
-        terminal = a.get_final_client()
+        terminal = a.get_final_company()
         # The cycle-guard returns either A or B; caller is responsible for
         # not passing source as destination. Service must refuse the no-op.
         if terminal.id == a.id:
             with self.assertRaises(ValueError):
-                reassign_client_fk_records(a, terminal, self.test_staff)
+                reassign_company_fk_records(a, terminal, self.test_staff)
         else:
             make_job(a, self.test_staff)
-            counts = reassign_client_fk_records(a, terminal, self.test_staff)
+            counts = reassign_company_fk_records(a, terminal, self.test_staff)
             self.assertEqual(counts["jobs"], 1)
 
 
@@ -644,10 +644,10 @@ def __getattr__(self, name):
 
         with patch.object(Quote.objects, "filter", side_effect=_exploding_filter):
             with patch(
-                "apps.client.services.client_merge_service.persist_app_error"
+                "apps.company.services.company_merge_service.persist_app_error"
             ) as mock_persist:
                 with self.assertRaises(IntegrityError):
-                    reassign_client_fk_records(
+                    reassign_company_fk_records(
                         self.source, self.destination, self.test_staff
                     )
 
@@ -655,10 +655,10 @@ def __getattr__(self, name):
                 self.assertTrue(mock_persist.called)
 
         # Nothing should have moved — transaction rolled back.
-        self.assertEqual(Job.objects.filter(client=self.source).count(), 1)
-        self.assertEqual(Invoice.objects.filter(client=self.source).count(), 1)
-        self.assertEqual(Job.objects.filter(client=self.destination).count(), 0)
-        self.assertEqual(Invoice.objects.filter(client=self.destination).count(), 0)
+        self.assertEqual(Job.objects.filter(company=self.source).count(), 1)
+        self.assertEqual(Invoice.objects.filter(company=self.source).count(), 1)
+        self.assertEqual(Job.objects.filter(company=self.destination).count(), 0)
+        self.assertEqual(Invoice.objects.filter(company=self.destination).count(), 0)
 
 
 # ---------------------------------------------------------------------------
@@ -668,7 +668,7 @@ def __getattr__(self, name):
 
 class NoRecordsToMoveTests(ReassignFKBaseCase):
     def test_zero_records_returns_all_zero_counts(self) -> None:
-        counts = reassign_client_fk_records(
+        counts = reassign_company_fk_records(
             self.source, self.destination, self.test_staff
         )
         self.assertEqual(
diff --git a/apps/client/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
similarity index 71%
rename from apps/client/tests/test_contact_methods.py
rename to apps/company/tests/test_contact_methods.py
index be697b356..025a575f0 100644
--- a/apps/client/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -4,15 +4,15 @@
 from django.test import TestCase
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.crm.models import PhoneCallRecord
 from apps.crm.services.phone_call_service import rematch_calls_for_numbers
 from apps.testing import BaseAPITestCase
 
 
 class ClientContactMethodTests(TestCase):
-    def _client(self, name: str = "Acme Ltd") -> Client:
-        return Client.objects.create(name=name, xero_last_modified=timezone.now())
+    def _company(self, name: str = "Acme Ltd") -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
     def test_phone_normalization_matches_nz_variants(self) -> None:
         """Catches call matching failures when NZ local and E.164 numbers diverge."""
@@ -25,17 +25,17 @@ def test_phone_normalization_matches_nz_variants(self) -> None:
             "+6496365131",
         )
 
-    def test_primary_phone_is_single_per_client_owner(self) -> None:
-        """Catches multiple primary phone numbers being left on a client record."""
-        client = self._client()
+    def test_primary_phone_is_single_per_company_owner(self) -> None:
+        """Catches multiple primary phone numbers being left on a company record."""
+        company = self._company()
         first = ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
         second = ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 222 2222",
             is_primary=True,
@@ -47,12 +47,12 @@ def test_primary_phone_is_single_per_client_owner(self) -> None:
         self.assertFalse(first.is_primary)
         self.assertTrue(second.is_primary)
 
-    def test_same_number_allowed_on_client_and_its_own_contact(self) -> None:
-        """A client and its own contact sharing one line must not be rejected."""
-        client = self._client()
-        contact = ClientContact.objects.create(client=client, name="Jane Smith")
-        on_client = ClientContactMethod.objects.create(
-            client=client,
+    def test_same_number_allowed_on_company_and_its_own_contact(self) -> None:
+        """A company and its own contact sharing one line must not be rejected."""
+        company = self._company()
+        contact = ClientContact.objects.create(company=company, name="Jane Smith")
+        on_company = ClientContactMethod.objects.create(
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
@@ -62,14 +62,14 @@ def test_same_number_allowed_on_client_and_its_own_contact(self) -> None:
             value="021 111 111",
         )
 
-        self.assertEqual(on_client.normalized_value, on_contact.normalized_value)
+        self.assertEqual(on_company.normalized_value, on_contact.normalized_value)
         self.assertIsNotNone(on_contact.pk)
 
-    def test_same_number_allowed_on_two_contacts_of_same_client(self) -> None:
-        """Two contacts of one client can share a number (one effective client)."""
-        client = self._client()
-        first_contact = ClientContact.objects.create(client=client, name="A")
-        second_contact = ClientContact.objects.create(client=client, name="B")
+    def test_same_number_allowed_on_two_contacts_of_same_company(self) -> None:
+        """Two contacts of one company can share a number (one effective company)."""
+        company = self._company()
+        first_contact = ClientContact.objects.create(company=company, name="A")
+        second_contact = ClientContact.objects.create(company=company, name="B")
         ClientContactMethod.objects.create(
             contact=first_contact,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -83,28 +83,28 @@ def test_same_number_allowed_on_two_contacts_of_same_client(self) -> None:
 
         self.assertIsNotNone(on_second.pk)
 
-    def test_same_number_rejected_across_different_clients(self) -> None:
-        """Two different clients cannot own one number; the matcher would be ambiguous."""
-        client_a = self._client("Acme Ltd")
-        client_b = self._client("Beta Ltd")
+    def test_same_number_rejected_across_different_companies(self) -> None:
+        """Two different companies cannot own one number; the matcher would be ambiguous."""
+        company_a = self._company("Acme Ltd")
+        company_b = self._company("Beta Ltd")
         ClientContactMethod.objects.create(
-            client=client_a,
+            company=company_a,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         with self.assertRaises(ValidationError):
             ClientContactMethod.objects.create(
-                client=client_b,
+                company=company_b,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 value="021 111 111",
             )
 
-    def test_same_number_rejected_across_contacts_of_different_clients(self) -> None:
-        """Contacts of two different clients cannot share a number."""
-        client_a = self._client("Acme Ltd")
-        client_b = self._client("Beta Ltd")
-        contact_a = ClientContact.objects.create(client=client_a, name="A")
-        contact_b = ClientContact.objects.create(client=client_b, name="B")
+    def test_same_number_rejected_across_contacts_of_different_companies(self) -> None:
+        """Contacts of two different companies cannot share a number."""
+        company_a = self._company("Acme Ltd")
+        company_b = self._company("Beta Ltd")
+        contact_a = ClientContact.objects.create(company=company_a, name="A")
+        contact_b = ClientContact.objects.create(company=company_b, name="B")
         ClientContactMethod.objects.create(
             contact=contact_a,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -117,19 +117,19 @@ def test_same_number_rejected_across_contacts_of_different_clients(self) -> None
                 value="021 111 111",
             )
 
-    def test_grandfathered_cross_client_number_can_be_resaved(self) -> None:
-        """A pre-existing cross-client number (legacy data) re-saves unchanged."""
-        client_a = self._client("Acme Ltd")
-        client_b = self._client("Beta Ltd")
+    def test_grandfathered_cross_company_number_can_be_resaved(self) -> None:
+        """A pre-existing cross-company number (legacy data) re-saves unchanged."""
+        company_a = self._company("Acme Ltd")
+        company_b = self._company("Beta Ltd")
         ClientContactMethod.objects.create(
-            client=client_a,
+            company=company_a,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         # Simulate legacy prod data: B already owns the same number, inserted
         # bypassing the guard (as pre-guard rows were).
         legacy = ClientContactMethod(
-            client=client_b,
+            company=company_b,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
@@ -143,29 +143,29 @@ def test_grandfathered_cross_client_number_can_be_resaved(self) -> None:
         legacy.refresh_from_db()
         self.assertEqual(legacy.label, "Mobile")
 
-    def test_changing_number_into_another_clients_ownership_raises(self) -> None:
-        """Editing a method's number onto another client's number is blocked."""
-        client_a = self._client("Acme Ltd")
-        client_b = self._client("Beta Ltd")
+    def test_changing_number_into_another_companies_ownership_raises(self) -> None:
+        """Editing a method's number onto another company's number is blocked."""
+        company_a = self._company("Acme Ltd")
+        company_b = self._company("Beta Ltd")
         ClientContactMethod.objects.create(
-            client=client_a,
+            company=company_a,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         moving = ClientContactMethod.objects.create(
-            client=client_b,
+            company=company_b,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 222 222",
         )
 
-        moving.value = "021 111 111"  # now collides with client A
+        moving.value = "021 111 111"  # now collides with company A
         with self.assertRaises(ValidationError):
             moving.save()
 
     def test_primary_phone_is_single_per_contact_owner(self) -> None:
         """Catches multiple primary phone numbers being left on a contact record."""
-        client = self._client()
-        contact = ClientContact.objects.create(client=client, name="Jane Smith")
+        company = self._company()
+        contact = ClientContact.objects.create(company=company, name="Jane Smith")
         first = ClientContactMethod.objects.create(
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -188,9 +188,9 @@ def test_primary_phone_is_single_per_contact_owner(self) -> None:
     def test_partial_update_fields_still_persists_normalized_value(self) -> None:
         """save(update_fields=["value"]) must also persist the recomputed
         normalized_value, or the matching/uniqueness index goes stale."""
-        client = self._client("Acme Ltd")
+        company = self._company("Acme Ltd")
         method = ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
@@ -205,57 +205,57 @@ def test_partial_update_fields_still_persists_normalized_value(self) -> None:
         )
 
 
-class ClientPrimaryPhoneValueTests(TestCase):
+class CompanyPrimaryPhoneValueTests(TestCase):
     """Guards the helper PO PDFs and Xero sync use to print a supplier phone."""
 
     def test_returns_primary_phone_first(self) -> None:
-        client = Client.objects.create(
+        company = Company.objects.create(
             name="Acme Ltd", xero_last_modified=timezone.now()
         )
         ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 111 1111",
         )
         ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 222 2222",
             is_primary=True,
         )
 
-        self.assertEqual(client.primary_phone_value(), "09 222 2222")
+        self.assertEqual(company.primary_phone_value(), "09 222 2222")
 
     def test_returns_empty_string_when_no_phone_methods(self) -> None:
-        client = Client.objects.create(
+        company = Company.objects.create(
             name="Phoneless Ltd", xero_last_modified=timezone.now()
         )
         ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.EMAIL,
             value="office@example.com",
         )
 
-        self.assertEqual(client.primary_phone_value(), "")
+        self.assertEqual(company.primary_phone_value(), "")
 
 
 class ClientContactMethodApiTests(BaseAPITestCase):
-    def _client(self, name: str = "Acme Ltd") -> Client:
-        return Client.objects.create(name=name, xero_last_modified=timezone.now())
+    def _company(self, name: str = "Acme Ltd") -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
     def test_list_paginates_phone_contact_methods(self) -> None:
         """Catches CRM calls page regressions that fetch every phone method."""
         self.client.force_authenticate(user=self.test_staff)
-        client = self._client("Acme Ltd")
+        company = self._company("Acme Ltd")
         for index in range(3):
             ClientContactMethod.objects.create(
-                client=client,
+                company=company,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 value=f"021 555 10{index}",
             )
 
         response = self.client.get(
-            "/api/clients/contact-methods/",
+            "/api/companies/contact-methods/",
             {"method_type": "phone", "page_size": "2"},
         )
 
@@ -270,16 +270,16 @@ def test_list_paginates_phone_contact_methods(self) -> None:
     def test_list_page_size_is_capped(self) -> None:
         """Catches accidental oversized contact-method responses."""
         self.client.force_authenticate(user=self.test_staff)
-        client = self._client("Acme Ltd")
+        company = self._company("Acme Ltd")
         for index in range(101):
             ClientContactMethod.objects.create(
-                client=client,
+                company=company,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 value=f"021 555 {index:03d}",
             )
 
         response = self.client.get(
-            "/api/clients/contact-methods/",
+            "/api/companies/contact-methods/",
             {"method_type": "phone", "page_size": "250"},
         )
 
@@ -292,22 +292,22 @@ def test_list_page_size_is_capped(self) -> None:
     def test_updating_phone_contact_method_rematches_affected_calls(self) -> None:
         """Catches stale call ownership after a customer phone number changes."""
         self.client.force_authenticate(user=self.test_staff)
-        client = self._client("Acme Ltd")
+        company = self._company("Acme Ltd")
         method = ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
-        old_call = self._call("old-number", origin="021 555 100", client=client)
-        new_call = self._call("new-number", origin="021 555 200", client=None)
+        old_call = self._call("old-number", origin="021 555 100", company=company)
+        new_call = self._call("new-number", origin="021 555 200", company=None)
 
         with patch(
-            "apps.client.views.client_contact_method_viewset."
+            "apps.company.views.contact_method_viewset."
             "rematch_phone_calls_task.delay",
             side_effect=rematch_calls_for_numbers,
         ) as rematch:
             response = self.client.patch(
-                f"/api/clients/contact-methods/{method.id}/",
+                f"/api/companies/contact-methods/{method.id}/",
                 {"value": "021 555 200"},
                 format="json",
             )
@@ -316,38 +316,40 @@ def test_updating_phone_contact_method_rematches_affected_calls(self) -> None:
         rematch.assert_called_once_with(["+6421555100", "+6421555200"])
         old_call.refresh_from_db()
         new_call.refresh_from_db()
-        self.assertIsNone(old_call.client)
-        self.assertEqual(new_call.client, client)
+        self.assertIsNone(old_call.company)
+        self.assertEqual(new_call.company, company)
 
     def test_deleting_phone_contact_method_unmatches_affected_calls(self) -> None:
         """Catches deleted phone numbers continuing to own CRM calls."""
         self.client.force_authenticate(user=self.test_staff)
-        client = self._client("Acme Ltd")
+        company = self._company("Acme Ltd")
         method = ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
-        call = self._call("deleted-number", origin="021 555 100", client=client)
+        call = self._call("deleted-number", origin="021 555 100", company=company)
 
         with patch(
-            "apps.client.views.client_contact_method_viewset."
+            "apps.company.views.contact_method_viewset."
             "rematch_phone_calls_task.delay",
             side_effect=rematch_calls_for_numbers,
         ) as rematch:
-            response = self.client.delete(f"/api/clients/contact-methods/{method.id}/")
+            response = self.client.delete(
+                f"/api/companies/contact-methods/{method.id}/"
+            )
 
         self.assertEqual(response.status_code, 204)
         rematch.assert_called_once_with(["+6421555100"])
         call.refresh_from_db()
-        self.assertIsNone(call.client)
+        self.assertIsNone(call.company)
 
     def _call(
         self,
         provider_id: str,
         *,
         origin: str,
-        client: Client | None,
+        company: Company | None,
     ) -> PhoneCallRecord:
         call_datetime = timezone.now()
         return PhoneCallRecord.objects.create(
@@ -358,7 +360,7 @@ def _call(
             call_time=call_datetime.time(),
             origin=origin,
             destination="+6496365131",
-            client=client,
+            company=company,
             raw_json={
                 "id": provider_id,
                 "calldate": timezone.localdate().isoformat(),
diff --git a/apps/client/tests/test_duplicate_phone_report.py b/apps/company/tests/test_duplicate_phone_report.py
similarity index 74%
rename from apps/client/tests/test_duplicate_phone_report.py
rename to apps/company/tests/test_duplicate_phone_report.py
index 79dc0b4f9..d52eac761 100644
--- a/apps/client/tests/test_duplicate_phone_report.py
+++ b/apps/company/tests/test_duplicate_phone_report.py
@@ -1,24 +1,24 @@
 from django.test import TestCase
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact, ClientContactMethod
-from apps.client.services.duplicate_phone_report import DuplicatePhoneReportService
+from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.services.duplicate_phone_report import DuplicatePhoneReportService
 from apps.crm.models import PhoneEndpoint
 
 
 class DuplicatePhoneReportTests(TestCase):
-    def _client(self, name: str) -> Client:
-        return Client.objects.create(name=name, xero_last_modified=timezone.now())
+    def _company(self, name: str) -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
     def _phone(
         self,
         value: str,
-        client: Client | None = None,
+        company: Company | None = None,
         contact: ClientContact | None = None,
     ) -> ClientContactMethod:
         """Insert a phone method bypassing the save() guard (legacy-style data)."""
         method = ClientContactMethod(
-            client=client,
+            company=company,
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=value,
@@ -27,11 +27,11 @@ def _phone(
         ClientContactMethod.objects.bulk_create([method])
         return method
 
-    def test_detects_cross_client_number(self) -> None:
-        acme = self._client("Acme Ltd")
-        beta = self._client("Beta Ltd")
-        self._phone("021 111 111", client=acme)
-        self._phone("021 111 111", client=beta)
+    def test_detects_cross_company_number(self) -> None:
+        acme = self._company("Acme Ltd")
+        beta = self._company("Beta Ltd")
+        self._phone("021 111 111", company=acme)
+        self._phone("021 111 111", company=beta)
 
         report = DuplicatePhoneReportService().get_report()
 
@@ -45,8 +45,8 @@ def test_detects_cross_client_number(self) -> None:
         self.assertEqual(report["summary"]["cross_client"], 1)
 
     def test_detects_internal_line_collision(self) -> None:
-        client = self._client("Acme Ltd")
-        contact = ClientContact.objects.create(client=client, name="Paul Jones")
+        company = self._company("Acme Ltd")
+        contact = ClientContact.objects.create(company=company, name="Paul Jones")
         self._phone("09 636 5131", contact=contact)
         # Bypass PhoneEndpoint.save()'s collision guard (legacy-style data):
         # the report exists precisely to surface rows that predate the guard.
@@ -69,8 +69,8 @@ def test_detects_internal_line_collision(self) -> None:
         self.assertEqual(report["summary"]["internal_line"], 1)
 
     def test_clean_data_returns_empty(self) -> None:
-        client = self._client("Acme Ltd")
-        self._phone("021 111 111", client=client)
+        company = self._company("Acme Ltd")
+        self._phone("021 111 111", company=company)
 
         report = DuplicatePhoneReportService().get_report()
 
diff --git a/apps/client/tests/test_get_client_for_xero.py b/apps/company/tests/test_get_company_for_xero.py
similarity index 75%
rename from apps/client/tests/test_get_client_for_xero.py
rename to apps/company/tests/test_get_company_for_xero.py
index 01a7c96d7..ffa94301e 100644
--- a/apps/client/tests/test_get_client_for_xero.py
+++ b/apps/company/tests/test_get_company_for_xero.py
@@ -1,4 +1,4 @@
-"""Tests for Client.get_client_for_xero().
+"""Tests for Company.get_company_for_xero().
 
 Regression coverage for Trello #305 — the snake_case dict that this method
 used to return caused Xero to silently drop every field except Name on the
@@ -12,28 +12,28 @@
 from xero_python.accounting.models import Address, Contact, Phone
 from xero_python.api_client.serializer import serialize
 
-from apps.client.models import Client, ClientContactMethod
+from apps.company.models import ClientContactMethod, Company
 
 
-class GetClientForXeroTests(TestCase):
+class GetCompanyForXeroTests(TestCase):
     """Pin the wire-format contract independent of which push function consumes it."""
 
-    def _make_client(self, **overrides):
+    def _make_company(self, **overrides):
         defaults = {
             "name": "Acme Ltd",
             "xero_last_modified": timezone.now(),
         }
         phone = overrides.pop("phone", None)
         defaults.update(overrides)
-        client = Client.objects.create(**defaults)
+        company = Company.objects.create(**defaults)
         if phone is not None:
             ClientContactMethod.objects.create(
-                client=client,
+                company=company,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 value=phone,
                 is_primary=True,
             )
-        return client
+        return company
 
     def test_returns_sdk_contact_instance(self):
         """The payload must be a xero_python Contact, not a dict.
@@ -42,36 +42,36 @@ def test_returns_sdk_contact_instance(self):
         attribute_map only translates fields for model instances; raw dicts
         ship verbatim and Xero drops every non-Name field.
         """
-        client = self._make_client()
+        company = self._make_company()
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsInstance(payload, Contact)
 
     def test_phones_are_sdk_phone_instances(self):
-        client = self._make_client(phone="027 351 8326")
+        company = self._make_company(phone="027 351 8326")
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsInstance(payload.phones[0], Phone)
 
     def test_addresses_are_sdk_address_instances(self):
-        client = self._make_client(address="123 Test Street")
+        company = self._make_company(address="123 Test Street")
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsInstance(payload.addresses[0], Address)
 
-    def test_populated_client_carries_all_fields(self):
-        """Every field a fully-populated Client supplies must reach the Contact."""
-        client = self._make_client(
+    def test_populated_company_carries_all_fields(self):
+        """Every field a fully-populated Company supplies must reach the Contact."""
+        company = self._make_company(
             email="info@acme.test",
             phone="027 351 8326",
             address="123 Test Street",
             is_account_customer=True,
         )
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertEqual(payload.name, "Acme Ltd")
         self.assertEqual(payload.email_address, "info@acme.test")
@@ -82,16 +82,16 @@ def test_populated_client_carries_all_fields(self):
         self.assertEqual(payload.addresses[0].address_line1, "123 Test Street")
         self.assertEqual(payload.addresses[0].attention_to, "Acme Ltd")
 
-    def test_existing_client_populates_contact_id_on_instance(self):
+    def test_existing_company_populates_contact_id_on_instance(self):
         """contact_id lives on the Contact, not as a caller-side dict mutation.
 
         Regression for the dict-mutation pattern at push.py:40
-        (`contact_data["ContactID"] = client.xero_contact_id`).
+        (`contact_data["ContactID"] = company.xero_contact_id`).
         """
         xero_id = "9568adbc-aaaa-bbbb-cccc-000000000001"
-        client = self._make_client(xero_contact_id=xero_id)
+        company = self._make_company(xero_contact_id=xero_id)
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertEqual(payload.contact_id, xero_id)
 
@@ -101,33 +101,33 @@ def test_no_email_emits_none_not_empty_string(self):
         Empty string overwrites any operator-typed email Xero already holds
         on a round-trip update. The masked side-effect of #305.
         """
-        client = self._make_client(email=None)
+        company = self._make_company(email=None)
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsNone(payload.email_address)
 
     def test_no_phone_emits_none_not_empty_string(self):
-        client = self._make_client(phone=None)
+        company = self._make_company(phone=None)
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsNone(payload.phones[0].phone_number)
 
     def test_no_address_emits_none_not_empty_string(self):
-        client = self._make_client(address=None)
+        company = self._make_company(address=None)
 
-        payload = client.get_client_for_xero()
+        payload = company.get_company_for_xero()
 
         self.assertIsNone(payload.addresses[0].address_line1)
 
     def test_missing_name_raises_value_error(self):
         """The name guard must still trip."""
-        client = self._make_client()
-        client.name = ""
+        company = self._make_company()
+        company.name = ""
 
         with self.assertRaises(ValueError):
-            client.get_client_for_xero()
+            company.get_company_for_xero()
 
     def test_serialized_wire_format_is_pascalcase(self):
         """End-to-end wire format check — the bytes Xero would actually receive.
@@ -139,14 +139,14 @@ def test_serialized_wire_format_is_pascalcase(self):
         the fields that were silently lost so the bug cannot regress at
         any layer between the model and the HTTP body.
         """
-        client = self._make_client(
+        company = self._make_company(
             email="info@acme.test",
             phone="027 351 8326",
             address="123 Test Street",
             is_account_customer=True,
         )
 
-        wire = serialize(client.get_client_for_xero())
+        wire = serialize(company.get_company_for_xero())
 
         self.assertEqual(wire["Name"], "Acme Ltd")
         self.assertEqual(wire["EmailAddress"], "info@acme.test")
diff --git a/apps/company/urls_rest.py b/apps/company/urls_rest.py
new file mode 100644
index 000000000..92ef7a5f2
--- /dev/null
+++ b/apps/company/urls_rest.py
@@ -0,0 +1,108 @@
+"""
+Company REST URLs
+
+REST URLs for Company module following RESTful patterns:
+- Clearly defined endpoints
+- Appropriate HTTP verbs
+- Consistent structure with other REST modules
+"""
+
+from django.urls import include, path
+from rest_framework.routers import DefaultRouter
+
+from apps.company.views.address_views import AddressValidateView
+from apps.company.views.company_rest_views import (
+    CompanyCreateRestView,
+    CompanyJobsRestView,
+    CompanyListAllRestView,
+    CompanyRetrieveRestView,
+    CompanySearchRestView,
+    CompanyUpdateRestView,
+    JobContactRestView,
+)
+from apps.company.views.contact_method_viewset import ClientContactMethodViewSet
+from apps.company.views.contact_viewset import ClientContactViewSet
+from apps.company.views.supplier_pickup_address_viewset import (
+    SupplierPickupAddressViewSet,
+)
+from apps.company.views.supplier_search_alias_views import (
+    CompanySupplierAliasListCreateView,
+    SupplierAliasDetailView,
+)
+
+app_name = "companies_rest"
+
+# Router for ViewSet-based endpoints
+router = DefaultRouter()
+router.register(
+    "contact-methods",
+    ClientContactMethodViewSet,
+    basename="contact-method",
+)
+router.register("contacts", ClientContactViewSet, basename="company-contact")
+router.register(
+    "pickup-addresses", SupplierPickupAddressViewSet, basename="supplier-pickup-address"
+)
+
+urlpatterns = [
+    # Company list all REST endpoint
+    path(
+        "all/",
+        CompanyListAllRestView.as_view(),
+        name="company_list_all_rest",
+    ),
+    # Company creation REST endpoint
+    path(
+        "create/",
+        CompanyCreateRestView.as_view(),
+        name="company_create_rest",
+    ),
+    # Company search REST endpoint
+    path(
+        "search/",
+        CompanySearchRestView.as_view(),
+        name="company_search_rest",
+    ),
+    # Company retrieve REST endpoint
+    path(
+        "<uuid:company_id>/",
+        CompanyRetrieveRestView.as_view(),
+        name="company_retrieve_rest",
+    ),
+    # Company update REST endpoint
+    path(
+        "<uuid:company_id>/update/",
+        CompanyUpdateRestView.as_view(),
+        name="company_update_rest",
+    ),
+    # Company jobs REST endpoint
+    path(
+        "<uuid:company_id>/jobs/",
+        CompanyJobsRestView.as_view(),
+        name="company_jobs_rest",
+    ),
+    path(
+        "<uuid:company_id>/supplier-aliases/",
+        CompanySupplierAliasListCreateView.as_view(),
+        name="company_supplier_aliases_rest",
+    ),
+    path(
+        "supplier-aliases/<uuid:alias_id>/",
+        SupplierAliasDetailView.as_view(),
+        name="supplier_alias_detail_rest",
+    ),
+    # Job contact REST endpoint
+    path(
+        "jobs/<uuid:job_id>/contact/",
+        JobContactRestView.as_view(),
+        name="job_contact_rest",
+    ),
+    # Address validation endpoint
+    path(
+        "addresses/validate/",
+        AddressValidateView.as_view(),
+        name="address_validate",
+    ),
+    # ViewSet routes (contacts CRUD)
+    path("", include(router.urls)),
+]
diff --git a/apps/client/utils.py b/apps/company/utils.py
similarity index 94%
rename from apps/client/utils.py
rename to apps/company/utils.py
index 63d6671ff..d9d1f0249 100644
--- a/apps/client/utils.py
+++ b/apps/company/utils.py
@@ -1,5 +1,5 @@
 """
-Client utility functions
+Company utility functions
 """
 
 from datetime import datetime, time
diff --git a/apps/client/views/__init__.py b/apps/company/views/__init__.py
similarity index 54%
rename from apps/client/views/__init__.py
rename to apps/company/views/__init__.py
index 511ab6415..57fd58ebe 100644
--- a/apps/client/views/__init__.py
+++ b/apps/company/views/__init__.py
@@ -1,17 +1,17 @@
 # This file is autogenerated by update_init.py script
 
 from .address_views import AddressValidateView
-from .client_rest_views import (
-    ClientCreateRestView,
-    ClientJobsRestView,
-    ClientListAllRestView,
-    ClientRetrieveRestView,
-    ClientSearchRestView,
-    ClientUpdateRestView,
+from .company_rest_views import (
+    CompanyCreateRestView,
+    CompanyJobsRestView,
+    CompanyListAllRestView,
+    CompanyRetrieveRestView,
+    CompanySearchRestView,
+    CompanyUpdateRestView,
     JobContactRestView,
 )
 from .supplier_search_alias_views import (
-    ClientSupplierAliasListCreateView,
+    CompanySupplierAliasListCreateView,
     SupplierAliasDetailView,
 )
 
@@ -20,8 +20,8 @@
     from django.apps import apps
 
     if apps.ready:
-        from .client_contact_method_viewset import ClientContactMethodViewSet
-        from .client_contact_viewset import ClientContactViewSet
+        from .contact_method_viewset import ClientContactMethodViewSet
+        from .contact_viewset import ClientContactViewSet
         from .supplier_pickup_address_viewset import SupplierPickupAddressViewSet
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
@@ -31,13 +31,13 @@
     "AddressValidateView",
     "ClientContactMethodViewSet",
     "ClientContactViewSet",
-    "ClientCreateRestView",
-    "ClientJobsRestView",
-    "ClientListAllRestView",
-    "ClientRetrieveRestView",
-    "ClientSearchRestView",
-    "ClientSupplierAliasListCreateView",
-    "ClientUpdateRestView",
+    "CompanyCreateRestView",
+    "CompanyJobsRestView",
+    "CompanyListAllRestView",
+    "CompanyRetrieveRestView",
+    "CompanySearchRestView",
+    "CompanySupplierAliasListCreateView",
+    "CompanyUpdateRestView",
     "JobContactRestView",
     "SupplierAliasDetailView",
     "SupplierPickupAddressViewSet",
diff --git a/apps/client/views/address_views.py b/apps/company/views/address_views.py
similarity index 97%
rename from apps/client/views/address_views.py
rename to apps/company/views/address_views.py
index 360c648ca..880f00ed5 100644
--- a/apps/client/views/address_views.py
+++ b/apps/company/views/address_views.py
@@ -14,7 +14,7 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.client.services.geocoding_service import (
+from apps.company.services.geocoding_service import (
     GeocodingError,
     GeocodingNotConfiguredError,
     geocode_address,
@@ -28,7 +28,7 @@ class AddressValidateView(APIView):
     """
     Validate and clean an address using Google Address Validation API.
 
-    POST /api/clients/addresses/validate/
+    POST /api/companies/addresses/validate/
     Body: {"address": "123 Main St Melbourne"}
 
     Returns candidate addresses with structured components.
diff --git a/apps/client/views/client_rest_views.py b/apps/company/views/company_rest_views.py
similarity index 61%
rename from apps/client/views/client_rest_views.py
rename to apps/company/views/company_rest_views.py
index 4341a35eb..4a632be15 100644
--- a/apps/client/views/client_rest_views.py
+++ b/apps/company/views/company_rest_views.py
@@ -1,7 +1,7 @@
 """
-Client REST Views
+Company REST Views
 
-REST views for the Client module following clean code principles:
+REST views for the Company module following clean code principles:
 - SRP (Single Responsibility Principle)
 - Early return and guard clauses
 - Delegation to service layer
@@ -23,23 +23,23 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.client.models import Client
-from apps.client.serializers import (
-    ClientCreateResponseSerializer,
-    ClientCreateSerializer,
-    ClientDetailResponseSerializer,
-    ClientDuplicateErrorResponseSerializer,
-    ClientErrorResponseSerializer,
-    ClientJobsResponseSerializer,
-    ClientListResponseSerializer,
-    ClientNameOnlySerializer,
-    ClientSearchResponseSerializer,
-    ClientUpdateResponseSerializer,
-    ClientUpdateSerializer,
+from apps.company.models import Company
+from apps.company.serializers import (
+    CompanyCreateResponseSerializer,
+    CompanyCreateSerializer,
+    CompanyDetailResponseSerializer,
+    CompanyDuplicateErrorResponseSerializer,
+    CompanyErrorResponseSerializer,
+    CompanyJobsResponseSerializer,
+    CompanyListResponseSerializer,
+    CompanyNameOnlySerializer,
+    CompanySearchResponseSerializer,
+    CompanyUpdateResponseSerializer,
+    CompanyUpdateSerializer,
     JobContactResponseSerializer,
     JobContactUpdateSerializer,
 )
-from apps.client.services.client_rest_service import ClientRestService
+from apps.company.services.company_rest_service import CompanyRestService
 from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.error_persistence import persist_app_error
 
@@ -67,53 +67,53 @@ def _build_server_error_response(
     if error_id:
         payload["error_id"] = str(error_id)
 
-    serializer = ClientErrorResponseSerializer(data=payload)
+    serializer = CompanyErrorResponseSerializer(data=payload)
     serializer.is_valid(raise_exception=True)
     return Response(serializer.data, status=status_code)
 
 
 @extend_schema_view(
     get=extend_schema(
-        summary="List all clients",
-        description="Returns a list of all clients with basic information (id and name) for dropdowns and search.",
+        summary="List all companies",
+        description="Returns a list of all companies with basic information (id and name) for dropdowns and search.",
         responses={
-            200: ClientNameOnlySerializer(many=True),
-            500: ClientErrorResponseSerializer,
+            200: CompanyNameOnlySerializer(many=True),
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
-class ClientListAllRestView(APIView):
+class CompanyListAllRestView(APIView):
     """
-    REST view for listing all clients.
+    REST view for listing all companies.
     Used by dropdowns and advanced search.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientListResponseSerializer
+    serializer_class = CompanyListResponseSerializer
 
     def get(self, request: Request) -> Response:
         """
-        Lists all clients (only id and name) for fast dropdowns.
+        Lists all companies (only id and name) for fast dropdowns.
         """
         try:
-            clients_data = ClientRestService.get_all_clients()
-            return Response(clients_data)
+            companies_data = CompanyRestService.get_all_companies()
+            return Response(companies_data)
         except Exception as exc:
             return _build_server_error_response(
-                message="Error fetching all clients", exc=exc
+                message="Error fetching all companies", exc=exc
             )
 
 
 @extend_schema_view(
     get=extend_schema(
-        summary="Search clients",
+        summary="Search companies",
         parameters=[
             OpenApiParameter(
                 name="q",
                 location=OpenApiParameter.QUERY,
                 required=False,
-                description="Search query (case-insensitive substring match). If empty, returns all clients.",
+                description="Search query (case-insensitive substring match). If empty, returns all companies.",
                 type=OpenApiTypes.STR,
             ),
             OpenApiParameter(
@@ -146,24 +146,24 @@ def get(self, request: Request) -> Response:
             ),
         ],
         responses={
-            200: ClientSearchResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            200: CompanySearchResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
-class ClientSearchRestView(APIView):
+class CompanySearchRestView(APIView):
     """
-    REST view for client search with pagination and sorting.
-    Returns all clients when no search query provided.
+    REST view for company search with pagination and sorting.
+    Returns all companies when no search query provided.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientSearchResponseSerializer
+    serializer_class = CompanySearchResponseSerializer
 
     def get(self, request: Request) -> Response:
         """
-        Lists/searches clients with pagination and sorting.
+        Lists/searches companies with pagination and sorting.
         """
         try:
             query = (request.GET.get("q") or "").strip()
@@ -184,7 +184,7 @@ def get(self, request: Request) -> Response:
             sort_dir = request.GET.get("sort_dir", "asc")
 
             # Get paginated results
-            result = ClientRestService.list_clients(
+            result = CompanyRestService.list_companies(
                 query=query if len(query) >= 3 else None,
                 page=page,
                 page_size=page_size,
@@ -192,153 +192,153 @@ def get(self, request: Request) -> Response:
                 sort_dir=sort_dir,
             )
 
-            serializer = ClientSearchResponseSerializer(data=result)
+            serializer = CompanySearchResponseSerializer(data=result)
             serializer.is_valid(raise_exception=True)
-            ClientRestService.log_client_search_results(
+            CompanyRestService.log_company_search_results(
                 request=request,
-                source="client_search",
+                source="company_search",
                 query=query,
-                clients=result["results"],
+                companies=result["results"],
                 total_count=result["count"],
             )
             return Response(serializer.data)
 
         except Exception as exc:
             return _build_server_error_response(
-                message="Error searching clients", exc=exc
+                message="Error searching companies", exc=exc
             )
 
 
 @extend_schema_view(
     get=extend_schema(
-        summary="Get client details",
-        description="Retrieve detailed information for a specific client.",
+        summary="Get company details",
+        description="Retrieve detailed information for a specific company.",
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 location=OpenApiParameter.PATH,
-                description="UUID of the client",
+                description="UUID of the company",
                 required=True,
                 type=OpenApiTypes.UUID,
             )
         ],
         responses={
-            200: ClientDetailResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            200: CompanyDetailResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
-class ClientRetrieveRestView(APIView):
+class CompanyRetrieveRestView(APIView):
     """
-    REST view for retrieving a specific client by ID.
+    REST view for retrieving a specific company by ID.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientDetailResponseSerializer
+    serializer_class = CompanyDetailResponseSerializer
 
-    def get(self, request: Request, client_id: str) -> Response:
+    def get(self, request: Request, company_id: str) -> Response:
         """
-        Retrieves detailed information for a specific client.
+        Retrieves detailed information for a specific company.
         """
         try:
-            client_data = ClientRestService.get_client_by_id(client_id)
-            return Response(client_data)
+            company_data = CompanyRestService.get_company_by_id(company_id)
+            return Response(company_data)
         except ValueError as e:
-            error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+            error_serializer = CompanyErrorResponseSerializer(data={"error": str(e)})
             error_serializer.is_valid(raise_exception=True)
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as exc:
             return _build_server_error_response(
-                message="Error retrieving client", exc=exc
+                message="Error retrieving company", exc=exc
             )
 
 
 @extend_schema_view(
     put=extend_schema(
-        summary="Update client",
-        description="Update an existing client's information.",
+        summary="Update company",
+        description="Update an existing company's information.",
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 location=OpenApiParameter.PATH,
-                description="UUID of the client",
+                description="UUID of the company",
                 required=True,
                 type=OpenApiTypes.UUID,
             )
         ],
-        request=ClientUpdateSerializer,
+        request=CompanyUpdateSerializer,
         responses={
-            200: ClientUpdateResponseSerializer,
-            400: ClientErrorResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            200: CompanyUpdateResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     ),
     patch=extend_schema(
-        summary="Partially update client",
-        description="Partially update an existing client's information.",
+        summary="Partially update company",
+        description="Partially update an existing company's information.",
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 location=OpenApiParameter.PATH,
-                description="UUID of the client",
+                description="UUID of the company",
                 required=True,
                 type=OpenApiTypes.UUID,
             )
         ],
-        request=ClientUpdateSerializer,
+        request=CompanyUpdateSerializer,
         responses={
-            200: ClientUpdateResponseSerializer,
-            400: ClientErrorResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            200: CompanyUpdateResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     ),
 )
-class ClientUpdateRestView(APIView):
+class CompanyUpdateRestView(APIView):
     """
-    REST view for updating client information.
+    REST view for updating company information.
     Supports both PUT (full update) and PATCH (partial update).
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientUpdateResponseSerializer
+    serializer_class = CompanyUpdateResponseSerializer
 
     def get_serializer_class(self):
         """Return the appropriate serializer class based on the request method"""
         if self.request.method in ["PUT", "PATCH"]:
-            return ClientUpdateSerializer
-        return ClientUpdateResponseSerializer
+            return CompanyUpdateSerializer
+        return CompanyUpdateResponseSerializer
 
-    def put(self, request: Request, client_id: str) -> Response:
+    def put(self, request: Request, company_id: str) -> Response:
         """
-        Full update of client information.
+        Full update of company information.
         """
-        return self._update_client(request, client_id, partial=False)
+        return self._update_company(request, company_id, partial=False)
 
-    def patch(self, request: Request, client_id: str) -> Response:
+    def patch(self, request: Request, company_id: str) -> Response:
         """
-        Partial update of client information.
+        Partial update of company information.
         """
-        return self._update_client(request, client_id, partial=True)
+        return self._update_company(request, company_id, partial=True)
 
-    def _update_client(
-        self, request: Request, client_id: str, partial: bool = True
+    def _update_company(
+        self, request: Request, company_id: str, partial: bool = True
     ) -> Response:
         """
-        Common method for handling client updates.
+        Common method for handling company updates.
         """
         try:
             # Validate input data
-            input_serializer = ClientUpdateSerializer(
+            input_serializer = CompanyUpdateSerializer(
                 data=request.data, partial=partial
             )
             if not input_serializer.is_valid():
-                error_serializer = ClientErrorResponseSerializer(
+                error_serializer = CompanyErrorResponseSerializer(
                     data={"error": f"Invalid input data: {input_serializer.errors}"}
                 )
                 error_serializer.is_valid(raise_exception=True)
@@ -347,78 +347,84 @@ def _update_client(
                 )
 
             validated_data = input_serializer.validated_data
-            updated_client = ClientRestService.update_client(client_id, validated_data)
+            updated_company = CompanyRestService.update_company(
+                company_id, validated_data
+            )
 
             # Format response using the service method
-            client_data = ClientRestService._format_client_detail(updated_client)
+            company_data = CompanyRestService._format_company_detail(updated_company)
             response_data = {
                 "success": True,
-                "client": client_data,
-                "message": f'Client "{updated_client.name}" updated successfully',
+                "company": company_data,
+                "message": f'Company "{updated_company.name}" updated successfully',
             }
 
-            response_serializer = ClientUpdateResponseSerializer(data=response_data)
+            response_serializer = CompanyUpdateResponseSerializer(data=response_data)
             response_serializer.is_valid(raise_exception=True)
             return Response(response_serializer.data)
 
         except ValueError as e:
             # Handle not found and validation errors
             if "not found" in str(e).lower():
-                error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+                error_serializer = CompanyErrorResponseSerializer(
+                    data={"error": str(e)}
+                )
                 error_serializer.is_valid(raise_exception=True)
                 return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
             else:
-                error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+                error_serializer = CompanyErrorResponseSerializer(
+                    data={"error": str(e)}
+                )
                 error_serializer.is_valid(raise_exception=True)
                 return Response(
                     error_serializer.data, status=status.HTTP_400_BAD_REQUEST
                 )
         except Exception as exc:
             return _build_server_error_response(
-                message="Error updating client", exc=exc
+                message="Error updating company", exc=exc
             )
 
 
 @extend_schema_view(
     post=extend_schema(
-        summary="Create a new client",
-        description="Creates a new client in Xero first, then syncs locally. Requires valid Xero authentication.",
-        request=ClientCreateSerializer,
+        summary="Create a new company",
+        description="Creates a new company in Xero first, then syncs locally. Requires valid Xero authentication.",
+        request=CompanyCreateSerializer,
         responses={
-            201: ClientCreateResponseSerializer,
-            400: ClientErrorResponseSerializer,
-            401: ClientErrorResponseSerializer,
-            409: ClientDuplicateErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            201: CompanyCreateResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            401: CompanyErrorResponseSerializer,
+            409: CompanyDuplicateErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
-class ClientCreateRestView(APIView):
+class CompanyCreateRestView(APIView):
     """
-    REST view for creating new clients.
+    REST view for creating new companies.
     Follows clean code principles and delegates to service layer.
-    Creates client in Xero first, then syncs locally.
+    Creates company in Xero first, then syncs locally.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientCreateResponseSerializer
+    serializer_class = CompanyCreateResponseSerializer
 
     def get_serializer_class(self):
         """Return the appropriate serializer class based on the request method"""
         if self.request.method == "POST":
-            return ClientCreateSerializer
-        return ClientCreateResponseSerializer
+            return CompanyCreateSerializer
+        return CompanyCreateResponseSerializer
 
     def post(self, request: Request) -> Response:
         """
-        Create a new client, first in Xero, then sync locally.
+        Create a new company, first in Xero, then sync locally.
         """
         try:
             # Validate input data
-            input_serializer = ClientCreateSerializer(data=request.data)
+            input_serializer = CompanyCreateSerializer(data=request.data)
             if not input_serializer.is_valid():
-                error_serializer = ClientErrorResponseSerializer(
+                error_serializer = CompanyErrorResponseSerializer(
                     data={"error": f"Invalid input data: {input_serializer.errors}"}
                 )
                 error_serializer.is_valid(raise_exception=True)
@@ -427,34 +433,34 @@ def post(self, request: Request) -> Response:
                 )
 
             validated_data = input_serializer.validated_data
-            created_client = ClientRestService.create_client(validated_data)
-            created_client = Client.objects.with_invoice_summary().get(
-                id=created_client.id
+            created_company = CompanyRestService.create_company(validated_data)
+            created_company = Company.objects.with_invoice_summary().get(
+                id=created_company.id
             )
 
             response_data = {
                 "success": True,
-                "client": ClientRestService._format_client_summary(created_client),
-                "message": f'Client "{created_client.name}" created successfully',
+                "company": CompanyRestService._format_company_summary(created_company),
+                "message": f'Company "{created_company.name}" created successfully',
             }
 
-            response_serializer = ClientCreateResponseSerializer(data=response_data)
+            response_serializer = CompanyCreateResponseSerializer(data=response_data)
             response_serializer.is_valid(raise_exception=True)
             return Response(response_serializer.data, status=status.HTTP_201_CREATED)
 
         except ValueError as e:
             logger.error(
-                f"Error during client creation: {e} | Request data: {request.data}"
+                f"Error during company creation: {e} | Request data: {request.data}"
             )
-            # Handle duplicate client error
+            # Handle duplicate company error
             if "already exists in Xero" in str(e):
-                # Extract client name from error message
+                # Extract company name from error message
                 error_msg = str(e)
-                if "Client '" in error_msg and "' already exists" in error_msg:
-                    name = error_msg.split("Client '")[1].split("' already exists")[0]
+                if "Company '" in error_msg and "' already exists" in error_msg:
+                    name = error_msg.split("Company '")[1].split("' already exists")[0]
                     duplicate_error_data = {
                         "error": error_msg,
-                        "existing_client": {
+                        "existing_company": {
                             "name": name,
                             "xero_contact_id": (
                                 error_msg.split("ID: ")[-1]
@@ -463,7 +469,7 @@ def post(self, request: Request) -> Response:
                             ),
                         },
                     }
-                    error_serializer = ClientDuplicateErrorResponseSerializer(
+                    error_serializer = CompanyDuplicateErrorResponseSerializer(
                         data=duplicate_error_data
                     )
                     error_serializer.is_valid(raise_exception=True)
@@ -473,19 +479,21 @@ def post(self, request: Request) -> Response:
 
             # Handle validation errors
             if "authentication required" in str(e).lower():
-                error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+                error_serializer = CompanyErrorResponseSerializer(
+                    data={"error": str(e)}
+                )
                 error_serializer.is_valid(raise_exception=True)
                 return Response(
                     error_serializer.data, status=status.HTTP_401_UNAUTHORIZED
                 )
 
             # Other validation errors
-            error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+            error_serializer = CompanyErrorResponseSerializer(data={"error": str(e)})
             error_serializer.is_valid(raise_exception=True)
             return Response(error_serializer.data, status=status.HTTP_400_BAD_REQUEST)
         except Exception as exc:
             return _build_server_error_response(
-                message="Error creating client", exc=exc
+                message="Error creating company", exc=exc
             )
 
 
@@ -504,10 +512,10 @@ def post(self, request: Request) -> Response:
         ],
         responses={
             200: JobContactResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     ),
     put=extend_schema(
         summary="Update job contact",
@@ -524,12 +532,12 @@ def post(self, request: Request) -> Response:
         request=JobContactUpdateSerializer,
         responses={
             200: JobContactResponseSerializer,
-            400: ClientErrorResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
-        operation_id="clients_jobs_contact_update",
+        tags=["Companies"],
+        operation_id="companies_jobs_contact_update",
     ),
 )
 class JobContactRestView(APIView):
@@ -554,7 +562,7 @@ def get(self, request: Request, job_id: str) -> Response:
         try:
             # Guard clause: validate job_id
             if not job_id:
-                error_serializer = ClientErrorResponseSerializer(
+                error_serializer = CompanyErrorResponseSerializer(
                     data={"error": "Job ID is required"}
                 )
                 error_serializer.is_valid(raise_exception=True)
@@ -562,13 +570,13 @@ def get(self, request: Request, job_id: str) -> Response:
                     error_serializer.data, status=status.HTTP_400_BAD_REQUEST
                 )
 
-            contact_data = ClientRestService.get_job_contact(job_id)
+            contact_data = CompanyRestService.get_job_contact(job_id)
             serializer = JobContactResponseSerializer(data=contact_data)
             serializer.is_valid(raise_exception=True)
             return Response(serializer.data)
 
         except ValueError as e:
-            error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+            error_serializer = CompanyErrorResponseSerializer(data={"error": str(e)})
             error_serializer.is_valid(raise_exception=True)
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as exc:
@@ -583,7 +591,7 @@ def put(self, request: Request, job_id: str) -> Response:
         try:
             # Guard clause: validate job_id
             if not job_id:
-                error_serializer = ClientErrorResponseSerializer(
+                error_serializer = CompanyErrorResponseSerializer(
                     data={"error": "Job ID is required"}
                 )
                 error_serializer.is_valid(raise_exception=True)
@@ -594,7 +602,7 @@ def put(self, request: Request, job_id: str) -> Response:
             # Validate input data
             input_serializer = JobContactUpdateSerializer(data=request.data)
             if not input_serializer.is_valid():
-                error_serializer = ClientErrorResponseSerializer(
+                error_serializer = CompanyErrorResponseSerializer(
                     data={"error": f"Invalid input data: {input_serializer.errors}"}
                 )
                 error_serializer.is_valid(raise_exception=True)
@@ -603,7 +611,7 @@ def put(self, request: Request, job_id: str) -> Response:
                 )
 
             contact_data = input_serializer.validated_data
-            updated_contact = ClientRestService.update_job_contact(
+            updated_contact = CompanyRestService.update_job_contact(
                 job_id, contact_data, request.user
             )
             serializer = JobContactResponseSerializer(data=updated_contact)
@@ -611,7 +619,7 @@ def put(self, request: Request, job_id: str) -> Response:
             return Response(serializer.data)
 
         except ValueError as e:
-            error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+            error_serializer = CompanyErrorResponseSerializer(data={"error": str(e)})
             error_serializer.is_valid(raise_exception=True)
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as exc:
@@ -622,63 +630,63 @@ def put(self, request: Request, job_id: str) -> Response:
 
 @extend_schema_view(
     get=extend_schema(
-        summary="Get client jobs",
-        description="Retrieve all jobs for a specific client.",
+        summary="Get company jobs",
+        description="Retrieve all jobs for a specific company.",
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 location=OpenApiParameter.PATH,
-                description="UUID of the client",
+                description="UUID of the company",
                 required=True,
                 type=OpenApiTypes.UUID,
             )
         ],
         responses={
-            200: ClientJobsResponseSerializer,
-            404: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            200: CompanyJobsResponseSerializer,
+            404: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
-class ClientJobsRestView(APIView):
+class CompanyJobsRestView(APIView):
     """
-    REST view for fetching all jobs for a specific client.
+    REST view for fetching all jobs for a specific company.
     Returns job header information for fast loading.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = ClientJobsResponseSerializer
+    serializer_class = CompanyJobsResponseSerializer
 
-    def get(self, request: Request, client_id: str) -> Response:
+    def get(self, request: Request, company_id: str) -> Response:
         """
-        Retrieves all jobs for a specific client.
+        Retrieves all jobs for a specific company.
         """
         try:
-            # Guard clause: validate client_id
-            if not client_id:
-                error_serializer = ClientErrorResponseSerializer(
-                    data={"error": "Client ID is required"}
+            # Guard clause: validate company_id
+            if not company_id:
+                error_serializer = CompanyErrorResponseSerializer(
+                    data={"error": "Company ID is required"}
                 )
                 error_serializer.is_valid(raise_exception=True)
                 return Response(
                     error_serializer.data, status=status.HTTP_400_BAD_REQUEST
                 )
 
-            jobs = ClientRestService.get_client_jobs(client_id)
+            jobs = CompanyRestService.get_company_jobs(company_id)
             response_data = {"results": jobs}
-            serializer = ClientJobsResponseSerializer(data=response_data)
+            serializer = CompanyJobsResponseSerializer(data=response_data)
             serializer.is_valid(raise_exception=True)
             return Response(serializer.data)
 
         except ValueError as e:
-            error_serializer = ClientErrorResponseSerializer(data={"error": str(e)})
+            error_serializer = CompanyErrorResponseSerializer(data={"error": str(e)})
             error_serializer.is_valid(raise_exception=True)
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as e:
-            logger.error(f"Error fetching jobs for client {client_id}: {str(e)}")
-            error_serializer = ClientErrorResponseSerializer(
-                data={"error": "Error fetching client jobs", "details": str(e)}
+            logger.error(f"Error fetching jobs for company {company_id}: {str(e)}")
+            error_serializer = CompanyErrorResponseSerializer(
+                data={"error": "Error fetching company jobs", "details": str(e)}
             )
             error_serializer.is_valid(raise_exception=True)
             return Response(
diff --git a/apps/client/views/client_contact_method_viewset.py b/apps/company/views/contact_method_viewset.py
similarity index 86%
rename from apps/client/views/client_contact_method_viewset.py
rename to apps/company/views/contact_method_viewset.py
index ec30e4d8d..c273fc800 100644
--- a/apps/client/views/client_contact_method_viewset.py
+++ b/apps/company/views/contact_method_viewset.py
@@ -1,4 +1,4 @@
-"""Client/contact contact method ViewSet."""
+"""Company/contact contact method ViewSet."""
 
 from typing import cast
 
@@ -7,8 +7,8 @@
 from rest_framework import permissions, viewsets
 from rest_framework.serializers import BaseSerializer
 
-from apps.client.models import ClientContactMethod
-from apps.client.serializers import ClientContactMethodSerializer
+from apps.company.models import ClientContactMethod
+from apps.company.serializers import ClientContactMethodSerializer
 from apps.crm.tasks import rematch_phone_calls_task
 from apps.workflow.api.pagination import PageSizePagination
 
@@ -25,7 +25,7 @@ def _phone_number_for_rematch(method: ClientContactMethod | None) -> str | None:
 
 
 class ClientContactMethodViewSet(viewsets.ModelViewSet):
-    """CRUD API for canonical client/contact phone and email methods."""
+    """CRUD API for canonical company/contact phone and email methods."""
 
     serializer_class = ClientContactMethodSerializer
     permission_classes = [permissions.IsAuthenticated]
@@ -34,7 +34,7 @@ class ClientContactMethodViewSet(viewsets.ModelViewSet):
     @extend_schema(
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 type=OpenApiTypes.UUID,
                 location=OpenApiParameter.QUERY,
                 required=False,
@@ -70,14 +70,14 @@ def list(self, request, *args, **kwargs):
 
     def get_queryset(self):
         queryset = ClientContactMethod.objects.select_related(
-            "client",
+            "company",
             "contact",
-            "contact__client",
+            "contact__company",
         )
-        client_id = self.request.query_params.get("client_id")
-        if client_id:
-            queryset = queryset.filter(client_id=client_id) | queryset.filter(
-                contact__client_id=client_id
+        company_id = self.request.query_params.get("company_id")
+        if company_id:
+            queryset = queryset.filter(company_id=company_id) | queryset.filter(
+                contact__company_id=company_id
             )
 
         contact_id = self.request.query_params.get("contact_id")
diff --git a/apps/client/views/client_contact_viewset.py b/apps/company/views/contact_viewset.py
similarity index 61%
rename from apps/client/views/client_contact_viewset.py
rename to apps/company/views/contact_viewset.py
index c7c98a2cf..9d149954d 100644
--- a/apps/client/views/client_contact_viewset.py
+++ b/apps/company/views/contact_viewset.py
@@ -9,8 +9,8 @@
 from drf_spectacular.utils import OpenApiParameter, extend_schema
 from rest_framework import permissions, viewsets
 
-from apps.client.models import ClientContact
-from apps.client.serializers import ClientContactSerializer
+from apps.company.models import ClientContact
+from apps.company.serializers import ClientContactSerializer
 
 
 class ClientContactViewSet(viewsets.ModelViewSet):
@@ -18,15 +18,15 @@ class ClientContactViewSet(viewsets.ModelViewSet):
     ViewSet for ClientContact CRUD operations.
 
     Endpoints:
-    - GET    /api/clients/contacts/           - list all contacts
-    - POST   /api/clients/contacts/           - create contact
-    - GET    /api/clients/contacts/<id>/      - retrieve contact
-    - PUT    /api/clients/contacts/<id>/      - full update
-    - PATCH  /api/clients/contacts/<id>/      - partial update
-    - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+    - GET    /api/companies/contacts/           - list all contacts
+    - POST   /api/companies/contacts/           - create contact
+    - GET    /api/companies/contacts/<id>/      - retrieve contact
+    - PUT    /api/companies/contacts/<id>/      - full update
+    - PATCH  /api/companies/contacts/<id>/      - partial update
+    - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
     Query Parameters:
-    - client_id: Filter contacts by client UUID
+    - company_id: Filter contacts by company UUID
     """
 
     queryset = ClientContact.objects.filter(is_active=True)
@@ -36,26 +36,26 @@ class ClientContactViewSet(viewsets.ModelViewSet):
     @extend_schema(
         parameters=[
             OpenApiParameter(
-                name="client_id",
+                name="company_id",
                 type=OpenApiTypes.UUID,
                 location=OpenApiParameter.QUERY,
-                description="Filter contacts by client UUID",
+                description="Filter contacts by company UUID",
                 required=False,
             ),
         ]
     )
     def list(self, request, *args, **kwargs):
-        """List all contacts, optionally filtered by client_id."""
+        """List all contacts, optionally filtered by company_id."""
         return super().list(request, *args, **kwargs)
 
     def get_queryset(self):
         """
-        Filter to only active contacts, optionally filtered by client_id.
+        Filter to only active contacts, optionally filtered by company_id.
         """
         queryset = ClientContact.objects.filter(is_active=True)
-        client_id = self.request.query_params.get("client_id")
-        if client_id:
-            queryset = queryset.filter(client_id=client_id)
+        company_id = self.request.query_params.get("company_id")
+        if company_id:
+            queryset = queryset.filter(company_id=company_id)
         return queryset.order_by("-is_primary", "name")
 
     def perform_destroy(self, instance):
diff --git a/apps/client/views/supplier_pickup_address_viewset.py b/apps/company/views/supplier_pickup_address_viewset.py
similarity index 67%
rename from apps/client/views/supplier_pickup_address_viewset.py
rename to apps/company/views/supplier_pickup_address_viewset.py
index ecf5408d0..e8b41350c 100644
--- a/apps/client/views/supplier_pickup_address_viewset.py
+++ b/apps/company/views/supplier_pickup_address_viewset.py
@@ -4,16 +4,16 @@
 ViewSet for SupplierPickupAddress CRUD operations using DRF's ModelViewSet.
 Provides list, create, retrieve, update, partial_update, and destroy actions.
 
-These are delivery/pickup locations for suppliers (or any client).
-Despite the name, addresses can be created for any client, not just suppliers.
+These are delivery/pickup locations for suppliers (or any company).
+Despite the name, addresses can be created for any company, not just suppliers.
 """
 
 from drf_spectacular.types import OpenApiTypes
 from drf_spectacular.utils import OpenApiParameter, extend_schema
 from rest_framework import permissions, viewsets
 
-from apps.client.models import SupplierPickupAddress
-from apps.client.serializers import SupplierPickupAddressSerializer
+from apps.company.models import SupplierPickupAddress
+from apps.company.serializers import SupplierPickupAddressSerializer
 
 
 class SupplierPickupAddressViewSet(viewsets.ModelViewSet):
@@ -21,15 +21,15 @@ class SupplierPickupAddressViewSet(viewsets.ModelViewSet):
     ViewSet for SupplierPickupAddress CRUD operations.
 
     Endpoints:
-    - GET    /api/clients/pickup-addresses/           - list all addresses
-    - POST   /api/clients/pickup-addresses/           - create address
-    - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-    - PUT    /api/clients/pickup-addresses/<id>/      - full update
-    - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-    - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+    - GET    /api/companies/pickup-addresses/           - list all addresses
+    - POST   /api/companies/pickup-addresses/           - create address
+    - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+    - PUT    /api/companies/pickup-addresses/<id>/      - full update
+    - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+    - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
     Query Parameters:
-    - supplier_id: Filter addresses by supplier (client) UUID
+    - supplier_id: Filter addresses by supplier (company) UUID
     """
 
     queryset = SupplierPickupAddress.objects.filter(is_active=True)
@@ -58,7 +58,7 @@ def get_queryset(self):
         queryset = SupplierPickupAddress.objects.filter(is_active=True)
         supplier_id = self.request.query_params.get("supplier_id")
         if supplier_id:
-            queryset = queryset.filter(client_id=supplier_id)
+            queryset = queryset.filter(company_id=supplier_id)
         return queryset.order_by("-is_primary", "name")
 
     def perform_destroy(self, instance):
diff --git a/apps/client/views/supplier_search_alias_views.py b/apps/company/views/supplier_search_alias_views.py
similarity index 83%
rename from apps/client/views/supplier_search_alias_views.py
rename to apps/company/views/supplier_search_alias_views.py
index 15a219639..632004646 100644
--- a/apps/client/views/supplier_search_alias_views.py
+++ b/apps/company/views/supplier_search_alias_views.py
@@ -11,8 +11,8 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.client.models import Client, SupplierSearchAlias
-from apps.client.serializers import (
+from apps.company.models import Company, SupplierSearchAlias
+from apps.company.serializers import (
     SupplierSearchAliasCreateSerializer,
     SupplierSearchAliasSerializer,
 )
@@ -43,31 +43,31 @@ def _build_server_error_response(*, message: str, exc: Exception) -> Response:
     get=extend_schema(
         summary="List supplier search aliases",
         responses=SupplierSearchAliasSerializer(many=True),
-        tags=["Clients"],
+        tags=["Companies"],
     ),
     post=extend_schema(
         summary="Create supplier search alias",
         request=SupplierSearchAliasCreateSerializer,
         responses={status.HTTP_201_CREATED: SupplierSearchAliasSerializer},
-        tags=["Clients"],
+        tags=["Companies"],
     ),
 )
-class ClientSupplierAliasListCreateView(APIView):
-    """List and create search aliases for a client/supplier contact."""
+class CompanySupplierAliasListCreateView(APIView):
+    """List and create search aliases for a company/supplier contact."""
 
     permission_classes = [IsAuthenticated]
 
-    def get(self, request: Request, client_id) -> Response:
+    def get(self, request: Request, company_id) -> Response:
         try:
-            client = Client.objects.get(id=client_id)
-            aliases = client.supplier_search_aliases.filter(is_active=True).order_by(
+            company = Company.objects.get(id=company_id)
+            aliases = company.supplier_search_aliases.filter(is_active=True).order_by(
                 "alias"
             )
             serializer = SupplierSearchAliasSerializer(aliases, many=True)
             return Response(serializer.data)
-        except Client.DoesNotExist:
+        except Company.DoesNotExist:
             return Response(
-                {"error": "Client not found"},
+                {"error": "Company not found"},
                 status=status.HTTP_404_NOT_FOUND,
             )
         except Exception as exc:
@@ -75,15 +75,15 @@ def get(self, request: Request, client_id) -> Response:
                 message="Error listing supplier aliases", exc=exc
             )
 
-    def post(self, request: Request, client_id) -> Response:
+    def post(self, request: Request, company_id) -> Response:
         try:
-            client = Client.objects.get(id=client_id)
+            company = Company.objects.get(id=company_id)
             serializer = SupplierSearchAliasCreateSerializer(data=request.data)
             serializer.is_valid(raise_exception=True)
             alias_text = serializer.validated_data["alias"].strip()
 
             alias, _ = SupplierSearchAlias.objects.get_or_create(
-                client=client,
+                company=company,
                 alias=alias_text,
                 defaults={"is_active": True},
             )
@@ -93,9 +93,9 @@ def post(self, request: Request, client_id) -> Response:
 
             output = SupplierSearchAliasSerializer(alias)
             return Response(output.data, status=status.HTTP_201_CREATED)
-        except Client.DoesNotExist:
+        except Company.DoesNotExist:
             return Response(
-                {"error": "Client not found"},
+                {"error": "Company not found"},
                 status=status.HTTP_404_NOT_FOUND,
             )
         except ValidationError as exc:
@@ -113,7 +113,7 @@ def post(self, request: Request, client_id) -> Response:
     delete=extend_schema(
         summary="Deactivate supplier search alias",
         responses={204: None},
-        tags=["Clients"],
+        tags=["Companies"],
     )
 )
 class SupplierAliasDetailView(APIView):
diff --git a/apps/crm/migrations/0001_baseline.py b/apps/crm/migrations/0001_baseline.py
index 99570b94b..71e3b6941 100644
--- a/apps/crm/migrations/0001_baseline.py
+++ b/apps/crm/migrations/0001_baseline.py
@@ -13,7 +13,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         ("job", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
@@ -167,7 +167,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.SET_NULL,
                         related_name="phone_calls",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
                 (
@@ -177,7 +177,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.SET_NULL,
                         related_name="phone_calls",
-                        to="client.clientcontact",
+                        to="company.clientcontact",
                     ),
                 ),
                 (
diff --git a/apps/crm/migrations/0004_rename_client_company.py b/apps/crm/migrations/0004_rename_client_company.py
new file mode 100644
index 000000000..c99fa2b8e
--- /dev/null
+++ b/apps/crm/migrations/0004_rename_client_company.py
@@ -0,0 +1,30 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("crm", "0003_drop_orphaned_phone_mapping_table"),
+    ]
+
+    operations = [
+        # The index is removed BEFORE the field rename and re-added after:
+        # index ops render their field list against the state they run in, so
+        # the reverse direction of a RenameField/RemoveIndex/AddIndex ordering
+        # would re-add the index against the renamed field and fail.
+        migrations.RemoveIndex(
+            model_name="phonecallrecord",
+            name="crm_phone_client_call_idx",
+        ),
+        migrations.RenameField(
+            model_name="phonecallrecord",
+            old_name="client",
+            new_name="company",
+        ),
+        migrations.AddIndex(
+            model_name="phonecallrecord",
+            index=models.Index(
+                fields=["company", "-call_datetime"],
+                name="crm_phone_company_call_idx",
+            ),
+        ),
+    ]
diff --git a/apps/crm/models.py b/apps/crm/models.py
index 40df06676..01e42b576 100644
--- a/apps/crm/models.py
+++ b/apps/crm/models.py
@@ -61,16 +61,16 @@ def save(
         using: str | None = None,
         update_fields: Iterable[str] | None = None,
     ) -> None:
-        from apps.client.models import ClientContactMethod
+        from apps.company.models import ClientContactMethod
 
         self.normalized_number = ClientContactMethod.normalize_phone(self.number)
         if not self.normalized_number:
             raise ValueError("phone endpoint requires a phone number")
         if self.is_active and self._active_number_changed():
             # Mirror of the ClientContactMethod.save() guard: a number cannot be
-            # both a client contact method and an active internal endpoint, or
-            # the client's calls would silently reclassify as INTERNAL.
-            conflict = ClientContactMethod.conflicting_client(
+            # both a company contact method and an active internal endpoint, or
+            # the company's calls would silently reclassify as INTERNAL.
+            conflict = ClientContactMethod.conflicting_company(
                 self.normalized_number, None
             )
             if conflict:
@@ -181,15 +181,15 @@ class Direction(models.TextChoices):
     )
     duration_seconds = models.PositiveIntegerField(default=0)
     charge = models.DecimalField(max_digits=12, decimal_places=4, null=True, blank=True)
-    client = models.ForeignKey(
-        "client.Client",
+    company = models.ForeignKey(
+        "company.Company",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
         related_name="phone_calls",
     )
     contact = models.ForeignKey(
-        "client.ClientContact",
+        "company.ClientContact",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
@@ -222,8 +222,8 @@ class Meta:
                 name="crm_phone_acct_call_idx",
             ),
             models.Index(
-                fields=["client", "-call_datetime"],
-                name="crm_phone_client_call_idx",
+                fields=["company", "-call_datetime"],
+                name="crm_phone_company_call_idx",
             ),
             models.Index(
                 fields=["contact", "-call_datetime"],
@@ -263,7 +263,7 @@ def save(
         using: str | None = None,
         update_fields: Iterable[str] | None = None,
     ) -> None:
-        from apps.client.models import ClientContactMethod
+        from apps.company.models import ClientContactMethod
 
         self.normalized_origin = ClientContactMethod.normalize_phone(self.origin)
         self.normalized_destination = ClientContactMethod.normalize_phone(
diff --git a/apps/crm/serializers.py b/apps/crm/serializers.py
index 933059ffc..d73e80a3d 100644
--- a/apps/crm/serializers.py
+++ b/apps/crm/serializers.py
@@ -3,7 +3,7 @@
 from drf_spectacular.utils import extend_schema_field
 from rest_framework import serializers
 
-from apps.client.models import ClientContactMethod
+from apps.company.models import ClientContactMethod
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -25,9 +25,9 @@ class PhoneCallJobLinkSerializer(serializers.Serializer[None]):
 
 
 class PhoneNumberAssignmentSerializer(serializers.Serializer[None]):
-    """Request body for assigning a call's external number to a client."""
+    """Request body for assigning a call's external number to a company."""
 
-    client = serializers.UUIDField()
+    company = serializers.UUIDField()
     contact = serializers.UUIDField(required=False, allow_null=True, default=None)
     is_primary = serializers.BooleanField(required=False, default=False)
 
@@ -122,7 +122,7 @@ def validate_number(self, value: str) -> str:
         return value.strip()
 
     def validate(self, attrs: "PhoneEndpointAttrs") -> "PhoneEndpointAttrs":
-        """Reject an active endpoint over a number a client already owns.
+        """Reject an active endpoint over a number a company already owns.
 
         Mirrors PhoneEndpoint.save() so the API returns a clean 400 instead of
         a 500. Grandfathering symmetry: only enforced on create or when the
@@ -150,7 +150,7 @@ def validate(self, attrs: "PhoneEndpointAttrs") -> "PhoneEndpointAttrs":
             return attrs  # association unchanged — grandfathered, like save()
 
         if is_active:
-            conflict = ClientContactMethod.conflicting_client(normalized, None)
+            conflict = ClientContactMethod.conflicting_company(normalized, None)
             if conflict:
                 raise serializers.ValidationError(
                     {
@@ -242,7 +242,7 @@ def get_has_password(self, obj: PhoneProviderSettings) -> bool:
 class PhoneCallRecordSerializer(serializers.ModelSerializer[PhoneCallRecord]):
 
     recording = serializers.SerializerMethodField()
-    client_name = serializers.SerializerMethodField()
+    company_name = serializers.SerializerMethodField()
     contact_name = serializers.SerializerMethodField()
     origin_endpoint_label = serializers.SerializerMethodField()
     destination_endpoint_label = serializers.SerializerMethodField()
@@ -273,8 +273,8 @@ class Meta:
             "destination_endpoint_label",
             "duration_seconds",
             "charge",
-            "client",
-            "client_name",
+            "company",
+            "company_name",
             "contact",
             "contact_name",
             "job",
@@ -289,8 +289,8 @@ class Meta:
         )
         read_only_fields = fields
 
-    def get_client_name(self, obj: PhoneCallRecord) -> str:
-        return obj.client.name if obj.client else ""
+    def get_company_name(self, obj: PhoneCallRecord) -> str:
+        return obj.company.name if obj.company else ""
 
     def get_contact_name(self, obj: PhoneCallRecord) -> str:
         return obj.contact.name if obj.contact else ""
diff --git a/apps/crm/services/phone_call_service.py b/apps/crm/services/phone_call_service.py
index 13fa775ab..9c8ed1ef8 100644
--- a/apps/crm/services/phone_call_service.py
+++ b/apps/crm/services/phone_call_service.py
@@ -16,7 +16,7 @@
 from django.db import models, transaction
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -256,9 +256,9 @@ def link_phone_call_to_job(
         except PhoneCallRecord.DoesNotExist as exc:
             raise ValueError("Phone call not found") from exc
 
-        if not call.client_id:
+        if not call.company_id:
             raise ValueError(
-                "Phone call must be assigned to a client before linking a job"
+                "Phone call must be assigned to a company before linking a job"
             )
 
         try:
@@ -266,9 +266,9 @@ def link_phone_call_to_job(
         except Job.DoesNotExist as exc:
             raise ValueError("Job not found") from exc
 
-        if job.client_id != call.client_id:
+        if job.company_id != call.company_id:
             raise ValueError(
-                "Phone call can only be linked to a job for the same client"
+                "Phone call can only be linked to a job for the same company"
             )
 
         call.job = job
@@ -309,7 +309,7 @@ def unlink_phone_call_job(*, call_id: str) -> PhoneCallRecord:
 def assign_phone_number_from_call(
     *,
     call_id: str,
-    client_id: str,
+    company_id: str,
     contact_id: str | None = None,
     label: str = "",
     is_primary: bool = False,
@@ -325,7 +325,7 @@ def assign_phone_number_from_call(
 
     assign_phone_number(
         phone_number=call.external_number,
-        client_id=client_id,
+        company_id=company_id,
         contact_id=contact_id,
         label=label,
         is_primary=is_primary,
@@ -524,7 +524,7 @@ def upsert_call_record(
         "destination_endpoint": classification.destination_endpoint,
         "duration_seconds": _positive_int(payload.get("seconds")),
         "charge": _decimal_or_none(payload.get("charge")),
-        "client": classification.client,
+        "company": classification.company,
         "contact": classification.contact,
         "raw_json": payload,
     }
@@ -595,12 +595,12 @@ class CallClassification:
     external_number: str
     origin_endpoint: PhoneEndpoint | None
     destination_endpoint: PhoneEndpoint | None
-    client: Client | None
+    company: Company | None
     contact: ClientContact | None
 
 
 class PhoneMatcher:
-    """Classifies calls against internal endpoints and client phone methods.
+    """Classifies calls against internal endpoints and company phone methods.
 
     With ``numbers=None`` the full phone book is indexed (ingest
     classification). Passing a set of normalized numbers restricts the index
@@ -617,7 +617,7 @@ def __init__(self, numbers: set[str] | None = None):
 
     def match_customer(
         self, *values: str
-    ) -> tuple[Client | None, ClientContact | None]:
+    ) -> tuple[Company | None, ClientContact | None]:
         matches: set[tuple[str, str, str]] = set()
         for value in values:
             normalized = normalize_phone(value)
@@ -628,20 +628,20 @@ def match_customer(
         if not matches:
             return None, None
 
-        client_ids = {client_id for _, _, client_id in matches}
-        if len(client_ids) != 1:
+        company_ids = {company_id for _, _, company_id in matches}
+        if len(company_ids) != 1:
             return None, None
 
         if len(matches) != 1:
-            client = Client.objects.get(id=next(iter(client_ids)))
-            return client, None
+            company = Company.objects.get(id=next(iter(company_ids)))
+            return company, None
 
-        kind, object_id, _client_id = next(iter(matches))
+        kind, object_id, _company_id = next(iter(matches))
         if kind == "contact":
-            contact = ClientContact.objects.select_related("client").get(id=object_id)
-            return contact.client, contact
-        client = Client.objects.get(id=object_id)
-        return client, None
+            contact = ClientContact.objects.select_related("company").get(id=object_id)
+            return contact.company, contact
+        company = Company.objects.get(id=object_id)
+        return company, None
 
     def classify(self, origin: str, destination: str) -> CallClassification:
         normalized_origin = normalize_phone(origin)
@@ -656,35 +656,37 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 external_number="",
                 origin_endpoint=origin_endpoint,
                 destination_endpoint=destination_endpoint,
-                client=None,
+                company=None,
                 contact=None,
             )
 
         if origin_endpoint:
-            client, contact = self.match_customer(normalized_destination)
+            company, contact = self.match_customer(normalized_destination)
             return CallClassification(
                 direction=PhoneCallRecord.Direction.OUTBOUND,
                 our_number=normalized_origin,
                 external_number=normalized_destination,
                 origin_endpoint=origin_endpoint,
                 destination_endpoint=None,
-                client=client,
+                company=company,
                 contact=contact,
             )
 
         if destination_endpoint:
-            client, contact = self.match_customer(normalized_origin)
+            company, contact = self.match_customer(normalized_origin)
             return CallClassification(
                 direction=PhoneCallRecord.Direction.INBOUND,
                 our_number=normalized_destination,
                 external_number=normalized_origin,
                 origin_endpoint=None,
                 destination_endpoint=destination_endpoint,
-                client=client,
+                company=company,
                 contact=contact,
             )
 
-        client, contact = self.match_customer(normalized_origin, normalized_destination)
+        company, contact = self.match_customer(
+            normalized_origin, normalized_destination
+        )
         external_number = ""
         if normalized_origin and not normalized_destination:
             external_number = normalized_origin
@@ -698,7 +700,7 @@ def classify(self, origin: str, destination: str) -> CallClassification:
             external_number=external_number,
             origin_endpoint=None,
             destination_endpoint=None,
-            client=client,
+            company=company,
             contact=contact,
         )
 
@@ -724,7 +726,7 @@ def configured_own_numbers() -> set[str]:
 
 
 _REMATCH_FK_FIELDS = frozenset(
-    {"client", "contact", "origin_endpoint", "destination_endpoint"}
+    {"company", "contact", "origin_endpoint", "destination_endpoint"}
 )
 
 
@@ -760,9 +762,11 @@ def rematch_calls_for_numbers(numbers: list[str]) -> None:
     matcher = PhoneMatcher(numbers=relevant_numbers)
     for call in calls:
         classification = matcher.classify(call.origin, call.destination)
-        matched_client_id = classification.client.id if classification.client else None
+        matched_company_id = (
+            classification.company.id if classification.company else None
+        )
         new_values: dict[str, object] = {
-            "client": classification.client,
+            "company": classification.company,
             "contact": classification.contact,
             "direction": classification.direction,
             "our_number": classification.our_number,
@@ -780,14 +784,14 @@ def rematch_calls_for_numbers(numbers: list[str]) -> None:
         if linked_job is None:
             should_clear_job_link = False
         else:
-            should_clear_job_link = linked_job.client_id != matched_client_id
+            should_clear_job_link = linked_job.company_id != matched_company_id
         if should_clear_job_link:
             call.job = None
             call.job_linked_by = None
             call.job_linked_at = None
             update_fields.extend(["job", "job_linked_by", "job_linked_at"])
         else:
-            pass  # No linked job, or the existing job is still on the matched client.
+            pass  # No linked job, or the existing job is still on the matched company.
         for name, value in new_values.items():
             setattr(call, name, value)
         call.save(update_fields=update_fields)
@@ -796,7 +800,7 @@ def rematch_calls_for_numbers(numbers: list[str]) -> None:
 def assign_phone_number(
     *,
     phone_number: str,
-    client_id: str,
+    company_id: str,
     contact_id: str | None = None,
     label: str = "",
     is_primary: bool = False,
@@ -805,20 +809,20 @@ def assign_phone_number(
     if not normalized:
         raise ValueError("phone number is required")
     if normalized in configured_own_numbers():
-        raise ValueError("internal phone endpoint cannot be assigned to a client")
+        raise ValueError("internal phone endpoint cannot be assigned to a company")
 
-    client_uuid = _uuid_or_client_error(client_id, "Client not found")
+    company_uuid = _uuid_or_client_error(company_id, "Company not found")
     if contact_id:
         contact_uuid = _uuid_or_client_error(contact_id, "Contact not found")
         try:
-            contact = ClientContact.objects.select_related("client").get(
+            contact = ClientContact.objects.select_related("company").get(
                 id=contact_uuid,
-                client_id=client_uuid,
+                company_id=company_uuid,
                 is_active=True,
             )
         except ClientContact.DoesNotExist as exc:
             raise ValueError("Contact not found") from exc
-        owner_filter = {"contact": contact, "client": None}
+        owner_filter = {"contact": contact, "company": None}
         existing_primary = ClientContactMethod.objects.filter(
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -826,19 +830,19 @@ def assign_phone_number(
         ).exists()
     else:
         try:
-            client = Client.objects.get(id=client_uuid)
-        except Client.DoesNotExist as exc:
-            raise ValueError("Client not found") from exc
-        owner_filter = {"client": client, "contact": None}
+            company = Company.objects.get(id=company_uuid)
+        except Company.DoesNotExist as exc:
+            raise ValueError("Company not found") from exc
+        owner_filter = {"company": company, "contact": None}
         existing_primary = ClientContactMethod.objects.filter(
-            client=client,
+            company=company,
             contact__isnull=True,
             method_type=ClientContactMethod.MethodType.PHONE,
             is_primary=True,
         ).exists()
 
     should_be_primary = is_primary or not existing_primary
-    conflict = ClientContactMethod.conflicting_client(normalized, client_uuid)
+    conflict = ClientContactMethod.conflicting_company(normalized, company_uuid)
     if conflict:
         raise ValueError(
             f"phone number already belongs to {conflict.owner_display_name()}"
@@ -879,9 +883,9 @@ def _build_contact_method_phone_index(
     index: dict[str, set[tuple[str, str, str]]] = {}
     internal_numbers = configured_own_numbers()
     methods = ClientContactMethod.objects.select_related(
-        "client",
+        "company",
         "contact",
-        "contact__client",
+        "contact__company",
     ).filter(method_type=ClientContactMethod.MethodType.PHONE)
     if numbers is not None:
         methods = methods.filter(normalized_value__in=numbers)
@@ -893,13 +897,13 @@ def _build_contact_method_phone_index(
             if not method.contact.is_active:
                 continue
             index.setdefault(normalized, set()).add(
-                ("contact", str(method.contact_id), str(method.contact.client_id))
+                ("contact", str(method.contact_id), str(method.contact.company_id))
             )
         else:
-            if not method.client.allow_jobs:
+            if not method.company.allow_jobs:
                 continue
             index.setdefault(normalized, set()).add(
-                ("client", str(method.client_id), str(method.client_id))
+                ("company", str(method.company_id), str(method.company_id))
             )
     return index
 
diff --git a/apps/crm/tests/test_phone_call_service.py b/apps/crm/tests/test_phone_call_service.py
index 54cedc1ef..23b7d2eb5 100644
--- a/apps/crm/tests/test_phone_call_service.py
+++ b/apps/crm/tests/test_phone_call_service.py
@@ -10,7 +10,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -83,58 +83,58 @@ def test_normalize_phone_matches_nz_variants_by_local_tail(self) -> None:
 class PhoneMatcherDatabaseTests(TestCase):
     """Business case: call records drive customer history. The matcher should
     attach calls when ownership is unambiguous, and refuse ambiguous matches so
-    one client's calls are not shown under another client or contact.
+    one company's calls are not shown under another company or contact.
     """
 
-    def _client(self, name: str) -> Client:
-        return Client.objects.create(name=name, xero_last_modified=timezone.now())
+    def _client(self, name: str) -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
     def test_assign_phone_number_creates_primary_contact_method_and_matches_client(
         self,
     ) -> None:
-        client = self._client("Acme Ltd")
+        company = self._client("Acme Ltd")
 
         method = assign_phone_number(
             phone_number="09 636 5131",
-            client_id=str(client.id),
+            company_id=str(company.id),
             label="Reception",
         )
-        matched_client, matched_contact = PhoneMatcher().match_customer(
+        matched_company, matched_contact = PhoneMatcher().match_customer(
             "+6496365131",
             "+6490000000",
         )
 
         self.assertEqual(method.normalized_value, "+6496365131")
         self.assertTrue(method.is_primary)
-        self.assertEqual(matched_client, client)
+        self.assertEqual(matched_company, company)
         self.assertIsNone(matched_contact)
 
     def test_assign_number_allowed_on_contact_of_owning_client(self) -> None:
-        """Assigning a client's number to one of its own contacts is not a conflict."""
-        client = self._client("Acme Ltd")
-        contact = ClientContact.objects.create(client=client, name="Jane Smith")
-        assign_phone_number(phone_number="021 555 900", client_id=str(client.id))
+        """Assigning a company's number to one of its own contacts is not a conflict."""
+        company = self._client("Acme Ltd")
+        contact = ClientContact.objects.create(company=company, name="Jane Smith")
+        assign_phone_number(phone_number="021 555 900", company_id=str(company.id))
 
         method = assign_phone_number(
             phone_number="021 555 900",
-            client_id=str(client.id),
+            company_id=str(company.id),
             contact_id=str(contact.id),
         )
 
         self.assertEqual(method.contact_id, contact.id)
 
     def test_assign_number_rejected_for_different_client(self) -> None:
-        """A number owned by one client cannot be assigned to a different client."""
+        """A number owned by one company cannot be assigned to a different company."""
         owner = self._client("Acme Ltd")
         other = self._client("Beta Ltd")
-        assign_phone_number(phone_number="021 555 901", client_id=str(owner.id))
+        assign_phone_number(phone_number="021 555 901", company_id=str(owner.id))
 
         with self.assertRaisesRegex(ValueError, "already belongs"):
-            assign_phone_number(phone_number="021 555 901", client_id=str(other.id))
+            assign_phone_number(phone_number="021 555 901", company_id=str(other.id))
 
     def test_single_contact_method_matches_contact(self) -> None:
-        client = self._client("Acme Ltd")
-        contact = ClientContact.objects.create(client=client, name="Jane Smith")
+        company = self._client("Acme Ltd")
+        contact = ClientContact.objects.create(company=company, name="Jane Smith")
         ClientContactMethod.objects.create(
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -142,21 +142,21 @@ def test_single_contact_method_matches_contact(self) -> None:
             is_primary=True,
         )
 
-        matched_client, matched_contact = PhoneMatcher().match_customer(
+        matched_company, matched_contact = PhoneMatcher().match_customer(
             "+6490000000",
             "+6421555123",
         )
 
-        self.assertEqual(matched_client, client)
+        self.assertEqual(matched_company, company)
         self.assertEqual(matched_contact, contact)
 
     def test_same_number_across_contacts_on_one_client_is_allowed(
         self,
     ) -> None:
-        """Two contacts of one client resolve to a single effective client owner."""
-        client = self._client("Acme Ltd")
-        jane = ClientContact.objects.create(client=client, name="Jane Smith")
-        john = ClientContact.objects.create(client=client, name="John Smith")
+        """Two contacts of one company resolve to a single effective company owner."""
+        company = self._client("Acme Ltd")
+        jane = ClientContact.objects.create(company=company, name="Jane Smith")
+        john = ClientContact.objects.create(company=company, name="John Smith")
         ClientContactMethod.objects.create(
             contact=jane,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -168,24 +168,24 @@ def test_same_number_across_contacts_on_one_client_is_allowed(
             value="021 555 123",
         )
 
-        matched_client, matched_contact = PhoneMatcher().match_customer("+6421555123")
+        matched_company, matched_contact = PhoneMatcher().match_customer("+6421555123")
 
         self.assertIsNotNone(on_john.pk)
-        self.assertEqual(matched_client, client)
+        self.assertEqual(matched_company, company)
         self.assertIsNone(matched_contact)
 
     def test_same_number_across_clients_is_rejected(self) -> None:
         first = self._client("Acme Ltd")
         second = self._client("Beta Ltd")
         ClientContactMethod.objects.create(
-            client=first,
+            company=first,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
 
         with self.assertRaises(ValidationError):
             ClientContactMethod.objects.create(
-                client=second,
+                company=second,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 value="021 555 123",
             )
@@ -213,16 +213,16 @@ def test_rematch_clears_job_link_when_number_moves_to_other_client(
         second = self._client("Beta Ltd")
         CompanyDefaults.objects.create(
             company_name="Test Company",
-            shop_client=first,
+            shop_company=first,
         )
         staff = Staff.objects.create_user(
             email="rematch-link@example.com",
             password="testpass",
             is_office_staff=True,
         )
-        job = Job.objects.create(client=first, name="Linked Job", staff=staff)
+        job = Job.objects.create(company=first, name="Linked Job", staff=staff)
         ClientContactMethod.objects.create(
-            client=second,
+            company=second,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="+6421555123",
             normalized_value="+6421555123",
@@ -236,7 +236,7 @@ def test_rematch_clears_job_link_when_number_moves_to_other_client(
             call_time=call_datetime.time(),
             origin="021 555 123",
             destination="+6490000000",
-            client=first,
+            company=first,
             job=job,
             job_linked_by=staff,
             job_linked_at=call_datetime,
@@ -250,7 +250,7 @@ def test_rematch_clears_job_link_when_number_moves_to_other_client(
         rematch_calls_for_numbers(["+6421555123"])
 
         call.refresh_from_db()
-        self.assertEqual(call.client, second)
+        self.assertEqual(call.company, second)
         self.assertIsNone(call.contact)
         self.assertIsNone(call.job)
         self.assertIsNone(call.job_linked_by)
@@ -264,13 +264,13 @@ class ProviderRecordingDeletionTests(TestCase):
     """
 
     def setUp(self) -> None:
-        shop_client = Client.objects.create(
-            name="Shop Client",
+        shop_company = Company.objects.create(
+            name="Shop Company",
             xero_last_modified=timezone.now(),
         )
         CompanyDefaults.objects.create(
             company_name="Test Company",
-            shop_client=shop_client,
+            shop_company=shop_company,
         )
         PhoneProviderSettings.objects.update_or_create(
             pk=1,
@@ -380,12 +380,12 @@ def tearDown(self) -> None:
         super().tearDown()
 
     def test_sync_archives_recording_and_is_idempotent(self) -> None:
-        client = Client.objects.create(
-            name="Sync Client",
+        company = Company.objects.create(
+            name="Sync Company",
             xero_last_modified=timezone.now(),
         )
         ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
@@ -418,7 +418,7 @@ def test_sync_archives_recording_and_is_idempotent(self) -> None:
         self.assertEqual(PhoneCallRecording.objects.count(), 1)
 
         call = PhoneCallRecord.objects.get()
-        self.assertEqual(call.client, client)
+        self.assertEqual(call.company, company)
         recording = call.recording
         self.assertEqual(recording.filename, "call.mp3")
         self.assertEqual(recording.byte_size, len(b"recorded audio"))
@@ -468,7 +468,7 @@ def _payload(self, *, recording_id: str = "recording-1") -> dict[str, str]:
 
 class PhoneCallJobLinkApiTests(BaseAPITestCase):
     """Business case: office staff must be able to connect an imported phone
-    call to the job it was about, while preventing cross-client history leaks.
+    call to the job it was about, while preventing cross-company history leaks.
     """
 
     def setUp(self) -> None:
@@ -491,25 +491,25 @@ def setUp(self) -> None:
         )
         self.api = APIClient()
         self.api.force_authenticate(user=self.office_staff)
-        self.client_obj = Client.objects.create(
-            name="Phone Link Client",
+        self.company_obj = Company.objects.create(
+            name="Phone Link Company",
             xero_last_modified=timezone.now(),
         )
-        self.other_client = Client.objects.create(
-            name="Other Phone Link Client",
+        self.other_company = Company.objects.create(
+            name="Other Phone Link Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.company_obj,
             name="Phone Link Job",
             staff=self.test_staff,
         )
         self.other_job = Job.objects.create(
-            client=self.other_client,
+            company=self.other_company,
             name="Other Phone Link Job",
             staff=self.test_staff,
         )
-        self.call = self._call("call-1", client=self.client_obj)
+        self.call = self._call("call-1", company=self.company_obj)
 
     def tearDown(self) -> None:
         self.settings_override.disable()
@@ -542,8 +542,8 @@ def test_link_call_to_same_client_job_and_filter_by_job(self) -> None:
 
     def test_list_paginates_recent_calls(self) -> None:
         """Catches CRM calls page regressions that fetch the full call archive."""
-        self._call("call-2", client=self.client_obj)
-        self._call("call-3", client=self.client_obj)
+        self._call("call-2", company=self.company_obj)
+        self._call("call-3", company=self.company_obj)
 
         response = self.api.get("/api/crm/phone-calls/", {"page_size": "2"})
 
@@ -587,7 +587,7 @@ def test_empty_list_uses_paginator_total_pages(self) -> None:
     def test_list_page_size_is_capped(self) -> None:
         """Catches accidental oversized phone-call responses."""
         for index in range(101):
-            self._call(f"call-{index + 2}", client=self.client_obj)
+            self._call(f"call-{index + 2}", company=self.company_obj)
 
         response = self.api.get("/api/crm/phone-calls/", {"page_size": "250"})
 
@@ -601,8 +601,8 @@ def test_list_filters_unmatched_and_unlinked_calls(self) -> None:
         linked = self.call
         linked.job = self.job
         linked.save(update_fields=["job", "updated_at"])
-        unlinked = self._call("unlinked", client=self.client_obj)
-        unmatched = self._call("unmatched", client=None)
+        unlinked = self._call("unlinked", company=self.company_obj)
+        unmatched = self._call("unmatched", company=None)
 
         unmatched_response = self.api.get(
             "/api/crm/phone-calls/",
@@ -655,7 +655,7 @@ def test_list_filters_by_direction_recording_date_and_search(self) -> None:
         )
         outbound = self._call(
             "outbound",
-            client=self.client_obj,
+            company=self.company_obj,
             origin="+6496365131",
             destination="+6421555999",
         )
@@ -678,7 +678,7 @@ def test_list_filters_by_direction_recording_date_and_search(self) -> None:
                 "has_recording": "true",
                 "from_date": timezone.localdate().isoformat(),
                 "to_date": timezone.localdate().isoformat(),
-                "q": "Phone Link Client",
+                "q": "Phone Link Company",
             },
         )
 
@@ -687,7 +687,7 @@ def test_list_filters_by_direction_recording_date_and_search(self) -> None:
         self.assertEqual(response.data["results"][0]["id"], str(recorded_call.id))
 
     def test_bad_call_id_does_not_persist_app_error(self) -> None:
-        """Catches client typos being treated as server errors."""
+        """Catches company typos being treated as server errors."""
         before = AppError.objects.count()
 
         response = self.api.post(
@@ -714,7 +714,7 @@ def test_malformed_call_id_does_not_persist_app_error(self) -> None:
         self.assertEqual(AppError.objects.count(), before)
 
     def test_bad_job_id_does_not_persist_app_error(self) -> None:
-        """Catches client typos being treated as server errors."""
+        """Catches company typos being treated as server errors."""
         before = AppError.objects.count()
 
         response = self.api.post(
@@ -736,7 +736,7 @@ def test_service_rejects_malformed_job_id_as_client_error(self) -> None:
             )
 
     def test_bad_call_id_on_unlink_does_not_persist_app_error(self) -> None:
-        """Catches client typos being treated as server errors."""
+        """Catches company typos being treated as server errors."""
         before = AppError.objects.count()
 
         response = self.api.delete(f"/api/crm/phone-calls/{uuid.uuid4()}/job-link/")
@@ -762,13 +762,13 @@ def test_assign_number_bad_client_id_does_not_persist_app_error(self) -> None:
         response = self.api.post(
             f"/api/crm/phone-calls/{self.call.id}/assign-number/",
             {
-                "client": str(uuid.uuid4()),
+                "company": str(uuid.uuid4()),
             },
             format="json",
         )
 
         self.assertEqual(response.status_code, 400)
-        self.assertIn("Client not found", response.data["message"])
+        self.assertIn("Company not found", response.data["message"])
         self.assertEqual(AppError.objects.count(), before)
 
     def test_assign_number_cross_client_contact_does_not_persist_app_error(
@@ -777,7 +777,7 @@ def test_assign_number_cross_client_contact_does_not_persist_app_error(
         self.call.external_number = "+6421555001"
         self.call.save(update_fields=["external_number", "updated_at"])
         contact = ClientContact.objects.create(
-            client=self.other_client,
+            company=self.other_company,
             name="Other Contact",
         )
         before = AppError.objects.count()
@@ -785,7 +785,7 @@ def test_assign_number_cross_client_contact_does_not_persist_app_error(
         response = self.api.post(
             f"/api/crm/phone-calls/{self.call.id}/assign-number/",
             {
-                "client": str(self.client_obj.id),
+                "company": str(self.company_obj.id),
                 "contact": str(contact.id),
             },
             format="json",
@@ -796,7 +796,7 @@ def test_assign_number_cross_client_contact_does_not_persist_app_error(
         self.assertEqual(AppError.objects.count(), before)
 
     def test_link_rejects_unmatched_call(self) -> None:
-        unmatched = self._call("unmatched", client=None)
+        unmatched = self._call("unmatched", company=None)
 
         response = self.api.post(
             f"/api/crm/phone-calls/{unmatched.id}/job-link/",
@@ -805,7 +805,7 @@ def test_link_rejects_unmatched_call(self) -> None:
         )
 
         self.assertEqual(response.status_code, 400)
-        self.assertIn("assigned to a client", response.data["message"])
+        self.assertIn("assigned to a company", response.data["message"])
 
     def test_link_rejects_cross_client_job(self) -> None:
         response = self.api.post(
@@ -815,7 +815,7 @@ def test_link_rejects_cross_client_job(self) -> None:
         )
 
         self.assertEqual(response.status_code, 400)
-        self.assertIn("same client", response.data["message"])
+        self.assertIn("same company", response.data["message"])
 
     def test_unlink_clears_job_metadata(self) -> None:
         self.call.job = self.job
@@ -896,7 +896,7 @@ def _call(
         self,
         provider_id: str,
         *,
-        client: Client | None,
+        company: Company | None,
         origin: str = "+6421555123",
         destination: str = "+6496365131",
     ) -> PhoneCallRecord:
@@ -910,7 +910,7 @@ def _call(
             call_time=call_datetime.time(),
             origin=origin,
             destination=destination,
-            client=client,
+            company=company,
             raw_json={
                 "id": provider_id,
                 "calldate": call_date.isoformat(),
diff --git a/apps/crm/tests/test_phone_endpoint_guard.py b/apps/crm/tests/test_phone_endpoint_guard.py
index 12bf90f11..2a544321a 100644
--- a/apps/crm/tests/test_phone_endpoint_guard.py
+++ b/apps/crm/tests/test_phone_endpoint_guard.py
@@ -2,7 +2,7 @@
 
 ClientContactMethod.save() refuses numbers held by an active PhoneEndpoint;
 these tests cover the mirror — an active endpoint cannot claim a number a
-client already owns, or that client's calls silently become INTERNAL.
+company already owns, or that company's calls silently become INTERNAL.
 """
 
 from django.core.exceptions import ValidationError
@@ -11,18 +11,18 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.crm.models import PhoneEndpoint
 from apps.testing import BaseAPITestCase
 
 
-def _client(name: str = "Acme Ltd") -> Client:
-    return Client.objects.create(name=name, xero_last_modified=timezone.now())
+def _client(name: str = "Acme Ltd") -> Company:
+    return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
 
-def _client_phone(client: Client, value: str = "021 555 123") -> ClientContactMethod:
+def _client_phone(company: Company, value: str = "021 555 123") -> ClientContactMethod:
     return ClientContactMethod.objects.create(
-        client=client,
+        company=company,
         method_type=ClientContactMethod.MethodType.PHONE,
         value=value,
     )
@@ -43,13 +43,13 @@ def test_create_active_endpoint_over_client_number_raises(self) -> None:
         _client_phone(_client("Acme Ltd"))
 
         with self.assertRaisesRegex(
-            ValidationError, "already belongs to.*client Acme Ltd"
+            ValidationError, "already belongs to.*company Acme Ltd"
         ):
             _endpoint("021 555 123")
 
     def test_error_names_owning_contact(self) -> None:
         contact = ClientContact.objects.create(
-            client=_client("Acme Ltd"), name="Jane Smith"
+            company=_client("Acme Ltd"), name="Jane Smith"
         )
         ClientContactMethod.objects.create(
             contact=contact,
@@ -89,7 +89,7 @@ def test_existing_endpoint_resave_is_grandfathered(self) -> None:
         # Legacy cross-owned row inserted bypassing the method-side guard,
         # as pre-guard data was.
         legacy = ClientContactMethod(
-            client=_client(),
+            company=_client(),
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
@@ -137,7 +137,7 @@ def test_create_endpoint_over_client_number_returns_400(self) -> None:
     def test_update_unrelated_field_on_grandfathered_endpoint_succeeds(self) -> None:
         endpoint = _endpoint("021 555 123")
         legacy = ClientContactMethod(
-            client=_client(),
+            company=_client(),
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
diff --git a/apps/crm/views/phone_call_views.py b/apps/crm/views/phone_call_views.py
index 301836f4f..0185efe34 100644
--- a/apps/crm/views/phone_call_views.py
+++ b/apps/crm/views/phone_call_views.py
@@ -65,7 +65,7 @@ def _query_uuid(value: str | None, field_name: str) -> UUID | None:
 
 def _phone_call_filter_kwargs(request: Request) -> dict[str, UUID]:
     query_filters = (
-        ("client_id", _query_uuid(request.query_params.get("client"), "client")),
+        ("company_id", _query_uuid(request.query_params.get("company"), "company")),
         ("contact_id", _query_uuid(request.query_params.get("contact"), "contact")),
         ("job_id", _query_uuid(request.query_params.get("job"), "job")),
         (
@@ -122,9 +122,9 @@ def _apply_client_match_filter(
     client_match: str,
 ) -> QuerySet[PhoneCallRecord]:
     if client_match == "matched":
-        return queryset.filter(client_id__isnull=False)
+        return queryset.filter(company_id__isnull=False)
     if client_match == "unmatched":
-        return queryset.filter(client_id__isnull=True)
+        return queryset.filter(company_id__isnull=True)
     return queryset
 
 
@@ -184,7 +184,7 @@ def _apply_search_filter(
 
     normalized_phone = normalize_phone(search)
     filters = (
-        Q(client__name__icontains=search)
+        Q(company__name__icontains=search)
         | Q(contact__name__icontains=search)
         | Q(origin_endpoint__label__icontains=search)
         | Q(destination_endpoint__label__icontains=search)
@@ -240,7 +240,7 @@ class PhoneCallRecordViewSet(viewsets.ReadOnlyModelViewSet[PhoneCallRecord]):
 
     @extend_schema(
         parameters=[
-            OpenApiParameter("client", OpenApiTypes.UUID, OpenApiParameter.QUERY),
+            OpenApiParameter("company", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("contact", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("job", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter(
@@ -282,7 +282,7 @@ def list(self, request: Request, *args: str, **kwargs: str) -> Response:
     def get_queryset(self) -> QuerySet[PhoneCallRecord]:
         queryset = (
             PhoneCallRecord.objects.select_related(
-                "client",
+                "company",
                 "contact",
                 "job",
                 "job_linked_by",
@@ -301,7 +301,7 @@ def _call_operation_response(
     ) -> Response:
         """Run a phone-call service operation and serialize the updated call.
 
-        ValueError is the services' client-error contract (400, no AppError);
+        ValueError is the services' company-error contract (400, no AppError);
         anything else follows the mandatory two-arm persistence pattern.
         """
         try:
@@ -377,7 +377,7 @@ def assign_number(
         return self._call_operation_response(
             lambda: assign_phone_number_from_call(
                 call_id=str(pk),
-                client_id=str(payload.validated_data["client"]),
+                company_id=str(payload.validated_data["company"]),
                 contact_id=str(contact) if contact else None,
                 label=payload.validated_data["label"],
                 is_primary=payload.validated_data["is_primary"],
diff --git a/apps/job/management/commands/create_shop_jobs.py b/apps/job/management/commands/create_shop_jobs.py
index 809226514..b325751ca 100644
--- a/apps/job/management/commands/create_shop_jobs.py
+++ b/apps/job/management/commands/create_shop_jobs.py
@@ -13,12 +13,12 @@ def handle(self, *args, **kwargs):
         shop_jobs = [
             {
                 "name": "Business Development",
-                "description": "Sales without a specific client",
+                "description": "Sales without a specific company",
             },
             {
                 "name": "Bench - busy work",
                 "description": (
-                    "Busy work not directly tied to client jobs. "
+                    "Busy work not directly tied to company jobs. "
                     "Could slip without significant issues"
                 ),
             },
@@ -47,7 +47,7 @@ def handle(self, *args, **kwargs):
         ]
 
         company_defaults = CompanyDefaults.get_solo()
-        shop_client = company_defaults.shop_client
+        shop_company = company_defaults.shop_company
 
         # Iterate through the shop jobs and create them
         automation_user = Staff.get_automation_user()
@@ -55,7 +55,7 @@ def handle(self, *args, **kwargs):
             # Create the job instance
             job = Job(
                 name=job_details["name"],
-                client=shop_client,
+                company=shop_company,
                 description="",
                 status="special",
                 shop_job=True,  # Changed from shop_job to is_shop_job
diff --git a/apps/job/migrations/0001_baseline.py b/apps/job/migrations/0001_baseline.py
index 37a56db51..73c801867 100644
--- a/apps/job/migrations/0001_baseline.py
+++ b/apps/job/migrations/0001_baseline.py
@@ -16,7 +16,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         ("workflow", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
@@ -245,7 +245,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="jobs",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
                 (
@@ -256,7 +256,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.SET_NULL,
                         related_name="jobs",
-                        to="client.clientcontact",
+                        to="company.clientcontact",
                     ),
                 ),
                 (
diff --git a/apps/job/migrations/0003_rename_client_company.py b/apps/job/migrations/0003_rename_client_company.py
new file mode 100644
index 000000000..c409a740f
--- /dev/null
+++ b/apps/job/migrations/0003_rename_client_company.py
@@ -0,0 +1,15 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("job", "0002_seed_labour_subtypes"),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name="job",
+            old_name="client",
+            new_name="company",
+        ),
+    ]
diff --git a/apps/job/models/costing.py b/apps/job/models/costing.py
index 2a017461e..15fd011dd 100644
--- a/apps/job/models/costing.py
+++ b/apps/job/models/costing.py
@@ -98,7 +98,7 @@ class CostLine(models.Model):
     TIME (kind='time'):
         - staff_id (str, UUID): Legacy Staff reference; use staff FK instead
         - date (str, ISO date): Date the work was performed (legacy, use accounting_date field)
-        - is_billable (bool): Whether this time is billable to the client
+        - is_billable (bool): Whether this time is billable to the company
         - start_time (str, ISO time): Start time of the timesheet entry
         - end_time (str, ISO time): End time of the timesheet entry
         - wage_rate_multiplier (float): Multiplier for staff wage rate (e.g., 1.5 for overtime)
diff --git a/apps/job/models/job.py b/apps/job/models/job.py
index 5872dbcf8..fe98357cf 100644
--- a/apps/job/models/job.py
+++ b/apps/job/models/job.py
@@ -9,7 +9,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.enums import RDTIType, SpeedQualityTradeoff
 from apps.workflow.models import CompanyDefaults, XeroPayItem
 
@@ -108,8 +108,8 @@ class Job(models.Model):
     # CHECKLIST - when adding a new field or property to Job, check these locations:
     #   1. JOB_DIRECT_FIELDS below (if it's a model field)
     #   2. JobSerializer.Meta.fields in apps/job/serializers/job_serializer.py
-    #   3. ClientJobHeaderSerializer in apps/client/serializers.py
-    #   4. get_client_jobs() response dict in apps/client/services/client_rest_service.py
+    #   3. ClientJobHeaderSerializer in apps/company/serializers.py
+    #   4. get_company_jobs() response dict in apps/company/services/company_rest_service.py
     #   5. KanbanService.serialize_job_for_api() in apps/job/services/kanban_service.py
     #   6. KanbanJobSerializer and KanbanColumnJobSerializer in apps/job/serializers/kanban_serializer.py
     #   7. TestSerializeJobForApi.test_serialized_shape_for_fully_populated_job
@@ -207,17 +207,17 @@ class Job(models.Model):
         "archived": "The job has been paid for and picked up",
     }
 
-    client = models.ForeignKey(
-        "client.Client",
-        on_delete=models.PROTECT,  # Prevent deletion of clients with jobs
+    company = models.ForeignKey(
+        "company.Company",
+        on_delete=models.PROTECT,  # Prevent deletion of companies with jobs
         null=True,
-        related_name="jobs",  # Allows reverse lookup of jobs for a client
+        related_name="jobs",  # Allows reverse lookup of jobs for a company
     )
     order_number = models.CharField(max_length=100, null=True, blank=True)
 
     # New relationship to ClientContact
     contact = models.ForeignKey(
-        "client.ClientContact",
+        "company.ClientContact",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
@@ -301,7 +301,7 @@ class Job(models.Model):
     #     related_name="revisions",
     #     on_delete=models.SET_NULL,
     # )
-    # Shop job has no client (client_id is None)
+    # Shop job has no company (company_id is None)
 
     job_is_valid = models.BooleanField(default=False)
     collected: bool = models.BooleanField(default=False)
@@ -421,21 +421,21 @@ def _calculate_next_priority_for_status(cls, status_value: str) -> float:
 
     @property
     def shop_job(self) -> bool:
-        """Indicates if this is a shop job (belongs to shop client)."""
-        if not self.client_id:
+        """Indicates if this is a shop job (belongs to shop company)."""
+        if not self.company_id:
             return False
 
         defaults = CompanyDefaults.get_solo()
-        return self.client_id == defaults.shop_client_id
+        return self.company_id == defaults.shop_company_id
 
     @shop_job.setter
     def shop_job(self, value: bool) -> None:
-        """Sets whether this is a shop job by updating the client ID."""
+        """Sets whether this is a shop job by updating the company ID."""
         if value:
             defaults = CompanyDefaults.get_solo()
-            self.client_id = defaults.shop_client_id
+            self.company_id = defaults.shop_company_id
         else:
-            self.client_id = None
+            self.company_id = None
 
     @property
     def quoted(self) -> bool:
@@ -553,11 +553,11 @@ def set_latest(self, kind: str, cost_set: "CostSet", staff) -> None:
     @property
     def job_display_name(self) -> str:
         """
-        Returns a formatted display name for the job including client name.
-        Format: job_number - (first 12 chars of client name), job_name
+        Returns a formatted display name for the job including company name.
+        Format: job_number - (first 12 chars of company name), job_name
         """
-        client_name = self.client.name[:12] if self.client else "No Client"
-        return f"{self.job_number} - {client_name}, {self.name}"
+        company_name = self.company.name[:12] if self.company else "No Company"
+        return f"{self.job_number} - {company_name}, {self.name}"
 
     @property
     def start_date(self) -> Optional[date]:
@@ -930,19 +930,25 @@ def _handle_status_change(self_job, old_status, new_status):
         )
 
     @staticmethod
-    def _handle_client_change(self_job, old_client_id, new_client_id):
-        old_client = "Shop Job"
-        new_client = "Shop Job"
-        if old_client_id:
+    def _handle_company_change(self_job, old_company_id, new_company_id):
+        old_company = "Shop Job"
+        new_company = "Shop Job"
+        if old_company_id:
             try:
-                old_client = Client.objects.get(id=old_client_id).name
+                old_company = Company.objects.get(id=old_company_id).name
             except Exception:
-                old_client = "Unknown Client"
-        if new_client_id:
-            new_client = self_job.client.name if self_job.client else "Unknown Client"
+                old_company = "Unknown Company"
+        if new_company_id:
+            new_company = (
+                self_job.company.name if self_job.company else "Unknown Company"
+            )
         return (
             "client_changed",
-            {"field_name": "Client", "old_value": old_client, "new_value": new_client},
+            {
+                "field_name": "Company",
+                "old_value": old_company,
+                "new_value": new_company,
+            },
         )
 
     @staticmethod
@@ -951,7 +957,7 @@ def _handle_contact_change(self_job, old_contact_id, new_contact_id):
         new_contact = "None"
         if old_contact_id:
             try:
-                from apps.client.models import ClientContact
+                from apps.company.models import ClientContact
 
                 old_contact = ClientContact.objects.get(id=old_contact_id).name
             except Exception:
@@ -1098,7 +1104,7 @@ def _handle_rdti_type_change(_self_job, old_type, new_type):
             "job_updated",
             {"field_name": "Job name", "old_value": str(old), "new_value": str(new)},
         ),
-        "client_id": _handle_client_change.__func__,
+        "company_id": _handle_company_change.__func__,
         "contact_id": _handle_contact_change.__func__,
         "order_number": lambda _self, old, new: (
             "job_updated",
diff --git a/apps/job/models/job_event.py b/apps/job/models/job_event.py
index f83a74e6c..a9b6c88a3 100644
--- a/apps/job/models/job_event.py
+++ b/apps/job/models/job_event.py
@@ -272,13 +272,13 @@ def _build_status_changed_description(detail: dict) -> str:
     @staticmethod
     def _build_job_created_description(detail: dict) -> str:
         job_name = detail.get("job_name", "Unknown")
-        client_name = detail.get("client_name", "Unknown")
+        company_name = detail.get("company_name", "Unknown")
         contact_name = detail.get("contact_name")
         initial_status = detail.get("initial_status", "Unknown")
         pricing = detail.get("pricing_methodology", "Unknown")
         contact_info = f" (Contact: {contact_name})" if contact_name else ""
         return (
-            f"New job '{job_name}' created for client {client_name}{contact_info}. "
+            f"New job '{job_name}' created for company {company_name}{contact_info}. "
             f"Initial status: {initial_status}. "
             f"Pricing methodology: {pricing}."
         )
diff --git a/apps/job/serializers/costing_serializer.py b/apps/job/serializers/costing_serializer.py
index 31cfc654f..bd9100049 100644
--- a/apps/job/serializers/costing_serializer.py
+++ b/apps/job/serializers/costing_serializer.py
@@ -40,7 +40,7 @@ class TimesheetCostLineSerializer(serializers.ModelSerializer):
     Architecture principle: Job data comes from CostSet->Job relationship,
     NOT from metadata. This ensures data consistency and follows SRP:
     - Metadata = timesheet-specific data (staff, date, billable, etc.)
-    - Relationship = job data (job_id, job_number, job_name, client)
+    - Relationship = job data (job_id, job_number, job_name, company)
 
     Benefits:
     - No data duplication
@@ -64,8 +64,8 @@ class TimesheetCostLineSerializer(serializers.ModelSerializer):
         source="labour_subtype.name", read_only=True
     )
 
-    # Client name with null handling
-    client_name = serializers.SerializerMethodField()
+    # Company name with null handling
+    company_name = serializers.SerializerMethodField()
 
     # Staff wage rate for frontend cost calculations
     wage_rate = serializers.SerializerMethodField()
@@ -97,10 +97,10 @@ def get_total_rev(self, obj) -> float:
         """Get total revenue (quantity * unit_rev)"""
         return float(obj.quantity * obj.unit_rev) if obj.unit_rev else 0.0
 
-    def get_client_name(self, obj) -> str:
-        """Get client name with safe null handling"""
-        if obj.cost_set and obj.cost_set.job and obj.cost_set.job.client:
-            return obj.cost_set.job.client.name
+    def get_company_name(self, obj) -> str:
+        """Get company name with safe null handling"""
+        if obj.cost_set and obj.cost_set.job and obj.cost_set.job.company:
+            return obj.cost_set.job.company.name
         return ""
 
     def get_wage_rate(self, obj) -> float:
@@ -124,7 +124,7 @@ class Meta:
             "job_id",
             "job_number",
             "job_name",
-            "client_name",
+            "company_name",
             "charge_out_rate",
             "wage_rate",
             "xero_pay_item_name",
diff --git a/apps/job/serializers/data_quality_report_serializers.py b/apps/job/serializers/data_quality_report_serializers.py
index 2f023c932..c4729be92 100644
--- a/apps/job/serializers/data_quality_report_serializers.py
+++ b/apps/job/serializers/data_quality_report_serializers.py
@@ -2,7 +2,7 @@
 
 from rest_framework import serializers
 
-from apps.client.services.duplicate_phone_report import (
+from apps.company.services.duplicate_phone_report import (
     DuplicatePhoneIssue,
     DuplicatePhoneOwner,
     DuplicatePhonesReport,
@@ -30,7 +30,7 @@ class ArchivedJobIssueSerializer(serializers.Serializer):
 
     job_id = serializers.CharField(help_text="Job's unique identifier")
     job_number = serializers.CharField(help_text="Job number")
-    client_name = serializers.CharField(help_text="Client name or 'Shop Job'")
+    company_name = serializers.CharField(help_text="Company name or 'Shop Job'")
     archived_date = serializers.DateField(help_text="Date when job was archived")
     current_status = serializers.CharField(help_text="Job's current status")
     issue = serializers.CharField(
@@ -71,10 +71,10 @@ class DuplicatePhoneOwnerSerializer(serializers.Serializer[DuplicatePhoneOwner])
     """One owner of a mis-owned phone number."""
 
     method_id = serializers.CharField(help_text="Contact-method id")
-    owner_kind = serializers.CharField(help_text="'client' or 'contact'")
+    owner_kind = serializers.CharField(help_text="'company' or 'contact'")
     owner_name = serializers.CharField(help_text="Human-readable owner")
     effective_client_id = serializers.CharField(
-        allow_null=True, help_text="Client the number resolves to"
+        allow_null=True, help_text="Company the number resolves to"
     )
 
 
@@ -82,10 +82,10 @@ class DuplicatePhoneSummarySerializer(serializers.Serializer[DuplicatePhoneSumma
     """Summary of duplicate-phone issues."""
 
     cross_client = serializers.IntegerField(
-        help_text="Numbers owned by more than one client"
+        help_text="Numbers owned by more than one company"
     )
     internal_line = serializers.IntegerField(
-        help_text="Client numbers that are actually internal company lines"
+        help_text="Company numbers that are actually internal company lines"
     )
 
 
diff --git a/apps/job/serializers/job_profitability_report_serializers.py b/apps/job/serializers/job_profitability_report_serializers.py
index 1c16dca4c..6dc953377 100644
--- a/apps/job/serializers/job_profitability_report_serializers.py
+++ b/apps/job/serializers/job_profitability_report_serializers.py
@@ -59,7 +59,7 @@ class JobProfitabilityItemSerializer(serializers.Serializer):
     job_id = serializers.CharField(help_text="Job UUID")
     job_number = serializers.IntegerField(help_text="Job number")
     job_name = serializers.CharField(help_text="Job description", allow_blank=True)
-    client_name = serializers.CharField(help_text="Client name")
+    company_name = serializers.CharField(help_text="Company name")
     pricing_type = serializers.CharField(help_text="Pricing methodology key")
     pricing_type_display = serializers.CharField(help_text="Pricing methodology label")
     completion_date = serializers.CharField(
diff --git a/apps/job/serializers/job_serializer.py b/apps/job/serializers/job_serializer.py
index 069078a6e..0ef14b2a5 100644
--- a/apps/job/serializers/job_serializer.py
+++ b/apps/job/serializers/job_serializer.py
@@ -8,7 +8,7 @@
 
 from apps.accounting.models.invoice import Invoice
 from apps.accounting.models.quote import Quote
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job, JobEvent, JobFile
 from apps.workflow.models import XeroPayItem
 
@@ -113,16 +113,16 @@ class JobSerializer(serializers.ModelSerializer):
     xero_quote = serializers.SerializerMethodField()
     xero_invoices = serializers.SerializerMethodField()
 
-    client_id = serializers.PrimaryKeyRelatedField(
-        queryset=Client.objects.all(),
-        source="client",
+    company_id = serializers.PrimaryKeyRelatedField(
+        queryset=Company.objects.all(),
+        source="company",
         write_only=False,  # Allow read access,
         allow_null=True,
         required=False,
     )
-    # Some clients might not exist in old production data, so for compatibility we allow null values for it (unrequired, allow_null=True)
-    client_name = serializers.CharField(
-        source="client.name", read_only=True, allow_null=True, required=False
+    # Some companies might not exist in old production data, so for compatibility we allow null values for it (unrequired, allow_null=True)
+    company_name = serializers.CharField(
+        source="company.name", read_only=True, allow_null=True, required=False
     )
     contact_id = serializers.PrimaryKeyRelatedField(
         queryset=ClientContact.objects.all(),
@@ -206,8 +206,8 @@ class Meta:
         fields = [
             "id",
             "name",
-            "client_id",
-            "client_name",
+            "company_id",
+            "company_name",
             "contact_id",
             "contact_name",
             "job_number",
@@ -250,30 +250,30 @@ def validate(self, attrs):
         if DEBUG_SERIALIZER:
             logger.debug(f"JobSerializer validate called with attrs: {attrs}")
 
-        # Validate contact belongs to client
+        # Validate contact belongs to company
         contact = attrs.get("contact")
-        client = attrs.get("client")
+        company = attrs.get("company")
 
-        # If we're updating and no client is provided, use the existing client
-        if not client and self.instance:
-            client = self.instance.client
+        # If we're updating and no company is provided, use the existing company
+        if not company and self.instance:
+            company = self.instance.company
 
-        if contact and client:
+        if contact and company:
             logger.debug(
-                f"JobSerializer validate - Checking if contact {contact.id} belongs to client {client.id}"
+                f"JobSerializer validate - Checking if contact {contact.id} belongs to company {company.id}"
             )
-            if contact.client != client:
+            if contact.company != company:
                 logger.error(
-                    f"JobSerializer validate - Contact {contact.id} does not belong to client {client.id}"
+                    f"JobSerializer validate - Contact {contact.id} does not belong to company {company.id}"
                 )
                 raise serializers.ValidationError(
                     {
-                        "contact_id": f"Contact does not belong to the selected client. Contact belongs to {contact.client.name}, but job is for {client.name}."
+                        "contact_id": f"Contact does not belong to the selected company. Contact belongs to {contact.company.name}, but job is for {company.name}."
                     }
                 )
             if DEBUG_SERIALIZER:
                 logger.debug(
-                    f"JobSerializer validate - Contact {contact.id} belongs to client {client.id}"
+                    f"JobSerializer validate - Contact {contact.id} belongs to company {company.id}"
                 )
                 logger.debug("JobSerializer validate - Contact validation passed")
 
@@ -437,7 +437,7 @@ def get_undo_description(self, obj) -> str | None:
                 "status": "status",
                 "order_number": "order number",
                 "notes": "notes",
-                "client_id": "client",
+                "company_id": "company",
                 "contact_id": "contact",
                 "delivery_date": "delivery date",
                 "job_status": "status",
@@ -501,19 +501,26 @@ class JobSummaryResponseSerializer(serializers.Serializer):
 
 
 class CompleteJobSerializer(serializers.ModelSerializer):
-    client_name = serializers.CharField(source="client.name", read_only=True)
+    company_name = serializers.CharField(source="company.name", read_only=True)
     job_status = serializers.CharField(source="status")
 
     class Meta:
         model = Job
-        fields = ["id", "job_number", "name", "client_name", "updated_at", "job_status"]
+        fields = [
+            "id",
+            "job_number",
+            "name",
+            "company_name",
+            "updated_at",
+            "job_status",
+        ]
 
 
 class JobCreateSerializer(serializers.Serializer):
     """Serializer for job creation request data."""
 
     name = serializers.CharField(max_length=255)
-    client_id = serializers.UUIDField()
+    company_id = serializers.UUIDField()
     description = serializers.CharField(required=False, allow_blank=True)
     order_number = serializers.CharField(required=False, allow_blank=True)
     notes = serializers.CharField(required=False, allow_blank=True)
@@ -631,7 +638,7 @@ class MonthEndJobSerializer(serializers.Serializer):
     job_id = serializers.UUIDField()
     job_number = serializers.IntegerField()
     job_name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     history = MonthEndJobHistorySerializer(many=True)
     total_hours = serializers.FloatField()
     total_dollars = serializers.FloatField()
@@ -786,7 +793,7 @@ class WeeklyMetricsSerializer(serializers.Serializer):
     job_id = serializers.UUIDField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client = serializers.CharField(required=False, allow_null=True, allow_blank=True)
+    company = serializers.CharField(required=False, allow_null=True, allow_blank=True)
     description = serializers.CharField(
         required=False, allow_null=True, allow_blank=True
     )
@@ -806,11 +813,11 @@ class JobHeaderResponseSerializer(serializers.ModelSerializer):
     """Serializer for job header response - essential job data for fast loading."""
 
     job_id = serializers.UUIDField(source="id")
-    client_id = serializers.UUIDField(
-        source="client.id", read_only=True, allow_null=True
+    company_id = serializers.UUIDField(
+        source="company.id", read_only=True, allow_null=True
     )
-    client_name = serializers.CharField(
-        source="client.name", read_only=True, allow_null=True
+    company_name = serializers.CharField(
+        source="company.name", read_only=True, allow_null=True
     )
     contact_id = serializers.UUIDField(
         source="contact.id", read_only=True, allow_null=True
@@ -831,8 +838,8 @@ class Meta:
         # Derive fields from Job.JOB_DIRECT_FIELDS, plus special fields
         fields = [
             "job_id",
-            "client_id",
-            "client_name",
+            "company_id",
+            "company_name",
             "contact_id",
             "contact_name",
             "quoted",
@@ -1022,7 +1029,7 @@ def get_undo_description(self, obj) -> str | None:
                 "status": "status",
                 "order_number": "order number",
                 "notes": "notes",
-                "client_id": "client",
+                "company_id": "company",
                 "contact_id": "contact",
                 "delivery_date": "delivery date",
                 "job_status": "status",
@@ -1095,7 +1102,7 @@ class JobPatchSerializer(serializers.Serializer):
     )
     rejected_flag = serializers.BooleanField(
         required=False,
-        help_text="Whether the job was rejected (quote declined by client)",
+        help_text="Whether the job was rejected (quote declined by company)",
     )
 
     # Dates
@@ -1133,8 +1140,8 @@ class JobPatchSerializer(serializers.Serializer):
     )
 
     # Relationships (only IDs, no derived names)
-    client_id = serializers.UUIDField(
-        required=False, allow_null=True, help_text="Client ID"
+    company_id = serializers.UUIDField(
+        required=False, allow_null=True, help_text="Company ID"
     )
     contact_id = serializers.UUIDField(
         required=False, allow_null=True, help_text="Contact person ID"
@@ -1145,13 +1152,13 @@ class JobPatchSerializer(serializers.Serializer):
         child=serializers.DictField(), required=False, help_text="Job files"
     )
 
-    def validate_client_id(self, value):
-        """Validate that client exists if provided"""
+    def validate_company_id(self, value):
+        """Validate that company exists if provided"""
         if value:
             try:
-                Client.objects.get(id=value)
-            except Client.DoesNotExist:
-                raise serializers.ValidationError("Client not found")
+                Company.objects.get(id=value)
+            except Company.DoesNotExist:
+                raise serializers.ValidationError("Company not found")
         return value
 
     def validate_contact_id(self, value):
@@ -1165,19 +1172,21 @@ def validate_contact_id(self, value):
 
     def validate(self, attrs):
         """Cross-field validation"""
-        # Validate contact belongs to client if both are provided
+        # Validate contact belongs to company if both are provided
         contact_id = attrs.get("contact_id")
-        client_id = attrs.get("client_id")
+        company_id = attrs.get("company_id")
 
-        if contact_id and client_id:
+        if contact_id and company_id:
             try:
                 contact = ClientContact.objects.get(id=contact_id)
-                client = Client.objects.get(id=client_id)
-                if contact.client != client:
+                company = Company.objects.get(id=company_id)
+                if contact.company != company:
                     raise serializers.ValidationError(
-                        {"contact_id": "Contact does not belong to the selected client"}
+                        {
+                            "contact_id": "Contact does not belong to the selected company"
+                        }
                     )
-            except (ClientContact.DoesNotExist, Client.DoesNotExist):
+            except (ClientContact.DoesNotExist, Company.DoesNotExist):
                 pass  # Individual field validation will catch these
 
         return attrs
diff --git a/apps/job/serializers/kanban_serializer.py b/apps/job/serializers/kanban_serializer.py
index b1e2285ec..41fa8776a 100644
--- a/apps/job/serializers/kanban_serializer.py
+++ b/apps/job/serializers/kanban_serializer.py
@@ -69,7 +69,7 @@ class JobSearchFiltersSerializer(serializers.Serializer):
     job_number = serializers.IntegerField(required=False, allow_null=True)
     name = serializers.CharField(required=False, allow_blank=True)
     description = serializers.CharField(required=False, allow_blank=True)
-    client_name = serializers.CharField(required=False, allow_blank=True)
+    company_name = serializers.CharField(required=False, allow_blank=True)
     contact_person = serializers.CharField(required=False, allow_blank=True)
     created_by = serializers.CharField(required=False, allow_blank=True)
     created_after = serializers.DateField(required=False, allow_null=True)
@@ -100,8 +100,8 @@ class KanbanJobSerializer(serializers.Serializer):
     description = serializers.CharField(allow_blank=True, allow_null=True)
     job_number = serializers.IntegerField()
 
-    # Client and contact info
-    client_name = serializers.CharField(allow_blank=True)
+    # Company and contact info
+    company_name = serializers.CharField(allow_blank=True)
     contact_person = serializers.CharField(allow_blank=True)
 
     # People assigned to the job
@@ -198,8 +198,8 @@ class KanbanColumnJobSerializer(serializers.Serializer):
     name = serializers.CharField()
     description = serializers.CharField(allow_blank=True, allow_null=True)
 
-    # Client and contact info
-    client_name = serializers.CharField(allow_blank=True)
+    # Company and contact info
+    company_name = serializers.CharField(allow_blank=True)
     contact_person = serializers.CharField(allow_blank=True)
 
     # People assigned to the job (empty list for now)
@@ -264,6 +264,6 @@ class WorkshopJobSerializer(serializers.Serializer):
     name = serializers.CharField()
     description = serializers.CharField(allow_blank=True, allow_null=True)
     job_number = serializers.IntegerField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     contact_person = serializers.CharField(allow_blank=True, allow_null=True)
     people = KanbanJobPersonSerializer(many=True)
diff --git a/apps/job/services/chat_service.py b/apps/job/services/chat_service.py
index 62c71aacb..9702ff3c8 100644
--- a/apps/job/services/chat_service.py
+++ b/apps/job/services/chat_service.py
@@ -54,7 +54,7 @@ def _get_system_prompt(self, job: Job) -> str:
 Current Job Context:
 - Job: {job.name} (#{job.job_number})
 - Job ID: {job.id}
-- Client: {job.client.name}
+- Company: {job.company.name}
 - Status: {job.get_status_display()}
 - Description: {job.description or 'No description available'}
 
diff --git a/apps/job/services/data_integrity_service.py b/apps/job/services/data_integrity_service.py
index ef5bbdfef..4fc247647 100644
--- a/apps/job/services/data_integrity_service.py
+++ b/apps/job/services/data_integrity_service.py
@@ -17,7 +17,7 @@
     Quote,
 )
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import (
     CostLine,
     CostSet,
@@ -92,8 +92,8 @@ def _check_all_fk_references() -> list[dict[str, Any]]:
         # Workflow App
         issues.extend(DataIntegrityService._check_apperror_fks())
 
-        # Client App
-        issues.extend(DataIntegrityService._check_client_fks())
+        # Company App
+        issues.extend(DataIntegrityService._check_company_fks())
         issues.extend(DataIntegrityService._check_clientcontact_fks())
 
         # Purchasing App
@@ -115,20 +115,20 @@ def _check_all_fk_references() -> list[dict[str, Any]]:
     def _check_job_fks() -> list[dict[str, Any]]:
         """Check Job FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
         valid_contact_ids = set(ClientContact.objects.values_list("id", flat=True))
         valid_staff_ids = set(Staff.objects.values_list("id", flat=True))
         valid_costset_ids = set(CostSet.objects.values_list("id", flat=True))
 
         for job in Job.objects.all():
-            if job.client_id and job.client_id not in valid_client_ids:
+            if job.company_id and job.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "Job",
                         "record_id": str(job.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(job.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(job.company_id),
                     }
                 )
             if job.contact_id and job.contact_id not in valid_contact_ids:
@@ -335,7 +335,7 @@ def _check_invoice_fks() -> list[dict[str, Any]]:
         """Check Invoice FK references."""
         issues = []
         valid_job_ids = set(Job.objects.values_list("id", flat=True))
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for invoice in Invoice.objects.all():
             if invoice.job_id and invoice.job_id not in valid_job_ids:
@@ -348,14 +348,14 @@ def _check_invoice_fks() -> list[dict[str, Any]]:
                         "target_id": str(invoice.job_id),
                     }
                 )
-            if invoice.client_id not in valid_client_ids:
+            if invoice.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "Invoice",
                         "record_id": str(invoice.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(invoice.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(invoice.company_id),
                     }
                 )
 
@@ -365,17 +365,17 @@ def _check_invoice_fks() -> list[dict[str, Any]]:
     def _check_bill_fks() -> list[dict[str, Any]]:
         """Check Bill FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for bill in Bill.objects.all():
-            if bill.client_id not in valid_client_ids:
+            if bill.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "Bill",
                         "record_id": str(bill.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(bill.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(bill.company_id),
                     }
                 )
 
@@ -385,17 +385,17 @@ def _check_bill_fks() -> list[dict[str, Any]]:
     def _check_creditnote_fks() -> list[dict[str, Any]]:
         """Check CreditNote FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for creditnote in CreditNote.objects.all():
-            if creditnote.client_id not in valid_client_ids:
+            if creditnote.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "CreditNote",
                         "record_id": str(creditnote.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(creditnote.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(creditnote.company_id),
                     }
                 )
 
@@ -499,7 +499,7 @@ def _check_quote_fks() -> list[dict[str, Any]]:
         """Check Quote FK references."""
         issues = []
         valid_job_ids = set(Job.objects.values_list("id", flat=True))
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for quote in Quote.objects.all():
             if quote.job_id and quote.job_id not in valid_job_ids:
@@ -512,14 +512,14 @@ def _check_quote_fks() -> list[dict[str, Any]]:
                         "target_id": str(quote.job_id),
                     }
                 )
-            if quote.client_id not in valid_client_ids:
+            if quote.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "Quote",
                         "record_id": str(quote.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(quote.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(quote.company_id),
                     }
                 )
 
@@ -567,22 +567,25 @@ def _check_apperror_fks() -> list[dict[str, Any]]:
 
         return issues
 
-    # Client App FK Checks
+    # Company App FK Checks
     @staticmethod
-    def _check_client_fks() -> list[dict[str, Any]]:
-        """Check Client FK references."""
+    def _check_company_fks() -> list[dict[str, Any]]:
+        """Check Company FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
-        for client in Client.objects.all():
-            if client.merged_into_id and client.merged_into_id not in valid_client_ids:
+        for company in Company.objects.all():
+            if (
+                company.merged_into_id
+                and company.merged_into_id not in valid_company_ids
+            ):
                 issues.append(
                     {
-                        "model": "Client",
-                        "record_id": str(client.id),
+                        "model": "Company",
+                        "record_id": str(company.id),
                         "field": "merged_into",
-                        "target_model": "Client",
-                        "target_id": str(client.merged_into_id),
+                        "target_model": "Company",
+                        "target_id": str(company.merged_into_id),
                     }
                 )
 
@@ -592,17 +595,17 @@ def _check_client_fks() -> list[dict[str, Any]]:
     def _check_clientcontact_fks() -> list[dict[str, Any]]:
         """Check ClientContact FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for contact in ClientContact.objects.all():
-            if contact.client_id not in valid_client_ids:
+            if contact.company_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "ClientContact",
                         "record_id": str(contact.id),
-                        "field": "client",
-                        "target_model": "Client",
-                        "target_id": str(contact.client_id),
+                        "field": "company",
+                        "target_model": "Company",
+                        "target_id": str(contact.company_id),
                     }
                 )
 
@@ -613,17 +616,17 @@ def _check_clientcontact_fks() -> list[dict[str, Any]]:
     def _check_purchaseorder_fks() -> list[dict[str, Any]]:
         """Check PurchaseOrder FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
         valid_job_ids = set(Job.objects.values_list("id", flat=True))
 
         for po in PurchaseOrder.objects.all():
-            if po.supplier_id and po.supplier_id not in valid_client_ids:
+            if po.supplier_id and po.supplier_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "PurchaseOrder",
                         "record_id": str(po.id),
                         "field": "supplier",
-                        "target_model": "Client",
+                        "target_model": "Company",
                         "target_id": str(po.supplier_id),
                     }
                 )
@@ -757,19 +760,19 @@ def _check_stock_fks() -> list[dict[str, Any]]:
     def _check_supplierproduct_fks() -> list[dict[str, Any]]:
         """Check SupplierProduct FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
         valid_pricelist_ids = set(
             SupplierPriceList.objects.values_list("id", flat=True)
         )
 
         for product in SupplierProduct.objects.all():
-            if product.supplier_id not in valid_client_ids:
+            if product.supplier_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "SupplierProduct",
                         "record_id": str(product.id),
                         "field": "supplier",
-                        "target_model": "Client",
+                        "target_model": "Company",
                         "target_id": str(product.supplier_id),
                     }
                 )
@@ -790,16 +793,16 @@ def _check_supplierproduct_fks() -> list[dict[str, Any]]:
     def _check_supplierpricelist_fks() -> list[dict[str, Any]]:
         """Check SupplierPriceList FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for pricelist in SupplierPriceList.objects.all():
-            if pricelist.supplier_id not in valid_client_ids:
+            if pricelist.supplier_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "SupplierPriceList",
                         "record_id": str(pricelist.id),
                         "field": "supplier",
-                        "target_model": "Client",
+                        "target_model": "Company",
                         "target_id": str(pricelist.supplier_id),
                     }
                 )
@@ -810,16 +813,16 @@ def _check_supplierpricelist_fks() -> list[dict[str, Any]]:
     def _check_scrapejob_fks() -> list[dict[str, Any]]:
         """Check ScrapeJob FK references."""
         issues = []
-        valid_client_ids = set(Client.objects.values_list("id", flat=True))
+        valid_company_ids = set(Company.objects.values_list("id", flat=True))
 
         for scrapejob in ScrapeJob.objects.all():
-            if scrapejob.supplier_id not in valid_client_ids:
+            if scrapejob.supplier_id not in valid_company_ids:
                 issues.append(
                     {
                         "model": "ScrapeJob",
                         "record_id": str(scrapejob.id),
                         "field": "supplier",
-                        "target_model": "Client",
+                        "target_model": "Company",
                         "target_id": str(scrapejob.supplier_id),
                     }
                 )
@@ -941,8 +944,8 @@ def _check_business_rules() -> list[dict[str, Any]]:
         # Stock business rules
         issues.extend(DataIntegrityService._check_stock_business_rules())
 
-        # Client business rules
-        issues.extend(DataIntegrityService._check_client_business_rules())
+        # Company business rules
+        issues.extend(DataIntegrityService._check_company_business_rules())
 
         # JobFile business rules
         issues.extend(DataIntegrityService._check_jobfile_business_rules())
@@ -1215,24 +1218,24 @@ def _check_stock_business_rules() -> list[dict[str, Any]]:
         return issues
 
     @staticmethod
-    def _check_client_business_rules() -> list[dict[str, Any]]:
-        """Check Client business rules."""
+    def _check_company_business_rules() -> list[dict[str, Any]]:
+        """Check Company business rules."""
         issues = []
 
         # Check circular merges
-        checked_clients = set()
-        for client in Client.objects.exclude(merged_into__isnull=True):
-            if client.id in checked_clients:
+        checked_companies = set()
+        for company in Company.objects.exclude(merged_into__isnull=True):
+            if company.id in checked_companies:
                 continue
 
-            path = [client.id]
-            current = client
+            path = [company.id]
+            current = company
             while current.merged_into_id:
                 if current.merged_into_id in path:
                     issues.append(
                         {
-                            "model": "Client",
-                            "record_id": str(client.id),
+                            "model": "Company",
+                            "record_id": str(company.id),
                             "field": "merged_into",
                             "rule": "circular merge detected",
                             "path": [str(p) for p in path],
@@ -1240,10 +1243,10 @@ def _check_client_business_rules() -> list[dict[str, Any]]:
                     )
                     break
                 path.append(current.merged_into_id)
-                checked_clients.add(current.id)
+                checked_companies.add(current.id)
                 try:
-                    current = Client.objects.get(id=current.merged_into_id)
-                except Client.DoesNotExist:
+                    current = Company.objects.get(id=current.merged_into_id)
+                except Company.DoesNotExist:
                     break
 
         return issues
diff --git a/apps/job/services/data_quality_report.py b/apps/job/services/data_quality_report.py
index d9e98944d..cb292dcbf 100644
--- a/apps/job/services/data_quality_report.py
+++ b/apps/job/services/data_quality_report.py
@@ -33,7 +33,7 @@ def get_compliance_report(self) -> Dict[str, Any]:
         not_cancelled_count = 0
         has_open_tasks_count = 0
 
-        for job in archived_jobs.select_related("client"):
+        for job in archived_jobs.select_related("company"):
             issues = []
 
             # Job should either be cancelled/rejected OR (fully invoiced AND paid)
@@ -63,8 +63,8 @@ def get_compliance_report(self) -> Dict[str, Any]:
                             {
                                 "job_id": str(job.id),
                                 "job_number": job.job_number,
-                                "client_name": (
-                                    job.client.name if job.client else "Shop Job"
+                                "company_name": (
+                                    job.company.name if job.company else "Shop Job"
                                 ),
                                 "archived_date": (
                                     timezone.localtime(job.updated_at).date()
diff --git a/apps/job/services/job_profitability_report.py b/apps/job/services/job_profitability_report.py
index fdc2f851b..57e3d8587 100644
--- a/apps/job/services/job_profitability_report.py
+++ b/apps/job/services/job_profitability_report.py
@@ -69,14 +69,14 @@ def _get_queryset(self):
             completed_at__date__range=(self.start_date, self.end_date),
         )
 
-        shop_client_id = CompanyDefaults.get_solo().shop_client_id
-        qs = qs.exclude(client_id=shop_client_id)
+        shop_company_id = CompanyDefaults.get_solo().shop_company_id
+        qs = qs.exclude(company_id=shop_company_id)
 
         if self.pricing_type:
             qs = qs.filter(pricing_methodology=self.pricing_type)
 
         return qs.select_related(
-            "client", "latest_estimate", "latest_quote", "latest_actual"
+            "company", "latest_estimate", "latest_quote", "latest_actual"
         )
 
     def _build_job_rows(self, jobs_qs) -> List[Dict[str, Any]]:
@@ -162,7 +162,7 @@ def _compute_job_row(self, job: Job, revenue: Decimal) -> Dict[str, Any]:
             "job_id": str(job.id),
             "job_number": job.job_number,
             "job_name": job.description or "",
-            "client_name": job.client.name if job.client else "Unknown",
+            "company_name": job.company.name if job.company else "Unknown",
             "pricing_type": job.pricing_methodology,
             "pricing_type_display": job.get_pricing_methodology_display(),
             "completion_date": (
diff --git a/apps/job/services/job_rest_service.py b/apps/job/services/job_rest_service.py
index 9049b0fac..bbd98bd28 100644
--- a/apps/job/services/job_rest_service.py
+++ b/apps/job/services/job_rest_service.py
@@ -21,7 +21,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job, JobDeltaRejection, JobEvent, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.job.serializers import JobSerializer
@@ -74,7 +74,7 @@ def _current_job_etag_value(job: Job) -> str:
 @dataclass
 class JobDeltaPayload:
     """
-    Structured representation of the delta envelope submitted by the client.
+    Structured representation of the delta envelope submitted by the company.
 
     We keep this lightweight dataclass (instead of passing DRF serializer
     instances around) so the service layer can remain decoupled from REST
@@ -252,23 +252,23 @@ def create_job(data: Dict[str, Any], user: Staff) -> Job:
         if not data.get("name"):
             raise ValueError("Job name is required")
 
-        if not data.get("client_id"):
-            raise ValueError("Client is required")
+        if not data.get("company_id"):
+            raise ValueError("Company is required")
 
         try:
-            client = Client.objects.get(id=data["client_id"])
-        except Client.DoesNotExist:
-            raise ValueError("Client not found")
+            company = Company.objects.get(id=data["company_id"])
+        except Company.DoesNotExist:
+            raise ValueError("Company not found")
 
-        if not client.allow_jobs:
+        if not company.allow_jobs:
             raise ValueError(
-                f"Client '{client.name}' is not permitted for jobs. "
-                f"Update the client to allow jobs if this is wrong."
+                f"Company '{company.name}' is not permitted for jobs. "
+                f"Update the company to allow jobs if this is wrong."
             )
 
         job_data = {
             "name": data["name"],
-            "client": client,
+            "company": company,
             "created_by": user,
         }
 
@@ -310,14 +310,14 @@ def create_job(data: Dict[str, Any], user: Staff) -> Job:
             job.save(staff=user)
 
             # Create job creation event (moved from Job.save() to prevent duplicates)
-            client_name = job.client.name if job.client else "Shop Job"
+            company_name = job.company.name if job.company else "Shop Job"
             contact_name = job.contact.name if job.contact else None
             JobEvent.objects.create(
                 job=job,
                 event_type="job_created",
                 detail={
                     "job_name": job.name,
-                    "client_name": client_name,
+                    "company_name": company_name,
                     "contact_name": contact_name,
                     "initial_status": job.get_status_display(),
                     "pricing_methodology": job.get_pricing_methodology_display(),
@@ -669,7 +669,7 @@ def get_job_for_edit(job_id: UUID, request) -> Dict[str, Any]:
             ValueError: If job is not found.
         """
         try:
-            job = Job.objects.select_related("client").get(id=job_id)
+            job = Job.objects.select_related("company").get(id=job_id)
         except Job.DoesNotExist:
             raise ValueError(f"Job with id {job_id} not found")
 
@@ -715,7 +715,7 @@ def get_job_summary(job_id: UUID, request) -> Dict[str, Any]:
             ValueError: If job is not found.
         """
         try:
-            job = Job.objects.select_related("client").get(id=job_id)
+            job = Job.objects.select_related("company").get(id=job_id)
         except Job.DoesNotExist:
             raise ValueError(f"Job with id {job_id} not found")
 
@@ -948,7 +948,7 @@ def _mark_job_delta_rejection_group_by_fingerprint(
         """Match rows by sha256(reason) and cascade.
 
         Callers send the fingerprint returned by the grouped listing; this
-        sidesteps client-side whitespace mangling on the raw reason. See
+        sidesteps company-side whitespace mangling on the raw reason. See
         apps.workflow.services.error_grouping._mark_group_by_fingerprint
         for the same pattern on AppError/XeroError.
         """
@@ -1065,7 +1065,7 @@ def update_job(
                 else:
                     current_norm = _current_job_etag_value(job)
                     logger.debug(f"[JOB_UPDATE] Current ETag: {current_norm}")
-                    logger.debug(f"[JOB_UPDATE] Client ETag: {if_match}")
+                    logger.debug(f"[JOB_UPDATE] Company ETag: {if_match}")
                     if current_norm != if_match:
                         logger.error(
                             f"[JOB_UPDATE] ETag mismatch! Current: {current_norm}, Expected: {if_match}"
@@ -1082,9 +1082,9 @@ def update_job(
                     f"JobRestService.update_job - Current job contact_id: {job.contact.id if job.contact else None}"
                 )
 
-                # Snapshot values needed for post-save logic (priority bump, client change)
+                # Snapshot values needed for post-save logic (priority bump, company change)
                 original_status = job.status
-                original_client_id = job.client_id
+                original_company_id = job.company_id
 
                 if delta_payload.job_id and str(job.id) != delta_payload.job_id:
                     detail = {
@@ -1146,35 +1146,35 @@ def update_job(
                     job.priority = Job._calculate_next_priority_for_status(job.status)
                     job.save(staff=user, update_fields=["priority", "updated_at"])
 
-                # When client changes, auto-set contact to new client's primary contact.
+                # When company changes, auto-set contact to new company's primary contact.
                 # Only do this if contact_id was NOT explicitly provided in the update.
                 contact_explicitly_updated = "contact_id" in delta_payload.fields
                 try:
                     if (
-                        job.client
-                        and original_client_id != job.client_id
+                        job.company
+                        and original_company_id != job.company_id
                         and not contact_explicitly_updated
                     ):
                         primary_contact = ClientContact.objects.filter(
-                            client_id=job.client_id,
+                            company_id=job.company_id,
                             is_primary=True,
                             is_active=True,
                         ).first()
                         job.contact = primary_contact  # May be None if no primary
                         job.save(staff=user)
                         logger.info(
-                            f"Auto-set contact to primary contact after client change: "
-                            f"job.client_id={job.client_id}, "
+                            f"Auto-set contact to primary contact after company change: "
+                            f"job.company_id={job.company_id}, "
                             f"contact={'None' if not primary_contact else primary_contact.id}"
                         )
                     elif (
                         job.contact
-                        and job.client
-                        and job.contact.client_id != job.client_id
+                        and job.company
+                        and job.contact.company_id != job.company_id
                     ):
                         logger.warning(
-                            "Clearing mismatched contact after client change: "
-                            f"contact.client_id={job.contact.client_id} != job.client_id={job.client_id}"
+                            "Clearing mismatched contact after company change: "
+                            f"contact.company_id={job.contact.company_id} != job.company_id={job.company_id}"
                         )
                         job.contact = None
                         job.save(staff=user)
@@ -1577,7 +1577,7 @@ def get_job_timeline(job_id: UUID) -> list[Dict[str, Any]]:
                             "status": "status",
                             "order_number": "order number",
                             "notes": "notes",
-                            "client_id": "client",
+                            "company_id": "company",
                             "contact_id": "contact",
                             "delivery_date": "delivery date",
                             "job_status": "status",
@@ -1763,7 +1763,7 @@ def get_weekly_metrics(week: date = None) -> list[Dict[str, Any]]:
 
         jobs = (
             Job.objects.filter(id__in=job_ids_with_time_entries)
-            .select_related("client")
+            .select_related("company")
             .prefetch_related("people")
         )
 
@@ -1808,7 +1808,7 @@ def get_weekly_metrics(week: date = None) -> list[Dict[str, Any]]:
                     "job_id": str(job.id),
                     "name": job.name,
                     "job_number": job.job_number,
-                    "client": job.client.name if job.client else None,
+                    "company": job.company.name if job.company else None,
                     "description": job.description,
                     "status": job.status,
                     "price_cap": job.price_cap,
diff --git a/apps/job/services/job_service.py b/apps/job/services/job_service.py
index 728925194..041101016 100644
--- a/apps/job/services/job_service.py
+++ b/apps/job/services/job_service.py
@@ -20,7 +20,7 @@ def get_paid_complete_jobs():
     """Fetches the jobs that are both completed and paid."""
     return (
         Job.objects.filter(status__in=["completed", "recently_completed"], paid=True)
-        .select_related("client")
+        .select_related("company")
         .order_by("-updated_at")
     )
 
diff --git a/apps/job/services/kanban_service.py b/apps/job/services/kanban_service.py
index 1cb2e281d..62e2f56c5 100644
--- a/apps/job/services/kanban_service.py
+++ b/apps/job/services/kanban_service.py
@@ -34,7 +34,7 @@
 
 from apps.accounting.models import Invoice
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import CostSet, Job
 from apps.job.services.kanban_categorization_service import KanbanCategorizationService
 from apps.workflow.models import CompanyDefaults
@@ -55,9 +55,9 @@ class KanbanSerializationContext:
     full stack inspection (~20ms), which made fetch-all take 20-30s.
     """
 
-    shop_client_id: Optional[UUID]
+    shop_company_id: Optional[UUID]
     summaries: Dict[UUID, Dict[str, Any]]
-    client_names: Dict[UUID, str]
+    company_names: Dict[UUID, str]
     contact_names: Dict[UUID, str]
     people_by_job: Dict[UUID, List[Staff]]
 
@@ -71,7 +71,7 @@ class KanbanService:
     SEARCH_SCORE_JOB_NUMBER_CONTAINS = 45.0
     SEARCH_SCORE_QUOTE_CONTAINS = 75.0
     SEARCH_SCORE_NAME_CONTAINS = 65.0
-    SEARCH_SCORE_CLIENT_CONTAINS = 55.0
+    SEARCH_SCORE_COMPANY_CONTAINS = 55.0
     SEARCH_SCORE_CONTACT_CONTAINS = 55.0
     SEARCH_SCORE_DESCRIPTION_CONTAINS = 35.0
     SEARCH_SCORE_TRIGRAM_MULTIPLIER = 30.0
@@ -87,9 +87,11 @@ class KanbanService:
             "reason": "name_contains",
         },
         {
-            "db_path": "client__name",
-            "expression": Coalesce("client__name", Value(""), output_field=TextField()),
-            "score": SEARCH_SCORE_CLIENT_CONTAINS,
+            "db_path": "company__name",
+            "expression": Coalesce(
+                "company__name", Value(""), output_field=TextField()
+            ),
+            "score": SEARCH_SCORE_COMPANY_CONTAINS,
             "reason": "client_contains",
         },
         {
@@ -244,7 +246,7 @@ def _apply_kanban_search(jobs_query: QuerySet[Job], query: str) -> List[Job]:
 
         candidates = list(
             jobs_query.filter(token_filter)
-            .select_related("client", "contact", "quote")
+            .select_related("company", "contact", "quote")
             .prefetch_related("invoices")
             .order_by("-trigram_score", "-created_at")
         )
@@ -365,8 +367,10 @@ def _get_search_field_value(job: Job, db_path: str) -> str:
         match db_path:
             case "name":
                 return (job.name or "").lower()
-            case "client__name":
-                return (job.client.name if job.client_id and job.client else "").lower()
+            case "company__name":
+                return (
+                    job.company.name if job.company_id and job.company else ""
+                ).lower()
             case "contact__name":
                 return (
                     job.contact.name if job.contact_id and job.contact else ""
@@ -391,7 +395,7 @@ def explain_kanban_search(query: str, limit: int = 20) -> List[Dict[str, Any]]:
             {
                 "job_number": job.job_number,
                 "name": job.name,
-                "client": job.client.name if job.client_id else None,
+                "company": job.company.name if job.company_id else None,
                 "status": job.status,
                 "trigram_score": getattr(job, "trigram_score", None),
                 "search_score": getattr(job, "search_score", None),
@@ -440,7 +444,7 @@ def log_kanban_search_results(
                     "job_number": job.job_number,
                     "status": job.status,
                     "name": job.name,
-                    "client": job.client.name if job.client_id else None,
+                    "company": job.company.name if job.company_id else None,
                     "trigram_score": getattr(job, "trigram_score", None),
                     "search_score": getattr(job, "search_score", None),
                     "search_reasons": getattr(job, "search_reasons", None),
@@ -520,9 +524,9 @@ def build_serialization_context(jobs: List[Job]) -> KanbanSerializationContext:
             CostSet.objects.filter(id__in=costset_ids).values_list("id", "summary")
         )
 
-        client_ids = {job.client_id for job in jobs} - {None}
-        client_names = dict(
-            Client.objects.filter(id__in=client_ids).values_list("id", "name")
+        company_ids = {job.company_id for job in jobs} - {None}
+        company_names = dict(
+            Company.objects.filter(id__in=company_ids).values_list("id", "name")
         )
 
         contact_ids = {job.contact_id for job in jobs} - {None}
@@ -549,9 +553,9 @@ def build_serialization_context(jobs: List[Job]) -> KanbanSerializationContext:
             people.sort(key=lambda staff: (staff.last_name, staff.first_name))
 
         return KanbanSerializationContext(
-            shop_client_id=defaults.shop_client_id,
+            shop_company_id=defaults.shop_company_id,
             summaries=summaries,
-            client_names=client_names,
+            company_names=company_names,
             contact_names=contact_names,
             people_by_job=dict(people_by_job),
         )
@@ -623,8 +627,8 @@ def serialize_job_for_api(
             "name": job.name,
             "description": job.description or "",
             "job_number": job.job_number,
-            "client_name": (
-                context.client_names.get(job.client_id, "") if job.client_id else ""
+            "company_name": (
+                context.company_names.get(job.company_id, "") if job.company_id else ""
             ),
             "contact_person": (
                 context.contact_names.get(job.contact_id, "") if job.contact_id else ""
@@ -650,7 +654,7 @@ def serialize_job_for_api(
                 job.delivery_date.isoformat() if job.delivery_date else None
             ),
             "priority": job.priority,
-            "shop_job": job.client_id == context.shop_client_id,
+            "shop_job": job.company_id == context.shop_company_id,
             "over_budget": over_budget,
             "quote_revenue": quote_revenue,
             "time_and_materials_revenue": time_and_materials_revenue,
@@ -951,8 +955,8 @@ def perform_advanced_search(
         if description := filters.get("description", "").strip():
             jobs_query = jobs_query.filter(description__icontains=description)
 
-        if client_name := filters.get("client_name", "").strip():
-            jobs_query = jobs_query.filter(client__name__icontains=client_name)
+        if company_name := filters.get("company_name", "").strip():
+            jobs_query = jobs_query.filter(company__name__icontains=company_name)
 
         if contact_person := filters.get("contact_person", "").strip():
             jobs_query = jobs_query.filter(contact__name__icontains=contact_person)
diff --git a/apps/job/services/labour_subtype_service.py b/apps/job/services/labour_subtype_service.py
index eab11fd6a..30991f777 100644
--- a/apps/job/services/labour_subtype_service.py
+++ b/apps/job/services/labour_subtype_service.py
@@ -29,7 +29,7 @@ def seed_subtype_onto_existing_jobs(subtype: LabourSubtype) -> int:
         with connection.cursor() as cursor:
             cursor.execute(f"LOCK TABLE {table_name} IN SHARE ROW EXCLUSIVE MODE")
 
-        shop_client_id = CompanyDefaults.get_solo().shop_client_id
+        shop_company_id = CompanyDefaults.get_solo().shop_company_id
         existing_job_ids = set(
             JobLabourRate.objects.filter(labour_subtype=subtype).values_list(
                 "job_id", flat=True
@@ -41,13 +41,13 @@ def seed_subtype_onto_existing_jobs(subtype: LabourSubtype) -> int:
                 labour_subtype=subtype,
                 charge_out_rate=(
                     Decimal("0.00")
-                    if client_id == shop_client_id
+                    if company_id == shop_company_id
                     else subtype.default_charge_out_rate
                 ),
             )
-            for job_id, client_id in Job.objects.exclude(
+            for job_id, company_id in Job.objects.exclude(
                 id__in=existing_job_ids
-            ).values_list("id", "client_id")
+            ).values_list("id", "company_id")
         ]
         JobLabourRate.objects.bulk_create(rows, batch_size=1000, ignore_conflicts=True)
         missing_job_ids = list(
diff --git a/apps/job/services/mcp_chat_service.py b/apps/job/services/mcp_chat_service.py
index 895853f0c..c96d08831 100644
--- a/apps/job/services/mcp_chat_service.py
+++ b/apps/job/services/mcp_chat_service.py
@@ -46,7 +46,7 @@ def _get_system_prompt(self, job: Job) -> str:
 
 Current Job Context:
 - Job: {job.name}
-- Client: {job.client.name}
+- Company: {job.company.name}
 - Status: {job.get_status_display()}
 - Description: {job.description or 'No description available'}
 
diff --git a/apps/job/services/quote_mode_controller.py b/apps/job/services/quote_mode_controller.py
index 3dac323f2..0a76654ff 100644
--- a/apps/job/services/quote_mode_controller.py
+++ b/apps/job/services/quote_mode_controller.py
@@ -63,7 +63,7 @@ def _summarize_previous_context(
 
         Args:
             chat_history: List of previous chat messages
-            gemini_client: Gemini client for API calls
+            gemini_client: Gemini company for API calls
 
         Returns:
             Summary of relevant context from previous conversation
@@ -109,7 +109,7 @@ def render_prompt(
 
         job_info = ""
         if job_ctx:
-            job_info = f"\nJOB_CONTEXT: Job #{job_ctx.get('job_number', 'N/A')} for {job_ctx.get('client', 'N/A')}"
+            job_info = f"\nJOB_CONTEXT: Job #{job_ctx.get('job_number', 'N/A')} for {job_ctx.get('company', 'N/A')}"
 
         context_info = ""
         if context_summary:
@@ -477,7 +477,7 @@ def run(
         if job:
             job_ctx = {
                 "job_number": job.job_number,
-                "client": job.client.name if job.client else "N/A",
+                "company": job.company.name if job.company else "N/A",
                 "description": job.description or "",
             }
 
diff --git a/apps/job/services/workshop_pdf_service.py b/apps/job/services/workshop_pdf_service.py
index e9518f2a2..c8f4bf005 100644
--- a/apps/job/services/workshop_pdf_service.py
+++ b/apps/job/services/workshop_pdf_service.py
@@ -21,7 +21,7 @@
 from reportlab.pdfgen import canvas
 from reportlab.platypus import Flowable, Paragraph, Table, TableStyle
 
-from apps.client.models import ClientContactMethod
+from apps.company.models import ClientContactMethod
 from apps.crm.models import PhoneEndpoint
 from apps.job.enums import SpeedQualityTradeoff
 from apps.job.models import CostLine, CostSet, Job, JobFile
@@ -35,25 +35,25 @@
 WORKSHOP_PDF_COST_LINES_ATTR = "_workshop_pdf_cost_lines"
 WORKSHOP_PDF_FILES_ATTR = "_workshop_pdf_files_to_print"
 WORKSHOP_PDF_CONTACT_PHONE_ATTR = "_workshop_pdf_contact_phone"
-WORKSHOP_PDF_CLIENT_PHONE_ATTR = "_workshop_pdf_client_phone"
+WORKSHOP_PDF_COMPANY_PHONE_ATTR = "_workshop_pdf_company_phone"
 
 
 def _primary_phone_for_job(job: Job) -> str:
     """Phone to print on workshop docs and delivery dockets.
 
     Display preference order: the job contact's own number first, falling back
-    to the client's number when the contact has no phone method (the business
+    to the company's number when the contact has no phone method (the business
     rule carried over from the pre-ClientContactMethod scalar fields).
     """
     if not hasattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR) or not hasattr(
-        job, WORKSHOP_PDF_CLIENT_PHONE_ATTR
+        job, WORKSHOP_PDF_COMPANY_PHONE_ATTR
     ):
         raise ValueError("PDF phone fields must be loaded before rendering")
 
     contact_phone = getattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR)
     if contact_phone:
         return str(contact_phone)
-    return str(getattr(job, WORKSHOP_PDF_CLIENT_PHONE_ATTR) or "")
+    return str(getattr(job, WORKSHOP_PDF_COMPANY_PHONE_ATTR) or "")
 
 
 def _primary_company_endpoint_number() -> str:
@@ -77,17 +77,17 @@ def _primary_phone_annotations() -> dict[str, Subquery]:
         .order_by("-is_primary", "label", "value")
         .values("value")[:1]
     )
-    client_phone = (
+    company_phone = (
         ClientContactMethod.objects.filter(
             method_type=ClientContactMethod.MethodType.PHONE,
-            client_id=OuterRef("client_id"),
+            company_id=OuterRef("company_id"),
         )
         .order_by("-is_primary", "label", "value")
         .values("value")[:1]
     )
     return {
         WORKSHOP_PDF_CONTACT_PHONE_ATTR: Subquery(contact_phone),
-        WORKSHOP_PDF_CLIENT_PHONE_ATTR: Subquery(client_phone),
+        WORKSHOP_PDF_COMPANY_PHONE_ATTR: Subquery(company_phone),
     }
 
 
@@ -95,7 +95,7 @@ def get_job_for_delivery_docket_pdf(job_id: UUID) -> Job:
     """Load a job with the relations required to render a delivery docket."""
     return cast(
         Job,
-        Job.objects.select_related("client", "contact")
+        Job.objects.select_related("company", "contact")
         .annotate(**_primary_phone_annotations())
         .get(id=job_id),
     )
@@ -114,7 +114,7 @@ def get_job_for_workshop_pdf(job_id: UUID) -> Job:
     return cast(
         Job,
         Job.objects.select_related(
-            "client",
+            "company",
             "contact",
             "latest_estimate",
             "latest_quote",
@@ -162,7 +162,7 @@ def _ensure_workshop_pdf_job_loaded(job: Job) -> Job:
 
 def _ensure_delivery_docket_pdf_job_loaded(job: Job) -> Job:
     if hasattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR) and hasattr(
-        job, WORKSHOP_PDF_CLIENT_PHONE_ATTR
+        job, WORKSHOP_PDF_COMPANY_PHONE_ATTR
     ):
         return job
     return get_job_for_delivery_docket_pdf(job.id)
@@ -431,8 +431,8 @@ def get_time_breakdown(job: Job) -> dict:
 ROW_ALT = colors.HexColor("#F8FAFC")
 
 # Paragraph styles for table content
-header_client_style = ParagraphStyle(
-    "HeaderClient",
+header_company_style = ParagraphStyle(
+    "HeaderCompany",
     parent=styles["Normal"],
     fontName="Helvetica-Bold",
     fontSize=18,
@@ -1173,7 +1173,7 @@ def add_workshop_details_table(
     pdf: canvas.Canvas, y_position: float, job: Job
 ) -> float:
     """Render a full-page workshop brief: identity, constraints, labour budget, and specs."""
-    client_name = job.client.name if job.client else "N/A"
+    company_name = job.company.name if job.company else "N/A"
     contact_name = job.contact.name if job.contact else ""
     contact_phone = _primary_phone_for_job(job)
     contact_info = (
@@ -1185,7 +1185,7 @@ def add_workshop_details_table(
     contact_table = Table(
         [
             [
-                _plain_paragraph(client_name, header_client_style),
+                _plain_paragraph(company_name, header_company_style),
                 Paragraph(contact_info, header_contact_style),
             ]
         ],
@@ -1322,7 +1322,7 @@ def add_delivery_docket_details_table(
     job: Job,
 ):
     """Render the delivery docket details with page-aware wrapping."""
-    client_name = job.client.name if job.client else "N/A"
+    company_name = job.company.name if job.company else "N/A"
     contact_name = job.contact.name if job.contact else ""
 
     contact_phone = _primary_phone_for_job(job)
@@ -1333,7 +1333,7 @@ def add_delivery_docket_details_table(
     # Delivery docket details - no workshop time or internal notes
     job_details = [
         [
-            Paragraph(client_name, header_client_style),
+            Paragraph(company_name, header_company_style),
             Paragraph(contact_info, header_contact_style),
         ],
         [
diff --git a/apps/job/services/workshop_service.py b/apps/job/services/workshop_service.py
index 3f95f300f..7225641a7 100644
--- a/apps/job/services/workshop_service.py
+++ b/apps/job/services/workshop_service.py
@@ -45,7 +45,7 @@ def list_entries(self, entry_date) -> Tuple[list[CostLine], dict]:
                 staff=self.staff,
                 accounting_date=entry_date,
             )
-            .select_related("cost_set__job__client")
+            .select_related("cost_set__job__company")
             .order_by("entry_seq")
         )
 
@@ -116,7 +116,7 @@ def create_entry(self, data) -> CostLine:
 
     def update_entry(self, data) -> CostLine:
         """Update an existing CostLine belonging to the staff member."""
-        cost_line = CostLine.objects.select_related("cost_set__job__client").get(
+        cost_line = CostLine.objects.select_related("cost_set__job__company").get(
             id=data["entry_id"], kind="time"
         )
 
diff --git a/apps/job/tests/_pdf_golden_fixtures.py b/apps/job/tests/_pdf_golden_fixtures.py
index ec5db42db..326b67a9a 100644
--- a/apps/job/tests/_pdf_golden_fixtures.py
+++ b/apps/job/tests/_pdf_golden_fixtures.py
@@ -24,7 +24,7 @@
 from django.conf import settings
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import CostLine, Job, JobEvent, JobFile, LabourSubtype
 from apps.workflow.models import CompanyDefaults, XeroPayItem
 
@@ -73,18 +73,18 @@ def build_golden_job(test_staff: Staff) -> Job:
     company.starting_job_number = STARTING_JOB_NUMBER
     company.save()
 
-    client = Client.objects.create(
+    company = Company.objects.create(
         name="ACME Engineering Ltd",
         xero_last_modified=FROZEN_NOW,
     )
 
     contact = ClientContact.objects.create(
-        client=client,
+        company=company,
         name="Jane Doe",
     )
 
     job = Job.objects.create(
-        client=client,
+        company=company,
         contact=contact,
         name="Custom Bracket Fabrication",
         description=("Stainless steel mounting bracket, 200x100x5mm, 4 holes per spec"),
diff --git a/apps/job/tests/fixtures/chat_test_data.json b/apps/job/tests/fixtures/chat_test_data.json
index b43cd71af..20076716c 100644
--- a/apps/job/tests/fixtures/chat_test_data.json
+++ b/apps/job/tests/fixtures/chat_test_data.json
@@ -72,7 +72,7 @@
     }
   },
   {
-    "model": "client.client",
+    "model": "company.company",
     "pk": "550e8400-e29b-41d4-a716-446655440001",
     "fields": {
       "name": "Test Manufacturing Ltd",
@@ -90,7 +90,7 @@
     }
   },
   {
-    "model": "client.client",
+    "model": "company.company",
     "pk": "550e8400-e29b-41d4-a716-446655440002",
     "fields": {
       "name": "ABC Construction Co",
@@ -114,7 +114,7 @@
       "name": "Steel Handrail Project",
       "job_number": "JOB001",
       "description": "Custom steel handrail for commercial building",
-      "client": "550e8400-e29b-41d4-a716-446655440001",
+      "company": "550e8400-e29b-41d4-a716-446655440001",
       "status": "quoting",
       "priority": "medium",
       "due_date": "2024-02-15",
@@ -131,7 +131,7 @@
       "name": "Industrial Staircase",
       "job_number": "JOB002",
       "description": "Heavy-duty industrial staircase with platform",
-      "client": "550e8400-e29b-41d4-a716-446655440002",
+      "company": "550e8400-e29b-41d4-a716-446655440002",
       "status": "in_progress",
       "priority": "high",
       "due_date": "2024-03-01",
@@ -148,7 +148,7 @@
       "name": "Sheet Metal Ducting",
       "job_number": "JOB003",
       "description": "HVAC ducting for office building",
-      "client": "550e8400-e29b-41d4-a716-446655440001",
+      "company": "550e8400-e29b-41d4-a716-446655440001",
       "status": "quoting",
       "priority": "low",
       "due_date": "2024-02-28",
diff --git a/apps/job/tests/test_chat_api_endpoints.py b/apps/job/tests/test_chat_api_endpoints.py
index 9c300754d..6d2ea4be4 100644
--- a/apps/job/tests/test_chat_api_endpoints.py
+++ b/apps/job/tests/test_chat_api_endpoints.py
@@ -14,7 +14,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobQuoteChat
 from apps.testing import BaseTestCase
 from apps.workflow.enums import AIProviderTypes
@@ -31,9 +31,9 @@ def setUp(self):
         # Get test data from fixture
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -44,7 +44,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client_obj,
+            company=self.client_obj,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -352,9 +352,9 @@ def setUp(self):
         # Get test data from fixture
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -365,7 +365,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client_obj,
+            company=self.client_obj,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -436,9 +436,9 @@ def setUp(self):
 
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -449,7 +449,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client_obj,
+            company=self.client_obj,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
diff --git a/apps/job/tests/test_chat_performance.py b/apps/job/tests/test_chat_performance.py
index c12c85bc1..c33313137 100644
--- a/apps/job/tests/test_chat_performance.py
+++ b/apps/job/tests/test_chat_performance.py
@@ -7,7 +7,7 @@
 from django.db import connection
 from django.test.utils import CaptureQueriesContext
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobQuoteChat
 from apps.job.services.chat_service import ChatService
 from apps.testing import BaseTestCase
@@ -48,9 +48,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -61,7 +61,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -95,7 +95,7 @@ def test_database_query_optimization(self):
             mock_llm.completion.return_value = mock_response
             mock_get_llm.return_value = mock_llm
 
-            # Upper bound: Job, CompanyDefaults, Client, History, Insert, Savepoint x2.
+            # Upper bound: Job, CompanyDefaults, Company, History, Insert, Savepoint x2.
             # CompanyDefaults is usually cached by SOLO_CACHE after setUp() primes
             # it, so the observed count is typically 6 — but 7 is also acceptable
             # if the cache isn't warm.
@@ -118,7 +118,7 @@ def test_bulk_message_creation(self):
                 name=f"DB Test Job {i}",
                 job_number=3000 + i,
                 description=f"Database test job {i}",
-                client=self.client,
+                company=self.company,
                 status="quoting",
                 default_xero_pay_item=self.xero_pay_item,
                 staff=self.test_staff,
diff --git a/apps/job/tests/test_chat_service.py b/apps/job/tests/test_chat_service.py
index 0c3a4a7ab..dfddf2288 100644
--- a/apps/job/tests/test_chat_service.py
+++ b/apps/job/tests/test_chat_service.py
@@ -18,7 +18,7 @@
 
 from django.test import TestCase
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobQuoteChat
 from apps.job.services.chat_service import ChatService
 from apps.testing import BaseTestCase
@@ -122,9 +122,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -135,7 +135,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -197,7 +197,7 @@ def test_system_prompt_generation(self):
         self.assertIn(self.company_defaults.company_name, prompt)
         self.assertIn(self.job.name, prompt)
         self.assertIn(str(self.job.job_number), prompt)
-        self.assertIn(self.client.name, prompt)
+        self.assertIn(self.company.name, prompt)
         self.assertIn(self.job.description, prompt)
 
     def test_mcp_tools_definition(self):
@@ -266,9 +266,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -279,7 +279,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -416,9 +416,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -428,7 +428,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -615,9 +615,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -628,7 +628,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
@@ -703,9 +703,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -715,7 +715,7 @@ def setUp(self):
             name="Test Job",
             job_number=1001,
             description="Test job description",
-            client=self.client,
+            company=self.company,
             status="quoting",
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
diff --git a/apps/job/tests/test_costline_schema_validation.py b/apps/job/tests/test_costline_schema_validation.py
index 8990bc351..27ce5f286 100644
--- a/apps/job/tests/test_costline_schema_validation.py
+++ b/apps/job/tests/test_costline_schema_validation.py
@@ -6,7 +6,7 @@
 
 from django.core.exceptions import ValidationError
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, LabourSubtype
 from apps.testing import BaseTestCase
 from apps.workflow.models import XeroPayItem
@@ -15,8 +15,8 @@
 class CostLineSchemaValidationTests(BaseTestCase):
 
     def setUp(self) -> None:
-        self.client = Client.objects.create(
-            name="Test Client",
+        self.company = Company.objects.create(
+            name="Test Company",
             email="test@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
@@ -24,7 +24,7 @@ def setUp(self) -> None:
         self.job = Job.objects.create(
             job_number=1,
             name="CostLine Schema Test",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_costline_time_rate_serialization.py b/apps/job/tests/test_costline_time_rate_serialization.py
index bfd7c3e86..3273f24cf 100644
--- a/apps/job/tests/test_costline_time_rate_serialization.py
+++ b/apps/job/tests/test_costline_time_rate_serialization.py
@@ -4,7 +4,7 @@
 from decimal import Decimal
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, LabourSubtype
 from apps.job.serializers.costing_serializer import CostLineCreateUpdateSerializer
 from apps.testing import BaseTestCase
@@ -13,15 +13,15 @@
 
 class CostLineTimeRateSerializationTests(BaseTestCase):
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="Rate Serialization Client",
+        self.client_obj = Company.objects.create(
+            name="Rate Serialization Company",
             email="rates@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.job = Job.objects.create(
             job_number=9100,
             name="Rate Serialization Job",
-            client=self.client_obj,
+            company=self.client_obj,
             staff=self.test_staff,
         )
         self.job.labour_rates.update(charge_out_rate=Decimal("125.00"))
@@ -127,7 +127,7 @@ def test_leave_job_keeps_leave_pay_item(self) -> None:
         sick_job = Job.objects.create(
             job_number=9101,
             name="Sick Leave",
-            client=self.client_obj,
+            company=self.client_obj,
             staff=self.test_staff,
             default_xero_pay_item=sick_pay_item,
         )
diff --git a/apps/job/tests/test_delivery_docket_service.py b/apps/job/tests/test_delivery_docket_service.py
index 12ccec5a4..f56bd62d7 100644
--- a/apps/job/tests/test_delivery_docket_service.py
+++ b/apps/job/tests/test_delivery_docket_service.py
@@ -13,7 +13,7 @@
 from django.test import override_settings
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobEvent, JobFile
 from apps.job.services.delivery_docket_service import generate_delivery_docket
 from apps.testing import BaseTestCase
@@ -32,12 +32,12 @@ def setUp(self):
         )
         self._settings_override.enable()
 
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Test Delivery Job",
             description="Deliver some steel",
             staff=self.test_staff,
diff --git a/apps/job/tests/test_duplicate_phones_view.py b/apps/job/tests/test_duplicate_phones_view.py
index 9712fd4ad..347bf987d 100644
--- a/apps/job/tests/test_duplicate_phones_view.py
+++ b/apps/job/tests/test_duplicate_phones_view.py
@@ -1,7 +1,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContactMethod
+from apps.company.models import ClientContactMethod, Company
 from apps.testing import BaseAPITestCase
 
 URL = "/api/job/data-quality/duplicate-phones/"
@@ -17,18 +17,18 @@ def _office_staff(self) -> Staff:
             is_office_staff=True,
         )
 
-    def _phone(self, value: str, client: Client) -> None:
+    def _phone(self, value: str, company: Company) -> None:
         method = ClientContactMethod(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=value,
         )
         method.normalized_value = ClientContactMethod.normalize_phone(value)
         ClientContactMethod.objects.bulk_create([method])
 
-    def test_returns_cross_client_conflict_to_office_staff(self) -> None:
-        acme = Client.objects.create(name="Acme", xero_last_modified=timezone.now())
-        beta = Client.objects.create(name="Beta", xero_last_modified=timezone.now())
+    def test_returns_cross_company_conflict_to_office_staff(self) -> None:
+        acme = Company.objects.create(name="Acme", xero_last_modified=timezone.now())
+        beta = Company.objects.create(name="Beta", xero_last_modified=timezone.now())
         self._phone("021 111 111", acme)
         self._phone("021 111 111", beta)
         self.client.force_authenticate(self._office_staff())
diff --git a/apps/job/tests/test_event_deduplication.py b/apps/job/tests/test_event_deduplication.py
index 7601d9ed0..77347ac56 100644
--- a/apps/job/tests/test_event_deduplication.py
+++ b/apps/job/tests/test_event_deduplication.py
@@ -3,7 +3,7 @@
 from django.core.exceptions import ValidationError
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobEvent
 from apps.job.services.job_rest_service import JobRestService
 from apps.testing import BaseTestCase
@@ -25,16 +25,16 @@ def setUp(self):
             first_name="Test",
             last_name="User",
         )
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         # Get Ordinary Time pay item (created by migration)
         self.xero_pay_item = XeroPayItem.get_ordinary_time()
         self.job = Job.objects.create(
             name="Test Job",
-            client=self.client_obj,
+            company=self.client_obj,
             created_by=self.user,
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
diff --git a/apps/job/tests/test_job_event_tracking.py b/apps/job/tests/test_job_event_tracking.py
index 24b03ee2f..c632d7320 100644
--- a/apps/job/tests/test_job_event_tracking.py
+++ b/apps/job/tests/test_job_event_tracking.py
@@ -8,7 +8,7 @@
 from rest_framework.test import APIRequestFactory, force_authenticate
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobEvent
 from apps.job.models.job_event import (
     _format_ordinal,
@@ -32,15 +32,15 @@ def setUp(self):
             first_name="Test",
             last_name="Tracker",
         )
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.xero_pay_item = XeroPayItem.get_ordinary_time()
         self.job = Job(
             name="Test Job",
-            client=self.client_obj,
+            company=self.client_obj,
             created_by=self.user,
             default_xero_pay_item=self.xero_pay_item,
         )
@@ -537,8 +537,8 @@ def setUp(self):
             first_name="Kanban",
             last_name="Tester",
         )
-        self.client_obj = Client.objects.create(
-            name="Kanban Client",
+        self.client_obj = Company.objects.create(
+            name="Kanban Company",
             email="kc@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
@@ -547,7 +547,7 @@ def setUp(self):
     def _make_job(self, name, status="in_progress"):
         job = Job(
             name=name,
-            client=self.client_obj,
+            company=self.client_obj,
             created_by=self.user,
             default_xero_pay_item=self.xero_pay_item,
             status=status,
@@ -687,15 +687,15 @@ def setUp(self) -> None:
             first_name="Staff",
             last_name="Required",
         )
-        self.client_obj = Client.objects.create(
-            name="Required Client",
-            email="required-client@example.com",
+        self.client_obj = Company.objects.create(
+            name="Required Company",
+            email="required-company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.xero_pay_item = XeroPayItem.get_ordinary_time()
         self.job = Job(
             name="Required Job",
-            client=self.client_obj,
+            company=self.client_obj,
             created_by=self.user,
             default_xero_pay_item=self.xero_pay_item,
         )
diff --git a/apps/job/tests/test_job_files_api.py b/apps/job/tests/test_job_files_api.py
index 77358984e..6a5af452b 100644
--- a/apps/job/tests/test_job_files_api.py
+++ b/apps/job/tests/test_job_files_api.py
@@ -7,7 +7,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.testing import BaseAPITestCase
 
@@ -34,12 +34,12 @@ def setUp(self):
             is_office_staff=True,
             is_workshop_staff=False,
         )
-        self.client_obj = Client.objects.create(
-            name="Job Files Client",
+        self.client_obj = Company.objects.create(
+            name="Job Files Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Attachment API Job",
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_job_invoicing.py b/apps/job/tests/test_job_invoicing.py
index ae69918b4..55ddae0b8 100644
--- a/apps/job/tests/test_job_invoicing.py
+++ b/apps/job/tests/test_job_invoicing.py
@@ -7,7 +7,7 @@
 from django.utils import timezone
 
 from apps.accounting.models.invoice import Invoice
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.models.costing import CostLine
 from apps.job.services.job_service import recalculate_job_invoicing_state
@@ -18,15 +18,15 @@ class TestRecalculateJobInvoicingState(BaseTestCase):
     """Tests for recalculate_job_invoicing_state()."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             xero_last_modified=timezone.now(),
         )
 
     def _create_job(self, pricing_methodology="time_materials"):
         """Create a job. Job.save() auto-creates CostSets (actual, quote, estimate)."""
         job = Job(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Test Job",
             pricing_methodology=pricing_methodology,
         )
@@ -49,7 +49,7 @@ def _create_invoice(self, job, amount, status="AUTHORISED"):
         """Create an invoice for the given job."""
         return Invoice.objects.create(
             job=job,
-            client=self.client_obj,
+            company=self.client_obj,
             xero_id=uuid.uuid4(),
             number=f"INV-{uuid.uuid4().hex[:8]}",
             status=status,
diff --git a/apps/job/tests/test_job_latest_costsets.py b/apps/job/tests/test_job_latest_costsets.py
index 6ce24756a..35fbb2c89 100644
--- a/apps/job/tests/test_job_latest_costsets.py
+++ b/apps/job/tests/test_job_latest_costsets.py
@@ -2,7 +2,7 @@
 
 from django.db.models import RestrictedError
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.models.costing import CostSet
 from apps.testing import BaseTestCase
@@ -10,8 +10,8 @@
 
 class JobLatestCostSetCreationTests(BaseTestCase):
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Latest CostSet Client",
+        self.client_obj = Company.objects.create(
+            name="Latest CostSet Company",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -36,7 +36,7 @@ def _assert_initial_cost_sets(self, job: Job) -> None:
 
     def test_manager_create_seeds_required_latest_cost_sets(self):
         job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Manager create job",
             staff=self.test_staff,
         )
@@ -44,7 +44,7 @@ def test_manager_create_seeds_required_latest_cost_sets(self):
         self._assert_initial_cost_sets(job)
 
     def test_model_save_seeds_required_latest_cost_sets(self):
-        job = Job(client=self.client_obj, name="Model save job")
+        job = Job(company=self.client_obj, name="Model save job")
         job.save(staff=self.test_staff)
 
         self._assert_initial_cost_sets(job)
@@ -52,12 +52,12 @@ def test_model_save_seeds_required_latest_cost_sets(self):
 
 class JobLatestCostSetDeletionTests(BaseTestCase):
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Latest CostSet Deletion Client",
+        self.client_obj = Company.objects.create(
+            name="Latest CostSet Deletion Company",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Deletion behavior job",
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_job_quote_chat_model.py b/apps/job/tests/test_job_quote_chat_model.py
index 238835e50..b93cc4720 100644
--- a/apps/job/tests/test_job_quote_chat_model.py
+++ b/apps/job/tests/test_job_quote_chat_model.py
@@ -5,7 +5,7 @@
 from django.db import IntegrityError
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobQuoteChat
 from apps.testing import BaseTestCase
 from apps.workflow.models import CompanyDefaults, XeroPayItem
@@ -18,9 +18,9 @@ def setUp(self):
         """Set up test data"""
         self.company_defaults = CompanyDefaults.get_solo()
 
-        self.client = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        self.company = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified=timezone.now(),
         )
 
@@ -29,7 +29,7 @@ def setUp(self):
         self.job = Job.objects.create(
             name="Test Job",
             description="Test job description",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.xero_pay_item,
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_job_rest_service.py b/apps/job/tests/test_job_rest_service.py
index 4aea25f4b..6525f07f5 100644
--- a/apps/job/tests/test_job_rest_service.py
+++ b/apps/job/tests/test_job_rest_service.py
@@ -2,7 +2,7 @@
 
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job, JobEvent
 from apps.job.models.costing import CostLine
 from apps.job.services.job_rest_service import JobRestService
@@ -12,15 +12,15 @@
 
 class JobRestServiceCreateJobTests(BaseTestCase):
     def test_fixed_price_create_copies_estimate_pay_item_without_relation_loads(self):
-        client = Client.objects.create(
-            name="Create Job Client",
+        company = Company.objects.create(
+            name="Create Job Company",
             xero_last_modified=timezone.now(),
         )
 
         job = JobRestService.create_job(
             {
                 "name": "Fixed Price Job",
-                "client_id": client.id,
+                "company_id": company.id,
                 "pricing_methodology": "fixed_price",
                 "estimated_materials": Decimal("120.00"),
                 "estimated_time": Decimal("2.50"),
@@ -45,14 +45,14 @@ def test_fixed_price_create_copies_estimate_pay_item_without_relation_loads(self
 
 class JobRestServiceEditTests(BaseTestCase):
     def test_get_job_for_edit_serializes_event_staff(self):
-        client = Client.objects.create(
-            name="Edit Job Client",
+        company = Company.objects.create(
+            name="Edit Job Company",
             xero_last_modified=timezone.now(),
         )
-        contact = ClientContact.objects.create(client=client, name="Site Contact")
+        contact = ClientContact.objects.create(company=company, name="Site Contact")
         job = Job.objects.create(
             name="Editable Job",
-            client=client,
+            company=company,
             contact=contact,
             created_by=self.test_staff,
             default_xero_pay_item=XeroPayItem.get_ordinary_time(),
diff --git a/apps/job/tests/test_job_summary_pdf_service.py b/apps/job/tests/test_job_summary_pdf_service.py
index a77e50b27..728fd9e12 100644
--- a/apps/job/tests/test_job_summary_pdf_service.py
+++ b/apps/job/tests/test_job_summary_pdf_service.py
@@ -10,7 +10,7 @@
 from django.test import TestCase, override_settings
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, JobFile
 from apps.job.services.job_summary_pdf_service import JobSummaryPdfService
 from apps.job.services.workshop_pdf_service import JOB_SUMMARY_PDF_FILENAME
@@ -31,12 +31,12 @@ def setUp(self) -> None:
         self.dropbox = tempfile.mkdtemp(prefix="dw-summary-pdf-")
         self.settings_override = override_settings(DROPBOX_WORKFLOW_FOLDER=self.dropbox)
         self.settings_override.enable()
-        self.client_obj = Client.objects.create(
-            name="Summary Client",
+        self.client_obj = Company.objects.create(
+            name="Summary Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Summary Job",
             staff=self.test_staff,
         )
@@ -66,12 +66,12 @@ def test_refresh_writes_stable_pdf_and_job_file(self) -> None:
 
     def test_refresh_batches_missing_jobs_and_skips_fresh(self) -> None:
         missing = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Missing Summary",
             staff=self.test_staff,
         )
         fresh = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Fresh Summary",
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_kanban_reorder_priority.py b/apps/job/tests/test_kanban_reorder_priority.py
index 3c1c1085c..9dc1b1a3d 100644
--- a/apps/job/tests/test_kanban_reorder_priority.py
+++ b/apps/job/tests/test_kanban_reorder_priority.py
@@ -2,7 +2,7 @@
 
 from django.contrib.auth import get_user_model
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobEvent
 from apps.job.services.kanban_service import KanbanService
 from apps.testing import BaseTestCase
@@ -19,9 +19,9 @@ def setUp(self):
             first_name="Reorder",
             last_name="Tester",
         )
-        self.client = Client.objects.create(
-            name="Reorder Client",
-            email="reorder-client@example.com",
+        self.company = Company.objects.create(
+            name="Reorder Company",
+            email="reorder-company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.xero_pay_item = XeroPayItem.get_ordinary_time()
@@ -29,7 +29,7 @@ def setUp(self):
     def _make_job(self, name, status="in_progress"):
         job = Job(
             name=name,
-            client=self.client,
+            company=self.company,
             created_by=self.user,
             default_xero_pay_item=self.xero_pay_item,
             status=status,
diff --git a/apps/job/tests/test_kanban_search.py b/apps/job/tests/test_kanban_search.py
index c37ca756d..fcdedffc2 100644
--- a/apps/job/tests/test_kanban_search.py
+++ b/apps/job/tests/test_kanban_search.py
@@ -12,7 +12,7 @@
 from nplusone.ext.django.patch import apply_patches
 
 from apps.accounting.models import Invoice, Quote
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job
 from apps.job.services.kanban_service import KanbanService
 from apps.testing import BaseTestCase
@@ -23,11 +23,11 @@ class KanbanSearchTest(BaseTestCase):
     def setUp(self):
         super().setUp()
         self.xero_pay_item = XeroPayItem.get_ordinary_time()
-        self.shop_client = self._make_client("Demo Company Shop")
+        self.shop_company = self._make_client("Demo Company Shop")
         self.job_number = 9000
 
-    def _make_client(self, name: str) -> Client:
-        return Client.objects.create(
+    def _make_client(self, name: str) -> Company:
+        return Company.objects.create(
             name=name,
             xero_last_modified=timezone.now(),
         )
@@ -36,21 +36,21 @@ def _make_job(
         self,
         *,
         name: str,
-        client_name: str,
+        company_name: str,
         status: str = "in_progress",
         contact_name: str | None = None,
         order_number: str | None = None,
     ):
-        client = self._make_client(client_name)
+        company = self._make_client(company_name)
         contact = None
         if contact_name:
-            contact = ClientContact.objects.create(client=client, name=contact_name)
+            contact = ClientContact.objects.create(company=company, name=contact_name)
 
         self.job_number += 1
         return Job.objects.create(
             staff=self.test_staff,
             name=name,
-            client=client,
+            company=company,
             contact=contact,
             status=status,
             job_number=self.job_number,
@@ -68,7 +68,7 @@ def _make_invoice(self, job: Job, *, number: str) -> Invoice:
         return Invoice.objects.create(
             xero_id=uuid.uuid4(),
             number=number,
-            client=job.client,
+            company=job.company,
             job=job,
             date=date.today(),
             total_excl_tax=Decimal("100.00"),
@@ -83,7 +83,7 @@ def _make_quote(self, job: Job, *, number: str) -> Quote:
         return Quote.objects.create(
             xero_id=uuid.uuid4(),
             number=number,
-            client=job.client,
+            company=job.company,
             job=job,
             date=date.today(),
             total_excl_tax=Decimal("100.00"),
@@ -96,11 +96,11 @@ def test_perform_advanced_search_matches_single_token_job_name_substring(self):
         """Catches quick search no longer finding job-name substrings."""
         target = self._make_job(
             name="2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         self._make_job(
             name="Aluminium handrail",
-            client_name="Other Client",
+            company_name="Other Company",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "kick"}))
@@ -114,7 +114,7 @@ def test_perform_advanced_search_serializes_without_lazy_relation_loads(self):
         """
         target = self._make_job(
             name="2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "kick"}))
@@ -137,7 +137,7 @@ def test_search_with_results_does_not_trip_unused_eager_load_guard(self) -> None
         """
         target = self._make_job(
             name="Stainless balustrade panels",
-            client_name="Guarded Rails Ltd",
+            company_name="Guarded Rails Ltd",
         )
 
         # The middleware only installs (and patches only auto-apply) when
@@ -157,11 +157,11 @@ def test_perform_advanced_search_preloads_quote_for_ranking(self):
         """Catches quote ranking that re-queries quotes per candidate job."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         other = self._make_job(
             name="Cool Store",
-            client_name="Cool Stores Ltd",
+            company_name="Cool Stores Ltd",
         )
         self._make_quote(target, number="QU-56005")
         self._make_quote(other, number="QU-99999")
@@ -183,11 +183,11 @@ def test_perform_advanced_search_matches_quote_number(self):
         """Catches quote-number search no longer finding the owning job."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_quote(target, number="QU-56005")
         self._make_quote(other, number="QU-99999")
@@ -202,11 +202,11 @@ def test_perform_advanced_search_matches_numeric_substring(self):
         """Catches numeric quick search no longer matching job descriptions."""
         target = self._make_job(
             name="2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         self._make_job(
             name="5MM folded flashing 1200MM",
-            client_name="Other Client",
+            company_name="Other Company",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "910"}))
@@ -218,20 +218,20 @@ def test_numeric_query_prefers_job_number_over_long_description_substring(self):
         target = self._set_job_number(
             self._make_job(
                 name="Workshop Closed due to new roof",
-                client_name="Weaver, Decker and Schultz",
+                company_name="Weaver, Decker and Schultz",
             ),
             96977,
         )
         description_match = self._make_job(
             name="Auckland airport - bag drop",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         description_match.description = "quote for bag drop components\n2-3977"
         description_match.save(staff=self.test_staff, update_fields=["description"])
         for index in range(100):
             noisy_job = self._make_job(
                 name=f"Noise job {index}",
-                client_name=f"Noise Client {index}",
+                company_name=f"Noise Company {index}",
             )
             self._set_job_number(noisy_job, 70000 + index)
 
@@ -245,7 +245,7 @@ def test_get_jobs_by_kanban_column_exact_job_number_suppresses_distant_noise(sel
         target = self._set_job_number(
             self._make_job(
                 name="Best matching job",
-                client_name="Weaver, Decker and Schultz",
+                company_name="Weaver, Decker and Schultz",
                 status="in_progress",
             ),
             78941,
@@ -253,7 +253,7 @@ def test_get_jobs_by_kanban_column_exact_job_number_suppresses_distant_noise(sel
         self._set_job_number(
             self._make_job(
                 name="Adjacent but weaker job",
-                client_name="Other Client",
+                company_name="Other Company",
                 status="in_progress",
             ),
             78940,
@@ -261,7 +261,7 @@ def test_get_jobs_by_kanban_column_exact_job_number_suppresses_distant_noise(sel
         for index in range(100):
             noisy_job = self._make_job(
                 name=f"Noise job {index}",
-                client_name=f"Noise Client {index}",
+                company_name=f"Noise Company {index}",
                 status="in_progress",
             )
             self._set_job_number(noisy_job, 70000 + index)
@@ -280,13 +280,13 @@ def test_perform_advanced_search_keeps_plausible_short_job_number_match(
         near_match = self._set_job_number(
             self._make_job(
                 name="Best approximate job",
-                client_name="Other Client",
+                company_name="Other Company",
             ),
             96977,
         )
         self._make_job(
             name="Auckland airport - bag drop",
-            client_name="Another Client",
+            company_name="Another Company",
             contact_name="Alice Brown",
         )
 
@@ -299,14 +299,14 @@ def test_numeric_query_prefers_job_number_suffix_over_middle_substring(self):
         suffix_match = self._set_job_number(
             self._make_job(
                 name="Suffix match",
-                client_name="Other Client",
+                company_name="Other Company",
             ),
             96977,
         )
         middle_match = self._set_job_number(
             self._make_job(
                 name="Middle match",
-                client_name="Other Client",
+                company_name="Other Company",
             ),
             97701,
         )
@@ -328,15 +328,15 @@ def test_perform_advanced_search_keeps_multiple_close_text_matches(self):
         """Catches text search collapsing distinct plausible job matches."""
         target_one = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         target_two = self._make_job(
             name="Kick rails",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_job(
             name="Aluminium handrail",
-            client_name="Distant Client",
+            company_name="Distant Company",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "kick"}))
@@ -344,14 +344,14 @@ def test_perform_advanced_search_keeps_multiple_close_text_matches(self):
         self.assertEqual({job.id for job in jobs}, {target_one.id, target_two.id})
 
     def test_perform_advanced_search_matches_client_tokens_in_any_order(self):
-        """Catches client-name token search becoming order-sensitive."""
+        """Catches company-name token search becoming order-sensitive."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         self._make_job(
             name="Other work",
-            client_name="Schultz Fabrication Only",
+            company_name="Schultz Fabrication Only",
         )
 
         jobs = list(
@@ -366,12 +366,12 @@ def test_perform_advanced_search_matches_contact_name_substring(self):
         """Catches contact-name search no longer matching partial names."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
             contact_name="Molly Wainwright",
         )
         self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
             contact_name="Alice Brown",
         )
 
@@ -380,15 +380,15 @@ def test_perform_advanced_search_matches_contact_name_substring(self):
         self.assertEqual([job.id for job in jobs], [target.id])
 
     def test_get_jobs_by_kanban_column_matches_client_tokens_in_any_order(self):
-        """Catches kanban column search ignoring unordered client-name tokens."""
+        """Catches kanban column search ignoring unordered company-name tokens."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
             status="in_progress",
         )
         self._make_job(
             name="Draft work",
-            client_name="Weaver Draft",
+            company_name="Weaver Draft",
             status="draft",
         )
 
@@ -403,7 +403,7 @@ def test_perform_advanced_search_returns_empty_when_query_not_present(self):
         """Catches unrelated jobs being returned for absent search terms."""
         self._make_job(
             name="2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
 
         jobs = list(
@@ -416,7 +416,7 @@ def test_perform_advanced_search_returns_empty_for_only_weak_trigram_matches(sel
         """Catches weak fuzzy matches leaking below the display threshold."""
         weak_match = self._make_job(
             name="5x swaged ends",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         setattr(
             weak_match,
@@ -432,10 +432,10 @@ def test_perform_advanced_search_returns_empty_for_only_weak_trigram_matches(sel
         self.assertEqual(ranked_jobs, [])
 
     def test_perform_advanced_search_recovers_typo_tolerance(self):
-        """Catches typo tolerance no longer recovering misspelled client searches."""
+        """Catches typo tolerance no longer recovering misspelled company searches."""
         target = self._make_job(
             name="2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
 
         jobs = list(
@@ -450,7 +450,7 @@ def test_get_jobs_by_kanban_column_recovers_typo_tolerance(self):
         """Catches kanban column search losing typo tolerance."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
             status="in_progress",
         )
 
@@ -465,11 +465,11 @@ def test_perform_advanced_search_does_not_fuzzy_match_invoice_numbers(self):
         """Catches invoice searches fuzzily matching the wrong invoice."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_invoice(target, number="INV-15152")
         self._make_invoice(other, number="INV-15153")
@@ -484,11 +484,11 @@ def test_perform_advanced_search_matches_invoice_number_exactly_via_filter(self)
         """Catches the invoice filter failing to match a full invoice number."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_invoice(target, number="INV-15151")
         self._make_invoice(other, number="INV-15152")
@@ -503,11 +503,11 @@ def test_perform_advanced_search_matches_bare_invoice_number(self):
         """Catches the invoice filter failing to match bare invoice digits."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_invoice(target, number="INV-56005")
         self._make_invoice(other, number="INV-12345")
@@ -522,7 +522,7 @@ def test_perform_advanced_search_unrecognised_invoice_returns_empty(self):
         """Catches invalid invoice filters returning unrelated jobs."""
         target = self._make_job(
             name="Kick plates",
-            client_name="Weaver, Decker and Schultz",
+            company_name="Weaver, Decker and Schultz",
         )
         self._make_invoice(target, number="INV-15151")
 
@@ -536,12 +536,12 @@ def test_perform_advanced_search_quick_search_matches_order_number(self):
         """Catches universal search no longer matching order numbers."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
             order_number="8057",
         )
         self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
             order_number="99999",
         )
 
@@ -553,12 +553,12 @@ def test_perform_advanced_search_order_number_filter(self):
         """Catches the explicit order-number filter returning the wrong job."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
             order_number="8057",
         )
         self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
             order_number="99999",
         )
 
@@ -570,11 +570,11 @@ def test_perform_advanced_search_quick_search_matches_invoice_number(self):
         """Catches universal search no longer matching full invoice numbers."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_invoice(target, number="INV-56005")
         self._make_invoice(other, number="INV-99999")
@@ -589,11 +589,11 @@ def test_perform_advanced_search_quick_search_matches_bare_invoice_number(self):
         """Catches universal search no longer matching bare invoice digits."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         other = self._make_job(
             name="Other work",
-            client_name="Other Client",
+            company_name="Other Company",
         )
         self._make_invoice(target, number="INV-56005")
         self._make_invoice(other, number="INV-99999")
@@ -610,7 +610,7 @@ def test_perform_advanced_search_invoice_match_returns_job_once_with_multiple_in
         """Catches invoice joins duplicating jobs with multiple matching invoices."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         self._make_invoice(target, number="INV-56005")
         self._make_invoice(target, number="INV-56005-REV")
@@ -627,7 +627,7 @@ def test_perform_advanced_search_text_match_returns_job_once_with_multiple_invoi
         """Catches text search duplicating jobs that have multiple invoices."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         self._make_invoice(target, number="INV-56005")
         self._make_invoice(target, number="INV-99999")
@@ -640,7 +640,7 @@ def test_perform_advanced_search_invoice_reason_present(self):
         """Catches invoice matches losing their explainable search reason."""
         target = self._make_job(
             name="Cool Awnings",
-            client_name="Cool Awnings Ltd",
+            company_name="Cool Awnings Ltd",
         )
         self._make_invoice(target, number="INV-56005")
 
@@ -658,7 +658,7 @@ def test_kanban_search_logging_records_ranked_results_and_reasons(self):
         target = self._set_job_number(
             self._make_job(
                 name="Workshop Closed due to new roof",
-                client_name="Weaver, Decker and Schultz",
+                company_name="Weaver, Decker and Schultz",
             ),
             96977,
         )
diff --git a/apps/job/tests/test_kanban_service.py b/apps/job/tests/test_kanban_service.py
index 8a8bcd369..f4dbe3221 100644
--- a/apps/job/tests/test_kanban_service.py
+++ b/apps/job/tests/test_kanban_service.py
@@ -8,7 +8,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job
 from apps.job.services.kanban_service import KanbanService
 from apps.testing import BaseTestCase
@@ -19,16 +19,16 @@ class TestSerializeJobForApi(BaseTestCase):
     """Tests for KanbanService kanban job serialization."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             xero_last_modified=timezone.now(),
         )
-        self.shop_client = CompanyDefaults.get_solo().shop_client
+        self.shop_company = CompanyDefaults.get_solo().shop_company
 
     def _create_job(self, pricing_methodology="time_materials", name="Test Job"):
         """Create a job. Job.save() auto-creates CostSets (actual, quote, estimate)."""
         job = Job(
-            client=self.client_obj,
+            company=self.client_obj,
             name=name,
             pricing_methodology=pricing_methodology,
         )
@@ -81,7 +81,7 @@ def test_serialize_jobs_for_api_query_count_is_constant(self):
         for index in range(3):
             job = self._create_job(name=f"Batch Job {index}")
             job.contact = ClientContact.objects.create(
-                client=self.client_obj, name=f"Contact {index}"
+                company=self.client_obj, name=f"Contact {index}"
             )
             job.save(staff=self.test_staff, update_fields=["contact"])
             job.people.add(self.test_staff)
@@ -107,7 +107,7 @@ def test_serialized_shape_for_fully_populated_job(self):
         """The rewritten serializer must keep the exact response contract the
         frontend Zod schema requires."""
         job = self._create_job(name="Shape Job")
-        contact = ClientContact.objects.create(client=self.client_obj, name="Jane Doe")
+        contact = ClientContact.objects.create(company=self.client_obj, name="Jane Doe")
         job.contact = contact
         job.delivery_date = timezone.localdate()
         job.save(staff=self.test_staff, update_fields=["contact", "delivery_date"])
@@ -136,7 +136,7 @@ def test_serialized_shape_for_fully_populated_job(self):
                 "name",
                 "description",
                 "job_number",
-                "client_name",
+                "company_name",
                 "contact_person",
                 "people",
                 "status",
@@ -161,7 +161,7 @@ def test_serialized_shape_for_fully_populated_job(self):
                 "badge_color",
             },
         )
-        self.assertEqual(serialized["client_name"], "Test Client")
+        self.assertEqual(serialized["company_name"], "Test Company")
         self.assertEqual(serialized["contact_person"], "Jane Doe")
         self.assertEqual(serialized["quote_revenue"], 200.0)
         self.assertEqual(serialized["time_and_materials_revenue"], 100.0)
@@ -178,7 +178,7 @@ def test_serialized_shape_for_fully_populated_job(self):
 
     def test_serialize_jobs_for_api_resolves_shop_client_once_for_batch(self):
         shop_job = Job(
-            client=self.shop_client,
+            company=self.shop_company,
             name="Shop Job",
             pricing_methodology="time_materials",
         )
@@ -200,7 +200,7 @@ def test_serialize_jobs_for_api_resolves_shop_client_once_for_batch(self):
         shop_client_queries = [
             query["sql"]
             for query in captured
-            if "client_client" in query["sql"] and "Demo Company Shop" in query["sql"]
+            if "company_company" in query["sql"] and "Demo Company Shop" in query["sql"]
         ]
         self.assertEqual(shop_client_queries, [])
         self.assertEqual(
diff --git a/apps/job/tests/test_labour_subtypes.py b/apps/job/tests/test_labour_subtypes.py
index a800841f4..95e7bdcb7 100644
--- a/apps/job/tests/test_labour_subtypes.py
+++ b/apps/job/tests/test_labour_subtypes.py
@@ -9,7 +9,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job, JobLabourRate, LabourSubtype
 from apps.job.services.labour_subtype_service import seed_subtype_onto_existing_jobs
 from apps.job.services.workshop_service import WorkshopTimesheetService
@@ -60,14 +60,14 @@ def test_onsite_defaults_to_onsite_charge_out_rate(self) -> None:
 
 class JobLabourRateSeedingTests(BaseTestCase):
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="Labour Rate Client",
+        self.client_obj = Company.objects.create(
+            name="Labour Rate Company",
             email="labour-rates@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
     def _create_job(self) -> Job:
-        job = Job(name="Labour Rate Job", client=self.client_obj)
+        job = Job(name="Labour Rate Job", company=self.client_obj)
         job.save(staff=self.test_staff)
         return job
 
@@ -137,12 +137,12 @@ def test_new_non_workshop_staff_defaults_to_office_admin(self) -> None:
 
 class TimesheetLabourSubtypeTests(BaseTestCase):
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="Timesheet Subtype Client",
+        self.client_obj = Company.objects.create(
+            name="Timesheet Subtype Company",
             email="timesheet-subtypes@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
-        self.job = Job(name="Timesheet Subtype Job", client=self.client_obj)
+        self.job = Job(name="Timesheet Subtype Job", company=self.client_obj)
         self.job.save(staff=self.test_staff)
         self.staff = Staff.objects.create_user(
             email="timesheet-subtypes@example.com",
@@ -248,16 +248,16 @@ def setUp(self) -> None:
         )
         self.api = APIClient()
         self.api.force_authenticate(user=self.office_staff)
-        self.client_obj = Client.objects.create(
-            name="Mgmt Client",
+        self.client_obj = Company.objects.create(
+            name="Mgmt Company",
             email="mgmt-subtypes@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
-        self.job = Job(name="Mgmt Job", client=self.client_obj)
+        self.job = Job(name="Mgmt Job", company=self.client_obj)
         self.job.save(staff=self.test_staff)
 
     def _create_job(self, name: str) -> Job:
-        job = Job(name=name, client=self.client_obj)
+        job = Job(name=name, company=self.client_obj)
         job.save(staff=self.test_staff)
         return job
 
diff --git a/apps/job/tests/test_mcp_tool_integration.py b/apps/job/tests/test_mcp_tool_integration.py
index 9c410674b..a6b1109e8 100644
--- a/apps/job/tests/test_mcp_tool_integration.py
+++ b/apps/job/tests/test_mcp_tool_integration.py
@@ -8,7 +8,7 @@
 - Error handling in tool execution
 """
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.quoting.mcp import QuotingTool, SupplierProductQueryTool
 from apps.quoting.models import SupplierPriceList, SupplierProduct
@@ -21,7 +21,7 @@ class QuotingToolTests(BaseTestCase):
     def setUp(self):
         """Set up test data"""
         # Create a supplier
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="ABC Steel",
             email="sales@abcsteel.com",
             is_supplier=True,
@@ -29,17 +29,17 @@ def setUp(self):
         )
 
         # Create another supplier for comparison tests
-        self.supplier2 = Client.objects.create(
+        self.supplier2 = Company.objects.create(
             name="XYZ Metals",
             email="sales@xyzmetals.com",
             is_supplier=True,
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
-        # Create a client for job tests
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@example.com",
+        # Create a company for job tests
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
@@ -107,7 +107,7 @@ def setUp(self):
         self.job = Job.objects.create(
             name="Test Job",
             description="Test job description",
-            client=self.client_obj,
+            company=self.client_obj,
             status="quoting",
             staff=self.test_staff,
         )
@@ -254,7 +254,7 @@ class SupplierProductQueryToolTests(BaseTestCase):
 
     def setUp(self):
         """Set up test data"""
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="Test Supplier",
             email="supplier@test.com",
             is_supplier=True,
@@ -304,22 +304,22 @@ class MCPToolIntegrationTests(BaseTestCase):
 
     def setUp(self):
         """Set up test data"""
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="Integration Test Supplier",
             email="int@test.com",
             is_supplier=True,
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@test.com",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
+            email="company@test.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
         self.job = Job.objects.create(
             name="Integration Test Job",
-            client=self.client_obj,
+            company=self.client_obj,
             status="quoting",
             staff=self.test_staff,
         )
diff --git a/apps/job/tests/test_modern_timesheet_views.py b/apps/job/tests/test_modern_timesheet_views.py
index 62095ff3f..2dcf31633 100644
--- a/apps/job/tests/test_modern_timesheet_views.py
+++ b/apps/job/tests/test_modern_timesheet_views.py
@@ -5,7 +5,7 @@
 from rest_framework.test import APIRequestFactory, force_authenticate
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, LabourSubtype
 from apps.job.serializers.costing_serializer import TimesheetCostLineSerializer
 from apps.job.views.modern_timesheet_views import ModernTimesheetEntryView
@@ -17,8 +17,8 @@ class ModernTimesheetEntryQueryTests(BaseTestCase):
     def setUp(self):
         super().setUp()
         self.target_date = date(2026, 5, 22)
-        self.client = Client.objects.create(
-            name="Modern Timesheet Client",
+        self.company = Company.objects.create(
+            name="Modern Timesheet Company",
             email="modern-timesheet@example.com",
             xero_last_modified=timezone.now(),
         )
@@ -26,7 +26,7 @@ def setUp(self):
         self.job = Job.objects.create(
             job_number=98767,
             name="Modern Timesheet Job",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.pay_item,
             staff=self.test_staff,
         )
@@ -57,7 +57,7 @@ def test_timesheet_cost_line_serializer_uses_preloaded_relations(self):
         cost_lines = (
             CostLine.objects.filter(pk=self.cost_line.pk)
             .select_related(
-                "cost_set__job__client",
+                "cost_set__job__company",
                 "staff",
                 "xero_pay_item",
                 "labour_subtype",
@@ -70,7 +70,7 @@ def test_timesheet_cost_line_serializer_uses_preloaded_relations(self):
         with self.assertNumQueries(2):
             data = TimesheetCostLineSerializer(cost_lines, many=True).data
 
-        self.assertEqual(data[0]["client_name"], "Modern Timesheet Client")
+        self.assertEqual(data[0]["company_name"], "Modern Timesheet Company")
         self.assertEqual(data[0]["wage_rate"], 40.0)
         self.assertEqual(data[0]["xero_pay_item_name"], self.pay_item.name)
         self.assertEqual(data[0]["labour_subtype_name"], "Workshop")
diff --git a/apps/job/tests/test_paid_flag_service.py b/apps/job/tests/test_paid_flag_service.py
index f7496af90..e0099bd67 100644
--- a/apps/job/tests/test_paid_flag_service.py
+++ b/apps/job/tests/test_paid_flag_service.py
@@ -9,7 +9,7 @@
 from django.utils import timezone
 
 from apps.accounting.models import Invoice
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.services.paid_flag_service import PaidFlagService
 from apps.testing import BaseTestCase
@@ -17,14 +17,14 @@
 
 class PaidFlagServiceTests(BaseTestCase):
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Paid Flag Client",
+        self.client_obj = Company.objects.create(
+            name="Paid Flag Company",
             xero_last_modified=timezone.now(),
         )
 
     def _create_job(self, name: str) -> Job:
         job = Job(
-            client=self.client_obj,
+            company=self.client_obj,
             name=name,
             status="recently_completed",
             paid=False,
@@ -35,7 +35,7 @@ def _create_job(self, name: str) -> Job:
     def _create_invoice(self, job: Job, status: str) -> Invoice:
         return Invoice.objects.create(
             job=job,
-            client=self.client_obj,
+            company=self.client_obj,
             xero_id=uuid.uuid4(),
             number=f"INV-{uuid.uuid4().hex[:8]}",
             status=status,
diff --git a/apps/job/tests/test_quote_modes.py b/apps/job/tests/test_quote_modes.py
index 7ee79eead..58161daab 100644
--- a/apps/job/tests/test_quote_modes.py
+++ b/apps/job/tests/test_quote_modes.py
@@ -11,7 +11,7 @@
 from django.utils import timezone
 from jsonschema import ValidationError
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.schemas import quote_mode_schemas
 from apps.job.services.quote_mode_controller import QuoteModeController
@@ -147,14 +147,14 @@ def setUp(self):
         self.controller = QuoteModeController()
 
         # Create test job
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             email="test@example.com",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
             name="Test Job",
-            client=self.client_obj,
+            company=self.client_obj,
             staff=self.test_staff,
         )
 
@@ -240,7 +240,7 @@ def test_render_prompt(self):
         calc_prompt = self.controller.render_prompt(
             mode="CALC",
             user_input="Calculate area for 100x50mm",
-            job_ctx={"job_number": "TEST001", "client": "Test Client"},
+            job_ctx={"job_number": "TEST001", "company": "Test Company"},
         )
         self.assertIn("MODE=CALC", calc_prompt)
         self.assertIn("SCHEMA for CALC", calc_prompt)
@@ -317,14 +317,14 @@ class TestSheetTenthsIntegration(BaseTestCase):
     def setUp(self):
         """Set up test fixtures."""
         # Create test job
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             email="test@example.com",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
             name="Sheet Tenths Test Job",
-            client=self.client_obj,
+            company=self.client_obj,
             staff=self.test_staff,
         )
 
diff --git a/apps/job/tests/test_workshop_pdf_service.py b/apps/job/tests/test_workshop_pdf_service.py
index 99d3d59f2..612208bde 100644
--- a/apps/job/tests/test_workshop_pdf_service.py
+++ b/apps/job/tests/test_workshop_pdf_service.py
@@ -14,7 +14,7 @@
 from django.utils import timezone
 from pypdf import PdfReader
 
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.job.models import CostSet, Job, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.job.services.workshop_pdf_service import (
@@ -33,25 +33,25 @@
 
 class PrimaryPhoneForJobTests(BaseTestCase):
     """Phone preference order on workshop PDFs and delivery dockets:
-    the job contact's number first, then the client's own number."""
+    the job contact's number first, then the company's own number."""
 
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="Phone Pref Client",
+        self.client_obj = Company.objects.create(
+            name="Phone Pref Company",
             xero_last_modified=timezone.now(),
         )
         self.contact = ClientContact.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Jane Doe",
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             contact=self.contact,
             name="Phone Pref Job",
             staff=self.test_staff,
         )
         ClientContactMethod.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 555 0001",
         )
@@ -396,12 +396,12 @@ class WorkshopHourBreakdownTests(BaseTestCase):
     """Tests for subtype-based workshop PDF hour calculations."""
 
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="PDF Time Client",
+        self.client_obj = Company.objects.create(
+            name="PDF Time Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="PDF Time Job",
             staff=self.test_staff,
         )
@@ -554,7 +554,7 @@ def test_preloaded_workshop_pdf_render_does_not_query_cost_lines(self) -> None:
         assert estimate is not None
         self._add_time(estimate, "Workshop", "4.000", "Workshop")
         ClientContactMethod.objects.create(
-            client=self.job.client,
+            company=self.job.company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 555 0001",
         )
@@ -583,7 +583,7 @@ def test_preloaded_workshop_pdf_render_does_not_query_cost_lines(self) -> None:
         contact_method_queries = [
             query["sql"]
             for query in captured
-            if 'FROM "client_clientcontactmethod"' in query["sql"]
+            if 'FROM "company_clientcontactmethod"' in query["sql"]
         ]
         self.assertEqual(cost_line_queries, [])
         self.assertEqual(contact_method_queries, [])
@@ -659,12 +659,12 @@ class DeliveryDocketPDFTests(BaseTestCase):
     """Tests for delivery docket PDF generation."""
 
     def setUp(self) -> None:
-        self.client_obj = Client.objects.create(
-            name="Test Client",
+        self.client_obj = Company.objects.create(
+            name="Test Company",
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Test Delivery Job",
             description="Deliver some steel",
             staff=self.test_staff,
diff --git a/apps/job/tests/test_workshop_timesheet_api.py b/apps/job/tests/test_workshop_timesheet_api.py
index d1d0bfa95..436c80edb 100644
--- a/apps/job/tests/test_workshop_timesheet_api.py
+++ b/apps/job/tests/test_workshop_timesheet_api.py
@@ -7,7 +7,7 @@
 from django.urls import reverse
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job
 from apps.testing import BaseAPITestCase
 from apps.workflow.models import XeroPayItem
@@ -17,15 +17,15 @@ class WorkshopTimesheetAPITests(BaseAPITestCase):
     """Verify that normal (non-admin) staff can use the workshop timesheet API."""
 
     def setUp(self) -> None:
-        self.test_client = Client.objects.create(
-            name="Workshop Test Client",
+        self.test_company = Company.objects.create(
+            name="Workshop Test Company",
             email="workshop-test@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
         self.job = Job.objects.create(
             job_number=9000,
             name="Workshop Timesheet Test Job",
-            client=self.test_client,
+            company=self.test_company,
             staff=self.test_staff,
         )
         self.job.labour_rates.update(charge_out_rate=Decimal("120.00"))
diff --git a/apps/job/utils.py b/apps/job/utils.py
index a23c350b0..4cac5ca69 100644
--- a/apps/job/utils.py
+++ b/apps/job/utils.py
@@ -15,4 +15,4 @@ def get_active_jobs() -> models.QuerySet[Job]:
     """
     excluded_statuses = ["rejected", "on_hold", "archived"]
     # Include select_related for fields commonly needed when displaying these jobs
-    return Job.objects.exclude(status__in=excluded_statuses).select_related("client")
+    return Job.objects.exclude(status__in=excluded_statuses).select_related("company")
diff --git a/apps/job/views/data_quality_report_views.py b/apps/job/views/data_quality_report_views.py
index 905317af7..fd7570070 100644
--- a/apps/job/views/data_quality_report_views.py
+++ b/apps/job/views/data_quality_report_views.py
@@ -12,7 +12,7 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.client.services.duplicate_phone_report import DuplicatePhoneReportService
+from apps.company.services.duplicate_phone_report import DuplicatePhoneReportService
 from apps.job.permissions import IsOfficeStaff
 from apps.job.serializers.data_quality_report_serializers import (
     ArchivedJobsComplianceResponseSerializer,
@@ -71,7 +71,7 @@ class DuplicatePhonesView(APIView):
         operation_id="check_duplicate_phones",
         summary="Check duplicate phone ownership",
         description=(
-            "List phone numbers owned by more than one client, or client numbers "
+            "List phone numbers owned by more than one company, or company numbers "
             "that are actually internal company lines."
         ),
         responses={
@@ -81,7 +81,7 @@ class DuplicatePhonesView(APIView):
         tags=["Data Quality"],
     )
     def get(self, request: Request) -> Response:
-        """Return phone numbers that break the one-number-one-client rule."""
+        """Return phone numbers that break the one-number-one-company rule."""
         try:
             result = DuplicatePhoneReportService().get_report()
 
diff --git a/apps/job/views/delivery_docket_view.py b/apps/job/views/delivery_docket_view.py
index bffe79707..63a78ec69 100644
--- a/apps/job/views/delivery_docket_view.py
+++ b/apps/job/views/delivery_docket_view.py
@@ -23,7 +23,7 @@ class DeliveryDocketView(APIView):
     API view for generating and serving delivery docket PDFs.
 
     This view creates delivery docket PDFs that are identical to the workshop
-    PDF (job details, specifications, client info, signature fields), saves
+    PDF (job details, specifications, company info, signature fields), saves
     them as JobFile records, creates a JobEvent for tracking, and returns
     the PDF for immediate download or printing.
 
diff --git a/apps/job/views/job_rest_views.py b/apps/job/views/job_rest_views.py
index 4d78f686b..dd0b39096 100644
--- a/apps/job/views/job_rest_views.py
+++ b/apps/job/views/job_rest_views.py
@@ -259,7 +259,7 @@ def post(self, request):
         Expected JSON:
         {
             "name": "Job Name",
-            "client_id": "client-uuid",
+            "company_id": "company-uuid",
             "description": "Optional description",
             "order_number": "Optional order number",
             "notes": "Optional notes",
@@ -709,7 +709,7 @@ def post(self, request, job_id):
             if not if_match:
                 return self._precondition_required_response()
 
-            # Verify client ETag against current job version
+            # Verify company ETag against current job version
             try:
                 job_for_etag = Job.objects.only("id", "updated_at").get(id=job_id)
                 current_etag_norm = self._normalize_etag(
@@ -889,15 +889,15 @@ def get(self, request, job_id):
         Fetch essential job header data for fast initial loading.
         """
         try:
-            # Query fields derived from JOB_DIRECT_FIELDS, plus id and client/contact for joins
+            # Query fields derived from JOB_DIRECT_FIELDS, plus id and company/contact for joins
             query_fields = [
                 "id",
                 "updated_at",
-                "client_id",
+                "company_id",
                 "contact_id",
             ] + Job.JOB_DIRECT_FIELDS
             job = (
-                Job.objects.select_related("client", "contact")
+                Job.objects.select_related("company", "contact")
                 .only(*query_fields)
                 .get(id=job_id)
             )
diff --git a/apps/job/views/kanban_view_api.py b/apps/job/views/kanban_view_api.py
index 34169277d..9261b01ef 100644
--- a/apps/job/views/kanban_view_api.py
+++ b/apps/job/views/kanban_view_api.py
@@ -335,7 +335,7 @@ class AdvancedSearchAPIView(APIView):
                 type=str,
                 location=OpenApiParameter.QUERY,
                 required=False,
-                description="Universal search - searches across job number, name, description, and client name with OR logic",
+                description="Universal search - searches across job number, name, description, and company name with OR logic",
             ),
             OpenApiParameter(
                 name="job_number",
@@ -359,11 +359,11 @@ class AdvancedSearchAPIView(APIView):
                 description="Filter by job description",
             ),
             OpenApiParameter(
-                name="client_name",
+                name="company_name",
                 type=str,
                 location=OpenApiParameter.QUERY,
                 required=False,
-                description="Filter by client name",
+                description="Filter by company name",
             ),
             OpenApiParameter(
                 name="contact_person",
@@ -439,7 +439,7 @@ def get(self, request: Request) -> Response:
                 "job_number": request.GET.get("job_number", ""),
                 "name": request.GET.get("name", ""),
                 "description": request.GET.get("description", ""),
-                "client_name": request.GET.get("client_name", ""),
+                "company_name": request.GET.get("company_name", ""),
                 "contact_person": request.GET.get("contact_person", ""),
                 "order_number": request.GET.get("order_number", ""),
                 "created_by": request.GET.get("created_by", ""),
diff --git a/apps/job/views/modern_timesheet_views.py b/apps/job/views/modern_timesheet_views.py
index a67dc1f62..81a1ba2eb 100644
--- a/apps/job/views/modern_timesheet_views.py
+++ b/apps/job/views/modern_timesheet_views.py
@@ -158,7 +158,7 @@ def get(self, request):
                     accounting_date=parsed_date,
                 )
                 .select_related(
-                    "cost_set__job__client",
+                    "cost_set__job__company",
                     "staff",
                     "xero_pay_item",
                     "labour_subtype",
@@ -553,7 +553,7 @@ def get(self, request, staff_id, entry_date):
                     accounting_date=parsed_date,
                 )
                 .select_related(
-                    "cost_set__job__client",
+                    "cost_set__job__company",
                     "staff",
                     "xero_pay_item",
                     "labour_subtype",
@@ -624,7 +624,7 @@ def get(self, request, job_id):
                     meta__created_from_timesheet=True,
                 )
                 .select_related(
-                    "cost_set__job__client",
+                    "cost_set__job__company",
                     "staff",
                     "xero_pay_item",
                     "labour_subtype",
diff --git a/apps/job/views/month_end_rest_view.py b/apps/job/views/month_end_rest_view.py
index 377557321..aab2036b3 100644
--- a/apps/job/views/month_end_rest_view.py
+++ b/apps/job/views/month_end_rest_view.py
@@ -50,8 +50,8 @@ def get(self, request):
                     "job_id": str(item["job"].id),
                     "job_number": item["job"].job_number,
                     "job_name": item["job"].name,
-                    "client_name": (
-                        item["job"].client.name if item["job"].client else ""
+                    "company_name": (
+                        item["job"].company.name if item["job"].company else ""
                     ),
                     "history": [
                         {
diff --git a/apps/job/views/workshop_view.py b/apps/job/views/workshop_view.py
index fe2170d10..fdb8b5e03 100644
--- a/apps/job/views/workshop_view.py
+++ b/apps/job/views/workshop_view.py
@@ -39,7 +39,7 @@ def get_queryset(self):
                 "name": job.name,
                 "description": job.description,
                 "job_number": job.job_number,
-                "client_name": job.client.name,
+                "company_name": job.company.name,
                 "contact_person": job.contact.name if job.contact else None,
                 "people": [
                     {
diff --git a/apps/operations/serializers/workshop_schedule_serializer.py b/apps/operations/serializers/workshop_schedule_serializer.py
index e78570248..a908c2f07 100644
--- a/apps/operations/serializers/workshop_schedule_serializer.py
+++ b/apps/operations/serializers/workshop_schedule_serializer.py
@@ -17,7 +17,7 @@ class ScheduledJobSerializer(serializers.Serializer):
     id = serializers.UUIDField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     remaining_hours = serializers.FloatField()
     delivery_date = serializers.DateField(allow_null=True)
     anticipated_start_date = serializers.DateField(allow_null=True)
@@ -33,7 +33,7 @@ class UnscheduledJobSerializer(serializers.Serializer):
     id = serializers.UUIDField()
     job_number = serializers.IntegerField()
     name = serializers.CharField()
-    client_name = serializers.CharField()
+    company_name = serializers.CharField()
     delivery_date = serializers.DateField(allow_null=True)
     remaining_hours = serializers.FloatField()
     reason = serializers.CharField()
diff --git a/apps/operations/tests/test_scheduler_persistence.py b/apps/operations/tests/test_scheduler_persistence.py
index 24f1f459b..2626ac90e 100644
--- a/apps/operations/tests/test_scheduler_persistence.py
+++ b/apps/operations/tests/test_scheduler_persistence.py
@@ -8,7 +8,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostSet, Job, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.operations.models import AllocationBlock, JobProjection, SchedulerRun
@@ -56,11 +56,11 @@ def _set_workshop_hours(cost_set: CostSet, hours: float) -> None:
     )
 
 
-def _make_job(client: Client, staff: Staff, name: str = "Persist Test Job") -> Job:
+def _make_job(company: Company, staff: Staff, name: str = "Persist Test Job") -> Job:
     job = cast(
         Job,
         Job.objects.create(
-            client=client,
+            company=company,
             name=name,
             status="approved",
             staff=staff,
@@ -74,8 +74,8 @@ class TestSchedulerRunRecord(BaseTestCase):
     """Verify SchedulerRun records are created correctly."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Persist Client",
+        self.client_obj = Company.objects.create(
+            name="Persist Company",
             xero_last_modified=timezone.now(),
         )
         _make_staff("p1")
@@ -101,8 +101,8 @@ class TestFailedRunPreservesData(BaseTestCase):
     """Verify a failed run does not overwrite good data from a previous run."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Persist Client",
+        self.client_obj = Company.objects.create(
+            name="Persist Company",
             xero_last_modified=timezone.now(),
         )
         _make_staff("p2")
@@ -155,8 +155,8 @@ class TestLatestForecastReadsNewestRun(BaseTestCase):
     """Verify the API reads from the most recent successful SchedulerRun."""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Persist Client",
+        self.client_obj = Company.objects.create(
+            name="Persist Company",
             xero_last_modified=timezone.now(),
         )
         _make_staff("p3")
diff --git a/apps/operations/tests/test_scheduler_service.py b/apps/operations/tests/test_scheduler_service.py
index d10c8a627..b55ed8ba3 100644
--- a/apps/operations/tests/test_scheduler_service.py
+++ b/apps/operations/tests/test_scheduler_service.py
@@ -6,7 +6,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostSet, Job, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.operations.models import AllocationBlock, JobProjection
@@ -35,15 +35,15 @@ def _make_staff(
     )
 
 
-def _make_client() -> Client:
-    return Client.objects.create(
-        name="Test Client",
+def _make_client() -> Company:
+    return Company.objects.create(
+        name="Test Company",
         xero_last_modified=timezone.now(),
     )
 
 
 def _make_job(
-    client: Client,
+    company: Company,
     staff: Staff,
     name: str = "Test Job",
     status: str = "approved",
@@ -51,7 +51,7 @@ def _make_job(
     max_people: int = 1,
 ) -> Job:
     job = Job(
-        client=client,
+        company=company,
         name=name,
         status=status,
         min_people=min_people,
@@ -474,7 +474,7 @@ def _make_special_leave_job(self):
         """Create a leave-style job with an actual CostSet for booking time
         against (matches how create_leave_entries.py models leave)."""
         leave_job = Job(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Annual Leave",
             status="special",
             min_people=1,
diff --git a/apps/operations/tests/test_workshop_schedule_api.py b/apps/operations/tests/test_workshop_schedule_api.py
index cb7251b04..f6c82eb85 100644
--- a/apps/operations/tests/test_workshop_schedule_api.py
+++ b/apps/operations/tests/test_workshop_schedule_api.py
@@ -9,7 +9,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostSet, Job, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.operations.services.scheduler_service import run_workshop_schedule
@@ -57,7 +57,7 @@ def _set_workshop_hours(cost_set: CostSet, hours: float) -> None:
 
 
 def _make_job(
-    client: Client,
+    company: Company,
     staff: Staff,
     name: str = "API Test Job",
     hours: float = 8.0,
@@ -65,7 +65,7 @@ def _make_job(
     job = cast(
         Job,
         Job.objects.create(
-            client=client,
+            company=company,
             name=name,
             status="approved",
             staff=staff,
@@ -79,8 +79,8 @@ class WorkshopScheduleGetTests(BaseAPITestCase):
     """Tests for GET /api/operations/workshop-schedule/"""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="API Test Client",
+        self.client_obj = Company.objects.create(
+            name="API Test Company",
             xero_last_modified=timezone.now(),
         )
         self.staff = _make_staff("a1")
@@ -139,7 +139,7 @@ def test_unscheduled_job_has_reason(self):
         """Unscheduled jobs include a machine-readable reason field."""
         # Job with no hours → unscheduled
         Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="No Hours Job",
             status="approved",
             staff=self.test_staff,
@@ -166,8 +166,8 @@ class WorkshopScheduleRecalculateTests(BaseAPITestCase):
     """Tests for POST /api/operations/workshop-schedule/recalculate/"""
 
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Recalc Test Client",
+        self.client_obj = Company.objects.create(
+            name="Recalc Test Company",
             xero_last_modified=timezone.now(),
         )
         self.staff = _make_staff("b1")
diff --git a/apps/operations/views/workshop_schedule_view.py b/apps/operations/views/workshop_schedule_view.py
index 4da1e19a4..9416b0601 100644
--- a/apps/operations/views/workshop_schedule_view.py
+++ b/apps/operations/views/workshop_schedule_view.py
@@ -34,7 +34,7 @@ def _build_schedule_response(day_horizon: int) -> dict[str, Any]:
         return {"days": [], "jobs": [], "unscheduled_jobs": []}
 
     projections = JobProjection.objects.filter(scheduler_run=latest_run).select_related(
-        "job", "job__client"
+        "job", "job__company"
     )
     projections = list(projections)
     scheduled_job_ids = [
@@ -59,7 +59,7 @@ def _build_schedule_response(day_horizon: int) -> dict[str, Any]:
 
     for projection in projections:
         job = projection.job
-        client_name = job.client.name if job.client else ""
+        company_name = job.company.name if job.company else ""
 
         if projection.is_unscheduled:
             unscheduled_jobs.append(
@@ -67,7 +67,7 @@ def _build_schedule_response(day_horizon: int) -> dict[str, Any]:
                     "id": job.id,
                     "job_number": job.job_number,
                     "name": job.name,
-                    "client_name": client_name,
+                    "company_name": company_name,
                     "delivery_date": job.delivery_date,
                     "remaining_hours": projection.remaining_hours,
                     "reason": projection.unscheduled_reason or "",
@@ -88,7 +88,7 @@ def _build_schedule_response(day_horizon: int) -> dict[str, Any]:
                     "id": job.id,
                     "job_number": job.job_number,
                     "name": job.name,
-                    "client_name": client_name,
+                    "company_name": company_name,
                     "remaining_hours": projection.remaining_hours,
                     "delivery_date": job.delivery_date,
                     "anticipated_start_date": projection.anticipated_start_date,
diff --git a/apps/process/services/google_docs_service.py b/apps/process/services/google_docs_service.py
index 7f5ecb57f..8b47db89f 100644
--- a/apps/process/services/google_docs_service.py
+++ b/apps/process/services/google_docs_service.py
@@ -625,11 +625,11 @@ def _build_info_section(
 
         # Job details
         site_location = content.get("site_location", "To be confirmed")
-        client_name = job.client.name if job.client else "N/A"
+        company_name = job.company.name if job.company else "N/A"
 
         info_lines = [
             f"Job Number: {job.job_number}",
-            f"Client: {client_name}",
+            f"Company: {company_name}",
             f"Site Location: {site_location}",
         ]
 
diff --git a/apps/process/services/safety_ai_service.py b/apps/process/services/safety_ai_service.py
index 024bcbc7d..8422707a7 100644
--- a/apps/process/services/safety_ai_service.py
+++ b/apps/process/services/safety_ai_service.py
@@ -110,12 +110,12 @@ def generate_full_jsa(self, job: Job) -> dict[str, Any]:
 
 Job Name: {job.name}
 Job Number: {job.job_number}
-Client: {job.client.name if job.client else 'Unknown'}
+Company: {job.company.name if job.company else 'Unknown'}
 Description: {job.description or 'No description provided'}
 
 Generate a comprehensive JSA with:
 1. A clear title (job name)
-2. Site location (use client address if known, otherwise "To be confirmed on site")
+2. Site location (use company address if known, otherwise "To be confirmed on site")
 3. A detailed job description for safety purposes
 4. 4-6 sequential tasks covering the work from setup to completion
 5. For each task: 2-4 potential hazards and appropriate control measures
diff --git a/apps/process/tests/conftest.py b/apps/process/tests/conftest.py
index 901e936cf..db535f5b9 100644
--- a/apps/process/tests/conftest.py
+++ b/apps/process/tests/conftest.py
@@ -2,7 +2,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.workflow.models import CompanyDefaults
 
@@ -19,16 +19,16 @@ def test_staff(db):
 
 @pytest.fixture
 def job(db, test_staff):
-    shop_client = Client.objects.create(
-        name="Process Shop Client",
+    shop_company = Company.objects.create(
+        name="Process Shop Company",
         xero_last_modified=timezone.now(),
     )
     CompanyDefaults.objects.create(
         company_name="Process Test Co",
-        shop_client=shop_client,
+        shop_company=shop_company,
     )
-    client = Client.objects.create(
-        name="Test Client",
+    company = Company.objects.create(
+        name="Test Company",
         xero_last_modified=timezone.now(),
     )
-    return Job.objects.create(client=client, name="Test Job", staff=test_staff)
+    return Job.objects.create(company=company, name="Test Job", staff=test_staff)
diff --git a/apps/process/tests/test_procedure_service.py b/apps/process/tests/test_procedure_service.py
index 3365e2ffd..8c7635ad1 100644
--- a/apps/process/tests/test_procedure_service.py
+++ b/apps/process/tests/test_procedure_service.py
@@ -3,7 +3,7 @@
 import pytest
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.process.services.google_docs_service import GoogleDocResult
 from apps.process.services.procedure_service import ProcedureService
 from apps.workflow.models import CompanyDefaults
@@ -20,8 +20,8 @@ def _make_service():
     return service
 
 
-def _create_shop_client(name: str = "Shop Client") -> Client:
-    return Client.objects.create(name=name, xero_last_modified=timezone.now())
+def _create_shop_client(name: str = "Shop Company") -> Company:
+    return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
 
 @pytest.mark.django_db
@@ -30,7 +30,7 @@ def test_create_blank_procedure_happy_path(self):
         CompanyDefaults.objects.create(
             company_name="Morris Sheetmetal",
             gdrive_reference_library_folder_id="folder-123",
-            shop_client=_create_shop_client(),
+            shop_company=_create_shop_client(),
         )
 
         service = _make_service()
@@ -73,7 +73,7 @@ def test_create_blank_procedure_rejects_missing_folder_config(self):
         CompanyDefaults.objects.create(
             company_name="Test",
             gdrive_reference_library_folder_id="",
-            shop_client=_create_shop_client(),
+            shop_company=_create_shop_client(),
         )
 
         service = _make_service()
diff --git a/apps/purchasing/migrations/0001_baseline.py b/apps/purchasing/migrations/0001_baseline.py
index fa1bd201f..0efad55f0 100644
--- a/apps/purchasing/migrations/0001_baseline.py
+++ b/apps/purchasing/migrations/0001_baseline.py
@@ -15,7 +15,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         ("job", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
@@ -111,7 +111,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.SET_NULL,
                         related_name="purchase_orders",
-                        to="client.supplierpickupaddress",
+                        to="company.supplierpickupaddress",
                     ),
                 ),
                 (
@@ -121,7 +121,7 @@ class Migration(migrations.Migration):
                         null=True,
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="purchase_orders",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
diff --git a/apps/purchasing/models.py b/apps/purchasing/models.py
index fc6fb4c29..015ca492b 100644
--- a/apps/purchasing/models.py
+++ b/apps/purchasing/models.py
@@ -73,14 +73,14 @@ class PurchaseOrder(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.ForeignKey(
-        "client.Client",
+        "company.Company",
         on_delete=models.PROTECT,
         related_name="purchase_orders",
         null=True,
         blank=True,
     )
     pickup_address = models.ForeignKey(
-        "client.SupplierPickupAddress",
+        "company.SupplierPickupAddress",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
diff --git a/apps/purchasing/serializers.py b/apps/purchasing/serializers.py
index e869b7010..270e33f6a 100644
--- a/apps/purchasing/serializers.py
+++ b/apps/purchasing/serializers.py
@@ -2,7 +2,7 @@
 
 from rest_framework import serializers
 
-from apps.client.serializers import SupplierPickupAddressSerializer
+from apps.company.serializers import SupplierPickupAddressSerializer
 from apps.job.models import Job
 from apps.job.models.costing import CostLine
 from apps.job.serializers.costing_serializer import CostLineSerializer
@@ -62,10 +62,10 @@ class SupplierSearchResponseSerializer(serializers.Serializer):
 class JobForPurchasingSerializer(serializers.ModelSerializer):
     """Serializer for Job model in purchasing contexts."""
 
-    client_name = serializers.CharField(
-        source="client.name",
+    company_name = serializers.CharField(
+        source="company.name",
         read_only=True,
-        default="No Client",
+        default="No Company",
     )
     is_stock_holding = serializers.SerializerMethodField()
     job_display_name = serializers.SerializerMethodField()
@@ -83,7 +83,7 @@ class Meta:
             "id",
             "job_number",
             "name",
-            "client_name",
+            "company_name",
             "status",
             "is_stock_holding",
             "job_display_name",
@@ -97,8 +97,8 @@ class PurchaseOrderLineSerializer(serializers.ModelSerializer):
     job_number = serializers.IntegerField(
         source="job.job_number", read_only=True, allow_null=True
     )
-    client_name = serializers.CharField(
-        source="job.client.name", read_only=True, allow_null=True
+    company_name = serializers.CharField(
+        source="job.company.name", read_only=True, allow_null=True
     )
     job_name = serializers.CharField(source="job.name", read_only=True, allow_null=True)
     times_used = serializers.SerializerMethodField()
@@ -108,13 +108,13 @@ class Meta:
         fields = PurchaseOrderLine.PURCHASEORDERLINE_API_FIELDS + [
             "job_id",
             "job_number",
-            "client_name",
+            "company_name",
             "job_name",
             "times_used",
         ]
 
     def get_times_used(self, obj: PurchaseOrderLine) -> int:
-        """Always emit a numeric usage count for generated client validation."""
+        """Always emit a numeric usage count for generated company validation."""
         if not obj.item_code:
             return 0
 
@@ -220,7 +220,7 @@ class PurchaseOrderJobSerializer(serializers.Serializer):
 
     job_number = serializers.CharField()
     name = serializers.CharField()
-    client = serializers.CharField(allow_blank=True)
+    company = serializers.CharField(allow_blank=True)
 
 
 class PurchaseOrderListSerializer(serializers.Serializer):
@@ -370,7 +370,7 @@ class Meta:
         fields = Stock.STOCK_API_FIELDS + ["job_id", "times_used"]
 
     def get_times_used(self, obj: Stock) -> int:
-        """Always emit a numeric usage count for generated client validation."""
+        """Always emit a numeric usage count for generated company validation."""
         return int(getattr(obj, "times_used", 0) or 0)
 
 
diff --git a/apps/purchasing/services/purchasing_rest_service.py b/apps/purchasing/services/purchasing_rest_service.py
index cbca2f7cd..9d46c04e3 100644
--- a/apps/purchasing/services/purchasing_rest_service.py
+++ b/apps/purchasing/services/purchasing_rest_service.py
@@ -13,7 +13,7 @@
 from django.shortcuts import get_object_or_404
 from django.utils import timezone
 
-from apps.client.models import Supplier, SupplierPickupAddress
+from apps.company.models import Supplier, SupplierPickupAddress
 from apps.job.models.costing import CostLine
 from apps.job.models.job import Job
 from apps.purchasing.etag import generate_po_etag, normalize_etag
@@ -293,7 +293,7 @@ def _process_field(
     def list_purchase_orders() -> List[Dict[str, Any]]:
         pos = (
             PurchaseOrder.objects.select_related("supplier", "created_by")
-            .prefetch_related("po_lines__job__client")
+            .prefetch_related("po_lines__job__company")
             .order_by("-created_at")
         )
         result = []
@@ -305,7 +305,7 @@ def list_purchase_orders() -> List[Dict[str, Any]]:
                     seen_jobs[line.job.id] = {
                         "job_number": str(line.job.job_number),
                         "name": line.job.name,
-                        "client": line.job.client.name if line.job.client else "",
+                        "company": line.job.company.name if line.job.company else "",
                     }
             jobs = sorted(seen_jobs.values(), key=lambda j: j["job_number"])
 
@@ -357,7 +357,7 @@ def create_purchase_order(
         elif supplier:
             # Auto-select primary address if supplier is set and no address specified
             pickup_address = SupplierPickupAddress.objects.filter(
-                client=supplier, is_primary=True, is_active=True
+                company=supplier, is_primary=True, is_active=True
             ).first()
 
         order_date = data.get("order_date")
diff --git a/apps/purchasing/services/quote_to_po_service.py b/apps/purchasing/services/quote_to_po_service.py
index ff3eca303..3bfcfb840 100644
--- a/apps/purchasing/services/quote_to_po_service.py
+++ b/apps/purchasing/services/quote_to_po_service.py
@@ -17,7 +17,7 @@
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from rapidfuzz import fuzz, process
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.enums import MetalType
 from apps.purchasing.models import (
     PurchaseOrder,
@@ -102,7 +102,7 @@ def normalize(s: str) -> str:
     )  # lower, remove extra whitespace, preserve everything else
 
 
-def fuzzy_find_supplier(supplier_name: str) -> tuple[Client | None, str]:
+def fuzzy_find_supplier(supplier_name: str) -> tuple[Company | None, str]:
     """
     Find a supplier in the database using fuzzy matching.
 
@@ -116,7 +116,7 @@ def fuzzy_find_supplier(supplier_name: str) -> tuple[Client | None, str]:
         raise ValueError("Supplier name must be a non-empty string")
 
     # Get all suppliers
-    suppliers = Client.objects.all()
+    suppliers = Company.objects.all()
 
     # Extract supplier names and create a mapping from name to supplier object
     supplier_names = [s.name for s in suppliers]
diff --git a/apps/purchasing/services/supplier_search_service.py b/apps/purchasing/services/supplier_search_service.py
index 3d1f4ec5e..a5a67b433 100644
--- a/apps/purchasing/services/supplier_search_service.py
+++ b/apps/purchasing/services/supplier_search_service.py
@@ -12,7 +12,7 @@
 from django.db.models import Count, OuterRef, Q, Subquery
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContactMethod, SupplierSearchAlias
+from apps.company.models import ClientContactMethod, Company, SupplierSearchAlias
 
 if TYPE_CHECKING:
     from django_stubs_ext import WithAnnotations
@@ -26,7 +26,7 @@
 
 
 class _SupplierAnnotations(TypedDict):
-    """Queryset annotations list_suppliers() adds; not Client model fields."""
+    """Queryset annotations list_suppliers() adds; not Company model fields."""
 
     recent_purchase_count: int
     primary_phone: str | None
@@ -36,12 +36,12 @@ class _SupplierAnnotations(TypedDict):
     # Only the type checker evaluates this alias (all annotations in this
     # module are strings via __future__ annotations), so the dev-only
     # django_stubs_ext dependency is never imported at runtime.
-    _AnnotatedSupplier = WithAnnotations[Client, _SupplierAnnotations]
+    _AnnotatedSupplier = WithAnnotations[Company, _SupplierAnnotations]
 
 
 @dataclass(frozen=True)
 class _CandidateScore:
-    client: _AnnotatedSupplier
+    company: _AnnotatedSupplier
     score: float
     name_score: float
     recent_purchase_count: int
@@ -138,20 +138,20 @@ def _supplier_candidate_filter(query: str, query_norm: str) -> Q:
 
 
 def _format_supplier(
-    client: _AnnotatedSupplier, score: _CandidateScore
+    company: _AnnotatedSupplier, score: _CandidateScore
 ) -> dict[str, Any]:
     return {
-        "id": str(client.id),
-        "name": client.name,
-        "email": client.email or "",
+        "id": str(company.id),
+        "name": company.name,
+        "email": company.email or "",
         # The Subquery annotation yields None for suppliers with no phone
         # method; the API contract is a plain string.
-        "phone": client.primary_phone or "",
-        "address": client.address or "",
-        "is_account_customer": client.is_account_customer,
-        "is_supplier": client.is_supplier,
-        "allow_jobs": client.allow_jobs,
-        "xero_contact_id": client.xero_contact_id or "",
+        "phone": company.primary_phone or "",
+        "address": company.address or "",
+        "is_account_customer": company.is_account_customer,
+        "is_supplier": company.is_supplier,
+        "allow_jobs": company.allow_jobs,
+        "xero_contact_id": company.xero_contact_id or "",
         "last_invoice_date": None,
         "total_spend": "$0.00",
         "recent_purchase_count": score.recent_purchase_count,
@@ -175,7 +175,7 @@ def list_suppliers(
     cutoff = timezone.localdate() - timedelta(days=RECENT_PURCHASE_WINDOW_DAYS)
 
     queryset = (
-        Client.objects.filter(xero_archived=False, merged_into__isnull=True)
+        Company.objects.filter(xero_archived=False, merged_into__isnull=True)
         .annotate(
             recent_purchase_count=Count(
                 "purchase_orders",
@@ -185,7 +185,7 @@ def list_suppliers(
             ),
             primary_phone=Subquery(
                 ClientContactMethod.objects.filter(
-                    client=OuterRef("pk"),
+                    company=OuterRef("pk"),
                     method_type=ClientContactMethod.MethodType.PHONE,
                 )
                 .order_by("-is_primary", "label", "value")
@@ -213,7 +213,7 @@ def list_suppliers(
         ]
         scores = [
             _CandidateScore(
-                client=supplier,
+                company=supplier,
                 score=float(supplier.recent_purchase_count),
                 name_score=0.0,
                 recent_purchase_count=supplier.recent_purchase_count,
@@ -229,15 +229,15 @@ def list_suppliers(
                 _supplier_candidate_filter(query, query_norm)
             ).distinct()
             suppliers = list(queryset)
-            aliases_by_client_id: dict[Any, list[SupplierSearchAlias]] = {
+            aliases_by_company_id: dict[Any, list[SupplierSearchAlias]] = {
                 supplier.id: [] for supplier in suppliers
             }
             aliases = SupplierSearchAlias.objects.filter(
                 is_active=True,
-                client_id__in=aliases_by_client_id,
-            ).only("id", "client_id", "alias")
+                company_id__in=aliases_by_company_id,
+            ).only("id", "company_id", "alias")
             for alias in aliases:
-                aliases_by_client_id[alias.client_id].append(alias)
+                aliases_by_company_id[alias.company_id].append(alias)
 
             for supplier in suppliers:
                 candidate_terms = [
@@ -246,7 +246,7 @@ def list_suppliers(
                 ]
                 candidate_terms.extend(
                     term
-                    for alias in aliases_by_client_id[supplier.id]
+                    for alias in aliases_by_company_id[supplier.id]
                     for term in (
                         normalize_supplier_phrase(alias.alias),
                         _normalize_literal_phrase(alias.alias),
@@ -260,7 +260,7 @@ def list_suppliers(
                 purchase_boost = min(recent_purchase_count, 50) * 5.0
                 scores.append(
                     _CandidateScore(
-                        client=supplier,
+                        company=supplier,
                         score=name_score + purchase_boost,
                         name_score=name_score,
                         recent_purchase_count=recent_purchase_count,
@@ -274,7 +274,7 @@ def list_suppliers(
                 -score.score,
                 -score.name_score,
                 -score.recent_purchase_count,
-                score.client.name.lower(),
+                score.company.name.lower(),
             )
         )
         total_count = len(scores)
@@ -283,7 +283,7 @@ def list_suppliers(
 
     total_pages = math.ceil(total_count / page_size) if total_count else 0
     return {
-        "results": [_format_supplier(score.client, score) for score in scores],
+        "results": [_format_supplier(score.company, score) for score in scores],
         "count": total_count,
         "page": page,
         "page_size": page_size,
diff --git a/apps/purchasing/tests/test_purchase_order_line_usage.py b/apps/purchasing/tests/test_purchase_order_line_usage.py
index a91c19c8d..3793f63aa 100644
--- a/apps/purchasing/tests/test_purchase_order_line_usage.py
+++ b/apps/purchasing/tests/test_purchase_order_line_usage.py
@@ -16,7 +16,7 @@
 @pytest.fixture
 def company_defaults(db: None) -> None:
     # Job.save -> generate_job_number -> CompanyDefaults.get_solo(); the
-    # singleton cannot be lazily created (shop_client is NOT NULL).
+    # singleton cannot be lazily created (shop_company is NOT NULL).
     call_command("loaddata", "company_defaults")
 
 
diff --git a/apps/purchasing/tests/test_quote_to_po_service.py b/apps/purchasing/tests/test_quote_to_po_service.py
index 3e72743c0..29fe2b57f 100644
--- a/apps/purchasing/tests/test_quote_to_po_service.py
+++ b/apps/purchasing/tests/test_quote_to_po_service.py
@@ -10,7 +10,7 @@
 from django.conf import settings
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.enums import MetalType
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderSupplierQuote
 from apps.purchasing.services.quote_to_po_service import (
@@ -40,7 +40,7 @@ def test_extract_uses_sdk_and_parses_response(
     anthropic_provider: AIProvider, tmp_path: Path
 ) -> None:
     """SDK path: prompt + file go through messages.create, JSON response parses."""
-    Client.objects.create(
+    Company.objects.create(
         name="Acme Metals",
         xero_contact_id="xero-contact-1",
         xero_last_modified=timezone.now(),
diff --git a/apps/purchasing/tests/test_serializers.py b/apps/purchasing/tests/test_serializers.py
index b558a843a..cb7c48b51 100644
--- a/apps/purchasing/tests/test_serializers.py
+++ b/apps/purchasing/tests/test_serializers.py
@@ -1,6 +1,6 @@
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.purchasing.models import PurchaseOrder
 from apps.purchasing.serializers import (
@@ -13,13 +13,13 @@
 
 class JobForPurchasingSerializerTests(BaseTestCase):
     def test_client_name_uses_related_client_name(self):
-        client = Client.objects.create(
-            name="Serializer Client",
+        company = Company.objects.create(
+            name="Serializer Company",
             xero_last_modified=timezone.now(),
         )
         job = Job.objects.create(
             name="Serializer Job",
-            client=client,
+            company=company,
             created_by=self.test_staff,
             default_xero_pay_item=XeroPayItem.get_ordinary_time(),
             staff=self.test_staff,
@@ -27,12 +27,12 @@ def test_client_name_uses_related_client_name(self):
 
         data = JobForPurchasingSerializer(job).data
 
-        self.assertEqual(data["client_name"], "Serializer Client")
+        self.assertEqual(data["company_name"], "Serializer Company")
 
 
 class PurchaseOrderDetailSerializerTests(BaseTestCase):
     def test_related_display_fields_use_related_objects(self):
-        supplier = Client.objects.create(
+        supplier = Company.objects.create(
             name="Serializer Supplier",
             xero_contact_id="00000000-0000-0000-0000-000000000001",
             xero_last_modified=timezone.now(),
diff --git a/apps/purchasing/tests/test_stock_fts_search.py b/apps/purchasing/tests/test_stock_fts_search.py
index 48a64f879..142bd9b77 100644
--- a/apps/purchasing/tests/test_stock_fts_search.py
+++ b/apps/purchasing/tests/test_stock_fts_search.py
@@ -1,6 +1,6 @@
 """Postgres FTS regression coverage for stock search (Trello #150).
 
-Same bug class as the client search: `description.includes(query)` (and the
+Same bug class as the company search: `description.includes(query)` (and the
 backend's `description__icontains`) matched the query as a contiguous
 substring, so `"5mm stainless"` could not find `"stainless 5mm sheet"`.
 These tests pin token-order independence, phrase ranking, the structured
@@ -16,7 +16,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.models.costing import CostLine
 from apps.purchasing.models import Stock
@@ -282,13 +282,13 @@ def test_galvanised_sheet_queries_surface_expected_material(db, query):
 class TestStockSearchHistoricalRanking(BaseTestCase):
     def setUp(self):
         super().setUp()
-        self.client_obj = Client.objects.create(
-            name="Stock Search Client",
+        self.client_obj = Company.objects.create(
+            name="Stock Search Company",
             xero_last_modified=timezone.now(),
         )
 
     def _create_job(self, name: str) -> Job:
-        job = Job(client=self.client_obj, name=name)
+        job = Job(company=self.client_obj, name=name)
         job.save(staff=self.test_staff)
         return job
 
@@ -390,16 +390,16 @@ def test_view_returns_search_results_via_http(auth_api, office_staff, db):
     """
     _stock(description="Stainless 5mm sheet", item_code="STK-001")
     _stock(description="Aluminium bar", item_code="STK-002")
-    client = Client.objects.create(
-        name="Stock Search View Client",
+    company = Company.objects.create(
+        name="Stock Search View Company",
         xero_last_modified=timezone.now(),
     )
-    shop_client = Client.objects.create(
-        name="Stock Search Shop Client",
+    shop_company = Company.objects.create(
+        name="Stock Search Shop Company",
         xero_last_modified=timezone.now(),
     )
-    CompanyDefaults.objects.create(company_name="Test Co", shop_client=shop_client)
-    job = Job(client=client, name="Stock Search View Job")
+    CompanyDefaults.objects.create(company_name="Test Co", shop_company=shop_company)
+    job = Job(company=company, name="Stock Search View Job")
     job.save(staff=office_staff)
     CostLine.objects.create(
         cost_set=job.latest_actual,
diff --git a/apps/purchasing/tests/test_stock_metadata_tasks.py b/apps/purchasing/tests/test_stock_metadata_tasks.py
index baa1f78b9..04e2e2c47 100644
--- a/apps/purchasing/tests/test_stock_metadata_tasks.py
+++ b/apps/purchasing/tests/test_stock_metadata_tasks.py
@@ -13,7 +13,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine, Stock
 from apps.purchasing.services.delivery_receipt_service import (
@@ -385,7 +385,7 @@ def test_stock_viewset_create_enqueues_metadata_parse() -> None:
 @pytest.fixture
 def company_defaults(db: None) -> None:
     # Job.save -> generate_job_number -> CompanyDefaults.get_solo(); the
-    # singleton cannot be lazily created (shop_client is NOT NULL).
+    # singleton cannot be lazily created (shop_company is NOT NULL).
     call_command("loaddata", "company_defaults")
 
 
@@ -394,11 +394,11 @@ def test_delivery_receipt_stock_creation_enqueues_metadata_parse(
     company_defaults: None,
 ) -> None:
     staff = _staff()
-    client = Client.objects.create(
-        name="Receipt Stock Client",
+    company = Company.objects.create(
+        name="Receipt Stock Company",
         xero_last_modified=timezone.now(),
     )
-    job = Job.objects.create(client=client, name="Receipt Stock Job", staff=staff)
+    job = Job.objects.create(company=company, name="Receipt Stock Job", staff=staff)
     po = PurchaseOrder.objects.create(po_number="PO-STOCK-META")
     line = PurchaseOrderLine.objects.create(
         purchase_order=po,
diff --git a/apps/purchasing/tests/test_supplier_search.py b/apps/purchasing/tests/test_supplier_search.py
index d2cbca92b..f1a91b687 100644
--- a/apps/purchasing/tests/test_supplier_search.py
+++ b/apps/purchasing/tests/test_supplier_search.py
@@ -10,7 +10,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, SupplierSearchAlias
+from apps.company.models import Company, SupplierSearchAlias
 from apps.purchasing.models import PurchaseOrder
 from apps.purchasing.services.supplier_search_service import (
     _name_match_score,
@@ -25,10 +25,10 @@ def _make_client(name: str, **overrides):
         "xero_last_modified": timezone.now(),
     }
     defaults.update(overrides)
-    return Client.objects.create(**defaults)
+    return Company.objects.create(**defaults)
 
 
-def _make_po(supplier: Client, *, days_ago: int = 0, status: str = "draft"):
+def _make_po(supplier: Company, *, days_ago: int = 0, status: str = "draft"):
     sequence = PurchaseOrder.objects.count() + 1
     return PurchaseOrder.objects.create(
         supplier=supplier,
@@ -114,7 +114,7 @@ def test_s_and_t_ranks_s_t_before_t_s():
 @pytest.mark.django_db
 def test_supplier_alias_matches_attached_client():
     supplier = _make_client("S&T Stainless Limited")
-    SupplierSearchAlias.objects.create(client=supplier, alias="Steel and Tube")
+    SupplierSearchAlias.objects.create(company=supplier, alias="Steel and Tube")
 
     assert _names("Steel and Tube")[0] == "S&T Stainless Limited"
 
@@ -187,24 +187,24 @@ def test_supplier_alias_api_lists_creates_and_deactivates_alias(auth_api):
     give suppliers nicknames — searching large supplier lists by legal name
     alone becomes unusable.
     """
-    client = _make_client("S&T Stainless Limited")
+    company = _make_client("S&T Stainless Limited")
 
     create_resp = auth_api.post(
-        f"/api/clients/{client.id}/supplier-aliases/",
+        f"/api/companies/{company.id}/supplier-aliases/",
         {"alias": "Steel and Tube"},
         format="json",
     )
     assert create_resp.status_code == 201, create_resp.content
     alias_id = create_resp.json()["id"]
 
-    list_resp = auth_api.get(f"/api/clients/{client.id}/supplier-aliases/")
+    list_resp = auth_api.get(f"/api/companies/{company.id}/supplier-aliases/")
     assert list_resp.status_code == 200, list_resp.content
     assert [row["alias"] for row in list_resp.json()] == ["Steel and Tube"]
 
-    delete_resp = auth_api.delete(f"/api/clients/supplier-aliases/{alias_id}/")
+    delete_resp = auth_api.delete(f"/api/companies/supplier-aliases/{alias_id}/")
     assert delete_resp.status_code == 204, delete_resp.content
 
-    list_resp = auth_api.get(f"/api/clients/{client.id}/supplier-aliases/")
+    list_resp = auth_api.get(f"/api/companies/{company.id}/supplier-aliases/")
     assert list_resp.status_code == 200, list_resp.content
     assert list_resp.json() == []
 
@@ -216,7 +216,7 @@ def test_supplier_search_view_returns_alias_match(auth_api):
     silently stops working.
     """
     supplier = _make_client("S&T Stainless Limited")
-    SupplierSearchAlias.objects.create(client=supplier, alias="Steel and Tube")
+    SupplierSearchAlias.objects.create(company=supplier, alias="Steel and Tube")
 
     resp = auth_api.get("/api/purchasing/suppliers/search/", {"q": "Steel and Tube"})
 
diff --git a/apps/purchasing/views/purchasing_rest_views.py b/apps/purchasing/views/purchasing_rest_views.py
index a6d2bf79a..f82229e81 100644
--- a/apps/purchasing/views/purchasing_rest_views.py
+++ b/apps/purchasing/views/purchasing_rest_views.py
@@ -100,7 +100,7 @@ def _set_etag(self, response, etag: str):
 class SupplierPriceStatusAPIView(APIView):
     """Return latest price upload status per supplier.
 
-    Minimal-impact: read-only query over existing Client and SupplierPriceList
+    Minimal-impact: read-only query over existing Company and SupplierPriceList
     models. No migrations required.
     """
 
@@ -112,7 +112,7 @@ class SupplierPriceStatusAPIView(APIView):
     )
     def get(self, request):
         try:
-            from apps.client.models import Client
+            from apps.company.models import Company
             from apps.quoting.models import SupplierPriceList
 
             # Subquery to get the latest upload per supplier
@@ -121,7 +121,7 @@ def get(self, request):
             ).order_by("-uploaded_at")
 
             suppliers = (
-                Client.objects.filter(
+                Company.objects.filter(
                     id__in=SupplierPriceList.objects.values("supplier_id").distinct()
                 )
                 .annotate(
@@ -208,7 +208,7 @@ def get(self, request):
             # Get active jobs for purchasing (archived jobs don't need POs)
             jobs = (
                 Job.objects.exclude(status="archived")
-                .select_related("client")
+                .select_related("company")
                 .order_by("job_number")
             )
 
@@ -259,7 +259,7 @@ def get(self, request):
                     ]
                 )
                 .exclude(status__in=excluded_statuses)
-                .select_related("client")
+                .select_related("company")
                 .prefetch_related("cost_sets")
                 .order_by("job_number")
             )
@@ -296,7 +296,9 @@ def get(self, request):
                         "id": str(job.id),
                         "job_number": job.job_number,
                         "name": job.name,
-                        "client_name": job.client.name if job.client else "No Client",
+                        "company_name": (
+                            job.company.name if job.company else "No Company"
+                        ),
                         "status": job.status,
                         "cost_set_id": (
                             str(actual_cost_set.id) if actual_cost_set else None
@@ -439,7 +441,7 @@ def get(self, request, po_id):
         po = get_object_or_404(queryset, id=po_id)
         po.detail_lines = list(
             PurchaseOrderLine.objects.filter(purchase_order=po).select_related(
-                "job__client"
+                "job__company"
             )
         )
         item_codes = [line.item_code for line in po.detail_lines if line.item_code]
diff --git a/apps/purchasing/views/stock_search_rest_view.py b/apps/purchasing/views/stock_search_rest_view.py
index 9ee17cded..c511dd3d2 100644
--- a/apps/purchasing/views/stock_search_rest_view.py
+++ b/apps/purchasing/views/stock_search_rest_view.py
@@ -3,7 +3,7 @@
 
 Mirrors ClientSearchRestView in shape: paginated list with an optional `q`
 parameter that runs Postgres FTS over the stock table. The 3-character
-minimum-query guard matches client search.
+minimum-query guard matches company search.
 """
 
 import logging
diff --git a/apps/quoting/__init__.py b/apps/quoting/__init__.py
index 458ad02eb..351641e8f 100644
--- a/apps/quoting/__init__.py
+++ b/apps/quoting/__init__.py
@@ -47,7 +47,7 @@
 
 # EXCLUDED IMPORTS - These contain problematic dependencies that cause circular imports
 # Import these directly where needed using:
-# from .admin import ClientAdmin
+# from .admin import CompanyAdmin
 # from .admin import SupplierAdmin
 # from .admin import SupplierCredentialAdmin
 # from .admin import SupplierCredentialAdminForm
diff --git a/apps/quoting/admin.py b/apps/quoting/admin.py
index 78e99b2a3..f4b44d47b 100644
--- a/apps/quoting/admin.py
+++ b/apps/quoting/admin.py
@@ -6,7 +6,7 @@
 from django.forms.models import BaseInlineFormSet
 from django.http import HttpRequest
 
-from apps.client.models import Client, Supplier
+from apps.company.models import Company, Supplier
 from apps.quoting.models import SupplierCredential, SupplierScraperConfig
 
 
@@ -80,7 +80,7 @@ def add_fields(self, form: forms.BaseForm, index: int | None) -> None:
         )
 
 
-class SupplierCredentialInline(admin.TabularInline[SupplierCredential, Client]):
+class SupplierCredentialInline(admin.TabularInline[SupplierCredential, Company]):
     model = SupplierCredential
     form = SupplierCredentialAdminForm
     extra = 0
@@ -95,7 +95,7 @@ class SupplierCredentialInline(admin.TabularInline[SupplierCredential, Client]):
     )
 
 
-class SupplierScraperConfigInline(admin.StackedInline[SupplierScraperConfig, Client]):
+class SupplierScraperConfigInline(admin.StackedInline[SupplierScraperConfig, Company]):
     model = SupplierScraperConfig
     form = SupplierScraperConfigAdminForm
     formset = SupplierScraperConfigInlineFormSet
@@ -104,15 +104,15 @@ class SupplierScraperConfigInline(admin.StackedInline[SupplierScraperConfig, Cli
     fields = ("scraper_class", "portal_url", "is_enabled", "active_credential")
 
 
-class ClientAdmin(admin.ModelAdmin[Client]):
+class CompanyAdmin(admin.ModelAdmin[Company]):
     list_display = ("name", "is_supplier", "email")
     list_filter = ("is_supplier",)
     search_fields = ("name", "email")
     inlines = (SupplierCredentialInline, SupplierScraperConfigInline)
 
 
-class SupplierAdmin(ClientAdmin):
-    def get_queryset(self, request: HttpRequest) -> QuerySet[Client]:
+class SupplierAdmin(CompanyAdmin):
+    def get_queryset(self, request: HttpRequest) -> QuerySet[Company]:
         return super().get_queryset(request).filter(is_supplier=True)
 
 
@@ -132,5 +132,5 @@ class SupplierScraperConfigAdmin(admin.ModelAdmin[SupplierScraperConfig]):
     search_fields = ("supplier__name", "scraper_class", "portal_url")
 
 
-admin.site.register(Client, ClientAdmin)
+admin.site.register(Company, CompanyAdmin)
 admin.site.register(Supplier, SupplierAdmin)
diff --git a/apps/quoting/mcp.py b/apps/quoting/mcp.py
index 147e91bba..1c1523a28 100644
--- a/apps/quoting/mcp.py
+++ b/apps/quoting/mcp.py
@@ -3,7 +3,7 @@
 from django.db.models import Q
 from mcp_server import MCPToolset, ModelQueryToolset
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 
 from .models import ScrapeJob, SupplierPriceList, SupplierProduct
@@ -102,7 +102,7 @@ def create_quote_estimate(
         # Create a basic quote structure
         quote_info = [
             f"Quote Estimate for Job: {job.name}",
-            f"Client: {job.client.name}",
+            f"Company: {job.company.name}",
             f"Materials requested: {materials}",
             "",
         ]
@@ -147,11 +147,11 @@ def create_quote_estimate(
     def get_supplier_status(self, supplier_name: str = None) -> str:
         """Get status of supplier scraping and price lists"""
         if supplier_name:
-            suppliers = Client.objects.filter(
+            suppliers = Company.objects.filter(
                 name__icontains=supplier_name, is_supplier=True
             )
         else:
-            suppliers = Client.objects.filter(is_supplier=True)
+            suppliers = Company.objects.filter(is_supplier=True)
 
         results = ["Supplier Status Report:"]
 
diff --git a/apps/quoting/migrations/0001_baseline.py b/apps/quoting/migrations/0001_baseline.py
index 3bf913acc..5b981f73d 100644
--- a/apps/quoting/migrations/0001_baseline.py
+++ b/apps/quoting/migrations/0001_baseline.py
@@ -14,7 +14,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
@@ -53,7 +53,7 @@ class Migration(migrations.Migration):
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="scrape_jobs",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -115,7 +115,7 @@ class Migration(migrations.Migration):
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="supplier_credentials",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -150,7 +150,7 @@ class Migration(migrations.Migration):
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="price_lists",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -357,7 +357,7 @@ class Migration(migrations.Migration):
                     models.ForeignKey(
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="scraped_products",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
@@ -392,7 +392,7 @@ class Migration(migrations.Migration):
                     models.OneToOneField(
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="scraper_config",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
diff --git a/apps/quoting/models.py b/apps/quoting/models.py
index 67444a7ab..c7fc65544 100644
--- a/apps/quoting/models.py
+++ b/apps/quoting/models.py
@@ -8,7 +8,7 @@
     EncryptedCharField,
 )
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.enums import MetalType
 from apps.purchasing.models import Stock
 
@@ -24,7 +24,7 @@ class CredentialType(models.TextChoices):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.ForeignKey(
-        Client, on_delete=models.PROTECT, related_name="supplier_credentials"
+        Company, on_delete=models.PROTECT, related_name="supplier_credentials"
     )
     label = models.CharField(max_length=255)
     credential_type = models.CharField(
@@ -99,7 +99,7 @@ class SupplierScraperConfig(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.OneToOneField(
-        Client, on_delete=models.PROTECT, related_name="scraper_config"
+        Company, on_delete=models.PROTECT, related_name="scraper_config"
     )
     scraper_class = models.CharField(max_length=255, db_index=True)
     portal_url = models.URLField(max_length=1000)
@@ -151,7 +151,7 @@ class SupplierProduct(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.ForeignKey(
-        Client, on_delete=models.PROTECT, related_name="scraped_products"
+        Company, on_delete=models.PROTECT, related_name="scraped_products"
     )
     price_list = models.ForeignKey(
         "SupplierPriceList", on_delete=models.CASCADE, related_name="products"
@@ -284,7 +284,7 @@ class SupplierPriceList(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.ForeignKey(
-        Client, on_delete=models.PROTECT, related_name="price_lists"
+        Company, on_delete=models.PROTECT, related_name="price_lists"
     )
     file_name = models.CharField(
         max_length=255, help_text="Original filename of the uploaded price list"
@@ -313,7 +313,7 @@ class ScrapeJob(models.Model):
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     supplier = models.ForeignKey(
-        Client, on_delete=models.PROTECT, related_name="scrape_jobs"
+        Company, on_delete=models.PROTECT, related_name="scrape_jobs"
     )
     status = models.CharField(max_length=20, choices=STATUS_CHOICES, default="running")
     started_at = models.DateTimeField(default=timezone.now)
diff --git a/apps/quoting/services/pdf_data_validation.py b/apps/quoting/services/pdf_data_validation.py
index 4d84f286b..f50f21800 100644
--- a/apps/quoting/services/pdf_data_validation.py
+++ b/apps/quoting/services/pdf_data_validation.py
@@ -2,7 +2,7 @@
 import re
 from typing import Any, Dict, List, Optional, Tuple
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.quoting.models import SupplierProduct
 
 logger = logging.getLogger(__name__)
@@ -283,8 +283,8 @@ def check_duplicates(
             Dictionary with 'duplicates' and 'new' product lists
         """
         try:
-            supplier = Client.objects.get(name=supplier_name)
-        except Client.DoesNotExist:
+            supplier = Company.objects.get(name=supplier_name)
+        except Company.DoesNotExist:
             # If supplier doesn't exist, all products are new
             return {"duplicates": [], "new": products}
 
diff --git a/apps/quoting/services/pdf_import_service.py b/apps/quoting/services/pdf_import_service.py
index 3e930d1d4..5b2f33da9 100644
--- a/apps/quoting/services/pdf_import_service.py
+++ b/apps/quoting/services/pdf_import_service.py
@@ -4,7 +4,7 @@
 from django.db import transaction
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.quoting.models import SupplierPriceList, SupplierProduct
 from apps.quoting.services.product_parser import create_mapping_record
 
@@ -28,35 +28,35 @@ def __init__(self):
             "errors": [],
         }
 
-    def create_or_get_supplier(self, supplier_name: str) -> Tuple[Client, bool]:
+    def create_or_get_supplier(self, supplier_name: str) -> Tuple[Company, bool]:
         """
-        Create or retrieve supplier client record.
+        Create or retrieve supplier company record.
 
         Args:
             supplier_name: Name of the supplier
 
         Returns:
-            Tuple of (Client instance, was_created boolean)
+            Tuple of (Company instance, was_created boolean)
         """
         try:
-            supplier = Client.objects.get(name=supplier_name)
+            supplier = Company.objects.get(name=supplier_name)
             logger.info(f"Found existing supplier: {supplier.name} (ID: {supplier.id})")
             return supplier, False
-        except Client.DoesNotExist:
+        except Company.DoesNotExist:
             # Create new supplier
-            supplier = Client.objects.create(
+            supplier = Company.objects.create(
                 name=supplier_name, is_supplier=True, xero_last_modified=timezone.now()
             )
             logger.info(f"Created new supplier: {supplier.name} (ID: {supplier.id})")
             self.import_stats["supplier_created"] = True
             return supplier, True
 
-    def create_price_list(self, supplier: Client, filename: str) -> SupplierPriceList:
+    def create_price_list(self, supplier: Company, filename: str) -> SupplierPriceList:
         """
         Create a new price list record for the supplier.
 
         Args:
-            supplier: Supplier client instance
+            supplier: Supplier company instance
             filename: Original filename of the uploaded PDF
 
         Returns:
@@ -73,7 +73,7 @@ def create_price_list(self, supplier: Client, filename: str) -> SupplierPriceLis
     def import_products(
         self,
         products: List[Dict],
-        supplier: Client,
+        supplier: Company,
         price_list: SupplierPriceList,
         duplicate_strategy: str = "skip",
     ) -> Dict[str, int]:
@@ -82,7 +82,7 @@ def import_products(
 
         Args:
             products: List of sanitized product dictionaries
-            supplier: Supplier client instance
+            supplier: Supplier company instance
             price_list: Price list instance
             duplicate_strategy: How to handle duplicates ("skip", "update", "create_new")
 
@@ -155,7 +155,7 @@ def import_products(
     def _import_single_product(
         self,
         product_data: Dict,
-        supplier: Client,
+        supplier: Company,
         price_list: SupplierPriceList,
         duplicate_strategy: str,
         index: int,
@@ -165,7 +165,7 @@ def _import_single_product(
 
         Args:
             product_data: Sanitized product data dictionary
-            supplier: Supplier client instance
+            supplier: Supplier company instance
             price_list: Price list instance
             duplicate_strategy: How to handle duplicates
             index: Product index for logging
@@ -185,14 +185,14 @@ def _import_single_product(
             return self._create_new_product(product_data, supplier, price_list, index)
 
     def _find_existing_product(
-        self, product_data: Dict, supplier: Client
+        self, product_data: Dict, supplier: Company
     ) -> SupplierProduct:
         """
         Find existing product by item_no or product_name.
 
         Args:
             product_data: Product data dictionary
-            supplier: Supplier client instance
+            supplier: Supplier company instance
 
         Returns:
             Existing SupplierProduct instance or None
@@ -301,7 +301,7 @@ def _update_existing_product(
     def _create_new_product(
         self,
         product_data: Dict,
-        supplier: Client,
+        supplier: Company,
         price_list: SupplierPriceList,
         index: int,
     ) -> str:
@@ -310,7 +310,7 @@ def _create_new_product(
 
         Args:
             product_data: Product data dictionary
-            supplier: Supplier client instance
+            supplier: Supplier company instance
             price_list: Price list instance
             index: Product index for logging
 
@@ -360,8 +360,8 @@ def handle_duplicates(
             Dictionary with duplicate analysis results
         """
         try:
-            supplier = Client.objects.get(name=supplier_name)
-        except Client.DoesNotExist:
+            supplier = Company.objects.get(name=supplier_name)
+        except Company.DoesNotExist:
             # No supplier exists, so no duplicates possible
             return {
                 "duplicates_found": 0,
diff --git a/apps/quoting/tests/test_pdf_data_validation.py b/apps/quoting/tests/test_pdf_data_validation.py
index 2aa307e94..d650238a8 100644
--- a/apps/quoting/tests/test_pdf_data_validation.py
+++ b/apps/quoting/tests/test_pdf_data_validation.py
@@ -1,4 +1,4 @@
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.quoting.models import SupplierPriceList, SupplierProduct
 from apps.quoting.services.pdf_data_validation import PDFDataValidationService
 from apps.testing import BaseTestCase
@@ -12,7 +12,7 @@ def setUp(self):
         self.service = PDFDataValidationService()
 
         # Create test supplier
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="Test Supplier",
             is_supplier=True,
             xero_last_modified="2023-01-01T00:00:00Z",
diff --git a/apps/quoting/tests/test_supplier_scraper_credentials.py b/apps/quoting/tests/test_supplier_scraper_credentials.py
index af189d4da..a24294255 100644
--- a/apps/quoting/tests/test_supplier_scraper_credentials.py
+++ b/apps/quoting/tests/test_supplier_scraper_credentials.py
@@ -1,7 +1,7 @@
 from django.core.exceptions import ValidationError
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.quoting.management.commands.run_scrapers import Command
 from apps.quoting.models import SupplierCredential, SupplierScraperConfig
 from apps.quoting.scrapers.steel_and_tube import SteelAndTubeScraper
@@ -14,7 +14,7 @@ class DummyScraper:
 
 class SupplierScraperCredentialTests(BaseTestCase):
     def setUp(self) -> None:
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="S&T Stainless Limited",
             is_supplier=True,
             xero_last_modified=timezone.now(),
@@ -49,7 +49,7 @@ def test_username_password_requires_username_and_password(self) -> None:
         self.assertIn("password", context.exception.message_dict)
 
     def test_supplier_scraper_config_requires_same_supplier_credential(self) -> None:
-        other_supplier = Client.objects.create(
+        other_supplier = Company.objects.create(
             name="Other Supplier",
             is_supplier=True,
             xero_last_modified=timezone.now(),
diff --git a/apps/quoting/tests_mcp.py b/apps/quoting/tests_mcp.py
index 921904626..05e8251ef 100644
--- a/apps/quoting/tests_mcp.py
+++ b/apps/quoting/tests_mcp.py
@@ -3,7 +3,7 @@
 Run with: python manage.py test apps.quoting.tests_mcp
 """
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.quoting.models import SupplierPriceList, SupplierProduct
 from apps.testing import BaseTestCase
@@ -17,23 +17,23 @@ def setUp(self):
         self.tool = QuotingTool()
 
         # Create test supplier
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="Test Steel Co",
             is_supplier=True,
             email="test@steelco.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
-        # Create test client and job
-        self.client_obj = Client.objects.create(
-            name="Test Client",
-            email="client@test.com",
+        # Create test company and job
+        self.company_obj = Company.objects.create(
+            name="Test Company",
+            email="company@test.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
 
         self.job = Job.objects.create(
             name="Test Job",
-            client=self.client_obj,
+            company=self.company_obj,
             description="Test metal work",
             staff=self.test_staff,
         )
@@ -95,7 +95,7 @@ def test_create_quote_estimate(self):
         )
 
         self.assertIn("Quote Estimate for Job: Test Job", result)
-        self.assertIn("Client: Test Client", result)
+        self.assertIn("Company: Test Company", result)
         self.assertIn("steel sheet", result)
         self.assertIn("Labor estimate: 10.0 hours", result)
 
@@ -131,7 +131,7 @@ def setUp(self):
         self.tool = SupplierProductQueryTool()
 
         # Create test data
-        self.supplier = Client.objects.create(
+        self.supplier = Company.objects.create(
             name="Query Test Supplier",
             is_supplier=True,
             xero_last_modified="2024-01-01T00:00:00Z",
diff --git a/apps/testing.py b/apps/testing.py
index 6c48386d8..a2a1f99d4 100644
--- a/apps/testing.py
+++ b/apps/testing.py
@@ -61,7 +61,7 @@ class BaseTestCase(TestCase):
     Base test case that loads required fixtures.
 
     The company_defaults fixture is required for most tests because:
-    - Job creation needs CompanyDefaults (shop client, wage rate)
+    - Job creation needs CompanyDefaults (shop company, wage rate)
     - XeroPayItem (Ordinary Time) must exist for time entries
 
     Provides ``self.test_staff`` — a generic Staff created once per TestCase
diff --git a/apps/timesheet/management/commands/create_special_job.py b/apps/timesheet/management/commands/create_special_job.py
index 5d1224264..9d9c8c1d9 100644
--- a/apps/timesheet/management/commands/create_special_job.py
+++ b/apps/timesheet/management/commands/create_special_job.py
@@ -44,9 +44,9 @@ def handle(self, *args, **options):
         if Job.objects.filter(name=name).exists():
             raise CommandError(f"Job '{name}' already exists")
 
-        # Resolve shop client from CompanyDefaults
+        # Resolve shop company from CompanyDefaults
         defaults = CompanyDefaults.get_solo()
-        client = defaults.shop_client
+        company = defaults.shop_company
 
         # Resolve pay item
         pay_item = XeroPayItem.objects.filter(
@@ -58,7 +58,7 @@ def handle(self, *args, **options):
         if options["dry_run"]:
             self.stdout.write(self.style.WARNING("DRY RUN — no changes made:"))
             self.stdout.write(f"  Job: '{name}' (status=special)")
-            self.stdout.write(f"  Client: {client.name}")
+            self.stdout.write(f"  Company: {company.name}")
             self.stdout.write(
                 f"  Default pay item: {pay_item.name} ({pay_item.multiplier}x)"
             )
@@ -69,7 +69,7 @@ def handle(self, *args, **options):
             job = Job(
                 name=name,
                 status="special",
-                client=client,
+                company=company,
                 contact=None,
                 pricing_methodology="time_materials",
                 speed_quality_tradeoff="normal",
diff --git a/apps/timesheet/serializers/daily_timesheet_serializers.py b/apps/timesheet/serializers/daily_timesheet_serializers.py
index efc18c251..d03c519b0 100644
--- a/apps/timesheet/serializers/daily_timesheet_serializers.py
+++ b/apps/timesheet/serializers/daily_timesheet_serializers.py
@@ -13,7 +13,7 @@ class JobBreakdownSerializer(serializers.Serializer):
     job_id = serializers.CharField()
     job_number = serializers.IntegerField()
     job_name = serializers.CharField()
-    client = serializers.CharField()
+    company = serializers.CharField()
     hours = serializers.FloatField()
     revenue = serializers.FloatField()
     cost = serializers.FloatField()
diff --git a/apps/timesheet/serializers/modern_timesheet_serializers.py b/apps/timesheet/serializers/modern_timesheet_serializers.py
index 96d7bbecb..6d8a1655d 100644
--- a/apps/timesheet/serializers/modern_timesheet_serializers.py
+++ b/apps/timesheet/serializers/modern_timesheet_serializers.py
@@ -19,8 +19,8 @@
 class ModernTimesheetJobSerializer(serializers.ModelSerializer):
     """Serializer for jobs in timesheet context using modern CostSet system"""
 
-    client_name = serializers.CharField(
-        source="client.name", read_only=True, required=False, allow_null=True
+    company_name = serializers.CharField(
+        source="company.name", read_only=True, required=False, allow_null=True
     )
     labour_rates = JobLabourRateSerializer(many=True, read_only=True)
     has_actual_costset = serializers.SerializerMethodField()
@@ -43,7 +43,7 @@ class Meta:
             "id",
             "job_number",
             "name",
-            "client_name",
+            "company_name",
             "status",
             "labour_rates",
             "has_actual_costset",
@@ -228,7 +228,7 @@ class WorkshopTimesheetEntrySerializer(serializers.Serializer):
     job_id = serializers.UUIDField(read_only=True)
     job_number = serializers.IntegerField(read_only=True)
     job_name = serializers.CharField(read_only=True)
-    client_name = serializers.CharField(read_only=True, allow_blank=True)
+    company_name = serializers.CharField(read_only=True, allow_blank=True)
     description = serializers.CharField(read_only=True, allow_blank=True)
     hours = serializers.DecimalField(
         max_digits=7, decimal_places=2, read_only=True, source="quantity"
@@ -273,7 +273,7 @@ def to_representation(self, instance):
             "job_id": str(job.id) if job else None,
             "job_number": job.job_number if job else None,
             "job_name": job.name if job else "",
-            "client_name": job.client.name if job and job.client else "",
+            "company_name": job.company.name if job and job.company else "",
             "description": instance.desc or "",
             "hours": float(instance.quantity),
             "accounting_date": instance.accounting_date,
diff --git a/apps/timesheet/services/daily_timesheet_service.py b/apps/timesheet/services/daily_timesheet_service.py
index 26cc522d2..4caea5655 100644
--- a/apps/timesheet/services/daily_timesheet_service.py
+++ b/apps/timesheet/services/daily_timesheet_service.py
@@ -105,7 +105,7 @@ def _get_staff_timesheet_data(
                 kind="time",
                 staff=staff,
                 accounting_date=target_date,
-            ).select_related("cost_set__job__client")
+            ).select_related("cost_set__job__company")
 
             logger.debug(f"Found {len(cost_lines)} cost lines for staff {staff.id}")
 
@@ -239,7 +239,7 @@ def _get_job_breakdown(cls, cost_lines) -> List[Dict]:
                         "job_id": job_id_str,
                         "job_number": job_number,
                         "job_name": job_name,
-                        "client": job.client.name if job.client else "",
+                        "company": job.company.name if job.company else "",
                         "price_cap": job.price_cap,
                         "hours": Decimal("0.0"),
                         "revenue": Decimal("0.0"),
diff --git a/apps/timesheet/tests/test_daily_timesheet_service.py b/apps/timesheet/tests/test_daily_timesheet_service.py
index 78a0a99ee..0d2d1c5b8 100644
--- a/apps/timesheet/tests/test_daily_timesheet_service.py
+++ b/apps/timesheet/tests/test_daily_timesheet_service.py
@@ -5,7 +5,7 @@
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, LabourSubtype
 from apps.testing import BaseTestCase
 from apps.timesheet.services.daily_timesheet_service import DailyTimesheetService
@@ -16,8 +16,8 @@ class DailyTimesheetServiceTests(BaseTestCase):
     def setUp(self):
         super().setUp()
         self.target_date = date(2026, 5, 22)
-        self.client = Client.objects.create(
-            name="Daily Timesheet Client",
+        self.company = Company.objects.create(
+            name="Daily Timesheet Company",
             email="daily-timesheet@example.com",
             xero_last_modified=timezone.now(),
         )
@@ -25,7 +25,7 @@ def setUp(self):
         self.job = Job.objects.create(
             job_number=98766,
             name="Daily Timesheet Job",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.pay_item,
             staff=self.test_staff,
         )
@@ -50,16 +50,16 @@ def setUp(self):
             entry_seq=1,
         )
 
-    def _create_job(self, *, job_number: int, client_name: str) -> Job:
-        client = Client.objects.create(
-            name=client_name,
+    def _create_job(self, *, job_number: int, company_name: str) -> Job:
+        company = Company.objects.create(
+            name=company_name,
             email=f"{job_number}@example.com",
             xero_last_modified=timezone.now(),
         )
         job = Job.objects.create(
             job_number=job_number,
             name=f"Daily Timesheet Job {job_number}",
-            client=client,
+            company=company,
             default_xero_pay_item=self.pay_item,
             staff=self.test_staff,
         )
@@ -88,10 +88,10 @@ def _create_time_line(self, job: Job, *, hours: str, entry_seq: int) -> CostLine
         )
 
     def test_staff_timesheet_data_does_not_lazy_load_job_breakdown_relations(self):
-        """Catches N+1 DB access while daily timesheets serialize job/client data."""
+        """Catches N+1 DB access while daily timesheets serialize job/company data."""
         other_job = self._create_job(
             job_number=98767,
-            client_name="Second Daily Timesheet Client",
+            company_name="Second Daily Timesheet Company",
         )
         self._create_time_line(other_job, hours="3.000", entry_seq=2)
 
@@ -105,14 +105,14 @@ def test_staff_timesheet_data_does_not_lazy_load_job_breakdown_relations(self):
             for query in captured
             if 'FROM "job_costset"' in query["sql"]
             or 'FROM "job_job"' in query["sql"]
-            or 'FROM "client_client"' in query["sql"]
+            or 'FROM "company_company"' in query["sql"]
         ]
 
         self.assertEqual(direct_relation_queries, [])
         self.assertEqual(
-            [(row["client"], row["hours"]) for row in staff_data["job_breakdown"]],
+            [(row["company"], row["hours"]) for row in staff_data["job_breakdown"]],
             [
-                ("Second Daily Timesheet Client", 3.0),
-                ("Daily Timesheet Client", 2.0),
+                ("Second Daily Timesheet Company", 3.0),
+                ("Daily Timesheet Company", 2.0),
             ],
         )
diff --git a/apps/timesheet/tests/test_jobs_api_filter.py b/apps/timesheet/tests/test_jobs_api_filter.py
index 4de3c14ad..1b2c43c65 100644
--- a/apps/timesheet/tests/test_jobs_api_filter.py
+++ b/apps/timesheet/tests/test_jobs_api_filter.py
@@ -11,7 +11,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.testing import BaseTestCase
 
@@ -30,8 +30,8 @@ def setUp(self) -> None:
             is_office_staff=True,
         )
         self.api.force_authenticate(user=self.superuser)
-        self.test_client = Client.objects.create(
-            name="Test Client",
+        self.test_client = Company.objects.create(
+            name="Test Company",
             email="test@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
@@ -46,7 +46,7 @@ def _make_job(
         # Job.save() auto-generates job_number, so we can't set it here.
         job = Job.objects.create(
             name=f"Job {status} {pricing_methodology}",
-            client=self.test_client,
+            company=self.test_client,
             status=status,
             pricing_methodology=pricing_methodology,
             staff=self.test_staff,
diff --git a/apps/timesheet/tests/test_weekly_timesheet_service.py b/apps/timesheet/tests/test_weekly_timesheet_service.py
index 514e79f3f..ef0600c03 100644
--- a/apps/timesheet/tests/test_weekly_timesheet_service.py
+++ b/apps/timesheet/tests/test_weekly_timesheet_service.py
@@ -4,7 +4,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, Job, LabourSubtype
 from apps.testing import BaseTestCase
 from apps.timesheet.services.weekly_timesheet_service import WeeklyTimesheetService
@@ -32,8 +32,8 @@ def setUp(self):
         Staff.objects.filter(pk=self.staff.pk).update(
             date_joined=timezone.make_aware(datetime(2025, 1, 1))
         )
-        self.client = Client.objects.create(
-            name="Cost Test Client",
+        self.company = Company.objects.create(
+            name="Cost Test Company",
             email="cost-test@example.com",
             xero_last_modified="2024-01-01T00:00:00Z",
         )
@@ -41,7 +41,7 @@ def setUp(self):
         self.job = Job.objects.create(
             job_number=98765,
             name="Weekly Cost Test",
-            client=self.client,
+            company=self.company,
             default_xero_pay_item=self.pay_item,
             staff=self.test_staff,
         )
diff --git a/apps/timesheet/views/api.py b/apps/timesheet/views/api.py
index 245b6686d..789836806 100644
--- a/apps/timesheet/views/api.py
+++ b/apps/timesheet/views/api.py
@@ -21,7 +21,7 @@
 
 from apps.accounts.models import Staff
 from apps.accounts.utils import get_displayable_staff
-from apps.client.serializers import ClientErrorResponseSerializer
+from apps.company.serializers import CompanyErrorResponseSerializer
 from apps.job.models import Job
 from apps.job.models.costing import CostLine
 from apps.timesheet.serializers import (
@@ -216,7 +216,7 @@ def get(self, request):
                     )
                 )
                 .select_related(
-                    "client",
+                    "company",
                     "default_xero_pay_item",
                     "latest_actual",
                     "latest_estimate",
@@ -321,8 +321,8 @@ class WeeklyTimesheetAPIView(TimesheetResponseMixin, TimesheetBaseView):
         ],
         responses={
             200: WeeklyTimesheetDataSerializer,
-            400: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
     )
     def get(self, request):
@@ -340,9 +340,9 @@ class CreatePayRunAPIView(TimesheetBaseView):
         request=CreatePayRunSerializer,
         responses={
             201: CreatePayRunResponseSerializer,
-            400: ClientErrorResponseSerializer,
-            409: ClientErrorResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            400: CompanyErrorResponseSerializer,
+            409: CompanyErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
     )
     def post(self, request):
@@ -421,7 +421,7 @@ def post(self, request):
             )
 
         except ValueError as exc:
-            # Client errors (bad date, not Monday)
+            # Company errors (bad date, not Monday)
             return Response({"error": str(exc)}, status=status.HTTP_400_BAD_REQUEST)
         except Exception as exc:
             error_msg = str(exc)
@@ -443,7 +443,7 @@ class PayRunListAPIView(TimesheetBaseView):
         summary="List pay runs",
         responses={
             200: PayRunListResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
     )
     def get(self, request):
@@ -484,7 +484,7 @@ class RefreshPayRunsAPIView(TimesheetBaseView):
         request=None,
         responses={
             200: PayRunSyncResponseSerializer,
-            500: ClientErrorResponseSerializer,
+            500: CompanyErrorResponseSerializer,
         },
     )
     def post(self, request):
@@ -523,7 +523,7 @@ class PostWeekToXeroPayrollAPIView(TimesheetBaseView):
         request=PostWeekToXeroSerializer,
         responses={
             200: PostWeekToXeroStartResponseSerializer,
-            400: ClientErrorResponseSerializer,
+            400: CompanyErrorResponseSerializer,
         },
     )
     def post(self, request):
diff --git a/apps/workflow/accounting/provider.py b/apps/workflow/accounting/provider.py
index 8a25ef0bb..77efd0469 100644
--- a/apps/workflow/accounting/provider.py
+++ b/apps/workflow/accounting/provider.py
@@ -8,7 +8,7 @@
 from typing import TYPE_CHECKING, Protocol
 
 if TYPE_CHECKING:
-    from apps.client.models import Client
+    from apps.company.models import Company
     from apps.job.models import Job
 
     from .types import (
@@ -61,11 +61,11 @@ def disconnect(self) -> None:
 
     # --- Contacts/Clients ---
 
-    def create_contact(self, client: Client) -> ContactResult:
-        """Create a contact in the accounting system from a local Client."""
+    def create_contact(self, company: Company) -> ContactResult:
+        """Create a contact in the accounting system from a local Company."""
         ...
 
-    def update_contact(self, client: Client) -> ContactResult:
+    def update_contact(self, company: Company) -> ContactResult:
         """Update an existing contact in the accounting system."""
         ...
 
diff --git a/apps/workflow/accounting/types.py b/apps/workflow/accounting/types.py
index 8a844d4d1..e872706d3 100644
--- a/apps/workflow/accounting/types.py
+++ b/apps/workflow/accounting/types.py
@@ -22,7 +22,7 @@ class InvoicePayload:
     """Data needed to create an invoice in any accounting system."""
 
     client_external_id: str
-    client_name: str
+    company_name: str
     line_items: list[DocumentLineItem]
     date: date
     due_date: date
@@ -38,7 +38,7 @@ class QuotePayload:
     """Data needed to create a quote in any accounting system."""
 
     client_external_id: str
-    client_name: str
+    company_name: str
     line_items: list[DocumentLineItem]
     date: date
     expiry_date: date
diff --git a/apps/workflow/accounting/xero/provider.py b/apps/workflow/accounting/xero/provider.py
index 8137553ba..f63237356 100644
--- a/apps/workflow/accounting/xero/provider.py
+++ b/apps/workflow/accounting/xero/provider.py
@@ -11,7 +11,7 @@
 from apps.workflow.services.error_persistence import persist_app_error
 
 if TYPE_CHECKING:
-    from apps.client.models import Client
+    from apps.company.models import Company
     from apps.job.models import Job
     from apps.workflow.accounting.types import (
         ContactResult,
@@ -125,31 +125,31 @@ def disconnect(self) -> None:
 
     # --- Contacts ---
 
-    def create_contact(self, client: Client) -> ContactResult:
+    def create_contact(self, company: Company) -> ContactResult:
         from apps.workflow.accounting.types import ContactResult
-        from apps.workflow.api.xero.push import create_client_contact_in_xero
+        from apps.workflow.api.xero.push import create_company_contact_in_xero
 
         try:
-            xero_contact_id = create_client_contact_in_xero(client)
+            xero_contact_id = create_company_contact_in_xero(company)
             return ContactResult(
                 success=True,
                 external_id=xero_contact_id,
-                name=client.name,
+                name=company.name,
             )
         except Exception as exc:
             persist_app_error(exc)
             return ContactResult(success=False, error=str(exc))
 
-    def update_contact(self, client: Client) -> ContactResult:
+    def update_contact(self, company: Company) -> ContactResult:
         from apps.workflow.accounting.types import ContactResult
-        from apps.workflow.api.xero.push import sync_client_to_xero
+        from apps.workflow.api.xero.push import sync_company_to_xero
 
         try:
-            sync_client_to_xero(client)
+            sync_company_to_xero(company)
             return ContactResult(
                 success=True,
-                external_id=client.xero_contact_id,
-                name=client.name,
+                external_id=company.xero_contact_id,
+                name=company.name,
             )
         except Exception as exc:
             persist_app_error(exc)
@@ -182,7 +182,7 @@ def create_invoice(self, payload: InvoicePayload) -> DocumentResult:
                 type="ACCREC",
                 contact=Contact(
                     contact_id=payload.client_external_id,
-                    name=payload.client_name,
+                    name=payload.company_name,
                 ),
                 line_items=self._build_line_items(payload.line_items),
                 date=payload.date.isoformat(),
@@ -253,7 +253,7 @@ def create_quote(self, payload: QuotePayload) -> DocumentResult:
             xero_quote = Quote(
                 contact=Contact(
                     contact_id=payload.client_external_id,
-                    name=payload.client_name,
+                    name=payload.company_name,
                 ),
                 line_items=self._build_line_items(payload.line_items),
                 date=payload.date.isoformat(),
diff --git a/apps/workflow/api/reports/job_movement.py b/apps/workflow/api/reports/job_movement.py
index 8f48a7992..9e72115f5 100644
--- a/apps/workflow/api/reports/job_movement.py
+++ b/apps/workflow/api/reports/job_movement.py
@@ -47,7 +47,7 @@ def get_draft_jobs_created(self, start_date, end_date):
         """
         return Job.objects.filter(
             created_at__gte=start_date, created_at__lte=end_date
-        ).select_related("client", "created_by")
+        ).select_related("company", "created_by")
 
     def get_quotes_submitted(self, start_date, end_date):
         """
@@ -195,7 +195,7 @@ def serialize_job_list(self, jobs):
                 "id": str(job.id),
                 "job_number": job.job_number,
                 "name": job.name,
-                "client_name": job.client.name if job.client else None,
+                "company_name": job.company.name if job.company else None,
                 "status": job.status,
                 "status_display": job.get_status_display(),
                 "created_at": job.created_at.isoformat(),
@@ -216,7 +216,7 @@ def serialize_event_list(self, events):
                 "job_id": str(event.job.id),
                 "job_number": event.job.job_number,
                 "job_name": event.job.name,
-                "client_name": event.job.client.name if event.job.client else None,
+                "company_name": event.job.company.name if event.job.company else None,
                 "timestamp": event.timestamp.isoformat(),
                 "current_status": event.job.status,
                 "current_status_display": event.job.get_status_display(),
diff --git a/apps/workflow/api/xero/__init__.py b/apps/workflow/api/xero/__init__.py
index 39e132d53..4b1935ef1 100644
--- a/apps/workflow/api/xero/__init__.py
+++ b/apps/workflow/api/xero/__init__.py
@@ -58,11 +58,11 @@
         )
         from .push import (
             bulk_create_contacts_in_xero,
-            create_client_contact_in_xero,
+            create_company_contact_in_xero,
             get_all_xero_contacts,
             map_costline_to_expense_entry,
             map_costline_to_time_entry,
-            sync_client_to_xero,
+            sync_company_to_xero,
             sync_costlines_to_xero,
             sync_expense_entries_bulk,
             sync_job_to_xero,
@@ -71,16 +71,16 @@
         from .reprocess_xero import (
             reprocess_all,
             reprocess_bills,
-            reprocess_clients,
+            reprocess_companies,
             reprocess_credit_notes,
             reprocess_invoices,
-            set_client_fields,
+            set_company_fields,
             set_invoice_or_bill_fields,
             sync_xero_phone_methods,
         )
         from .seed import (
             fetch_xero_entity_lookup,
-            seed_clients_to_xero,
+            seed_companies_to_xero,
             seed_jobs_to_xero,
             sync_single_contact,
             sync_single_invoice,
@@ -111,13 +111,13 @@
         )
         from .transforms import (
             clean_json,
-            get_or_fetch_client,
+            get_or_fetch_company,
             process_xero_data,
-            resolve_client_from_xero_contact,
+            resolve_company_from_xero_contact,
             serialize_xero_object,
             sync_accounts,
-            sync_client_from_xero_contact,
-            sync_clients,
+            sync_companies,
+            sync_company_from_xero_contact,
             sync_entities,
             transform_bill,
             transform_credit_note,
@@ -152,7 +152,7 @@
     "bind_token_callbacks",
     "bulk_create_contacts_in_xero",
     "clean_json",
-    "create_client_contact_in_xero",
+    "create_company_contact_in_xero",
     "create_default_task",
     "create_employee_leave",
     "create_expense_entries",
@@ -183,7 +183,7 @@
     "get_last_modified_time",
     "get_leave_type_id_by_name",
     "get_leave_types",
-    "get_or_fetch_client",
+    "get_or_fetch_company",
     "get_pay_run",
     "get_pay_runs",
     "get_pay_runs_for_sync",
@@ -212,22 +212,22 @@
     "refresh_token",
     "reprocess_all",
     "reprocess_bills",
-    "reprocess_clients",
+    "reprocess_companies",
     "reprocess_credit_notes",
     "reprocess_invoices",
-    "resolve_client_from_xero_contact",
-    "seed_clients_to_xero",
+    "resolve_company_from_xero_contact",
+    "seed_companies_to_xero",
     "seed_jobs_to_xero",
     "serialize_xero_object",
-    "set_client_fields",
+    "set_company_fields",
     "set_invoice_or_bill_fields",
     "swap_active",
     "sync_accounts",
     "sync_all_local_stock_to_xero",
     "sync_all_xero_data",
-    "sync_client_from_xero_contact",
-    "sync_client_to_xero",
-    "sync_clients",
+    "sync_companies",
+    "sync_company_from_xero_contact",
+    "sync_company_to_xero",
     "sync_costlines_to_xero",
     "sync_entities",
     "sync_expense_entries_bulk",
diff --git a/apps/workflow/api/xero/push.py b/apps/workflow/api/xero/push.py
index e7817097e..0df6d6700 100644
--- a/apps/workflow/api/xero/push.py
+++ b/apps/workflow/api/xero/push.py
@@ -23,36 +23,36 @@
 SLEEP_TIME = 1  # Sleep after every API call to avoid hitting rate limits
 
 
-def sync_client_to_xero(client):
-    """Push a client to Xero"""
-    if not client.validate_for_xero():
-        logger.error(f"Client {client.id} failed validation")
+def sync_company_to_xero(company):
+    """Push a company to Xero"""
+    if not company.validate_for_xero():
+        logger.error(f"Company {company.id} failed validation")
         return False
 
     accounting_api = AccountingApi(api_client)
-    contact_data = client.get_client_for_xero()
+    contact_data = company.get_company_for_xero()
 
     if not contact_data:
-        logger.error(f"Client {client.id} failed to generate Xero data")
+        logger.error(f"Company {company.id} failed to generate Xero data")
         return False
 
-    if client.xero_contact_id:
+    if company.xero_contact_id:
         response = accounting_api.update_contact(
             get_tenant_id(),
-            contact_id=client.xero_contact_id,
+            contact_id=company.xero_contact_id,
             contacts={"contacts": [contact_data]},
         )
         time.sleep(SLEEP_TIME)
-        logger.info(f"Updated client {client.name} in Xero")
+        logger.info(f"Updated company {company.name} in Xero")
     else:
         response = accounting_api.create_contacts(
             get_tenant_id(), contacts={"contacts": [contact_data]}
         )
         time.sleep(SLEEP_TIME)
-        client.xero_contact_id = response.contacts[0].contact_id
-        client.save()
+        company.xero_contact_id = response.contacts[0].contact_id
+        company.save()
         logger.info(
-            f"Created client {client.name} in Xero with ID {client.xero_contact_id}"
+            f"Created company {company.name} in Xero with ID {company.xero_contact_id}"
         )
 
     return True
@@ -60,7 +60,7 @@ def sync_client_to_xero(client):
 
 def sync_job_to_xero(job):
     """Push a job to Xero Projects API"""
-    from apps.workflow.api.xero.transforms import get_or_fetch_client
+    from apps.workflow.api.xero.transforms import get_or_fetch_company
 
     if not settings.XERO_SYNC_PROJECTS:
         logger.info(
@@ -72,25 +72,25 @@ def sync_job_to_xero(job):
     logger.info(f"Syncing Job {job.job_number} ({job.name}) to Xero")
 
     # Validation
-    if not job.client:
-        logger.error(f"Job {job.job_number} has no client - cannot sync to Xero")
+    if not job.company:
+        logger.error(f"Job {job.job_number} has no company - cannot sync to Xero")
         return False
 
-    if not job.client.xero_contact_id:
+    if not job.company.xero_contact_id:
         logger.error(
-            f"Job {job.job_number} client '{job.client.name}' has no xero_contact_id - sync client first"
+            f"Job {job.job_number} company '{job.company.name}' has no xero_contact_id - sync company first"
         )
         return False
 
     # Validate contact exists in Xero - fail early
     try:
-        valid_client = get_or_fetch_client(
-            job.client.xero_contact_id, f"job {job.job_number}"
+        valid_client = get_or_fetch_company(
+            job.company.xero_contact_id, f"job {job.job_number}"
         )
-        logger.info(f"Validated client exists in Xero: {valid_client.name}")
+        logger.info(f"Validated company exists in Xero: {valid_client.name}")
     except Exception as e:
         logger.error(
-            f"Job {job.job_number} client contact_id {job.client.xero_contact_id} does not exist in Xero: {e}"
+            f"Job {job.job_number} company contact_id {job.company.xero_contact_id} does not exist in Xero: {e}"
         )
         return False
 
@@ -104,7 +104,7 @@ def sync_job_to_xero(job):
     )
     project_data = {
         "name": project_name,
-        "contact_id": job.client.xero_contact_id,
+        "contact_id": job.company.xero_contact_id,
     }
 
     # Add optional fields (correct field names per SDK) - defensive programming
@@ -452,16 +452,16 @@ def get_all_xero_contacts():
     return all_contacts
 
 
-def create_client_contact_in_xero(client):
-    """Create a single client as Xero contact. Returns xero_contact_id on success, raises on failure."""
-    if not client.validate_for_xero():
-        raise ValueError(f"Client {client.id} failed Xero validation")
+def create_company_contact_in_xero(company):
+    """Create a single company as Xero contact. Returns xero_contact_id on success, raises on failure."""
+    if not company.validate_for_xero():
+        raise ValueError(f"Company {company.id} failed Xero validation")
 
     accounting_api = AccountingApi(api_client)
-    contact_data = client.get_client_for_xero()
+    contact_data = company.get_company_for_xero()
 
     if not contact_data:
-        raise ValueError(f"Client {client.id} failed to generate Xero data")
+        raise ValueError(f"Company {company.id} failed to generate Xero data")
 
     response = accounting_api.create_contacts(
         get_tenant_id(), contacts={"contacts": [contact_data]}
@@ -470,16 +470,16 @@ def create_client_contact_in_xero(client):
 
     if not response or not response.contacts:
         raise ValueError(
-            f"Xero API returned empty response when creating contact for client {client.id}"
+            f"Xero API returned empty response when creating contact for company {company.id}"
         )
 
-    client.xero_contact_id = str(response.contacts[0].contact_id)
-    client.save(update_fields=["xero_contact_id"])
-    return client.xero_contact_id
+    company.xero_contact_id = str(response.contacts[0].contact_id)
+    company.save(update_fields=["xero_contact_id"])
+    return company.xero_contact_id
 
 
 def bulk_create_contacts_in_xero(clients_to_create, batch_size=50):
-    """Create multiple client contacts in Xero in batches of 50"""
+    """Create multiple company contacts in Xero in batches of 50"""
     if not clients_to_create:
         return 0
 
@@ -491,18 +491,18 @@ def bulk_create_contacts_in_xero(clients_to_create, batch_size=50):
         batch = clients_to_create[i : i + batch_size]
 
         contact_batch = []
-        for client in batch:
-            if not client.validate_for_xero():
-                logger.error(f"Client {client.name} failed Xero validation")
+        for company in batch:
+            if not company.validate_for_xero():
+                logger.error(f"Company {company.name} failed Xero validation")
                 raise ValueError(
-                    f"Client {client.name} failed Xero validation"
+                    f"Company {company.name} failed Xero validation"
                 )  # FAIL EARLY
 
-            contact_data = client.get_client_for_xero()
+            contact_data = company.get_company_for_xero()
             if not contact_data:
-                logger.error(f"Client {client.name} failed to generate Xero data")
+                logger.error(f"Company {company.name} failed to generate Xero data")
                 raise ValueError(
-                    f"Client {client.name} failed to generate Xero data"
+                    f"Company {company.name} failed to generate Xero data"
                 )  # FAIL EARLY
 
             contact_batch.append(contact_data)
@@ -529,22 +529,22 @@ def bulk_create_contacts_in_xero(clients_to_create, batch_size=50):
 
             # Map response back to clients by submission order. Verified
             # against dev Xero by scripts/integration/verify_xero_batch_order.py.
-            for idx, (client, created_contact) in enumerate(
+            for idx, (company, created_contact) in enumerate(
                 zip(batch, response.contacts, strict=True)
             ):
-                if created_contact.name != client.name:
+                if created_contact.name != company.name:
                     raise ValueError(
                         f"Xero response order mismatch at position {idx}: "
-                        f"sent {client.name!r} but received "
+                        f"sent {company.name!r} but received "
                         f"{created_contact.name!r}. Re-run "
                         f"scripts/integration/verify_xero_batch_order.py to confirm "
                         f"Xero is still preserving submission order."
                     )
-                client.xero_contact_id = created_contact.contact_id
-                client.save(update_fields=["xero_contact_id"])
+                company.xero_contact_id = created_contact.contact_id
+                company.save(update_fields=["xero_contact_id"])
                 total_created += 1
                 logger.info(
-                    f"Created Xero contact for client {client.name}: {client.xero_contact_id}"
+                    f"Created Xero contact for company {company.name}: {company.xero_contact_id}"
                 )
 
         except Exception as e:
diff --git a/apps/workflow/api/xero/reprocess_xero.py b/apps/workflow/api/xero/reprocess_xero.py
index b026dae03..9b46a397a 100644
--- a/apps/workflow/api/xero/reprocess_xero.py
+++ b/apps/workflow/api/xero/reprocess_xero.py
@@ -16,10 +16,10 @@
     Invoice,
     InvoiceLineItem,
 )
-from apps.client.models import (
-    Client,
+from apps.company.models import (
     ClientContact,
     ClientContactMethod,
+    Company,
     SupplierPickupAddress,
 )
 from apps.crm.tasks import rematch_phone_calls_task
@@ -40,8 +40,8 @@ def _xero_phone_value(phone_entry: Mapping[str, str | None]) -> str:
     return f"{country_code} {area_code} {number}".strip()
 
 
-def sync_xero_phone_methods(client: Client) -> list[str]:
-    """Ensure the client's Xero phone numbers exist as contact methods.
+def sync_xero_phone_methods(company: Company) -> list[str]:
+    """Ensure the company's Xero phone numbers exist as contact methods.
 
     Xero owns the number's existence; the CRM user owns label/is_primary.
     Existing rows are therefore never updated here — only missing numbers are
@@ -50,7 +50,7 @@ def sync_xero_phone_methods(client: Client) -> list[str]:
     Returns the normalized numbers that were newly created, so the caller can
     dispatch a call rematch for them.
     """
-    phones = client.raw_json.get("_phones", []) if client.raw_json else []
+    phones = company.raw_json.get("_phones", []) if company.raw_json else []
     if not isinstance(phones, list):
         return []
 
@@ -62,15 +62,15 @@ def sync_xero_phone_methods(client: Client) -> list[str]:
         normalized = ClientContactMethod.normalize_phone(value)
         if not normalized:
             continue
-        # The "one number, one client" rule is enforced by the grandfathered
+        # The "one number, one company" rule is enforced by the grandfathered
         # ClientContactMethod.save() guard reached via get_or_create below:
         # re-syncing an existing number never saves (nothing to update), while
-        # a genuinely-new cross-client number raises and hard-fails this
-        # client's sync (deliberate — the data must be fixed, not skipped).
+        # a genuinely-new cross-company number raises and hard-fails this
+        # company's sync (deliberate — the data must be fixed, not skipped).
         phone_type = phone_entry.get("_phone_type") or ""
         try:
             _, created = ClientContactMethod.objects.get_or_create(
-                client=client,
+                company=company,
                 contact=None,
                 method_type=ClientContactMethod.MethodType.PHONE,
                 normalized_value=normalized,
@@ -85,7 +85,7 @@ def sync_xero_phone_methods(client: Client) -> list[str]:
             raise
         except ValidationError as exc:
             error = ValidationError(
-                f"Xero phone sync for client '{client.name}' ({client.id}) "
+                f"Xero phone sync for company '{company.name}' ({company.id}) "
                 f"rejected number '{value}' ({normalized}): "
                 f"{'; '.join(exc.messages)}"
             )
@@ -93,7 +93,7 @@ def sync_xero_phone_methods(client: Client) -> list[str]:
                 error,
                 additional_context={
                     "operation": "sync_xero_phone_methods_duplicate_owner",
-                    "client_id": str(client.id),
+                    "client_id": str(company.id),
                     "normalized_number": normalized,
                 },
             )
@@ -169,15 +169,15 @@ def set_invoice_or_bill_fields(document, document_type, new_from_xero=False):
         document.xero_last_modified = document.xero_last_modified or timezone.now()
     document.xero_last_synced = timezone.now()
 
-    # Set or create the client/supplier
+    # Set or create the company/supplier
     contact_data = raw_data.get("_contact", {})
     contact_id = contact_data.get("_contact_id")
-    client = Client.objects.filter(xero_contact_id=contact_id).first()
-    if not client:
+    company = Company.objects.filter(xero_contact_id=contact_id).first()
+    if not company:
         raise ValueError(
-            f"Client not found for {document_type.lower()} {document.number}"
+            f"Company not found for {document_type.lower()} {document.number}"
         )
-    document.client = client
+    document.company = company
 
     document.save()
 
@@ -243,19 +243,24 @@ def set_invoice_or_bill_fields(document, document_type, new_from_xero=False):
         #       f"Total Incl. Tax: {line_item.line_amount_incl_tax}")
 
 
-def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
+def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
     """
-    Set client fields from raw_json.
-    If new_from_xero is True, it means the client was just created from Xero data.
+    Set company fields from raw_json.
+    If new_from_xero is True, it means the company was just created from Xero data.
     """
-    raw_json = client.raw_json
+    raw_json = company.raw_json
     if not raw_json:
-        logger.warning(f"Client {client.id} has no raw_json to process.")
+        logger.warning(f"Company {company.id} has no raw_json to process.")
+        # BUG BUG BUG
+        # Multiple breaches of 'fail early'.  REMOVE.
+        # Do not allow 'or ' with fallbacks
+        # DO not allow # type
+        # Do not continue after logging a warning.  This is a data integrity issue.
         # Ensure essential fields are not None if raw_json is missing
-        client.name = client.name or "Unnamed Client"
-        client.xero_last_modified = client.xero_last_modified or timezone.now()
-        # type ignore: Client.save is still untyped (apps/client/models.py).
-        client.save()  # type: ignore[no-untyped-call]
+        company.name = company.name or "Unnamed Company"
+        company.xero_last_modified = company.xero_last_modified or timezone.now()
+        # type ignore: Company.save is still untyped (apps/company/models.py).
+        company.save()  # type: ignore[no-untyped-call]
         return
 
     # Capture old values for change tracking (only for updates, not new clients)
@@ -270,27 +275,27 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
     ]
     old_values = {}
     if not new_from_xero:
-        old_values = {field: getattr(client, field, None) for field in tracked_fields}
+        old_values = {field: getattr(company, field, None) for field in tracked_fields}
 
-    client.name = raw_json.get("_name", client.name or "Unnamed Client")
+    company.name = raw_json.get("_name", company.name or "Unnamed Company")
     # This is the general email for the contact/company
-    client.email = raw_json.get("_email_address", client.email)
+    company.email = raw_json.get("_email_address", company.email)
 
     # Update xero_contact_id from raw_json if available
     # This ensures the link to the Xero contact is maintained or established.
     xero_contact_id_from_json = raw_json.get("_contact_id")
     if xero_contact_id_from_json:
-        client.xero_contact_id = xero_contact_id_from_json
+        company.xero_contact_id = xero_contact_id_from_json
 
     # Check for archived/merged status from raw_json
     contact_status = raw_json.get("_contact_status", "ACTIVE")
     if contact_status == "ARCHIVED":
-        client.xero_archived = True
-        client.allow_jobs = False
+        company.xero_archived = True
+        company.allow_jobs = False
         # FIXME: asymmetric -- un-archiving in Xero does not reset either
         # flag. If a contact is archived then un-archived, `xero_archived`
         # and `allow_jobs` stay in the archived state until an admin toggles
-        # `allow_jobs` back on via the client detail UI. The un-archive
+        # `allow_jobs` back on via the company detail UI. The un-archive
         # path is rare enough that we accepted the asymmetry rather than
         # introduce a "manually set" protection flag. If un-archive becomes
         # common, revisit: (a) auto-reset both flags, which overwrites any
@@ -300,12 +305,14 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
     # Check for merge information
     merged_to_contact_id = raw_json.get("_merged_to_contact_id")
     if merged_to_contact_id:
-        client.xero_merged_into_id = merged_to_contact_id
+        company.xero_merged_into_id = merged_to_contact_id
 
     # Attempt to get address from the 'STREET' address entry if available
     street_address = ""
     if isinstance(raw_json.get("_addresses"), list):
         for address_entry in raw_json.get("_addresses", []):
+            # Bug.  Bare if must only be if <unhappy case>.  Anything else needs else
+            # isinstance looks like it's trying to check a data contract
             if (
                 isinstance(address_entry, dict)
                 and address_entry.get("_address_type") == "STREET"
@@ -324,11 +331,11 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                 ]
                 street_address = ", ".join(filter(None, parts))
                 break  # Found street address
-    client.address = (
-        street_address or client.address
+    company.address = (
+        street_address or company.address
     )  # Use street_address if found, else keep existing or empty
 
-    # Create SupplierPickupAddress from Xero STREET address for any client
+    # Create SupplierPickupAddress from Xero STREET address for any company
     if isinstance(raw_json.get("_addresses"), list):
         for address_entry in raw_json.get("_addresses", []):
             if (
@@ -349,7 +356,7 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                 # Only create if we have both street and city (required fields)
                 if street and city:
                     SupplierPickupAddress.objects.get_or_create(
-                        client=client,
+                        company=company,
                         name="Xero Address",
                         defaults={
                             "street": street,
@@ -362,8 +369,8 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                     )
                 break  # Only process first STREET address
 
-    client.is_account_customer = raw_json.get(
-        "_is_customer", client.is_account_customer
+    company.is_account_customer = raw_json.get(
+        "_is_customer", company.is_account_customer
     )
 
     contact_first_name = raw_json.get("_first_name", None)
@@ -371,21 +378,21 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
 
     match (contact_first_name, contact_last_name):
         case (str() as first, str() as last) if first and last:
-            client.primary_contact_name = f"{first} {last}"
+            company.primary_contact_name = f"{first} {last}"
         case (str() as first, None) if first:
-            client.primary_contact_name = first
+            company.primary_contact_name = first
         case (None, str() as last) if last:
-            client.primary_contact_name = last
+            company.primary_contact_name = last
         case _:
-            client.primary_contact_name = "Unnamed Contact"
+            company.primary_contact_name = "Unnamed Contact"
 
     contact_email = raw_json.get("_email_address", None)
     if contact_email:
-        client.primary_contact_email = contact_email
+        company.primary_contact_email = contact_email
 
     additional_persons = raw_json.get("_contact_persons", [])
     if len(additional_persons) > 0:
-        client.additional_contact_persons = [
+        company.additional_contact_persons = [
             {
                 "name": (person.get("_first_name") or "")
                 + (" " + person.get("_last_name") if person.get("_last_name") else ""),
@@ -403,7 +410,7 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                 # Skip contacts with empty names - they're pointless
                 if not name:
                     logger.debug(
-                        f"Skipping contact with empty name for client {client.name}"
+                        f"Skipping contact with empty name for company {company.name}"
                     )
                     continue
 
@@ -412,7 +419,7 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
 
                 try:
                     contact, created = ClientContact.objects.get_or_create(
-                        client=client,
+                        company=company,
                         name=name,
                         defaults={"email": email},
                     )
@@ -426,8 +433,8 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                     persist_and_raise(
                         exc,
                         additional_context={
-                            "operation": "set_client_fields_duplicate_contact",
-                            "client_id": str(client.id),
+                            "operation": "set_company_fields_duplicate_contact",
+                            "client_id": str(company.id),
                             "contact_name": name,
                         },
                     )
@@ -441,24 +448,24 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
                 # parse_datetime returns None for malformed input instead of
                 # raising; normalize both failure modes into the except arm.
                 raise ValueError(f"unparseable datetime {updated_date_utc_str!r}")
-            client.xero_last_modified = parsed_last_modified
+            company.xero_last_modified = parsed_last_modified
         except ValueError:
             logger.error(
                 f"Could not parse _updated_date_utc: {updated_date_utc_str} "
-                f"for client {client.id}"
+                f"for company {company.id}"
             )
-            client.xero_last_modified = client.xero_last_modified or timezone.now()
+            company.xero_last_modified = company.xero_last_modified or timezone.now()
     else:
-        client.xero_last_modified = client.xero_last_modified or timezone.now()
+        company.xero_last_modified = company.xero_last_modified or timezone.now()
 
-    client.xero_last_synced = timezone.now()
-    # Keep the client write and its phone sync atomic: a cross-client phone
-    # conflict raised by sync_xero_phone_methods must roll back this client's
+    company.xero_last_synced = timezone.now()
+    # Keep the company write and its phone sync atomic: a cross-company phone
+    # conflict raised by sync_xero_phone_methods must roll back this company's
     # field update too, rather than leaving it committed without its numbers.
     with transaction.atomic():
-        # type ignore: Client.save is still untyped (apps/client/models.py).
-        client.save()  # type: ignore[no-untyped-call]
-        created_numbers = sync_xero_phone_methods(client)
+        # type ignore: Company.save is still untyped (apps/company/models.py).
+        company.save()  # type: ignore[no-untyped-call]
+        created_numbers = sync_xero_phone_methods(company)
     if created_numbers:
         # Numbers imported from Xero must rematch historical calls just like
         # UI-edited numbers do. Dispatch after the DB work is committed so the
@@ -467,7 +474,7 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
 
     if new_from_xero:
         logger.info(
-            f"[XERO-WEBHOOK] Client {client.name} (ID: {client.id}) "
+            f"[XERO-WEBHOOK] Company {company.name} (ID: {company.id}) "
             f"created from Xero data."
         )
     else:
@@ -475,18 +482,18 @@ def set_client_fields(client: Client, new_from_xero: bool = False) -> None:
         changes = []
         for field in tracked_fields:
             old_val = old_values.get(field)
-            new_val = getattr(client, field, None)
+            new_val = getattr(company, field, None)
             if old_val != new_val:
                 changes.append(f"{field}: {old_val!r} → {new_val!r}")
 
         if changes:
             logger.info(
-                f"Client {client.name} (ID: {client.id}) updated from Xero data. "
+                f"Company {company.name} (ID: {company.id}) updated from Xero data. "
                 f"Changes: {', '.join(changes)}"
             )
         else:
             logger.info(
-                f"Client {client.name} (ID: {client.id}) synced from Xero (no changes)."
+                f"Company {company.name} (ID: {company.id}) synced from Xero (no changes)."
             )
 
 
@@ -522,21 +529,21 @@ def reprocess_credit_notes():
             )
 
 
-def reprocess_clients():
+def reprocess_companies():
     """Reprocess all existing clients to set fields based on raw JSON."""
-    for client in Client.objects.all():
+    for company in Company.objects.all():
         try:
-            set_client_fields(client)
-            logger.info(f"Reprocessed client: {client.name}")
+            set_company_fields(company)
+            logger.info(f"Reprocessed company: {company.name}")
         except Exception as e:
-            logger.error(f"Error reprocessing client {client.name}: {str(e)}")
+            logger.error(f"Error reprocessing company {company.name}: {str(e)}")
 
 
 def reprocess_all():
     """Reprocesses all data to set fields based on raw JSON."""
     # NOte, we don't have a reprocess accounts because it just feels too weird.
     # If you break accounts, you probably want to handle it manually
-    reprocess_clients()
+    reprocess_companies()
     reprocess_invoices()
     reprocess_bills()
     reprocess_credit_notes()
diff --git a/apps/workflow/api/xero/seed.py b/apps/workflow/api/xero/seed.py
index f9b017970..d1d4408aa 100644
--- a/apps/workflow/api/xero/seed.py
+++ b/apps/workflow/api/xero/seed.py
@@ -6,7 +6,7 @@
 from xero_python.accounting import AccountingApi
 
 from apps.accounting.models import Bill, Invoice
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.workflow.api.xero.auth import api_client, get_tenant_id
 from apps.workflow.api.xero.push import (
     bulk_create_contacts_in_xero,
@@ -14,7 +14,7 @@
     sync_job_to_xero,
 )
 from apps.workflow.api.xero.reprocess_xero import (
-    set_client_fields,
+    set_company_fields,
     set_invoice_or_bill_fields,
 )
 from apps.workflow.api.xero.transforms import process_xero_data, transform_pay_run
@@ -24,7 +24,7 @@
 logger = logging.getLogger("xero")
 
 
-def seed_clients_to_xero(clients):
+def seed_companies_to_xero(clients):
     """Bulk process clients: link existing contacts + create missing ones in batches of 50"""
     # Get all existing Xero contacts (one API call)
     try:
@@ -47,28 +47,28 @@ def seed_clients_to_xero(clients):
     clients_to_link = []
     clients_to_create = []
 
-    for client in clients:
-        candidates = existing_by_name.get(client.name.lower())
+    for company in clients:
+        candidates = existing_by_name.get(company.name.lower())
         if candidates:
-            # Pop one candidate so a second local client with the same name
+            # Pop one candidate so a second local company with the same name
             # doesn't race onto the same xero_contact_id; it falls through
             # to create instead.
             existing_contact_id = candidates.pop(0)
-            clients_to_link.append((client, existing_contact_id))
+            clients_to_link.append((company, existing_contact_id))
         else:
-            clients_to_create.append(client)
+            clients_to_create.append(company)
 
     # Process linking (fast, no API calls)
-    for client, existing_contact_id in clients_to_link:
+    for company, existing_contact_id in clients_to_link:
         try:
-            client.xero_contact_id = existing_contact_id
-            client.save(update_fields=["xero_contact_id"])
+            company.xero_contact_id = existing_contact_id
+            company.save(update_fields=["xero_contact_id"])
             results["linked"] += 1
             logger.info(
-                f"Linked client {client.name} to existing Xero contact: {existing_contact_id}"
+                f"Linked company {company.name} to existing Xero contact: {existing_contact_id}"
             )
         except Exception as e:
-            logger.error(f"Error linking client {client.name}: {e}")
+            logger.error(f"Error linking company {company.name}: {e}")
             raise  # FAIL EARLY
 
     # Process creation in batches using dedicated function.
@@ -124,7 +124,7 @@ def sync_single_contact(sync_service, contact_id):
     contact = response.contacts[0]
     raw_json = process_xero_data(contact)
 
-    client, created = Client.objects.update_or_create(
+    company, created = Company.objects.update_or_create(
         xero_contact_id=contact.contact_id,
         defaults={
             "raw_json": raw_json,
@@ -134,34 +134,34 @@ def sync_single_contact(sync_service, contact_id):
         },
     )
 
-    set_client_fields(client, new_from_xero=created)
+    set_company_fields(company, new_from_xero=created)
 
     # Handle merge if needed — set pointer, then move stranded FK records
-    # onto the terminal client.
-    if client.xero_merged_into_id and not client.merged_into:
-        merged_into = Client.objects.filter(
-            xero_contact_id=client.xero_merged_into_id
+    # onto the terminal company.
+    if company.xero_merged_into_id and not company.merged_into:
+        merged_into = Company.objects.filter(
+            xero_contact_id=company.xero_merged_into_id
         ).first()
         if not merged_into:
             logger.warning(
-                "Deferred merge: client %s points at unsynced "
+                "Deferred merge: company %s points at unsynced "
                 "xero_contact_id=%s; reassignment will retry on next sync",
-                client.id,
-                client.xero_merged_into_id,
+                company.id,
+                company.xero_merged_into_id,
             )
         else:
             from apps.accounts.models import Staff
-            from apps.client.services.client_merge_service import (
-                reassign_client_fk_records,
+            from apps.company.services.company_merge_service import (
+                reassign_company_fk_records,
             )
 
-            client.merged_into = merged_into
-            client.allow_jobs = False
-            client.save()
-            destination = client.get_final_client()
-            if destination.id != client.id:
-                reassign_client_fk_records(
-                    client,
+            company.merged_into = merged_into
+            company.allow_jobs = False
+            company.save()
+            destination = company.get_final_company()
+            if destination.id != company.id:
+                reassign_company_fk_records(
+                    company,
                     destination,
                     Staff.get_automation_user(),
                     logger_prefix="[webhook] ",
diff --git a/apps/workflow/api/xero/sync.py b/apps/workflow/api/xero/sync.py
index 66b9dc553..d614c8ad2 100644
--- a/apps/workflow/api/xero/sync.py
+++ b/apps/workflow/api/xero/sync.py
@@ -11,7 +11,7 @@
 from xero_python.accounting import AccountingApi
 
 from apps.accounting.models import Bill, CreditNote, Invoice, Quote
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.purchasing.models import PurchaseOrder, Stock
 from apps.workflow.api.xero.auth import api_client, get_tenant_id, get_valid_token
 from apps.workflow.api.xero.client import quota_floor_breached
@@ -21,25 +21,25 @@
 )
 from apps.workflow.api.xero.push import (  # noqa: F401
     bulk_create_contacts_in_xero,
-    create_client_contact_in_xero,
+    create_company_contact_in_xero,
     get_all_xero_contacts,
     map_costline_to_expense_entry,
     map_costline_to_time_entry,
-    sync_client_to_xero,
+    sync_company_to_xero,
     sync_costlines_to_xero,
     sync_expense_entries_bulk,
     sync_job_to_xero,
     sync_time_entries_bulk,
 )
 from apps.workflow.api.xero.seed import (  # noqa: F401
-    seed_clients_to_xero,
+    seed_companies_to_xero,
     seed_jobs_to_xero,
     sync_single_contact,
     sync_single_invoice,
     sync_single_pay_run,
 )
 from apps.workflow.api.xero.transforms import process_xero_data  # noqa: F401
-from apps.workflow.api.xero.transforms import sync_clients  # noqa: F401
+from apps.workflow.api.xero.transforms import sync_companies  # noqa: F401
 from apps.workflow.api.xero.transforms import (
     sync_accounts,
     sync_entities,
@@ -343,9 +343,9 @@ def sync_xero_data(
     "contacts": (
         "contacts",
         "contacts",
-        Client,
+        Company,
         "get_contacts",
-        sync_clients,
+        sync_companies,
         {"include_archived": True},
         "page",
     ),
diff --git a/apps/workflow/api/xero/transforms.py b/apps/workflow/api/xero/transforms.py
index 18b74d03d..58851c73e 100644
--- a/apps/workflow/api/xero/transforms.py
+++ b/apps/workflow/api/xero/transforms.py
@@ -9,7 +9,7 @@
 from xero_python.accounting import AccountingApi
 
 from apps.accounting.models import Bill, CreditNote, Invoice, Quote
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine, Stock
 from apps.purchasing.tasks import (
     enqueue_stock_metadata_parse,
@@ -17,7 +17,7 @@
 )
 from apps.workflow.api.xero.auth import api_client, get_tenant_id
 from apps.workflow.api.xero.reprocess_xero import (
-    set_client_fields,
+    set_company_fields,
     set_invoice_or_bill_fields,
 )
 from apps.workflow.exceptions import XeroValidationError
@@ -119,11 +119,11 @@ def process_xero_data(xero_obj):
     return clean_json(serialize_xero_object(xero_obj))
 
 
-def get_or_fetch_client(contact_id, reference=None):
-    """Get client by Xero contact_id, fetching from API if needed"""
-    client = Client.objects.filter(xero_contact_id=contact_id).first()
-    if client:
-        return client.get_final_client()
+def get_or_fetch_company(contact_id, reference=None):
+    """Get company by Xero contact_id, fetching from API if needed"""
+    company = Company.objects.filter(xero_contact_id=contact_id).first()
+    if company:
+        return company.get_final_company()
 
     response = AccountingApi(api_client).get_contacts(
         get_tenant_id(), i_ds=[contact_id], include_archived=True
@@ -131,17 +131,17 @@ def get_or_fetch_client(contact_id, reference=None):
     time.sleep(SLEEP_TIME)
 
     if not response.contacts:
-        raise ValueError(f"Client not found for {reference or contact_id}")
+        raise ValueError(f"Company not found for {reference or contact_id}")
 
-    synced = sync_clients([response.contacts[0]])
+    synced = sync_companies([response.contacts[0]])
     if not synced:
-        raise ValueError(f"Failed to sync client for {reference or contact_id}")
+        raise ValueError(f"Failed to sync company for {reference or contact_id}")
 
-    return synced[0].get_final_client()
+    return synced[0].get_final_company()
 
 
-def sync_client_from_xero_contact(contact, reference=None):
-    """Resolve a local client from embedded Xero contact data.
+def sync_company_from_xero_contact(contact, reference=None):
+    """Resolve a local company from embedded Xero contact data.
 
     Use embedded contact payloads from parent Xero documents first. Only the
     caller decides when the payload is too incomplete and a separate API fetch
@@ -149,33 +149,33 @@ def sync_client_from_xero_contact(contact, reference=None):
     """
     contact_id = getattr(contact, "contact_id", None)
     if not contact_id:
-        raise ValueError(f"Client not found for {reference or 'missing contact'}")
+        raise ValueError(f"Company not found for {reference or 'missing contact'}")
 
-    client = Client.objects.filter(xero_contact_id=contact_id).first()
-    if client:
-        return client.get_final_client()
+    company = Company.objects.filter(xero_contact_id=contact_id).first()
+    if company:
+        return company.get_final_company()
 
-    synced = sync_clients([contact])
+    synced = sync_companies([contact])
     if not synced:
-        raise ValueError(f"Failed to sync client for {reference or contact_id}")
+        raise ValueError(f"Failed to sync company for {reference or contact_id}")
 
-    return synced[0].get_final_client()
+    return synced[0].get_final_company()
 
 
-def resolve_client_from_xero_contact(contact, reference=None):
-    """Resolve a client from embedded contact data, falling back to GET only if absent."""
+def resolve_company_from_xero_contact(contact, reference=None):
+    """Resolve a company from embedded contact data, falling back to GET only if absent."""
     if contact is None:
-        raise ValueError(f"Client not found for {reference or 'missing contact'}")
+        raise ValueError(f"Company not found for {reference or 'missing contact'}")
 
     contact_id = getattr(contact, "contact_id", None)
     if contact_id is None:
-        raise ValueError(f"Client not found for {reference or 'missing contact id'}")
+        raise ValueError(f"Company not found for {reference or 'missing contact id'}")
 
     contact_attrs = getattr(contact, "__dict__", None) or {}
     if len(contact_attrs) > 1:
-        return sync_client_from_xero_contact(contact, reference)
+        return sync_company_from_xero_contact(contact, reference)
 
-    return get_or_fetch_client(contact_id, reference)
+    return get_or_fetch_company(contact_id, reference)
 
 
 def sync_entities(
@@ -259,7 +259,7 @@ def _extract_required_fields_xero(doc_type, xero_obj, xero_id):
         Mapping of required field names to values.
     """
     number = _resolve_document_number(doc_type, xero_obj, xero_id)
-    client = resolve_client_from_xero_contact(
+    company = resolve_company_from_xero_contact(
         getattr(xero_obj, "contact", None), number
     )
     date = getattr(xero_obj, "date", None)
@@ -275,7 +275,7 @@ def _extract_required_fields_xero(doc_type, xero_obj, xero_id):
     raw_json = process_xero_data(xero_obj)
 
     required_fields = {
-        "client": client,
+        "company": company,
         "date": date,
         "number": number,
         "total_excl_tax": total_excl_tax,
@@ -550,7 +550,7 @@ def transform_quote(xero_quote, xero_id):
     Returns:
         The saved Quote model.
     """
-    client = resolve_client_from_xero_contact(
+    company = resolve_company_from_xero_contact(
         getattr(xero_quote, "contact", None), f"quote {xero_id}"
     )
     raw_json = process_xero_data(xero_quote)
@@ -560,7 +560,7 @@ def transform_quote(xero_quote, xero_id):
     validate_required_fields({"status": status}, "quote", xero_id)
 
     defaults = {
-        "client": client,
+        "company": company,
         "date": raw_json.get("_date"),
         "number": getattr(xero_quote, "quote_number", None),
         "status": status,
@@ -595,7 +595,7 @@ def transform_purchase_order(xero_po, xero_id):
         "BILLED": "fully_received",
         "VOIDED": "deleted",
     }
-    supplier = resolve_client_from_xero_contact(
+    supplier = resolve_company_from_xero_contact(
         getattr(xero_po, "contact", None), xero_po.purchase_order_number
     )
 
@@ -868,32 +868,32 @@ def transform_pay_slip(xero_pay_slip, xero_id):
     return pay_slip, _build_sync_status(created, changed_fields)
 
 
-def sync_clients(xero_contacts):
-    """Sync Xero contacts to Client model"""
+def sync_companies(xero_contacts):
+    """Sync Xero contacts to Company model"""
     clients = []
 
     for contact in xero_contacts:
         raw_json = process_xero_data(contact)
 
-        # Check if we already have a client with this xero_contact_id
-        existing_client = Client.objects.filter(
+        # Check if we already have a company with this xero_contact_id
+        existing_client = Company.objects.filter(
             xero_contact_id=contact.contact_id
         ).first()
 
         if existing_client:
             # Already linked - just update with latest Xero data
-            client = existing_client
-            client.raw_json = raw_json
-            client.xero_last_modified = timezone.now()
-            client.xero_archived = contact.contact_status == "ARCHIVED"
-            client.xero_merged_into_id = getattr(contact, "merged_to_contact_id", None)
-            client.save()
+            company = existing_client
+            company.raw_json = raw_json
+            company.xero_last_modified = timezone.now()
+            company.xero_archived = contact.contact_status == "ARCHIVED"
+            company.xero_merged_into_id = getattr(contact, "merged_to_contact_id", None)
+            company.save()
             created = False
         else:
             # Not linked yet - check if name already exists in our database
             contact_name = raw_json.get("_name", "").strip()
             if contact_name:
-                matching_client = Client.objects.filter(name=contact_name).first()
+                matching_client = Company.objects.filter(name=contact_name).first()
 
                 if matching_client:
                     if matching_client.xero_contact_id is None:
@@ -909,22 +909,22 @@ def sync_clients(xero_contacts):
                         )
                         matching_client.save()
                         logger.info(
-                            f"Linked existing client '{contact_name}' (ID: {matching_client.id}) to Xero contact {contact.contact_id}"
+                            f"Linked existing company '{contact_name}' (ID: {matching_client.id}) to Xero contact {contact.contact_id}"
                         )
-                        client = matching_client
+                        company = matching_client
                         created = False
                     else:
                         if contact.contact_status == "ARCHIVED":
-                            # Archived contact with same name as an existing client
+                            # Archived contact with same name as an existing company
                             # linked to a different (active) Xero contact. This
                             # commonly happens when Xero merges contacts — the old
-                            # record is archived. Create a separate archived client.
+                            # record is archived. Create a separate archived company.
                             logger.warning(
                                 f"Archived Xero contact '{contact_name}' ({contact.contact_id}) "
-                                f"has same name as client already linked to {matching_client.xero_contact_id}. "
-                                f"Creating separate archived client record."
+                                f"has same name as company already linked to {matching_client.xero_contact_id}. "
+                                f"Creating separate archived company record."
                             )
-                            client = Client.objects.create(
+                            company = Company.objects.create(
                                 xero_contact_id=contact.contact_id,
                                 raw_json=raw_json,
                                 xero_last_modified=timezone.now(),
@@ -940,8 +940,8 @@ def sync_clients(xero_contacts):
                                 f"Name '{contact_name}' already linked to Xero ID {matching_client.xero_contact_id}, cannot link to {contact.contact_id}"
                             )
                 else:
-                    # No existing client with this name - safe to create new one
-                    client = Client.objects.create(
+                    # No existing company with this name - safe to create new one
+                    company = Company.objects.create(
                         xero_contact_id=contact.contact_id,
                         raw_json=raw_json,
                         xero_last_modified=timezone.now(),
@@ -953,7 +953,7 @@ def sync_clients(xero_contacts):
                     created = True
             else:
                 # No name in contact - create anyway
-                client = Client.objects.create(
+                company = Company.objects.create(
                     xero_contact_id=contact.contact_id,
                     raw_json=raw_json,
                     xero_last_modified=timezone.now(),
@@ -962,34 +962,34 @@ def sync_clients(xero_contacts):
                 )
                 created = True
 
-        set_client_fields(client, new_from_xero=created)
-        clients.append(client)
+        set_company_fields(company, new_from_xero=created)
+        clients.append(company)
 
-    # Resolve merges and move stranded FK records onto the terminal client.
-    from apps.client.services.client_merge_service import reassign_client_fk_records
+    # Resolve merges and move stranded FK records onto the terminal company.
+    from apps.company.services.company_merge_service import reassign_company_fk_records
 
-    for client in clients:
-        if client.xero_merged_into_id and not client.merged_into:
-            merged_into = Client.objects.filter(
-                xero_contact_id=client.xero_merged_into_id
+    for company in clients:
+        if company.xero_merged_into_id and not company.merged_into:
+            merged_into = Company.objects.filter(
+                xero_contact_id=company.xero_merged_into_id
             ).first()
             if not merged_into:
                 logger.warning(
-                    "Deferred merge: client %s points at unsynced "
+                    "Deferred merge: company %s points at unsynced "
                     "xero_contact_id=%s; reassignment will retry next sync",
-                    client.id,
-                    client.xero_merged_into_id,
+                    company.id,
+                    company.xero_merged_into_id,
                 )
                 continue
-            client.merged_into = merged_into
-            client.allow_jobs = False
-            client.save()
-            destination = client.get_final_client()
-            if destination.id != client.id:
+            company.merged_into = merged_into
+            company.allow_jobs = False
+            company.save()
+            destination = company.get_final_company()
+            if destination.id != company.id:
                 from apps.accounts.models import Staff
 
-                reassign_client_fk_records(
-                    client,
+                reassign_company_fk_records(
+                    company,
                     destination,
                     Staff.get_automation_user(),
                     logger_prefix="[batch-sync] ",
diff --git a/apps/workflow/fixtures/company_defaults.json b/apps/workflow/fixtures/company_defaults.json
index 0d6542400..f9880f264 100644
--- a/apps/workflow/fixtures/company_defaults.json
+++ b/apps/workflow/fixtures/company_defaults.json
@@ -1,6 +1,6 @@
 [
   {
-    "model": "client.client",
+    "model": "company.company",
     "pk": "00000000-0000-0000-0000-000000000001",
     "fields": {
       "xero_contact_id": null,
@@ -75,8 +75,8 @@
       "updated_at": "2024-01-01T00:00:00Z",
       "last_xero_sync": null,
       "last_xero_deep_sync": null,
-      "shop_client": "00000000-0000-0000-0000-000000000001",
-      "test_client_name": "ABC Carpet Cleaning TEST IGNORE",
+      "shop_company": "00000000-0000-0000-0000-000000000001",
+      "test_company_name": "ABC Carpet Cleaning TEST IGNORE",
       "kpi_daily_billable_hours_green": "45.00",
       "kpi_daily_billable_hours_amber": "35.00",
       "kpi_daily_gp_target": "1250.00",
diff --git a/apps/workflow/fixtures/company_defaults_prospect.json b/apps/workflow/fixtures/company_defaults_prospect.json
index a81e97c0a..eee5b85d7 100644
--- a/apps/workflow/fixtures/company_defaults_prospect.json
+++ b/apps/workflow/fixtures/company_defaults_prospect.json
@@ -1,6 +1,6 @@
 [
   {
-    "model": "client.client",
+    "model": "company.company",
     "pk": "00000000-0000-0000-0000-000000000001",
     "fields": {
       "xero_contact_id": null,
@@ -75,8 +75,8 @@
       "updated_at": "2024-01-01T00:00:00Z",
       "last_xero_sync": null,
       "last_xero_deep_sync": null,
-      "shop_client": "00000000-0000-0000-0000-000000000001",
-      "test_client_name": "ABC Carpet Cleaning TEST IGNORE",
+      "shop_company": "00000000-0000-0000-0000-000000000001",
+      "test_company_name": "ABC Carpet Cleaning TEST IGNORE",
       "kpi_daily_billable_hours_green": "45.00",
       "kpi_daily_billable_hours_amber": "35.00",
       "kpi_daily_gp_target": "1250.00",
diff --git a/apps/workflow/fixtures/initial_data.json b/apps/workflow/fixtures/initial_data.json
index 4b2e85335..69fae2b95 100644
--- a/apps/workflow/fixtures/initial_data.json
+++ b/apps/workflow/fixtures/initial_data.json
@@ -1,6 +1,6 @@
 [
   {
-    "model": "client.client",
+    "model": "company.company",
     "pk": "00000000-0000-0000-0000-000000000001",
     "fields": {
       "xero_contact_id": null,
diff --git a/apps/workflow/management/commands/e2e_cleanup.py b/apps/workflow/management/commands/e2e_cleanup.py
index 255039dde..20b5bd4f4 100644
--- a/apps/workflow/management/commands/e2e_cleanup.py
+++ b/apps/workflow/management/commands/e2e_cleanup.py
@@ -15,7 +15,7 @@
 from django.db import transaction
 
 from apps.accounting.models import Invoice, Quote
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job, QuoteSpreadsheet
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine
 
@@ -42,11 +42,11 @@ def handle(self, *args, **options):
         # Collect what to delete
         test_jobs = Job.objects.filter(name__startswith=TEST_DATA_PREFIX)
         test_contacts = ClientContact.objects.filter(name__startswith=TEST_DATA_PREFIX)
-        test_clients = Client.objects.filter(name__startswith=TEST_DATA_PREFIX)
-        # Swept so Job.client PROTECT doesn't block the [TEST] client delete.
-        test_prefix_client_jobs = Job.objects.filter(client__in=test_clients)
+        test_clients = Company.objects.filter(name__startswith=TEST_DATA_PREFIX)
+        # Swept so Job.company PROTECT doesn't block the [TEST] company delete.
+        test_prefix_client_jobs = Job.objects.filter(company__in=test_clients)
         test_prefix_client_contacts = ClientContact.objects.filter(
-            client__in=test_clients
+            company__in=test_clients
         )
 
         # Legacy E2E-prefixed clients and their data
@@ -55,14 +55,16 @@ def handle(self, *args, **options):
         legacy_q = Q()
         for prefix in LEGACY_E2E_PREFIXES:
             legacy_q |= Q(name__startswith=prefix)
-        legacy_clients = Client.objects.filter(legacy_q)
-        legacy_client_jobs = Job.objects.filter(client__in=legacy_clients)
-        legacy_client_contacts = ClientContact.objects.filter(client__in=legacy_clients)
+        legacy_clients = Company.objects.filter(legacy_q)
+        legacy_client_jobs = Job.objects.filter(company__in=legacy_clients)
+        legacy_client_contacts = ClientContact.objects.filter(
+            company__in=legacy_clients
+        )
 
-        # Test client data (all jobs/contacts on the test client are test artifacts)
-        test_client_qs = Client.objects.filter(name=TEST_CLIENT_NAME)
-        test_client_jobs = Job.objects.filter(client__in=test_client_qs)
-        test_client_contacts = ClientContact.objects.filter(client__in=test_client_qs)
+        # Test company data (all jobs/contacts on the test company are test artifacts)
+        test_client_qs = Company.objects.filter(name=TEST_CLIENT_NAME)
+        test_client_jobs = Job.objects.filter(company__in=test_client_qs)
+        test_client_contacts = ClientContact.objects.filter(company__in=test_client_qs)
 
         # Report
         self.stdout.write("\n=== E2E Test Data ===\n")
@@ -71,15 +73,15 @@ def handle(self, *args, **options):
         self._report_queryset("[TEST]-prefixed contacts", test_contacts, "name")
         self._report_queryset("[TEST]-prefixed clients", test_clients, "name")
         self._report_queryset("Legacy E2E clients", legacy_clients, "name")
-        self._report_queryset("Legacy E2E client jobs", legacy_client_jobs, "name")
+        self._report_queryset("Legacy E2E company jobs", legacy_client_jobs, "name")
         self._report_queryset(
-            "Legacy E2E client contacts", legacy_client_contacts, "name"
+            "Legacy E2E company contacts", legacy_client_contacts, "name"
         )
         self._report_queryset(
-            f"Jobs on test client ({TEST_CLIENT_NAME})", test_client_jobs, "name"
+            f"Jobs on test company ({TEST_CLIENT_NAME})", test_client_jobs, "name"
         )
         self._report_queryset(
-            f"Contacts on test client ({TEST_CLIENT_NAME})",
+            f"Contacts on test company ({TEST_CLIENT_NAME})",
             test_client_contacts,
             "name",
         )
@@ -203,20 +205,20 @@ def handle(self, *args, **options):
             if count:
                 self.stdout.write(f"  Quote spreadsheets: {count} objects ({details})")
 
-            # 4. Jobs on test client (cascade deletes cost sets, cost lines, etc.)
+            # 4. Jobs on test company (cascade deletes cost sets, cost lines, etc.)
             count, details = test_client_jobs.delete()
-            self.stdout.write(f"  Test client jobs: {count} objects ({details})")
+            self.stdout.write(f"  Test company jobs: {count} objects ({details})")
 
-            # 5. Contacts on test client
+            # 5. Contacts on test company
             count, details = test_client_contacts.delete()
-            self.stdout.write(f"  Test client contacts: {count} objects ({details})")
+            self.stdout.write(f"  Test company contacts: {count} objects ({details})")
 
-            # 6. Legacy client data
+            # 6. Legacy company data
             count, details = legacy_client_jobs.delete()
-            self.stdout.write(f"  Legacy client jobs: {count} objects ({details})")
+            self.stdout.write(f"  Legacy company jobs: {count} objects ({details})")
 
             count, details = legacy_client_contacts.delete()
-            self.stdout.write(f"  Legacy client contacts: {count} objects ({details})")
+            self.stdout.write(f"  Legacy company contacts: {count} objects ({details})")
 
             count, details = legacy_clients.delete()
             self.stdout.write(f"  Legacy clients: {count} objects ({details})")
@@ -228,7 +230,7 @@ def handle(self, *args, **options):
             count, details = test_contacts.delete()
             self.stdout.write(f"  [TEST] contacts: {count} objects ({details})")
 
-            # 8. Jobs/contacts on [TEST]-prefixed clients (unblocks client delete)
+            # 8. Jobs/contacts on [TEST]-prefixed clients (unblocks company delete)
             count, details = test_prefix_client_jobs.delete()
             self.stdout.write(f"  Jobs on [TEST] clients: {count} objects ({details})")
 
diff --git a/apps/workflow/management/commands/relabel_client_app.py b/apps/workflow/management/commands/relabel_client_app.py
new file mode 100644
index 000000000..d52395475
--- /dev/null
+++ b/apps/workflow/management/commands/relabel_client_app.py
@@ -0,0 +1,84 @@
+"""Relabel the historical `client` app to `company` (KAN-278 one-time surgery).
+
+Runs before `migrate` (deploy.sh calls it for every instance). Idempotent:
+keys off django_migrations rows still recorded under the old label.
+
+The historic pre-squash rows (0001_initial .. 0023_drop_scalar_phone_fields)
+are DELETED rather than relabelled: with the squash's `replaces` lists gone,
+a blanket relabel would strand ("company", "0001_initial")-style ghost rows
+that collide with any future company migration reusing one of those names
+and can never be pruned. Only the baseline row carries state worth keeping.
+"""
+
+from django.core.management.base import BaseCommand, CommandError
+from django.db import connection, transaction
+
+TABLE_RENAMES = [
+    ("client_client", "company_client"),
+    ("client_clientcontact", "company_clientcontact"),
+    ("client_clientcontactmethod", "company_clientcontactmethod"),
+    ("client_suppliersearchalias", "company_suppliersearchalias"),
+    ("client_supplierpickupaddress", "company_supplierpickupaddress"),
+]
+
+
+class Command(BaseCommand):
+    help = (
+        "Relabel the 'client' app to 'company' in django_migrations/"
+        "content types/tables."
+    )
+
+    def handle(
+        self,
+        *args: object,  # object: Django's untyped pass-through args; unused here
+        **options: object,  # object: Django's untyped pass-through args; unused here
+    ) -> None:
+        # Atomic so a crash mid-surgery rolls back everything. The idempotence
+        # guard keys off django_migrations, so a half-applied state (UPDATE done,
+        # ALTERs not) must be impossible; Postgres DDL is transactional.
+        with transaction.atomic(), connection.cursor() as cursor:
+            cursor.execute(
+                "SELECT COUNT(*) FROM django_migrations WHERE app = 'client'"
+            )
+            row = cursor.fetchone()
+            if row is None:
+                raise RuntimeError("django_migrations COUNT(*) query returned no row")
+            (stale_rows,) = row
+            if stale_rows == 0:
+                self.stdout.write("Already relabelled; nothing to do.")
+                return
+            cursor.execute(
+                "SELECT COUNT(*) FROM django_migrations "
+                "WHERE app = 'client' AND name = '0001_baseline'"
+            )
+            baseline_row = cursor.fetchone()
+            if baseline_row is None:
+                raise RuntimeError("django_migrations COUNT(*) query returned no row")
+            (baseline_count,) = baseline_row
+            if baseline_count == 0:
+                raise CommandError(
+                    "django_migrations has app='client' rows but no "
+                    "('client', '0001_baseline') row - this database predates "
+                    "the migration squash. Deploy a pre-squash release, run "
+                    "migrate, then retry this deploy."
+                )
+            cursor.execute(
+                "DELETE FROM django_migrations "
+                "WHERE app = 'client' AND name <> '0001_baseline'"
+            )
+            cursor.execute(
+                "UPDATE django_migrations SET app = 'company' WHERE app = 'client'"
+            )
+            cursor.execute(
+                "UPDATE django_content_type SET app_label = 'company' "
+                "WHERE app_label = 'client'"
+            )
+            for old, new in TABLE_RENAMES:
+                cursor.execute(f'ALTER TABLE "{old}" RENAME TO "{new}"')
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Relabelled the client app: dropped {stale_rows - 1} historic "
+                "ledger rows, kept 0001_baseline, renamed content types and "
+                f"{len(TABLE_RENAMES)} tables."
+            )
+        )
diff --git a/apps/workflow/management/commands/seed_xero_from_database.py b/apps/workflow/management/commands/seed_xero_from_database.py
index fc73f68c7..965cdc6a3 100644
--- a/apps/workflow/management/commands/seed_xero_from_database.py
+++ b/apps/workflow/management/commands/seed_xero_from_database.py
@@ -14,7 +14,7 @@
 
 from apps.accounting.models import Invoice, Quote
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.purchasing.models import Stock
 from apps.timesheet.services.payroll_employee_sync import PayrollEmployeeSyncService
@@ -22,7 +22,7 @@
 from apps.workflow.api.xero.payroll import sync_xero_pay_items
 from apps.workflow.api.xero.seed import (
     fetch_xero_entity_lookup,
-    seed_clients_to_xero,
+    seed_companies_to_xero,
     seed_jobs_to_xero,
 )
 from apps.workflow.api.xero.stock_sync import sync_all_local_stock_to_xero
@@ -233,34 +233,34 @@ def process_accounts(self, dry_run):
         return updated + created
 
     def process_contacts(self, dry_run):
-        """Phase 1: Link/Create contacts for all clients with jobs + test client"""
-        # Validate test client exists - required for testing Xero flows
+        """Phase 1: Link/Create contacts for all clients with jobs + test company"""
+        # Validate test company exists - required for testing Xero flows
         cd = CompanyDefaults.get_solo()
-        if not cd.test_client_name:
+        if not cd.test_company_name:
             raise ValueError(
-                "CompanyDefaults.test_client_name is not set. "
+                "CompanyDefaults.test_company_name is not set. "
                 "This is required for Xero sync testing."
             )
-        test_client = Client.objects.filter(name=cd.test_client_name).first()
+        test_client = Company.objects.filter(name=cd.test_company_name).first()
         if not test_client:
             raise ValueError(
-                f"Test client '{cd.test_client_name}' not found in database. "
-                "Ensure the test client is created before running Xero sync."
+                f"Test company '{cd.test_company_name}' not found in database. "
+                "Ensure the test company is created before running Xero sync."
             )
 
         # Find clients with jobs that need xero_contact_id
         client_ids_needing_sync = set(
-            Client.objects.filter(
+            Company.objects.filter(
                 jobs__isnull=False, xero_contact_id__isnull=True
             ).values_list("id", flat=True)
         )
 
-        # Also include test client if it needs syncing
+        # Also include test company if it needs syncing
         if not test_client.xero_contact_id:
             client_ids_needing_sync.add(test_client.id)
-            self.stdout.write(f"Including test client: {cd.test_client_name}")
+            self.stdout.write(f"Including test company: {cd.test_company_name}")
 
-        clients_needing_sync = Client.objects.filter(id__in=client_ids_needing_sync)
+        clients_needing_sync = Company.objects.filter(id__in=client_ids_needing_sync)
 
         self.stdout.write(
             f"Found {clients_needing_sync.count()} clients needing Xero contact IDs"
@@ -271,10 +271,10 @@ def process_contacts(self, dry_run):
             return 0
 
         if dry_run:
-            for client in clients_needing_sync[:10]:  # Show first 10
-                job_count = client.jobs.count()
+            for company in clients_needing_sync[:10]:  # Show first 10
+                job_count = company.jobs.count()
                 self.stdout.write(
-                    f"  • Would process: {client.name} ({job_count} jobs)"
+                    f"  • Would process: {company.name} ({job_count} jobs)"
                 )
             if clients_needing_sync.count() > 10:
                 self.stdout.write(f"  ... and {clients_needing_sync.count() - 10} more")
@@ -282,7 +282,7 @@ def process_contacts(self, dry_run):
 
         # Call sync module for bulk processing
         self.stdout.write("Processing clients with Xero sync module...")
-        results = seed_clients_to_xero(clients_needing_sync)
+        results = seed_companies_to_xero(clients_needing_sync)
 
         # Report results
         self.stdout.write(
@@ -302,7 +302,7 @@ def process_projects(self, dry_run):
         """Phase 2: Create projects for all jobs whose clients have xero_contact_id"""
         # Find jobs that need xero_project_id
         jobs_needing_sync = Job.objects.filter(
-            client__xero_contact_id__isnull=False, xero_project_id__isnull=True
+            company__xero_contact_id__isnull=False, xero_project_id__isnull=True
         )
 
         self.stdout.write(
@@ -318,7 +318,7 @@ def process_projects(self, dry_run):
         if dry_run:
             for job in jobs_needing_sync[:10]:  # Show first 10
                 self.stdout.write(
-                    f"  • Would create project: {job.name} (Client: {job.client.name})"
+                    f"  • Would create project: {job.name} (Company: {job.company.name})"
                 )
             if jobs_needing_sync.count() > 10:
                 self.stdout.write(f"  ... and {jobs_needing_sync.count() - 10} more")
@@ -353,7 +353,7 @@ def process_invoices(self, dry_run):
             if dry_run:
                 for inv in orphaned[:5]:
                     self.stdout.write(
-                        f"  • Would delete: {inv.number} ({inv.client.name})"
+                        f"  • Would delete: {inv.number} ({inv.company.name})"
                     )
                 if orphan_count > 5:
                     self.stdout.write(f"  ... and {orphan_count - 5} more")
@@ -369,7 +369,7 @@ def process_invoices(self, dry_run):
         job_invoices = (
             Invoice.objects.filter(job__isnull=False)
             .exclude(xero_tenant_id=xero_tenant_id)
-            .select_related("job", "client")
+            .select_related("job", "company")
         )
         already_seeded = Invoice.objects.filter(
             job__isnull=False, xero_tenant_id=xero_tenant_id
@@ -385,18 +385,18 @@ def process_invoices(self, dry_run):
         if dry_run:
             for inv in job_invoices[:10]:
                 self.stdout.write(
-                    f"  • Would seed: {inv.number} - {inv.client.name} "
+                    f"  • Would seed: {inv.number} - {inv.company.name} "
                     f"(${inv.total_excl_tax})"
                 )
             if job_invoices.count() > 10:
                 self.stdout.write(f"  ... and {job_invoices.count() - 10} more")
             return result
 
-        # Skip invoices whose client has no xero_contact_id (contacts not seeded)
+        # Skip invoices whose company has no xero_contact_id (contacts not seeded)
         skipped_no_contact = 0
         invoices_to_seed = []
         for inv in job_invoices:
-            if not inv.client.xero_contact_id:
+            if not inv.company.xero_contact_id:
                 skipped_no_contact += 1
                 continue
             invoices_to_seed.append(inv)
@@ -404,7 +404,7 @@ def process_invoices(self, dry_run):
         if skipped_no_contact > 0:
             self.stdout.write(
                 f"Skipping {skipped_no_contact} invoices "
-                f"(client missing xero_contact_id - run contacts first)"
+                f"(company missing xero_contact_id - run contacts first)"
             )
 
         # Fetch existing invoices from Xero to detect interrupted previous runs
@@ -429,7 +429,7 @@ def process_invoices(self, dry_run):
                 )
                 linked += 1
                 self.stdout.write(
-                    f"  ↳ Linked existing: {inv.number} ({inv.client.name})"
+                    f"  ↳ Linked existing: {inv.number} ({inv.company.name})"
                 )
             else:
                 invoices_to_create.append(inv)
@@ -450,8 +450,8 @@ def _build_invoice_payload(self, invoice):
         account_code = XeroAccount.objects.get(account_name="Sales").account_code
 
         contact = XeroContact(
-            contact_id=invoice.client.xero_contact_id,
-            name=invoice.client.name,
+            contact_id=invoice.company.xero_contact_id,
+            name=invoice.company.name,
         )
 
         line_items = []
@@ -562,7 +562,7 @@ def _batch_create_invoices(
                 )
                 created += 1
                 self.stdout.write(
-                    f"    ↳ Seeded: {local_inv.number} ({local_inv.client.name})"
+                    f"    ↳ Seeded: {local_inv.number} ({local_inv.company.name})"
                 )
 
         return created
@@ -592,7 +592,9 @@ def process_quotes(self, dry_run):
         if orphan_count > 0:
             if dry_run:
                 for q in orphaned[:5]:
-                    self.stdout.write(f"  - Would delete: {q.number} ({q.client.name})")
+                    self.stdout.write(
+                        f"  - Would delete: {q.number} ({q.company.name})"
+                    )
                 if orphan_count > 5:
                     self.stdout.write(f"  ... and {orphan_count - 5} more")
             else:
@@ -607,7 +609,7 @@ def process_quotes(self, dry_run):
         job_quotes = (
             Quote.objects.filter(job__isnull=False)
             .exclude(xero_tenant_id=xero_tenant_id)
-            .select_related("job", "client")
+            .select_related("job", "company")
         )
         already_seeded = Quote.objects.filter(
             job__isnull=False, xero_tenant_id=xero_tenant_id
@@ -623,18 +625,18 @@ def process_quotes(self, dry_run):
         if dry_run:
             for q in job_quotes[:10]:
                 self.stdout.write(
-                    f"  - Would seed: {q.number} - {q.client.name} "
+                    f"  - Would seed: {q.number} - {q.company.name} "
                     f"(${q.total_excl_tax})"
                 )
             if job_quotes.count() > 10:
                 self.stdout.write(f"  ... and {job_quotes.count() - 10} more")
             return result
 
-        # Skip quotes whose client has no xero_contact_id (contacts not seeded)
+        # Skip quotes whose company has no xero_contact_id (contacts not seeded)
         skipped_no_contact = 0
         quotes_to_seed = []
         for q in job_quotes:
-            if not q.client.xero_contact_id:
+            if not q.company.xero_contact_id:
                 skipped_no_contact += 1
                 continue
             quotes_to_seed.append(q)
@@ -657,7 +659,7 @@ def process_quotes(self, dry_run):
                 q.xero_tenant_id = xero_tenant_id
                 q.save(update_fields=["xero_id", "xero_tenant_id"])
                 linked += 1
-                self.stdout.write(f"  ↳ Linked existing: {q.number} ({q.client.name})")
+                self.stdout.write(f"  ↳ Linked existing: {q.number} ({q.company.name})")
             else:
                 quotes_to_create.append(q)
 
@@ -677,8 +679,8 @@ def _build_quote_payload(self, quote):
         account_code = XeroAccount.objects.get(account_name="Sales").account_code
 
         contact = XeroContact(
-            contact_id=quote.client.xero_contact_id,
-            name=quote.client.name,
+            contact_id=quote.company.xero_contact_id,
+            name=quote.company.name,
         )
 
         description = f"Job: {quote.job.job_number}"
@@ -756,7 +758,7 @@ def _batch_create_quotes(
                 local_q.save(update_fields=["xero_id", "xero_tenant_id"])
                 created += 1
                 self.stdout.write(
-                    f"    ↳ Seeded: {local_q.number} ({local_q.client.name})"
+                    f"    ↳ Seeded: {local_q.number} ({local_q.company.name})"
                 )
 
         return created
@@ -915,7 +917,7 @@ def process_employees(self, dry_run):
     def clear_production_xero_ids(self, dry_run):
         """Clear production Xero IDs from all relevant tables."""
         # Refuse if the configured DB is a prod instance. The naming
-        # standard `dw_<client>_<env>` (`scripts/server/instance.sh:171`)
+        # standard `dw_<company>_<env>` (`scripts/server/instance.sh:171`)
         # validates env against {dev,uat,staging,prod}, so the `_prod`
         # suffix is a deterministic instance-scoped signal — works on
         # multi-instance servers where `/etc/machine-id` is shared.
@@ -943,17 +945,19 @@ def clear_production_xero_ids(self, dry_run):
         tables_cleared = []
 
         with connection.cursor() as cursor:
-            # Clear client contact IDs - allows re-linking by name
-            self.stdout.write("Clearing client xero_contact_id values...")
-            if self._table_exists(cursor, "client_client"):
+            # Clear company contact IDs - allows re-linking by name
+            self.stdout.write("Clearing company xero_contact_id values...")
+            if self._table_exists(cursor, "company_company"):
                 cursor.execute(
-                    "UPDATE client_client SET xero_contact_id = NULL WHERE xero_contact_id IS NOT NULL"
+                    "UPDATE company_company SET xero_contact_id = NULL WHERE xero_contact_id IS NOT NULL"
                 )
-                client_count = cursor.rowcount
-                if client_count > 0:
-                    tables_cleared.append(f"client_client: {client_count} records")
+                company_count = cursor.rowcount
+                if company_count > 0:
+                    tables_cleared.append(f"company_company: {company_count} records")
             else:
-                self.stdout.write("  WARNING: client_client table not found - skipping")
+                self.stdout.write(
+                    "  WARNING: company_company table not found - skipping"
+                )
 
             # Clear job project IDs - allows fresh project sync
             self.stdout.write("Clearing job xero_project_id values...")
diff --git a/apps/workflow/middleware.py b/apps/workflow/middleware.py
index c4fb6443f..518aabc25 100644
--- a/apps/workflow/middleware.py
+++ b/apps/workflow/middleware.py
@@ -234,8 +234,8 @@ def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
         self.exempt_url_prefixes.append("/api/schema/")
 
     def __call__(self, request: HttpRequest) -> HttpResponse:
-        # Debug logging for client create endpoint
-        if request.path_info == "/api/clients/create/":
+        # Debug logging for company create endpoint
+        if request.path_info == "/api/companies/create/":
             access_logger.info(
                 f"DEBUG LoginRequiredMiddleware: Processing {request.path_info}"
             )
@@ -248,7 +248,7 @@ def __call__(self, request: HttpRequest) -> HttpResponse:
 
         # In DEBUG mode, skip login requirements entirely
         if settings.DEBUG:
-            if request.path_info == "/api/clients/create/":
+            if request.path_info == "/api/companies/create/":
                 access_logger.info(
                     "DEBUG LoginRequiredMiddleware: Skipping due to DEBUG mode"
                 )
@@ -279,7 +279,7 @@ def __call__(self, request: HttpRequest) -> HttpResponse:
             if any(
                 request.path_info.startswith(endpoint) for endpoint in drf_endpoints
             ):
-                if request.path_info == "/api/clients/create/":
+                if request.path_info == "/api/companies/create/":
                     access_logger.info(
                         f"DEBUG LoginRequiredMiddleware: Allowing DRF endpoint {request.path_info}"
                     )
diff --git a/apps/workflow/migrations/0001_baseline.py b/apps/workflow/migrations/0001_baseline.py
index 09e54e6ba..47bdaa354 100644
--- a/apps/workflow/migrations/0001_baseline.py
+++ b/apps/workflow/migrations/0001_baseline.py
@@ -14,7 +14,7 @@ class Migration(migrations.Migration):
     initial = True
 
     dependencies = [
-        ("client", "0001_baseline"),
+        ("company", "0001_baseline"),
         migrations.swappable_dependency(settings.AUTH_USER_MODEL),
     ]
 
@@ -1018,7 +1018,7 @@ class Migration(migrations.Migration):
                         help_text="Internal client used for tracking shop work.",
                         on_delete=django.db.models.deletion.PROTECT,
                         related_name="+",
-                        to="client.client",
+                        to="company.client",
                     ),
                 ),
             ],
diff --git a/apps/workflow/migrations/0005_rename_shop_client_fields.py b/apps/workflow/migrations/0005_rename_shop_client_fields.py
new file mode 100644
index 000000000..826459764
--- /dev/null
+++ b/apps/workflow/migrations/0005_rename_shop_client_fields.py
@@ -0,0 +1,20 @@
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("workflow", "0004_drop_orphaned_company_name_index"),
+    ]
+
+    operations = [
+        migrations.RenameField(
+            model_name="companydefaults",
+            old_name="shop_client",
+            new_name="shop_company",
+        ),
+        migrations.RenameField(
+            model_name="companydefaults",
+            old_name="test_client_name",
+            new_name="test_company_name",
+        ),
+    ]
diff --git a/apps/workflow/migrations/0006_alter_companydefaults_shop_company_and_more.py b/apps/workflow/migrations/0006_alter_companydefaults_shop_company_and_more.py
new file mode 100644
index 000000000..e673b5cc1
--- /dev/null
+++ b/apps/workflow/migrations/0006_alter_companydefaults_shop_company_and_more.py
@@ -0,0 +1,35 @@
+# Generated by Django 6.0.4 on 2026-07-06 10:20
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0003_alter_clientcontact_company_and_more"),
+        ("workflow", "0005_rename_shop_client_fields"),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name="companydefaults",
+            name="shop_company",
+            field=models.ForeignKey(
+                help_text="Internal company used for tracking shop work.",
+                on_delete=django.db.models.deletion.PROTECT,
+                related_name="+",
+                to="company.company",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="companydefaults",
+            name="test_company_name",
+            field=models.CharField(
+                blank=True,
+                help_text="Name of the test company used for testing (e.g., 'ABC Carpet Cleaning TEST IGNORE'). This company's name is preserved during data backports.",
+                max_length=255,
+                null=True,
+            ),
+        ),
+    ]
diff --git a/apps/workflow/models/company_defaults.py b/apps/workflow/models/company_defaults.py
index ecc14b336..567a75d54 100644
--- a/apps/workflow/models/company_defaults.py
+++ b/apps/workflow/models/company_defaults.py
@@ -250,19 +250,19 @@ class CompanyDefaults(SingletonModel):
         help_text="Wide company logo for letterheads and PDFs",
     )
 
-    shop_client = models.ForeignKey(
-        "client.Client",
+    shop_company = models.ForeignKey(
+        "company.Company",
         on_delete=models.PROTECT,
         related_name="+",
-        help_text="Internal client used for tracking shop work.",
+        help_text="Internal company used for tracking shop work.",
     )
 
-    # Test client configuration
-    test_client_name = models.CharField(
+    # Test company configuration
+    test_company_name = models.CharField(
         max_length=255,
         null=True,
         blank=True,
-        help_text="Name of the test client used for testing (e.g., 'ABC Carpet Cleaning TEST IGNORE'). This client's name is preserved during data backports.",
+        help_text="Name of the test company used for testing (e.g., 'ABC Carpet Cleaning TEST IGNORE'). This company's name is preserved during data backports.",
     )
 
     # KPI thresholds — all daily unless noted otherwise
diff --git a/apps/workflow/models/search_telemetry_event.py b/apps/workflow/models/search_telemetry_event.py
index 5d0e2c7fa..e0972e8b2 100644
--- a/apps/workflow/models/search_telemetry_event.py
+++ b/apps/workflow/models/search_telemetry_event.py
@@ -6,7 +6,7 @@
 
 
 class SearchTelemetryEvent(models.Model):
-    """Search/click telemetry shared by client, Kanban, and stock search."""
+    """Search/click telemetry shared by company, Kanban, and stock search."""
 
     class EventType(models.TextChoices):
         SEARCH = "search", "Search"
diff --git a/apps/workflow/models/settings_metadata.py b/apps/workflow/models/settings_metadata.py
index 1bab5e9c8..2b6b59b95 100644
--- a/apps/workflow/models/settings_metadata.py
+++ b/apps/workflow/models/settings_metadata.py
@@ -135,8 +135,8 @@ def get_section_info(cls, key: str) -> tuple[str, str, int] | None:
     "starting_job_number": "setup",
     "starting_po_number": "setup",
     "po_prefix": "setup",
-    "shop_client": "setup",
-    "test_client_name": "setup",
+    "shop_company": "setup",
+    "test_company_name": "setup",
     # Xero integration
     "accounting_provider": "xero",
     "xero_tenant_id": "xero",
@@ -165,8 +165,8 @@ def get_ui_type_for_field(field: "models.Field[Any, Any]") -> str:
     """
     related_model = getattr(field.remote_field, "model", None)
     related_label = getattr(getattr(related_model, "_meta", None), "label", None)
-    if isinstance(field, models.ForeignKey) and related_label == "client.Client":
-        return "client"
+    if isinstance(field, models.ForeignKey) and related_label == "company.Company":
+        return "company"
 
     for field_class, ui_type in DJANGO_TO_UI_TYPE.items():
         if isinstance(field, field_class):
diff --git a/apps/workflow/serializers.py b/apps/workflow/serializers.py
index 2dd2f1c98..6eb2d1dc7 100644
--- a/apps/workflow/serializers.py
+++ b/apps/workflow/serializers.py
@@ -93,7 +93,7 @@ class XeroAppSerializer(serializers.ModelSerializer):
     """List / detail / PATCH serializer for XeroApp.
 
     client_secret and webhook_key are write-only — never returned. The
-    webhook signing key is comparable in sensitivity to the client secret
+    webhook signing key is comparable in sensitivity to the company secret
     (anyone holding it can forge webhook deliveries that we'd verify as
     authentic), so it gets the same treatment. access_token /
     refresh_token are not surfaced at all; instead a derived has_tokens
@@ -330,7 +330,7 @@ class XeroDocumentSuccessResponseSerializer(serializers.Serializer):
     )
 
     # Fields returned by Invoice/Quote managers
-    client = serializers.CharField(required=False, help_text="Name of the client.")
+    company = serializers.CharField(required=False, help_text="Name of the company.")
     total_excl_tax = serializers.DecimalField(
         max_digits=12, decimal_places=2, required=False
     )
@@ -630,7 +630,7 @@ class GroupedErrorResolveRequestSerializer(serializers.Serializer):
     iterates the unresolved rows, computes each message's hash, and cascades
     the resolve across every row whose hash matches.
 
-    Using a fingerprint (not the message string) avoids client-side
+    Using a fingerprint (not the message string) avoids company-side
     whitespace mangling: the frontend's global axios interceptor calls
     trimStringsDeep on outbound payloads, which would strip trailing
     whitespace and prevent a later exact match.
diff --git a/apps/workflow/services/db_scrubber.py b/apps/workflow/services/db_scrubber.py
index c8916ff8c..f2810afd0 100644
--- a/apps/workflow/services/db_scrubber.py
+++ b/apps/workflow/services/db_scrubber.py
@@ -31,7 +31,7 @@
 )
 from apps.accounts.models import SYSTEM_AUTOMATION_EMAIL, Staff
 from apps.accounts.staff_anonymization import create_staff_profile
-from apps.client.models import Client, ClientContact, ClientContactMethod
+from apps.company.models import ClientContact, ClientContactMethod, Company
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
 
@@ -83,15 +83,15 @@ def _scrub_staff() -> None:
         )
 
 
-def _preserved_client_names() -> set[str]:
-    """Names that must survive scrubbing: shop, test client, scraper suppliers.
+def _preserved_company_names() -> set[str]:
+    """Names that must survive scrubbing: shop, test company, scraper suppliers.
 
-    Mirrors legacy backport_data_backup._get_preserved_client_names() exactly.
+    Mirrors legacy backport_data_backup._get_preserved_company_names() exactly.
     """
     preserved: set[str] = set()
     cd = CompanyDefaults.objects.using(SCRUB_ALIAS).get()
-    preserved.add(cd.shop_client.name)
-    preserved.add(cd.test_client_name)
+    preserved.add(cd.shop_company.name)
+    preserved.add(cd.test_company_name)
 
     from apps.quoting.models import SupplierScraperConfig
 
@@ -115,7 +115,7 @@ def _unique_scrub_value(
     no two scrubbed contact methods can share a normalized value. That keeps the
     scrub clear of the per-owner unique constraints even against a real,
     not-yet-scrubbed number still in the table, without relying on the
-    one-number-one-client guard in ``ClientContactMethod.save()`` (which
+    one-number-one-company guard in ``ClientContactMethod.save()`` (which
     ``bulk_update`` deliberately bypasses).
     """
     for _ in range(1000):
@@ -130,8 +130,8 @@ def _unique_scrub_value(
     )
 
 
-def _scrub_clients() -> None:
-    """Mirror legacy PII_CONFIG entries for client.client and client.clientcontact.
+def _scrub_companies() -> None:
+    """Mirror legacy PII_CONFIG entries for company.company and company.clientcontact.
 
     Top-level fields touched: name (with allow-list), primary_contact_name,
     primary_contact_email, email.
@@ -143,10 +143,10 @@ def _scrub_clients() -> None:
     other raw_json keys) is left untouched — matches today's behaviour exactly.
     """
     fake = Faker()
-    preserved = _preserved_client_names()
+    preserved = _preserved_company_names()
     used_company_names: set[str] = set()
 
-    for client in Client.objects.using(SCRUB_ALIAS).exclude(name__in=preserved):
+    for company in Company.objects.using(SCRUB_ALIAS).exclude(name__in=preserved):
         for _ in range(1000):
             candidate = fake.company()
             if candidate not in used_company_names:
@@ -156,12 +156,12 @@ def _scrub_clients() -> None:
             raise RuntimeError(
                 "Failed to generate unique company name after 1000 attempts"
             )
-        client.name = candidate
-        client.primary_contact_name = fake.name()
-        client.primary_contact_email = fake.email()
-        client.email = fake.email()
+        company.name = candidate
+        company.primary_contact_name = fake.name()
+        company.primary_contact_email = fake.email()
+        company.email = fake.email()
 
-        rj = client.raw_json or {}
+        rj = company.raw_json or {}
         if "_name" in rj:
             rj["_name"] = candidate
         if "_email_address" in rj:
@@ -178,8 +178,8 @@ def _scrub_clients() -> None:
                 bp["_bank_account_number"] = fake.iban()
             if "_bank_account_name" in bp:
                 bp["_bank_account_name"] = fake.name()
-        client.raw_json = rj
-        client.save(using=SCRUB_ALIAS)
+        company.raw_json = rj
+        company.save(using=SCRUB_ALIAS)
 
     for contact in ClientContact.objects.using(SCRUB_ALIAS).all():
         contact.name = fake.name()
@@ -189,15 +189,15 @@ def _scrub_clients() -> None:
             update_fields=["name", "email"],
         )
 
-    # Preserved clients (shop, test, enabled scrapers) keep their real contact
+    # Preserved companies (shop, test, enabled scrapers) keep their real contact
     # methods, matching the name/email exclusion above. A method is preserved
-    # whether it is owned directly by the client or via one of its contacts.
+    # whether it is owned directly by the company or via one of its contacts.
     used_method_values: set[tuple[str, str]] = set()
     methods_to_update: list[ClientContactMethod] = []
     for method in (
         ClientContactMethod.objects.using(SCRUB_ALIAS)
-        .exclude(client__name__in=preserved)
-        .exclude(contact__client__name__in=preserved)
+        .exclude(company__name__in=preserved)
+        .exclude(contact__company__name__in=preserved)
     ):
         if method.method_type == ClientContactMethod.MethodType.PHONE:
             generate = fake.phone_number
@@ -211,7 +211,7 @@ def _scrub_clients() -> None:
         method.value = value
         method.normalized_value = normalized
         methods_to_update.append(method)
-    # bulk_update bypasses ClientContactMethod.save(), so the one-number-one-client
+    # bulk_update bypasses ClientContactMethod.save(), so the one-number-one-company
     # guard and primary-demotion logic (neither of which is a business operation
     # during a scrub) never run and cannot abort the transaction on a collision.
     ClientContactMethod.objects.using(SCRUB_ALIAS).bulk_update(
@@ -305,7 +305,7 @@ def scrub() -> None:
         with transaction.atomic(using=SCRUB_ALIAS):
             # Per-step helpers added by subsequent tasks.
             _scrub_staff()
-            _scrub_clients()
+            _scrub_companies()
             _scrub_accounting_contacts()
             _delete_unlinked_accounting()
             _truncate_excluded_tables()
diff --git a/apps/workflow/tests/test_api_schema_coverage.py b/apps/workflow/tests/test_api_schema_coverage.py
index 9a36cc624..5a8028023 100644
--- a/apps/workflow/tests/test_api_schema_coverage.py
+++ b/apps/workflow/tests/test_api_schema_coverage.py
@@ -35,7 +35,7 @@
     "api/enums/",
     # DRF router roots (meta-endpoints listing sub-routes, not real APIs)
     "api/workflow/",
-    "api/clients/",
+    "api/companies/",
     "api/crm/",
     "api/purchasing/",
     "api/quoting/",
diff --git a/apps/workflow/tests/test_company_defaults_api.py b/apps/workflow/tests/test_company_defaults_api.py
index 6eca7a986..28859f61c 100644
--- a/apps/workflow/tests/test_company_defaults_api.py
+++ b/apps/workflow/tests/test_company_defaults_api.py
@@ -12,24 +12,24 @@ def setUp(self):
         self.client = APIClient()
         self.client.force_authenticate(user=self.test_staff)
 
-    def test_get_returns_shop_client_fk_without_name_alias(self):
+    def test_get_returns_shop_company_fk_without_name_alias(self):
         response = self.client.get("/api/company-defaults/")
 
         self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertIn("shop_client", response.data)
-        self.assertNotIn("shop_client_name", response.data)
+        self.assertIn("shop_company", response.data)
+        self.assertNotIn("shop_company_name", response.data)
 
-    def test_get_does_not_query_client_for_shop_client_display_name(self):
+    def test_get_does_not_query_company_for_shop_company_display_name(self):
         with CaptureQueriesContext(connection) as captured:
             response = self.client.get("/api/company-defaults/")
 
         self.assertEqual(response.status_code, status.HTTP_200_OK)
-        client_queries = [
+        company_queries = [
             query["sql"]
             for query in captured.captured_queries
-            if 'FROM "client_client"' in query["sql"]
+            if 'FROM "company_company"' in query["sql"]
         ]
-        self.assertEqual(client_queries, [])
+        self.assertEqual(company_queries, [])
 
     def test_patch_canonicalizes_blank_optional_urls_to_null(self):
         response = self.client.patch(
diff --git a/apps/workflow/tests/test_data_versions_view.py b/apps/workflow/tests/test_data_versions_view.py
index e3351ab4e..ada90278b 100644
--- a/apps/workflow/tests/test_data_versions_view.py
+++ b/apps/workflow/tests/test_data_versions_view.py
@@ -1,5 +1,5 @@
 """Guards against stale-data regressions: any write to Stock, Job, Staff
-assignments, or Client contacts must bump the corresponding data-version
+assignments, or Company contacts must bump the corresponding data-version
 string so the frontend invalidates its cache and re-fetches.
 """
 
@@ -10,7 +10,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.crm.models import PhoneCallRecord, PhoneCallRecording
 from apps.job.models import Job
 from apps.job.services.job_service import JobStaffService
@@ -51,10 +51,10 @@ def _stock(**overrides):
 
 @pytest.fixture
 def kanban_prerequisites(db):
-    shop_client = _client(name="Shop Client")
+    shop_company = _client(name="Shop Company")
     CompanyDefaults.objects.get_or_create(
         company_name="Test Co",
-        defaults={"shop_client": shop_client},
+        defaults={"shop_company": shop_company},
     )
     XeroPayItem.objects.get_or_create(
         name="Ordinary Time",
@@ -64,15 +64,15 @@ def kanban_prerequisites(db):
 
 
 def _client(**overrides):
-    defaults = dict(name="Kanban Client", xero_last_modified=timezone.now())
+    defaults = dict(name="Kanban Company", xero_last_modified=timezone.now())
     defaults.update(overrides)
-    return Client.objects.create(**defaults)
+    return Company.objects.create(**defaults)
 
 
 def _job(staff, **overrides):
     defaults = dict(
         staff=staff,
-        client=_client(),
+        company=_client(),
         name="Kanban Job",
         pricing_methodology="time_materials",
     )
@@ -201,9 +201,9 @@ def test_assigning_staff_changes_kanban_version(
 def test_related_display_changes_change_kanban_version(
     auth_client, office_staff, kanban_prerequisites
 ):
-    client = _client(name="Original Client")
-    contact = ClientContact.objects.create(client=client, name="Original Contact")
-    _job(office_staff, client=client, contact=contact)
+    company = _client(name="Original Company")
+    contact = ClientContact.objects.create(company=company, name="Original Contact")
+    _job(office_staff, company=company, contact=contact)
     before = auth_client.get("/api/data-versions/").json()["kanban"]
     contact.name = "Updated Contact"
     contact.save(update_fields=["name"])
@@ -214,11 +214,11 @@ def test_related_display_changes_change_kanban_version(
 def test_client_partial_save_changes_kanban_version(
     auth_client: APIClient, office_staff: Staff, kanban_prerequisites: None
 ) -> None:
-    client = _client(name="Original Client")
-    _job(office_staff, client=client)
+    company = _client(name="Original Company")
+    _job(office_staff, company=company)
     before = auth_client.get("/api/data-versions/").json()["kanban"]
-    client.name = "Updated Client"
-    client.save(update_fields=["name"])
+    company.name = "Updated Company"
+    company.save(update_fields=["name"])
     after = auth_client.get("/api/data-versions/").json()["kanban"]
     assert before != after
 
diff --git a/apps/workflow/tests/test_db_scrubber.py b/apps/workflow/tests/test_db_scrubber.py
index f254323c1..af622759d 100644
--- a/apps/workflow/tests/test_db_scrubber.py
+++ b/apps/workflow/tests/test_db_scrubber.py
@@ -7,7 +7,7 @@
 
 from django.test import SimpleTestCase
 
-from apps.client.models import ClientContactMethod
+from apps.company.models import ClientContactMethod
 from apps.workflow.services.db_scrubber import _unique_scrub_value
 
 PHONE = ClientContactMethod.MethodType.PHONE
diff --git a/apps/workflow/tests/test_dev_demo_export.py b/apps/workflow/tests/test_dev_demo_export.py
index 48b50472a..1dfb0a96a 100644
--- a/apps/workflow/tests/test_dev_demo_export.py
+++ b/apps/workflow/tests/test_dev_demo_export.py
@@ -8,7 +8,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContactMethod
+from apps.company.models import ClientContactMethod, Company
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -42,21 +42,21 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
         first_name="Demo",
         last_name="Staff",
     )
-    client = Client.objects.create(
-        name="Realistic Client Ltd",
-        email="client@example.test",
+    company = Company.objects.create(
+        name="Realistic Company Ltd",
+        email="company@example.test",
         xero_last_modified=timezone.now(),
-        raw_json={"_name": "Realistic Client Ltd"},
+        raw_json={"_name": "Realistic Company Ltd"},
     )
     ClientContactMethod.objects.create(
-        client=client,
+        company=company,
         method_type=ClientContactMethod.MethodType.PHONE,
         value="+64211234567",
         is_primary=True,
     )
     CompanyDefaults.objects.create(
         company_name="Demo Co",
-        shop_client=client,
+        shop_company=company,
     )
     PhoneProviderSettings.objects.update_or_create(
         pk=1,
@@ -109,7 +109,7 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
         destination="+64212222222",
         duration_seconds=180,
         charge=Decimal("1.2300"),
-        client=client,
+        company=company,
         raw_json={"phone": "+64212222222", "provider": "payload"},
     )
     PhoneCallRecording.objects.create(
@@ -129,7 +129,7 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     )
     recording = SessionReplayRecording.objects.create(
         user=staff,
-        initial_path="/clients?email=client@example.test",
+        initial_path="/clients?email=company@example.test",
         latest_path="/jobs/secret",
         user_agent="Browser",
     )
@@ -147,11 +147,11 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     SearchTelemetryEvent.objects.create(
         event_type=SearchTelemetryEvent.EventType.CLICK,
         domain=SearchTelemetryEvent.Domain.CLIENT,
-        query="client@example.test",
-        normalized_query="client@example.test",
-        selected_result_id=str(client.id),
-        selected_label="Realistic Client Ltd",
-        metadata={"email": "client@example.test"},
+        query="company@example.test",
+        normalized_query="company@example.test",
+        selected_result_id=str(company.id),
+        selected_label="Realistic Company Ltd",
+        metadata={"email": "company@example.test"},
     )
     pay_run = XeroPayRun.objects.create(
         xero_id=uuid.uuid4(),
@@ -181,9 +181,9 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     results = scrub_dev_demo_export(using="default")
 
     assert {result.name for result in results}
-    client.refresh_from_db()
-    assert client.name == "Realistic Client Ltd"
-    assert client.email == "client@example.test"
+    company.refresh_from_db()
+    assert company.name == "Realistic Company Ltd"
+    assert company.email == "company@example.test"
 
     xero_app = XeroApp.objects.get()
     assert xero_app.client_id == "client-id"
@@ -205,7 +205,7 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     call.refresh_from_db()
     assert call.duration_seconds == 180
     assert call.charge == Decimal("1.2300")
-    assert call.client == client
+    assert call.company == company
     assert call.origin.startswith("demo-number-")
     assert call.destination.startswith("demo-number-")
     assert call.raw_json == {}
diff --git a/apps/workflow/tests/test_localdate_regression.py b/apps/workflow/tests/test_localdate_regression.py
index f953d2073..1c1382ded 100644
--- a/apps/workflow/tests/test_localdate_regression.py
+++ b/apps/workflow/tests/test_localdate_regression.py
@@ -25,16 +25,16 @@
 UTC_DATE = datetime.date(2026, 4, 27)
 
 
-def _make_client(name="Localdate Test Client"):
-    from apps.client.models import Client
+def _make_client(name="Localdate Test Company"):
+    from apps.company.models import Company
 
-    return Client.objects.create(name=name, xero_last_modified=timezone.now())
+    return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
 
-def _make_job(client, staff, name="Localdate Test Job", **extra):
+def _make_job(company, staff, name="Localdate Test Job", **extra):
     from apps.job.models import Job
 
-    job = Job(client=client, name=name, **extra)
+    job = Job(company=company, name=name, **extra)
     job.save(staff=staff)
     return job
 
@@ -145,8 +145,8 @@ class JobAgingLocalDateTests(BaseTestCase):
     def _make_aged_job(self):
         from apps.job.models import Job
 
-        client = _make_client("Aging Test Client")
-        job = _make_job(client, self.test_staff, name="Aging Test Job")
+        company = _make_client("Aging Test Company")
+        job = _make_job(company, self.test_staff, name="Aging Test Job")
         # Frozen "now" = UTC 2026-04-27 23:30 = NZ 2026-04-28 11:30 (UTC date
         # April 27, NZ date April 28). For the bug to actually change the
         # answer, the past timestamp must NOT also straddle midnight in the
@@ -221,16 +221,16 @@ class XeroInvoiceLocalDateTests(BaseTestCase):
     def _make_manager(self, *, is_account_customer):
         from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 
-        client = _make_client("Xero Invoice Test Client")
-        client.is_account_customer = is_account_customer
-        client.save()
+        company = _make_client("Xero Invoice Test Company")
+        company.is_account_customer = is_account_customer
+        company.save()
         job = _make_job(
-            client,
+            company,
             self.test_staff,
             name="Xero Invoice Test",
             pricing_methodology="fixed_price",
         )
-        return XeroInvoiceManager(client=client, job=job, staff=self.test_staff)
+        return XeroInvoiceManager(company=company, job=job, staff=self.test_staff)
 
     def test_build_payload_uses_nz_local_date(self):
         manager = self._make_manager(is_account_customer=False)
@@ -244,7 +244,7 @@ def test_build_payload_uses_nz_local_date(self):
         self.assertEqual(payload.date, NZ_DATE)
 
     def test_account_customer_due_date_is_20th_of_next_month(self):
-        """`Client.is_account_customer=True` → due on the 20th of next month."""
+        """`Company.is_account_customer=True` → due on the 20th of next month."""
         manager = self._make_manager(is_account_customer=True)
 
         with (
@@ -257,7 +257,7 @@ def test_account_customer_due_date_is_20th_of_next_month(self):
         self.assertEqual(payload.due_date, datetime.date(2026, 5, 20))
 
     def test_cash_customer_due_date_is_same_day(self):
-        """`Client.is_account_customer=False` → due same-day."""
+        """`Company.is_account_customer=False` → due same-day."""
         manager = self._make_manager(is_account_customer=False)
 
         with (
@@ -309,14 +309,14 @@ class XeroQuoteLocalDateTests(BaseTestCase):
     def test_build_payload_uses_nz_local_date(self):
         from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
 
-        client = _make_client("Xero Quote Test Client")
+        company = _make_client("Xero Quote Test Company")
         job = _make_job(
-            client,
+            company,
             self.test_staff,
             name="Xero Quote Test",
             pricing_methodology="fixed_price",
         )
-        manager = XeroQuoteManager(client=client, job=job, staff=self.test_staff)
+        manager = XeroQuoteManager(company=company, job=job, staff=self.test_staff)
 
         with (
             freeze_time(FROZEN_UTC_MOMENT),
@@ -337,8 +337,8 @@ def test_consume_creates_cost_line_with_nz_local_accounting_date(self):
         from apps.purchasing.models import Stock
         from apps.purchasing.services.stock_service import consume_stock
 
-        client = _make_client("Stock Test Client")
-        job = _make_job(client, self.test_staff, name="Stock Test Job")
+        company = _make_client("Stock Test Company")
+        job = _make_job(company, self.test_staff, name="Stock Test Job")
         item = Stock.objects.create(
             description="Test material",
             quantity=Decimal("10.00"),
@@ -368,10 +368,10 @@ def test_archived_date_uses_nz_local(self):
             ArchivedJobsComplianceService,
         )
 
-        client = _make_client("DQ Test Client")
+        company = _make_client("DQ Test Company")
         # Archived, not invoiced, not paid → produces a non-compliant row.
         job = _make_job(
-            client,
+            company,
             self.test_staff,
             name="DQ Test Job",
             status="archived",
diff --git a/apps/workflow/tests/test_push_contacts.py b/apps/workflow/tests/test_push_contacts.py
index 96772ef39..84c856a3d 100644
--- a/apps/workflow/tests/test_push_contacts.py
+++ b/apps/workflow/tests/test_push_contacts.py
@@ -14,7 +14,7 @@
 from django.utils import timezone
 from xero_python.accounting.models import Contact, Contacts
 
-from apps.client.models import Client, ClientContactMethod
+from apps.company.models import ClientContactMethod, Company
 from apps.workflow.tests.fixtures.xero_responses import make_create_contacts_response
 
 
@@ -27,15 +27,15 @@ def _make_client(**overrides):
     }
     phone = overrides.pop("phone", None)
     defaults.update(overrides)
-    client = Client.objects.create(**defaults)
+    company = Company.objects.create(**defaults)
     if phone is not None:
         ClientContactMethod.objects.create(
-            client=client,
+            company=company,
             method_type=ClientContactMethod.MethodType.PHONE,
             value=phone,
             is_primary=True,
         )
-    return client
+    return company
 
 
 def _create_response(contact_id, name):
@@ -48,20 +48,20 @@ def _create_response(contact_id, name):
 @patch("apps.workflow.api.xero.push.get_tenant_id", return_value="tenant-1")
 @patch("apps.workflow.api.xero.push.AccountingApi")
 class SyncClientToXeroPushTests(TestCase):
-    """sync_client_to_xero — both branches must pass Contact instances."""
+    """sync_company_to_xero — both branches must pass Contact instances."""
 
     def test_new_client_calls_create_contacts_with_sdk_contact(
         self, mock_api_class, _mock_tenant, _mock_sleep
     ):
-        client = _make_client(phone="027 351 8326")
+        company = _make_client(phone="027 351 8326")
         mock_api = mock_api_class.return_value
         mock_api.create_contacts.return_value = _create_response(
-            "00000000-0000-0000-0000-000000000001", client.name
+            "00000000-0000-0000-0000-000000000001", company.name
         )
 
-        from apps.workflow.api.xero.push import sync_client_to_xero
+        from apps.workflow.api.xero.push import sync_company_to_xero
 
-        result = sync_client_to_xero(client)
+        result = sync_company_to_xero(company)
 
         self.assertTrue(result)
         mock_api.create_contacts.assert_called_once()
@@ -75,13 +75,13 @@ def test_existing_client_calls_update_contact_with_sdk_contact(
         self, mock_api_class, _mock_tenant, _mock_sleep
     ):
         xero_id = "9568adbc-aaaa-bbbb-cccc-000000000001"
-        client = _make_client(xero_contact_id=xero_id, phone="027 351 8327")
+        company = _make_client(xero_contact_id=xero_id, phone="027 351 8327")
         mock_api = mock_api_class.return_value
-        mock_api.update_contact.return_value = _create_response(xero_id, client.name)
+        mock_api.update_contact.return_value = _create_response(xero_id, company.name)
 
-        from apps.workflow.api.xero.push import sync_client_to_xero
+        from apps.workflow.api.xero.push import sync_company_to_xero
 
-        result = sync_client_to_xero(client)
+        result = sync_company_to_xero(company)
 
         self.assertTrue(result)
         mock_api.update_contact.assert_called_once()
@@ -97,30 +97,30 @@ def test_existing_client_calls_update_contact_with_sdk_contact(
 @patch("apps.workflow.api.xero.push.get_tenant_id", return_value="tenant-1")
 @patch("apps.workflow.api.xero.push.AccountingApi")
 class CreateClientContactInXeroTests(TestCase):
-    """create_client_contact_in_xero — passes Contact, saves xero_contact_id."""
+    """create_company_contact_in_xero — passes Contact, saves xero_contact_id."""
 
     def test_passes_sdk_contact_and_saves_id(
         self, mock_api_class, _mock_tenant, _mock_sleep
     ):
-        client = _make_client(phone="027 351 8328")
+        company = _make_client(phone="027 351 8328")
         new_id = "00000000-0000-0000-0000-000000000042"
         mock_api = mock_api_class.return_value
         # Use the captured-from-Xero response fixture so the mock matches the
         # real shape (contact_status, updated_date_utc, etc.); only override
         # the fields this test actually asserts on.
         mock_api.create_contacts.return_value = make_create_contacts_response(
-            contact_id=new_id, name=client.name
+            contact_id=new_id, name=company.name
         )
 
-        from apps.workflow.api.xero.push import create_client_contact_in_xero
+        from apps.workflow.api.xero.push import create_company_contact_in_xero
 
-        result = create_client_contact_in_xero(client)
+        result = create_company_contact_in_xero(company)
 
         self.assertEqual(result, new_id)
         contact = mock_api.create_contacts.call_args.kwargs["contacts"]["contacts"][0]
         self.assertIsInstance(contact, Contact)
-        client.refresh_from_db()
-        self.assertEqual(client.xero_contact_id, new_id)
+        company.refresh_from_db()
+        self.assertEqual(company.xero_contact_id, new_id)
 
 
 @patch("time.sleep")
@@ -133,7 +133,7 @@ def test_passes_list_of_sdk_contacts(
         self, mock_api_class, _mock_tenant, _mock_sleep
     ):
         clients = [
-            _make_client(name=f"Bulk Client {i}", phone=f"027 351 84{i:02d}")
+            _make_client(name=f"Bulk Company {i}", phone=f"027 351 84{i:02d}")
             for i in range(3)
         ]
         mock_api = mock_api_class.return_value
@@ -160,13 +160,13 @@ def test_no_name_dict_key_workaround_in_payload(
 
         Anyone re-introducing the dict path "for safety" trips this immediately.
         """
-        client = _make_client(phone="027 351 8329")
+        company = _make_client(phone="027 351 8329")
         mock_api = mock_api_class.return_value
-        mock_api.create_contacts.return_value = _create_response("id-1", client.name)
+        mock_api.create_contacts.return_value = _create_response("id-1", company.name)
 
         from apps.workflow.api.xero.push import bulk_create_contacts_in_xero
 
-        bulk_create_contacts_in_xero([client])
+        bulk_create_contacts_in_xero([company])
 
         captured = mock_api.create_contacts.call_args.kwargs["contacts"]["contacts"][0]
         self.assertIsInstance(captured, Contact)
@@ -199,7 +199,7 @@ def test_duplicate_names_get_distinct_ids_when_response_in_order(
     ):
         """Regression: two clients with identical names in one batch must each
         receive their own xero_contact_id. The previous name-keyed mapping
-        silently overwrote the first client's mapping with the second's."""
+        silently overwrote the first company's mapping with the second's."""
         client_a = _make_client(
             name="Same Name",
             email="a@example.test",
diff --git a/apps/workflow/tests/test_relabel_client_app.py b/apps/workflow/tests/test_relabel_client_app.py
new file mode 100644
index 000000000..0544fe2dc
--- /dev/null
+++ b/apps/workflow/tests/test_relabel_client_app.py
@@ -0,0 +1,163 @@
+"""Tests for the KAN-278 relabel_client_app one-time DB surgery.
+
+The fully-migrated test DB is post-rename (tables are ``company_company``
+etc., ledger rows say app='company'), so each test stages the legacy state
+it needs with raw DDL/DML and restores the live table names afterwards -
+the surgery's net DDL is deliberately NOT zero (it only does the app-label
+half of the table renames; the rename migration does the model half).
+"""
+
+from django.core.management import call_command
+from django.core.management.base import CommandError
+from django.db import connection
+from django.test import TransactionTestCase
+
+# The pre-squash client migration names every production ledger carried
+# (verified against the dev ledger, which mirrored prod at the squash).
+HISTORIC_CLIENT_MIGRATIONS = [
+    "0001_initial",
+    "0002_clientcontact",
+    "0003_add_xero_merge_tracking",
+    "0004_populate_merge_fields",
+    "0005_client_is_supplier",
+    "0006_alter_client_name",
+    "0007_delete_empty_name_contacts",
+    "0008_merge_duplicate_contacts",
+    "0009_clientcontact_unique_client_contact_name",
+    "0010_add_is_active_to_clientcontact",
+    "0011_convert_empty_strings_to_null",
+    "0012_supplierpickupaddress",
+    "0013_add_google_fields_to_pickup_address",
+    "0014_add_suburb_to_pickup_address",
+    "0015_populate_xero_addresses",
+    "0016_alter_client_table_alter_clientcontact_table_and_more",
+    "0017_reassign_stranded_merged_client_fks",
+    "0018_client_allow_jobs",
+    "0019_client_name_fts_index",
+    "0020_suppliersearchalias_and_more",
+    "0021_clientcontactmethod",
+    "0022_client_name_trgm_index",
+    "0023_drop_scalar_phone_fields",
+]
+
+# live table name -> pre-surgery (legacy) table name
+LEGACY_TABLE_NAMES = [
+    ("company_company", "client_client"),
+    ("company_clientcontact", "client_clientcontact"),
+    ("company_clientcontactmethod", "client_clientcontactmethod"),
+    ("company_suppliersearchalias", "client_suppliersearchalias"),
+    ("company_supplierpickupaddress", "client_supplierpickupaddress"),
+]
+
+
+def _insert_ghost_rows(cursor) -> None:
+    for name in HISTORIC_CLIENT_MIGRATIONS:
+        cursor.execute(
+            "INSERT INTO django_migrations (app, name, applied) "
+            "VALUES ('client', %s, NOW())",
+            [name],
+        )
+
+
+class RelabelClientAppTests(TransactionTestCase):
+    def test_noop_on_fresh_db(self) -> None:
+        # The migrated test DB has no app='client' rows: the command must
+        # no-op without touching tables.
+        call_command("relabel_client_app")
+        with connection.cursor() as cursor:
+            cursor.execute(
+                "SELECT COUNT(*) FROM django_migrations WHERE app = 'client'"
+            )
+            self.assertEqual(cursor.fetchone()[0], 0)
+            cursor.execute("SELECT to_regclass('company_company')")
+            self.assertIsNotNone(cursor.fetchone()[0])
+
+    def test_relabels_postsquash_ledger(self) -> None:
+        # Stage the real pre-deploy state: legacy table names, the baseline
+        # ledger row under app='client', 23 historic ghost rows, content
+        # types under app_label='client'.
+        with connection.cursor() as cursor:
+            for live, legacy in LEGACY_TABLE_NAMES:
+                cursor.execute(f'ALTER TABLE "{live}" RENAME TO "{legacy}"')
+            cursor.execute(
+                "UPDATE django_migrations SET app = 'client' "
+                "WHERE app = 'company' AND name = '0001_baseline'"
+            )
+            _insert_ghost_rows(cursor)
+            cursor.execute(
+                "UPDATE django_content_type SET app_label = 'client' "
+                "WHERE app_label = 'company'"
+            )
+
+        try:
+            call_command("relabel_client_app")
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_migrations WHERE app = 'client'"
+                )
+                self.assertEqual(cursor.fetchone()[0], 0)
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_migrations "
+                    "WHERE app = 'company' AND name = '0001_baseline'"
+                )
+                self.assertEqual(cursor.fetchone()[0], 1)
+                # The historic ghosts are deleted, not relabelled.
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_migrations "
+                    "WHERE app = 'company' AND name = ANY(%s)",
+                    [HISTORIC_CLIENT_MIGRATIONS],
+                )
+                self.assertEqual(cursor.fetchone()[0], 0)
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_content_type "
+                    "WHERE app_label = 'client'"
+                )
+                self.assertEqual(cursor.fetchone()[0], 0)
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_content_type "
+                    "WHERE app_label = 'company'"
+                )
+                self.assertGreater(cursor.fetchone()[0], 0)
+                # Surgery does the label half only: client_client ends up at
+                # company_client; the rename migration owns the model half.
+                cursor.execute("SELECT to_regclass('company_client')")
+                self.assertIsNotNone(cursor.fetchone()[0])
+                cursor.execute("SELECT to_regclass('client_client')")
+                self.assertIsNone(cursor.fetchone()[0])
+
+            # Second run must be a clean no-op.
+            call_command("relabel_client_app")
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_migrations WHERE app = 'client'"
+                )
+                self.assertEqual(cursor.fetchone()[0], 0)
+        finally:
+            # Restore the live schema for subsequent tests: only the main
+            # table sits at its label-half name (company_client).
+            with connection.cursor() as cursor:
+                cursor.execute("SELECT to_regclass('company_client')")
+                if cursor.fetchone()[0] is not None:
+                    cursor.execute(
+                        "ALTER TABLE company_client RENAME TO company_company"
+                    )
+
+    def test_aborts_on_presquash_ledger(self) -> None:
+        # app='client' rows without a ('client', '0001_baseline') row mean a
+        # pre-squash database: the command must abort loudly and leave every
+        # staged row in place (its transaction rolls back atomically).
+        with connection.cursor() as cursor:
+            _insert_ghost_rows(cursor)
+        try:
+            with self.assertRaises(CommandError):
+                call_command("relabel_client_app")
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    "SELECT COUNT(*) FROM django_migrations WHERE app = 'client'"
+                )
+                self.assertEqual(cursor.fetchone()[0], len(HISTORIC_CLIENT_MIGRATIONS))
+                cursor.execute("SELECT to_regclass('company_company')")
+                self.assertIsNotNone(cursor.fetchone()[0])
+        finally:
+            with connection.cursor() as cursor:
+                cursor.execute("DELETE FROM django_migrations WHERE app = 'client'")
diff --git a/apps/workflow/tests/test_seed_xero_from_database.py b/apps/workflow/tests/test_seed_xero_from_database.py
index 11972ce55..e45192ba7 100644
--- a/apps/workflow/tests/test_seed_xero_from_database.py
+++ b/apps/workflow/tests/test_seed_xero_from_database.py
@@ -3,7 +3,7 @@
 Regression coverage for Trello #309 — the production-DB guard must
 prevent ``clear_production_xero_ids`` from wiping live
 ``xero_contact_id`` values when the configured DB name belongs to a
-prod instance. The DB name pattern is ``dw_<client>_<env>``
+prod instance. The DB name pattern is ``dw_<company>_<env>``
 (``scripts/server/instance.sh:171``); env is validated against
 ``dev``/``uat``/``staging``/``prod`` (``scripts/server/common.sh:13``),
 so the ``_prod`` suffix is a deterministic signal of a prod DB.
@@ -16,7 +16,7 @@
 from django.test import TestCase
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.workflow.management.commands.seed_xero_from_database import Command
 
 SENTINEL_XERO_CONTACT_ID = "11111111-1111-1111-1111-111111111111"
@@ -28,7 +28,7 @@ def test_refuses_when_db_name_ends_with_prod(self):
         ends with ``_prod``, ``clear_production_xero_ids`` must not
         touch the DB. Wiping live ``xero_contact_id``s breaks Xero
         sync until every contact is manually re-linked."""
-        client = Client.objects.create(
+        company = Company.objects.create(
             name="Acme Ltd",
             email="info@acme.test",
             address="123 Test Street",
@@ -42,5 +42,5 @@ def test_refuses_when_db_name_ends_with_prod(self):
         with patch.dict(settings.DATABASES["default"], {"NAME": "dw_msm_prod"}):
             cmd.clear_production_xero_ids(dry_run=False)
 
-        client.refresh_from_db()
-        self.assertEqual(client.xero_contact_id, SENTINEL_XERO_CONTACT_ID)
+        company.refresh_from_db()
+        self.assertEqual(company.xero_contact_id, SENTINEL_XERO_CONTACT_ID)
diff --git a/apps/workflow/tests/test_sync_clients.py b/apps/workflow/tests/test_sync_clients.py
index 00223db2c..ebbcdcee2 100644
--- a/apps/workflow/tests/test_sync_clients.py
+++ b/apps/workflow/tests/test_sync_clients.py
@@ -1,4 +1,4 @@
-"""Tests for sync_clients handling of archived Xero contacts."""
+"""Tests for sync_companies handling of archived Xero contacts."""
 
 from types import SimpleNamespace
 from unittest.mock import patch
@@ -8,12 +8,12 @@
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
-from apps.client.models import Client, ClientContactMethod
+from apps.company.models import ClientContactMethod, Company
 from apps.crm.models import PhoneCallRecord
 from apps.crm.services.phone_call_service import rematch_calls_for_numbers
 from apps.workflow.api.xero.reprocess_xero import (
     _xero_phone_value,
-    set_client_fields,
+    set_company_fields,
     sync_xero_phone_methods,
 )
 from apps.workflow.exceptions import AlreadyLoggedException
@@ -133,7 +133,7 @@ def _make_raw_json(contact_id, name, status="ACTIVE", merged_to=None):
 def _make_xero_contact(contact_id, name, status="ACTIVE", merged_to=None):
     """Build a fake Xero SDK contact object.
 
-    The real xero_python Contact has many attributes, but sync_clients()
+    The real xero_python Contact has many attributes, but sync_companies()
     only accesses contact_id, contact_status, and merged_to_contact_id.
     """
     contact = SimpleNamespace(
@@ -150,17 +150,17 @@ class SyncClientsArchivedContactTests(TestCase):
 
     Reproduces the production scenario where Xero merges two contacts:
     the surviving contact stays ACTIVE, the old one becomes ARCHIVED with
-    the same name.  sync_clients must handle both without crashing.
+    the same name.  sync_companies must handle both without crashing.
     """
 
     def setUp(self):
         self.active_xero_id = "9568adbc-aaaa-bbbb-cccc-000000000001"
         self.archived_xero_id = "17aa5e1e-aaaa-bbbb-cccc-000000000002"
-        self.client_name = "Powder Coating Group NZ Limited"
+        self.company_name = "Powder Coating Group NZ Limited"
 
-        # Pre-existing client linked to the active Xero contact
-        self.existing_client = Client.objects.create(
-            name=self.client_name,
+        # Pre-existing company linked to the active Xero contact
+        self.existing_client = Company.objects.create(
+            name=self.company_name,
             xero_contact_id=self.active_xero_id,
             xero_last_modified=timezone.now(),
         )
@@ -169,30 +169,30 @@ def _mock_process_xero_data(self, contact):
         """Substitute for process_xero_data that returns realistic raw_json."""
         return _make_raw_json(
             contact_id=contact.contact_id,
-            name=self.client_name,
+            name=self.company_name,
             status=contact.contact_status,
             merged_to=getattr(contact, "merged_to_contact_id", None),
         )
 
-    @patch("apps.workflow.api.xero.transforms.set_client_fields")
+    @patch("apps.workflow.api.xero.transforms.set_company_fields")
     @patch("apps.workflow.api.xero.transforms.process_xero_data")
     def test_archived_contact_creates_separate_record(
         self, mock_process, mock_set_fields
     ):
         """An archived Xero contact with a duplicate name should create a
-        separate client record instead of raising ValueError."""
+        separate company record instead of raising ValueError."""
         mock_process.side_effect = self._mock_process_xero_data
 
         archived_contact = _make_xero_contact(
             self.archived_xero_id,
-            self.client_name,
+            self.company_name,
             status="ARCHIVED",
             merged_to=self.active_xero_id,
         )
 
-        from apps.workflow.api.xero.sync import sync_clients
+        from apps.workflow.api.xero.sync import sync_companies
 
-        result = sync_clients([archived_contact])
+        result = sync_companies([archived_contact])
 
         self.assertEqual(len(result), 1)
         new_client = result[0]
@@ -203,34 +203,34 @@ def test_archived_contact_creates_separate_record(
         self.assertTrue(new_client.xero_archived)
         self.assertEqual(new_client.xero_merged_into_id, self.active_xero_id)
 
-        # Original client unchanged
+        # Original company unchanged
         self.existing_client.refresh_from_db()
         self.assertEqual(self.existing_client.xero_contact_id, self.active_xero_id)
         self.assertFalse(self.existing_client.xero_archived)
 
-    @patch("apps.workflow.api.xero.transforms.set_client_fields")
+    @patch("apps.workflow.api.xero.transforms.set_company_fields")
     @patch("apps.workflow.api.xero.transforms.process_xero_data")
     def test_active_contact_name_collision_still_raises(
         self, mock_process, mock_set_fields
     ):
-        """An active Xero contact whose name collides with an existing client
+        """An active Xero contact whose name collides with an existing company
         linked to a different Xero ID should still raise ValueError."""
         mock_process.side_effect = self._mock_process_xero_data
 
         conflicting_contact = _make_xero_contact(
             "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
-            self.client_name,
+            self.company_name,
             status="ACTIVE",
         )
 
-        from apps.workflow.api.xero.sync import sync_clients
+        from apps.workflow.api.xero.sync import sync_companies
 
         with self.assertRaises(ValueError) as ctx:
-            sync_clients([conflicting_contact])
+            sync_companies([conflicting_contact])
 
         self.assertIn(self.active_xero_id, str(ctx.exception))
 
-    @patch("apps.workflow.api.xero.transforms.set_client_fields")
+    @patch("apps.workflow.api.xero.transforms.set_company_fields")
     @patch("apps.workflow.api.xero.transforms.process_xero_data")
     def test_archived_contact_with_existing_xero_id_updates_in_place(
         self, mock_process, mock_set_fields
@@ -239,16 +239,16 @@ def test_archived_contact_with_existing_xero_id_updates_in_place(
         it should update that record (the normal 'already linked' path)."""
         mock_process.side_effect = self._mock_process_xero_data
 
-        # Contact whose ID matches the existing client — just now archived
+        # Contact whose ID matches the existing company — just now archived
         same_id_contact = _make_xero_contact(
             self.active_xero_id,
-            self.client_name,
+            self.company_name,
             status="ARCHIVED",
         )
 
-        from apps.workflow.api.xero.sync import sync_clients
+        from apps.workflow.api.xero.sync import sync_companies
 
-        result = sync_clients([same_id_contact])
+        result = sync_companies([same_id_contact])
 
         self.assertEqual(len(result), 1)
         self.assertEqual(result[0].id, self.existing_client.id)
@@ -263,8 +263,8 @@ def _client_with_phone(
         name: str,
         number: str = "021 555 123",
         phone_type: str = "DEFAULT",
-    ) -> Client:
-        return Client.objects.create(
+    ) -> Company:
+        return Company.objects.create(
             name=name,
             xero_last_modified=timezone.now(),
             raw_json={
@@ -280,13 +280,13 @@ def _client_with_phone(
         )
 
     def test_duplicate_phone_owner_crashes_sync_and_persists_app_error(self) -> None:
-        existing = Client.objects.create(
+        existing = Company.objects.create(
             name="Existing Phone Owner",
             xero_last_modified=timezone.now(),
         )
         imported = self._client_with_phone("Imported Phone Owner")
         ClientContactMethod.objects.create(
-            client=existing,
+            company=existing,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
@@ -301,22 +301,22 @@ def test_duplicate_phone_owner_crashes_sync_and_persists_app_error(self) -> None
         self.assertEqual(AppError.objects.count(), before + 1)
         app_error = AppError.objects.order_by("-timestamp").first()
         assert app_error is not None
-        # The persisted message must name the syncing client, the number, and
+        # The persisted message must name the syncing company, the number, and
         # the conflicting owner so the operator can fix the data.
         self.assertIn("Imported Phone Owner", app_error.message)
         self.assertIn("+6421555123", app_error.message)
         self.assertIn("Existing Phone Owner", app_error.message)
 
     def test_resync_of_existing_number_is_grandfathered(self) -> None:
-        """Re-syncing a client's own already-stored number must not raise."""
+        """Re-syncing a company's own already-stored number must not raise."""
         owner = self._client_with_phone("Phone Owner")
-        # A cross-client legacy row exists for the same number (grandfathered),
+        # A cross-company legacy row exists for the same number (grandfathered),
         # inserted bypassing the guard as pre-guard data was.
-        other = Client.objects.create(
+        other = Company.objects.create(
             name="Legacy Other Owner", xero_last_modified=timezone.now()
         )
         legacy = ClientContactMethod(
-            client=other,
+            company=other,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
@@ -324,7 +324,7 @@ def test_resync_of_existing_number_is_grandfathered(self) -> None:
         ClientContactMethod.objects.bulk_create([legacy])
         # owner already stores the number too (its own row).
         owner_method = ClientContactMethod(
-            client=owner,
+            company=owner,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
@@ -344,7 +344,7 @@ def test_user_edited_label_and_primary_survive_resync(self) -> None:
         owner = self._client_with_phone("Phone Owner")
         created = sync_xero_phone_methods(owner)
         self.assertEqual(created, ["+6421555123"])
-        imported_method = ClientContactMethod.objects.get(client=owner)
+        imported_method = ClientContactMethod.objects.get(company=owner)
         self.assertEqual(imported_method.label, "DEFAULT")
         self.assertTrue(imported_method.is_primary)
 
@@ -352,7 +352,7 @@ def test_user_edited_label_and_primary_survive_resync(self) -> None:
         imported_method.label = "Reception"
         imported_method.save()
         local_primary = ClientContactMethod.objects.create(
-            client=owner,
+            company=owner,
             method_type=ClientContactMethod.MethodType.PHONE,
             value="09 555 000",
             label="After hours",
@@ -372,7 +372,7 @@ def test_user_edited_label_and_primary_survive_resync(self) -> None:
     def test_unchanged_resync_does_not_write_the_method_row(self) -> None:
         owner = self._client_with_phone("Phone Owner")
         sync_xero_phone_methods(owner)
-        method = ClientContactMethod.objects.get(client=owner)
+        method = ClientContactMethod.objects.get(company=owner)
         updated_at_before = method.updated_at
 
         with CaptureQueriesContext(connection) as ctx:
@@ -389,7 +389,7 @@ def test_unchanged_resync_does_not_write_the_method_row(self) -> None:
 
     def test_new_xero_number_dispatches_rematch_of_historical_calls(self) -> None:
         """Numbers imported from Xero must attach existing calls, like UI edits."""
-        client = self._client_with_phone("Rematch Client")
+        company = self._client_with_phone("Rematch Company")
         call_datetime = timezone.now()
         call = PhoneCallRecord.objects.create(
             provider_call_id="account:xero-rematch",
@@ -407,15 +407,15 @@ def test_new_xero_number_dispatches_rematch_of_historical_calls(self) -> None:
             side_effect=rematch_calls_for_numbers,
         ) as rematch:
             with self.captureOnCommitCallbacks(execute=True):
-                set_client_fields(client)
+                set_company_fields(company)
 
         rematch.assert_called_once_with(["+6421555123"])
         call.refresh_from_db()
-        self.assertEqual(call.client, client)
+        self.assertEqual(call.company, company)
 
         # An unchanged re-sync creates nothing and must not dispatch a rematch.
         with self.captureOnCommitCallbacks() as callbacks:
-            set_client_fields(client)
+            set_company_fields(company)
         self.assertEqual(callbacks, [])
 
 
diff --git a/apps/workflow/tests/test_xero_document_raw_json.py b/apps/workflow/tests/test_xero_document_raw_json.py
index 5009ef9bb..f9f41b018 100644
--- a/apps/workflow/tests/test_xero_document_raw_json.py
+++ b/apps/workflow/tests/test_xero_document_raw_json.py
@@ -3,7 +3,7 @@
 
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.testing import BaseTestCase
 from apps.workflow.accounting.types import DocumentResult
@@ -33,13 +33,13 @@ def add_history_note_to_quote(self, external_id, note):
 
 class XeroDocumentRawJsonTests(BaseTestCase):
     def setUp(self):
-        self.client_obj = Client.objects.create(
-            name="Raw JSON Client",
+        self.client_obj = Company.objects.create(
+            name="Raw JSON Company",
             xero_contact_id=str(uuid.uuid4()),
             xero_last_modified=timezone.now(),
         )
         self.job = Job.objects.create(
-            client=self.client_obj,
+            company=self.client_obj,
             name="Raw JSON Job",
             pricing_methodology="fixed_price",
             staff=self.test_staff,
@@ -47,7 +47,7 @@ def setUp(self):
 
     def test_created_invoice_stores_canonical_raw_json_dict(self):
         raw_response = {
-            "_contact": {"_name": "Raw JSON Client"},
+            "_contact": {"_name": "Raw JSON Company"},
             "_invoice_id": str(uuid.uuid4()),
             "_invoice_number": "INV-RAW-1",
             "_sub_total": "100.00",
@@ -66,7 +66,7 @@ def test_created_invoice_stores_canonical_raw_json_dict(self):
         )
 
         manager = XeroInvoiceManager(
-            client=self.client_obj,
+            company=self.client_obj,
             job=self.job,
             staff=self.test_staff,
         )
@@ -78,7 +78,7 @@ def test_created_invoice_stores_canonical_raw_json_dict(self):
         self.assertTrue(result["success"])
         invoice = self.job.invoices.get()
         self.assertIsInstance(invoice.raw_json, dict)
-        self.assertEqual(invoice.raw_json["_contact"]["_name"], "Raw JSON Client")
+        self.assertEqual(invoice.raw_json["_contact"]["_name"], "Raw JSON Company")
         self.assertNotIn("full", invoice.raw_json)
         self.assertNotIn("contact", invoice.raw_json)
         self.assertEqual(invoice.total_excl_tax, Decimal("100.00"))
@@ -90,7 +90,7 @@ def test_created_quote_stores_canonical_raw_json_dict(self):
         self.job.latest_quote.summary = {"cost": 0.0, "rev": 250.0, "hours": 0.0}
         self.job.latest_quote.save(update_fields=["summary"])
         raw_response = {
-            "_contact": {"_name": "Raw JSON Client"},
+            "_contact": {"_name": "Raw JSON Company"},
             "_quote_id": str(uuid.uuid4()),
             "_quote_number": "QU-RAW-1",
             "_sub_total": "250.00",
@@ -107,7 +107,7 @@ def test_created_quote_stores_canonical_raw_json_dict(self):
         )
 
         manager = XeroQuoteManager(
-            client=self.client_obj,
+            company=self.client_obj,
             job=self.job,
             staff=self.test_staff,
         )
@@ -118,7 +118,7 @@ def test_created_quote_stores_canonical_raw_json_dict(self):
         self.assertTrue(result["success"])
         quote = self.job.quote
         self.assertIsInstance(quote.raw_json, dict)
-        self.assertEqual(quote.raw_json["_contact"]["_name"], "Raw JSON Client")
+        self.assertEqual(quote.raw_json["_contact"]["_name"], "Raw JSON Company")
         self.assertNotIn("contact", quote.raw_json)
         self.assertEqual(quote.total_excl_tax, Decimal("250.00"))
         self.assertEqual(quote.total_incl_tax, Decimal("287.50"))
diff --git a/apps/workflow/tests/test_xero_po_manager.py b/apps/workflow/tests/test_xero_po_manager.py
index 26c518f76..d66930aa3 100644
--- a/apps/workflow/tests/test_xero_po_manager.py
+++ b/apps/workflow/tests/test_xero_po_manager.py
@@ -20,7 +20,7 @@
 
 from django.utils import timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.purchasing.models import PurchaseOrder
 from apps.testing import BaseAPITestCase
 from apps.workflow.views.xero.xero_po_manager import XeroPurchaseOrderManager
@@ -34,7 +34,7 @@ def setUpTestData(cls):
         cls.test_staff.is_office_staff = True
         cls.test_staff.save(update_fields=["is_office_staff"])
 
-        cls.supplier = Client.objects.create(
+        cls.supplier = Company.objects.create(
             name="Test Supplier",
             xero_contact_id="00000000-0000-0000-0000-000000000001",
             xero_last_modified=timezone.now(),
diff --git a/apps/workflow/tests/test_xero_quota_floor.py b/apps/workflow/tests/test_xero_quota_floor.py
index d68b2e105..e962dfdf5 100644
--- a/apps/workflow/tests/test_xero_quota_floor.py
+++ b/apps/workflow/tests/test_xero_quota_floor.py
@@ -21,7 +21,7 @@
 from django.test import TestCase
 from django.utils import timezone as dj_timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.purchasing.models import Stock
 from apps.workflow.api.xero.client import quota_floor_breached
 from apps.workflow.api.xero.sync import sync_xero_data
@@ -79,13 +79,13 @@ def _set_company_floor(floor=100):
         CompanyDefaults.clear_cache()
         return
 
-    shop_client = Client.objects.create(
-        name="Shop Client",
+    shop_company = Company.objects.create(
+        name="Shop Company",
         xero_last_modified=dj_timezone.now(),
     )
     CompanyDefaults.objects.create(
         company_name="Demo Company",
-        shop_client=shop_client,
+        shop_company=shop_company,
         xero_automated_day_floor=floor,
     )
 
diff --git a/apps/workflow/tests/test_xero_transform_contact_resolution.py b/apps/workflow/tests/test_xero_transform_contact_resolution.py
index 7a6d7432b..09a961451 100644
--- a/apps/workflow/tests/test_xero_transform_contact_resolution.py
+++ b/apps/workflow/tests/test_xero_transform_contact_resolution.py
@@ -5,10 +5,10 @@
 from django.test import TestCase
 from django.utils import timezone as django_timezone
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.workflow.api.xero.transforms import (
     _extract_required_fields_xero,
-    resolve_client_from_xero_contact,
+    resolve_company_from_xero_contact,
     transform_purchase_order,
     transform_quote,
 )
@@ -20,41 +20,41 @@ def _make_contact(contact_id: str, **extra):
 
 class XeroTransformContactResolutionTests(TestCase):
     def setUp(self):
-        self.client = Client.objects.create(
-            name="Existing Client",
+        self.company = Company.objects.create(
+            name="Existing Company",
             xero_contact_id="contact-123",
             xero_last_modified=django_timezone.now(),
         )
 
-    @patch("apps.workflow.api.xero.transforms.get_or_fetch_client")
+    @patch("apps.workflow.api.xero.transforms.get_or_fetch_company")
     def test_resolve_client_uses_embedded_contact_without_follow_up_get(
         self, mock_get_or_fetch
     ):
-        contact = _make_contact("contact-123", name="Existing Client")
+        contact = _make_contact("contact-123", name="Existing Company")
 
-        resolved = resolve_client_from_xero_contact(contact, "INV-001")
+        resolved = resolve_company_from_xero_contact(contact, "INV-001")
 
-        self.assertEqual(resolved.id, self.client.id)
+        self.assertEqual(resolved.id, self.company.id)
         mock_get_or_fetch.assert_not_called()
 
-    @patch("apps.workflow.api.xero.transforms.get_or_fetch_client")
+    @patch("apps.workflow.api.xero.transforms.get_or_fetch_company")
     def test_resolve_client_falls_back_only_when_embedded_contact_missing(
         self, mock_get_or_fetch
     ):
-        mock_get_or_fetch.return_value = self.client
+        mock_get_or_fetch.return_value = self.company
 
-        resolved = resolve_client_from_xero_contact(
+        resolved = resolve_company_from_xero_contact(
             SimpleNamespace(contact_id="contact-123"), "INV-001"
         )
 
-        self.assertEqual(resolved.id, self.client.id)
+        self.assertEqual(resolved.id, self.company.id)
         mock_get_or_fetch.assert_called_once_with("contact-123", "INV-001")
 
-    @patch("apps.workflow.api.xero.transforms.resolve_client_from_xero_contact")
+    @patch("apps.workflow.api.xero.transforms.resolve_company_from_xero_contact")
     def test_invoice_extract_uses_contact_resolver(self, mock_resolve_client):
-        mock_resolve_client.return_value = self.client
+        mock_resolve_client.return_value = self.company
         invoice = SimpleNamespace(
-            contact=_make_contact("contact-123", name="Existing Client"),
+            contact=_make_contact("contact-123", name="Existing Company"),
             invoice_number="INV-001",
             date="2026-05-05",
             sub_total=100,
@@ -66,16 +66,16 @@ def test_invoice_extract_uses_contact_resolver(self, mock_resolve_client):
 
         fields = _extract_required_fields_xero("invoice", invoice, "inv-xero-id")
 
-        self.assertEqual(fields["client"].id, self.client.id)
+        self.assertEqual(fields["company"].id, self.company.id)
         mock_resolve_client.assert_called_once_with(invoice.contact, "INV-001")
 
-    @patch("apps.workflow.api.xero.transforms.resolve_client_from_xero_contact")
+    @patch("apps.workflow.api.xero.transforms.resolve_company_from_xero_contact")
     @patch("apps.workflow.api.xero.transforms.process_xero_data")
     @patch("apps.workflow.api.xero.transforms.Quote.objects.get_or_create")
     def test_quote_transform_uses_contact_resolver(
         self, mock_get_or_create, mock_process_xero_data, mock_resolve_client
     ):
-        mock_resolve_client.return_value = self.client
+        mock_resolve_client.return_value = self.company
         mock_process_xero_data.return_value = {
             "_status": {"_value_": "DRAFT"},
             "_date": "2026-05-05",
@@ -86,7 +86,7 @@ def test_quote_transform_uses_contact_resolver(
         mock_quote = SimpleNamespace(number="Q-001")
         mock_get_or_create.return_value = (mock_quote, True)
         quote = SimpleNamespace(
-            contact=_make_contact("contact-123", name="Existing Client"),
+            contact=_make_contact("contact-123", name="Existing Company"),
             quote_number="Q-001",
         )
 
@@ -96,7 +96,7 @@ def test_quote_transform_uses_contact_resolver(
             quote.contact, "quote quote-xero-id"
         )
 
-    @patch("apps.workflow.api.xero.transforms.resolve_client_from_xero_contact")
+    @patch("apps.workflow.api.xero.transforms.resolve_company_from_xero_contact")
     @patch("apps.workflow.api.xero.transforms.process_xero_data")
     @patch("apps.workflow.api.xero.transforms.PurchaseOrder.objects.filter")
     @patch("apps.workflow.api.xero.transforms.PurchaseOrder.objects.create")
@@ -107,7 +107,7 @@ def test_purchase_order_transform_uses_contact_resolver(
         mock_process_xero_data,
         mock_resolve_client,
     ):
-        mock_resolve_client.return_value = self.client
+        mock_resolve_client.return_value = self.company
         mock_process_xero_data.return_value = {"_line_items": []}
         mock_filter.return_value.first.return_value = None
         mock_po = SimpleNamespace(
@@ -117,7 +117,7 @@ def test_purchase_order_transform_uses_contact_resolver(
         )
         mock_create.return_value = mock_po
         xero_po = SimpleNamespace(
-            contact=_make_contact("contact-123", name="Existing Client"),
+            contact=_make_contact("contact-123", name="Existing Company"),
             purchase_order_number="PO-001",
             date="2026-05-05",
             status="DRAFT",
diff --git a/apps/workflow/views/data_versions_view.py b/apps/workflow/views/data_versions_view.py
index e332ed5f1..aad67ad14 100644
--- a/apps/workflow/views/data_versions_view.py
+++ b/apps/workflow/views/data_versions_view.py
@@ -23,7 +23,7 @@
 from rest_framework.views import APIView
 
 from apps.accounts.models import Staff
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.crm.models import PhoneCallRecord, PhoneCallRecording
 from apps.job.models import Job
 from apps.purchasing.models import Stock
@@ -48,7 +48,7 @@ def _kanban_version() -> str:
     return "|".join(
         [
             _model_version(Job, "updated_at"),
-            _model_version(Client, "django_updated_at"),
+            _model_version(Company, "django_updated_at"),
             _model_version(ClientContact, "updated_at"),
             _model_version(Staff, "updated_at"),
         ]
@@ -62,7 +62,7 @@ def _crm_calls_version() -> str:
         [
             _model_version(PhoneCallRecord, "updated_at"),
             _model_version(PhoneCallRecording, "updated_at"),
-            _model_version(Client, "django_updated_at"),
+            _model_version(Company, "django_updated_at"),
             _model_version(ClientContact, "updated_at"),
             _model_version(Job, "updated_at"),
         ]
diff --git a/apps/workflow/views/search_telemetry_view.py b/apps/workflow/views/search_telemetry_view.py
index 4d065d468..c4e9d03d7 100644
--- a/apps/workflow/views/search_telemetry_view.py
+++ b/apps/workflow/views/search_telemetry_view.py
@@ -39,7 +39,7 @@ def _build_server_error_response(*, message: str, exc: Exception) -> Response:
 @extend_schema_view(
     post=extend_schema(
         summary="Log search result selection",
-        description="Records a selected result from client, Kanban, or stock search.",
+        description="Records a selected result from company, Kanban, or stock search.",
         request=SearchTelemetryClickRequestSerializer,
         responses={200: SearchTelemetryClickResponseSerializer},
         tags=["Search telemetry"],
diff --git a/apps/workflow/views/xero/xero_base_manager.py b/apps/workflow/views/xero/xero_base_manager.py
index eec3cc374..45ed13b99 100644
--- a/apps/workflow/views/xero/xero_base_manager.py
+++ b/apps/workflow/views/xero/xero_base_manager.py
@@ -3,7 +3,7 @@
 from abc import ABC, abstractmethod
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 
 # Import models used in type hints or logic
 from apps.job.models import Job
@@ -20,15 +20,15 @@ class XeroDocumentManager(ABC):
     """
 
     job: Job | None  # Job is optional now
-    client: Client
+    company: Company
     staff: Staff
 
-    def __init__(self, client, staff: Staff, job=None):
+    def __init__(self, company, staff: Staff, job=None):
         """
         Initializes the creator.
 
         Args:
-            client (Client): The client or supplier associated with the document.
+            company (Company): The company or supplier associated with the document.
             staff (Staff): The authenticated staff member performing the action.
                            Used to attribute any Job audit events emitted by
                            create/delete operations.
@@ -36,11 +36,11 @@ def __init__(self, client, staff: Staff, job=None):
                                  Required for document types like Invoice/Quote.
                                  Not directly used for PurchaseOrder at this level.
         """
-        if client is None:
-            raise ValueError("Client cannot be None for XeroDocumentManager")
+        if company is None:
+            raise ValueError("Company cannot be None for XeroDocumentManager")
         if staff is None:
             raise ValueError("Staff cannot be None for XeroDocumentManager")
-        self.client = client
+        self.company = company
         self.staff = staff
         self.job = job  # Optional job association
         self.provider = get_provider()
@@ -93,15 +93,15 @@ def _get_account_code(self, account_name: str = "Sales") -> str | None:
         """
         return self.provider.get_account_code(account_name)
 
-    def validate_client(self):
+    def validate_company(self):
         """
-        Ensures the client exists and is synced with Xero.
+        Ensures the company exists and is synced with Xero.
         """
-        if not self.client:
-            raise ValueError("Client is missing")
-        if not self.client.validate_for_xero():
-            raise ValueError("Client data is not valid for Xero")
-        if not self.client.xero_contact_id:
+        if not self.company:
+            raise ValueError("Company is missing")
+        if not self.company.validate_for_xero():
+            raise ValueError("Company data is not valid for Xero")
+        if not self.company.xero_contact_id:
             raise ValueError(
-                f"Client {self.client.name} does not have a valid Xero contact ID. Sync the client with Xero first."
+                f"Company {self.company.name} does not have a valid Xero contact ID. Sync the company with Xero first."
             )
diff --git a/apps/workflow/views/xero/xero_invoice_manager.py b/apps/workflow/views/xero/xero_invoice_manager.py
index 85fc57156..9cf09f562 100644
--- a/apps/workflow/views/xero/xero_invoice_manager.py
+++ b/apps/workflow/views/xero/xero_invoice_manager.py
@@ -11,7 +11,7 @@
 # Import models
 from apps.accounting.models import Invoice
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.models.costing import CostSet
 from apps.job.services.workshop_pdf_service import create_workshop_pdf
@@ -32,7 +32,7 @@ class XeroInvoiceManager(XeroDocumentManager):
 
     def __init__(
         self,
-        client: Client,
+        company: Company,
         job: Job,
         staff: Staff,
         xero_invoice_id: str | None = None,
@@ -40,15 +40,15 @@ def __init__(
         """
         Initializes the invoice manager.
         Args:
-            client (Client): The client associated with the document.
+            company (Company): The company associated with the document.
             job (Job): The associated job.
             staff (Staff): The authenticated staff member performing the action.
             xero_invoice_id (str, optional): A specific Xero ID to operate on,
                                              useful for deletion of a specific invoice.
         """
-        if not client or not job:
-            raise ValueError("Client and Job are required for XeroInvoiceManager")
-        super().__init__(client=client, job=job, staff=staff)
+        if not company or not job:
+            raise ValueError("Company and Job are required for XeroInvoiceManager")
+        super().__init__(company=company, job=job, staff=staff)
 
         if xero_invoice_id is not None:
             self._xero_id_override = str(xero_invoice_id)
@@ -131,19 +131,19 @@ def get_line_items(
     def _compute_invoice_dates(self) -> tuple[date, date]:
         """Return ``(invoice_date, due_date)`` per the customer's payment terms.
 
-        Account customers (``Client.is_account_customer=True``) are due on
+        Account customers (``Company.is_account_customer=True``) are due on
         the 20th of the calendar month following the invoice date. Cash
         customers are due same-day.
         """
         invoice_date = timezone.localdate()
-        if self.client.is_account_customer:
+        if self.company.is_account_customer:
             due_date = (invoice_date + relativedelta(months=1)).replace(day=20)
         else:
             due_date = invoice_date
         return invoice_date, due_date
 
     def build_payload(self, total_amount: Decimal | None = None) -> InvoicePayload:
-        """Build a provider-agnostic invoice payload from the job and client."""
+        """Build a provider-agnostic invoice payload from the job and company."""
         if not self.job:
             raise ValueError("Job is required to build invoice payload.")
 
@@ -151,8 +151,8 @@ def build_payload(self, total_amount: Decimal | None = None) -> InvoicePayload:
         invoice_date, due_date = self._compute_invoice_dates()
 
         payload = InvoicePayload(
-            client_external_id=self.client.xero_contact_id,
-            client_name=self.client.name,
+            client_external_id=self.company.xero_contact_id,
+            company_name=self.company.name,
             line_items=line_items,
             date=invoice_date,
             due_date=due_date,
@@ -202,7 +202,7 @@ def create_document(
             billing_metadata: Calculation metadata to persist on the Invoice record.
         """
         try:
-            self.validate_client()
+            self.validate_company()
 
             if not self.state_valid_for_xero():
                 raise ValueError("Document is not in a valid state for submission.")
@@ -222,7 +222,7 @@ def create_document(
             invoice_kwargs = {
                 "xero_id": result.external_id,
                 "job": self.job,
-                "client": self.client,
+                "company": self.company,
                 "number": result.number,
                 "date": payload.date,
                 "due_date": payload.due_date,
@@ -294,7 +294,7 @@ def create_document(
                 "success": True,
                 "invoice_id": str(invoice.id),
                 "xero_id": result.external_id,
-                "client": self.client.name,
+                "company": self.company.name,
                 "total_excl_tax": str(invoice.total_excl_tax),
                 "total_incl_tax": str(invoice.total_incl_tax),
                 "online_url": result.online_url,
@@ -319,7 +319,7 @@ def create_document(
     def delete_document(self):
         """Deletes an invoice via the provider and removes the local record."""
         try:
-            self.validate_client()
+            self.validate_company()
             xero_id = self.get_xero_id()
             if not xero_id:
                 raise ValueError("Cannot delete invoice without a Xero ID.")
diff --git a/apps/workflow/views/xero/xero_po_manager.py b/apps/workflow/views/xero/xero_po_manager.py
index 847ad7389..8bc9a72e7 100644
--- a/apps/workflow/views/xero/xero_po_manager.py
+++ b/apps/workflow/views/xero/xero_po_manager.py
@@ -19,7 +19,7 @@ class XeroPurchaseOrderManager(XeroDocumentManager):
     """Xero PO sync handler using the accounting provider."""
 
     def __init__(self, purchase_order: PurchaseOrder, staff: Staff):
-        super().__init__(client=purchase_order.supplier, staff=staff, job=None)
+        super().__init__(company=purchase_order.supplier, staff=staff, job=None)
         self.purchase_order = purchase_order
 
     def can_sync_to_xero(self) -> bool:
@@ -151,8 +151,8 @@ def build_payload(self) -> POPayload:
                 delivery_date = date.fromisoformat(delivery_date)
 
         return POPayload(
-            supplier_external_id=self.client.xero_contact_id,
-            supplier_name=self.client.name,
+            supplier_external_id=self.company.xero_contact_id,
+            supplier_name=self.company.name,
             po_number=self.purchase_order.po_number,
             line_items=line_items,
             date=order_date,
diff --git a/apps/workflow/views/xero/xero_quote_manager.py b/apps/workflow/views/xero/xero_quote_manager.py
index 158c0b38d..c5ec23088 100644
--- a/apps/workflow/views/xero/xero_quote_manager.py
+++ b/apps/workflow/views/xero/xero_quote_manager.py
@@ -25,18 +25,18 @@ class XeroQuoteManager(XeroDocumentManager):
     Handles Quote creation and syncing via the accounting provider.
     """
 
-    def __init__(self, client, job, staff):
+    def __init__(self, company, job, staff):
         """
-        Initializes the quote manager. Client, job, and staff are all required.
+        Initializes the quote manager. Company, job, and staff are all required.
 
         Args:
-            client: The client associated with the quote.
+            company: The company associated with the quote.
             job: The associated job.
             staff: The authenticated staff member performing the action.
         """
-        if not client or not job:
-            raise ValueError("Client and Job are required for XeroQuoteManager")
-        super().__init__(client=client, job=job, staff=staff)
+        if not company or not job:
+            raise ValueError("Company and Job are required for XeroQuoteManager")
+        super().__init__(company=company, job=job, staff=staff)
 
     def get_xero_id(self):
         return (
@@ -122,7 +122,7 @@ def get_line_items(self, breakdown: bool = True) -> list[DocumentLineItem]:
             ]
 
     def build_payload(self, breakdown: bool = True) -> QuotePayload:
-        """Build a provider-agnostic quote payload from the job and client."""
+        """Build a provider-agnostic quote payload from the job and company."""
         if not self.job:
             raise ValueError("Job is required to build quote payload.")
 
@@ -130,8 +130,8 @@ def build_payload(self, breakdown: bool = True) -> QuotePayload:
         today = timezone.localdate()
 
         return QuotePayload(
-            client_external_id=self.client.xero_contact_id,
-            client_name=self.client.name,
+            client_external_id=self.company.xero_contact_id,
+            company_name=self.company.name,
             line_items=line_items,
             date=today,
             expiry_date=today + timedelta(days=30),
@@ -150,7 +150,7 @@ def create_document(self, breakdown: bool = True):
             breakdown: If True, sends detailed line items. If False, sends single total.
         """
         try:
-            self.validate_client()
+            self.validate_company()
 
             if not self.state_valid_for_xero():
                 raise ValueError("Document is not in a valid state for submission.")
@@ -170,7 +170,7 @@ def create_document(self, breakdown: bool = True):
             quote = Quote.objects.create(
                 xero_id=result.external_id,
                 job=self.job,
-                client=self.client,
+                company=self.company,
                 date=timezone.localdate(),
                 status=QuoteStatus.DRAFT,
                 number=result.number,
@@ -209,7 +209,7 @@ def create_document(self, breakdown: bool = True):
             return {
                 "success": True,
                 "xero_id": result.external_id,
-                "client": self.client.name,
+                "company": self.company.name,
                 "online_url": result.online_url,
             }
 
@@ -227,7 +227,7 @@ def create_document(self, breakdown: bool = True):
     def delete_document(self):
         """Deletes a quote via the provider and removes the local record."""
         try:
-            self.validate_client()
+            self.validate_company()
             xero_id = self.get_xero_id()
             if not xero_id:
                 raise ValueError("Cannot delete quote without a Xero ID.")
diff --git a/apps/workflow/views/xero/xero_view.py b/apps/workflow/views/xero/xero_view.py
index 592881840..663c279a9 100644
--- a/apps/workflow/views/xero/xero_view.py
+++ b/apps/workflow/views/xero/xero_view.py
@@ -447,7 +447,7 @@ def create_xero_invoice(request: Request, job_id: uuid.UUID) -> Response:
         if calc_result.requested_amount is not None:
             billing_metadata["requested_amount"] = str(calc_result.requested_amount)
 
-        manager = XeroInvoiceManager(client=job.client, job=job, staff=request.user)
+        manager = XeroInvoiceManager(company=job.company, job=job, staff=request.user)
         result_data = manager.create_document(
             total_amount=calc_result.calculated_amount,
             billing_metadata=billing_metadata,
@@ -693,7 +693,7 @@ def create_xero_quote(request: Request, job_id: uuid.UUID) -> Response:
 
     try:
         job = Job.objects.get(id=job_id)
-        manager = XeroQuoteManager(client=job.client, job=job, staff=request.user)
+        manager = XeroQuoteManager(company=job.company, job=job, staff=request.user)
         result_data = manager.create_document(breakdown=breakdown)
 
         if result_data.get("success"):
@@ -766,7 +766,7 @@ def delete_xero_invoice(request: Request, job_id: uuid.UUID) -> Response:
         job = Job.objects.get(id=job_id)
         invoice = Invoice.objects.get(xero_id=xero_invoice_id, job=job)
         manager = XeroInvoiceManager(
-            client=job.client,
+            company=job.company,
             job=job,
             staff=request.user,
             xero_invoice_id=invoice.xero_id,
@@ -827,7 +827,7 @@ def delete_xero_quote(request: Request, job_id: uuid.UUID) -> Response:
 
     try:
         job = Job.objects.get(id=job_id)
-        manager = XeroQuoteManager(client=job.client, job=job, staff=request.user)
+        manager = XeroQuoteManager(company=job.company, job=job, staff=request.user)
         result_data: dict = manager.delete_document()
 
         if result_data.get("success"):
diff --git a/docketworks/settings.py b/docketworks/settings.py
index c939403b3..68d841498 100644
--- a/docketworks/settings.py
+++ b/docketworks/settings.py
@@ -187,7 +187,7 @@ def validate_required_settings() -> None:
     "apps.timesheet.apps.TimesheetConfig",
     "apps.job.apps.JobConfig",
     "apps.quoting.apps.QuotingConfig",
-    "apps.client.apps.ClientConfig",
+    "apps.company.apps.CompanyConfig",
     "apps.crm.apps.CrmConfig",
     "apps.purchasing.apps.PurchasingConfig",
     "apps.process.apps.ProcessConfig",
@@ -415,7 +415,7 @@ def require_positive_int_env(name: str) -> int:
             os.path.join(BASE_DIR, "apps/accounts/templates"),
             os.path.join(BASE_DIR, "apps/timesheet/templates"),
             os.path.join(BASE_DIR, "apps/job/templates"),
-            os.path.join(BASE_DIR, "apps/client/templates"),
+            os.path.join(BASE_DIR, "apps/company/templates"),
             os.path.join(BASE_DIR, "apps/purchasing/templates"),
             os.path.join(BASE_DIR, "apps/accounting/templates"),
             os.path.join(BASE_DIR, "apps/quoting/templates"),
diff --git a/docketworks/urls.py b/docketworks/urls.py
index 382e28118..56524f778 100644
--- a/docketworks/urls.py
+++ b/docketworks/urls.py
@@ -11,7 +11,7 @@
     path(
         "api/quoting/", include(("apps.quoting.urls", "quoting"), namespace="quoting")
     ),
-    path("api/clients/", include("apps.client.urls_rest", namespace="clients")),
+    path("api/companies/", include("apps.company.urls_rest", namespace="companies")),
     path("api/crm/", include("apps.crm.urls", namespace="crm")),
     path("api/purchasing/", include("apps.purchasing.urls", namespace="purchasing")),
     path("api/accounting/", include("apps.accounting.urls", namespace="accounting")),
diff --git a/docs/architecture.md b/docs/architecture.md
index 3dd32d18e..2bdb0182b 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -78,10 +78,10 @@ The system is organized into focused Django apps, each handling specific busines
   - Password strength validation (minimum 10 characters)
   - Role-based permissions and authentication
 
-#### **`client`** - (Minimal) Customer Relationship Management
+#### **`company`** - (Minimal) Customer Relationship Management
 
 - **Purpose**: Customer data and (future) contact management
-- **Key Models**: Client
+- **Key Models**: Company
 - **Responsibilities**:
   - Bidirectional Xero contact synchronization
   - Contact person and communication history
@@ -135,7 +135,7 @@ erDiagram
     JobPricing ||--o{ TimeEntry : "tracks time"
     JobPricing ||--o{ MaterialEntry : "uses materials"
     Staff ||--o{ TimeEntry : "logs time"
-    Client ||--o{ Job : "requests work"
+    Company ||--o{ Job : "requests work"
     PurchaseOrder ||--o{ PurchaseOrderLine : "contains items"
     PurchaseOrderLine ||--o{ Stock : "creates inventory"
     Stock ||--o{ MaterialEntry : "used in jobs"
@@ -145,7 +145,7 @@ erDiagram
         string status
         text description
         datetime created_at
-        uuid client_id FK
+        uuid company_id FK
     }
 
     JobPricing {
@@ -218,7 +218,7 @@ Located in `frontend/`:
 
 ```
 /api/jobs/                 - Job CRUD operations
-/api/clients/              - Client management
+/api/companies/            - Company management
 /api/timesheets/           - Time entry operations
 /api/purchasing/           - Purchase order management
 /api/xero/                 - Xero integration endpoints
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index 1d3a7b62d..e7a2e2868 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -87,7 +87,7 @@ PGPASSWORD="$DB_PASSWORD" pg_restore --no-owner --no-privileges --exit-on-error
 PGPASSWORD="$DB_PASSWORD" psql -U "$DB_USER" "$DB_NAME" -c "
 SELECT 'job_job' as table_name, COUNT(*) as count FROM job_job
 UNION ALL SELECT 'accounts_staff', COUNT(*) FROM accounts_staff
-UNION ALL SELECT 'client_client', COUNT(*) FROM client_client
+UNION ALL SELECT 'company_company', COUNT(*) FROM company_company
 UNION ALL SELECT 'job_costset', COUNT(*) FROM job_costset
 UNION ALL SELECT 'job_costline', COUNT(*) FROM job_costline;
 "
@@ -100,7 +100,7 @@ UNION ALL SELECT 'job_costline', COUNT(*) FROM job_costline;
 ----------------+-------
  job_job         |  1054
  accounts_staff  |    20
- client_client   |  3739
+ company_company |  3739
  job_costset     |  3162
  job_costline    | 10334
 ```
@@ -116,7 +116,7 @@ python scripts/restore_checks/check_django_orm.py
 ```
 Jobs: ~1400
 Staff: ~22
-Clients: ~4800
+Companies: ~4800
 Sample job: [any real job name] (#XXXXX)
 Contact: [any real contact name]
 ```
@@ -175,21 +175,21 @@ Creates a default admin user and resets all staff passwords to defaults.
 python scripts/recreate_jobfiles.py
 ```
 
-#### Fix Shop Client Name
+#### Fix Shop Company Name
 
 ```bash
-python scripts/restore_checks/fix_shop_client.py
+python scripts/restore_checks/fix_shop_company.py
 ```
 
-#### Create Test Client
+#### Create Test Company
 
-Creates the test client named per `CompanyDefaults.test_client_name` (e.g. `ABC Carpet Cleaning TEST IGNORE`) if it isn't already there. Idempotent. Required by Seed Database to Xero, which crashes if the client is missing.
+Creates the test company named per `CompanyDefaults.test_company_name` (e.g. `ABC Carpet Cleaning TEST IGNORE`) if it isn't already there. Idempotent. Required by Seed Database to Xero, which crashes if the company is missing.
 
 ```bash
-python scripts/fix_test_client.py
+python scripts/fix_test_company.py
 ```
 
-**Expected output:** `Test client already exists: …` or `Created test client: …`.
+**Expected output:** `Test company already exists: …` or `Created test company: …`.
 
 #### Connect to Xero OAuth
 
@@ -246,10 +246,10 @@ echo "Background process started, PID: $!"
 ```
 
 **What this does:**
-1. Clears production Xero IDs (clients, jobs, stock, purchase orders, staff)
+1. Clears production Xero IDs (companies, jobs, stock, purchase orders, staff)
 2. Updates XeroAccount xero_ids from prod to dev Xero tenant (fetches from dev Xero, upserts by account_name)
 3. Remaps XeroPayItem FK references (Job.default_xero_pay_item, CostLine.xero_pay_item) from prod UUIDs to dev UUIDs by matching pay item names
-4. Links/creates contacts in Xero for all clients
+4. Links/creates contacts in Xero for all companies
 5. Creates projects in Xero for all jobs
 6. Deletes orphaned invoices, re-creates job-linked invoices in dev Xero
 7. Deletes orphaned quotes, re-creates job-linked quotes in dev Xero
@@ -297,7 +297,7 @@ Must show `active (running)`. The Beat startup banner shows the loaded schedule;
 for s in scripts/restore_checks/check_*.py; do python "$s"; done
 ```
 
-**Expected output:** Each script prints its own success line and exits zero. Covers: Django ORM (`check_django_orm.py`), admin user (`check_admin_user.py`), company defaults (`check_company_defaults.py`), AI providers (`check_ai_providers.py`), JobFiles (`check_jobfiles.py`), shop client (`check_shop_client.py`), test client (`check_test_client.py`), Xero app (`check_xero_app.py`), Xero accounts (`check_xero_accounts.py`), Xero seed (`check_xero_seed.py`).
+**Expected output:** Each script prints its own success line and exits zero. Covers: Django ORM (`check_django_orm.py`), admin user (`check_admin_user.py`), company defaults (`check_company_defaults.py`), AI providers (`check_ai_providers.py`), JobFiles (`check_jobfiles.py`), shop company (`check_shop_company.py`), test company (`check_test_company.py`), Xero app (`check_xero_app.py`), Xero accounts (`check_xero_accounts.py`), Xero seed (`check_xero_seed.py`).
 
 Any non-zero exit means the upstream mutation step that should have produced that state silently failed — fix the underlying problem, do not re-run just the failing check.
 
diff --git a/docs/urls/company.md b/docs/urls/company.md
new file mode 100644
index 000000000..6ec6bd2f7
--- /dev/null
+++ b/docs/urls/company.md
@@ -0,0 +1,56 @@
+# Company URLs Documentation
+
+<!-- This file is auto-generated. To regenerate, run: python scripts/generate_url_docs.py -->
+
+### Addresses Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/addresses/validate/` | `address_views.AddressValidateView` | `companies:address_validate` | Validate and clean an address using Google Address Validation API. |
+
+### All Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/all/` | `company_rest_views.CompanyListAllRestView` | `companies:company_list_all_rest` | REST view for listing all companies. |
+
+### Company-Defaults Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/company-defaults/schema/` | `company_defaults_schema_api.CompanyDefaultsSchemaAPIView` | `api_company_defaults_schema` | API endpoint that returns field metadata for CompanyDefaults. |
+| `/company-defaults/upload-logo/` | `company_defaults_logo_api.CompanyDefaultsLogoAPIView` | `api_company_defaults_upload_logo` | API view for uploading and deleting company logo images. |
+
+### Create Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/create/` | `company_rest_views.CompanyCreateRestView` | `companies:company_create_rest` | REST view for creating new companies. |
+
+### Jobs Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:company_id>/jobs/` | `company_rest_views.CompanyJobsRestView` | `companies:company_jobs_rest` | REST view for fetching all jobs for a specific company. |
+| `/jobs/<uuid:job_id>/contact/` | `company_rest_views.JobContactRestView` | `companies:job_contact_rest` | REST view for contact information operations for a job. |
+
+### Other
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:company_id>/` | `company_rest_views.CompanyRetrieveRestView` | `companies:company_retrieve_rest` | REST view for retrieving a specific company by ID. |
+
+### Search Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/search/` | `company_rest_views.CompanySearchRestView` | `companies:company_search_rest` | REST view for company search with pagination and sorting. |
+
+### Supplier-Aliases Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:company_id>/supplier-aliases/` | `supplier_search_alias_views.CompanySupplierAliasListCreateView` | `companies:company_supplier_aliases_rest` | List and create search aliases for a company/supplier contact. |
+| `/supplier-aliases/<uuid:alias_id>/` | `supplier_search_alias_views.SupplierAliasDetailView` | `companies:supplier_alias_detail_rest` | Deactivate a supplier search alias. |
+
+### System
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/company-defaults/` | `company_defaults_api.CompanyDefaultsAPIView` | `api_company_defaults` | API view for managing company default settings. |
+
+### Update Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:company_id>/update/` | `company_rest_views.CompanyUpdateRestView` | `companies:company_update_rest` | REST view for updating company information. |
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 979a80896..35f7beca6 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -371,7 +371,7 @@ paths:
                         date:
                           type: string
                           format: date
-                        client_name:
+                        company_name:
                           type: string
                         job_number:
                           type: integer
@@ -1134,21 +1134,21 @@ paths:
               schema:
                 $ref: '#/components/schemas/BuildId'
           description: ''
-  /api/clients/{client_id}/:
+  /api/companies/{company_id}/:
     get:
-      operationId: clients_retrieve
-      description: Retrieve detailed information for a specific client.
-      summary: Get client details
+      operationId: companies_retrieve
+      description: Retrieve detailed information for a specific company.
+      summary: Get company details
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
-          description: UUID of the client
+          description: UUID of the company
           required: true
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -1156,35 +1156,35 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientDetailResponse'
+                $ref: '#/components/schemas/CompanyDetailResponse'
           description: ''
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/{client_id}/jobs/:
+  /api/companies/{company_id}/jobs/:
     get:
-      operationId: clients_jobs_retrieve
-      description: Retrieve all jobs for a specific client.
-      summary: Get client jobs
+      operationId: companies_jobs_retrieve
+      description: Retrieve all jobs for a specific company.
+      summary: Get company jobs
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
-          description: UUID of the client
+          description: UUID of the company
           required: true
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -1192,34 +1192,34 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientJobsResponse'
+                $ref: '#/components/schemas/CompanyJobsResponse'
           description: ''
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/{client_id}/supplier-aliases/:
+  /api/companies/{company_id}/supplier-aliases/:
     get:
-      operationId: clients_supplier_aliases_list
-      description: List and create search aliases for a client/supplier contact.
+      operationId: companies_supplier_aliases_list
+      description: List and create search aliases for a company/supplier contact.
       summary: List supplier search aliases
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
           required: true
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -1232,18 +1232,18 @@ paths:
                   $ref: '#/components/schemas/SupplierSearchAlias'
           description: ''
     post:
-      operationId: clients_supplier_aliases_create
-      description: List and create search aliases for a client/supplier contact.
+      operationId: companies_supplier_aliases_create
+      description: List and create search aliases for a company/supplier contact.
       summary: Create supplier search alias
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
           required: true
       tags:
-        - Clients
+        - Companies
       requestBody:
         content:
           application/json:
@@ -1265,32 +1265,32 @@ paths:
               schema:
                 $ref: '#/components/schemas/SupplierSearchAlias'
           description: ''
-  /api/clients/{client_id}/update/:
+  /api/companies/{company_id}/update/:
     put:
-      operationId: clients_update_update
-      description: Update an existing client's information.
-      summary: Update client
+      operationId: companies_update_update
+      description: Update an existing company's information.
+      summary: Update company
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
-          description: UUID of the client
+          description: UUID of the company
           required: true
       tags:
-        - Clients
+        - Companies
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientUpdateRequest'
+              $ref: '#/components/schemas/CompanyUpdateRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientUpdateRequest'
+              $ref: '#/components/schemas/CompanyUpdateRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientUpdateRequest'
+              $ref: '#/components/schemas/CompanyUpdateRequest'
       security:
         - cookieAuth: []
       responses:
@@ -1298,51 +1298,51 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientUpdateResponse'
+                $ref: '#/components/schemas/CompanyUpdateResponse'
           description: ''
         '400':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
     patch:
-      operationId: clients_update_partial_update
-      description: Partially update an existing client's information.
-      summary: Partially update client
+      operationId: companies_update_partial_update
+      description: Partially update an existing company's information.
+      summary: Partially update company
       parameters:
         - in: path
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
-          description: UUID of the client
+          description: UUID of the company
           required: true
       tags:
-        - Clients
+        - Companies
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/PatchedClientUpdateRequest'
+              $ref: '#/components/schemas/PatchedCompanyUpdateRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/PatchedClientUpdateRequest'
+              $ref: '#/components/schemas/PatchedCompanyUpdateRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/PatchedClientUpdateRequest'
+              $ref: '#/components/schemas/PatchedCompanyUpdateRequest'
       security:
         - cookieAuth: []
       responses:
@@ -1350,32 +1350,32 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientUpdateResponse'
+                $ref: '#/components/schemas/CompanyUpdateResponse'
           description: ''
         '400':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/addresses/validate/:
+  /api/companies/addresses/validate/:
     post:
-      operationId: clients_addresses_validate_create
+      operationId: companies_addresses_validate_create
       description: Validate an address and return structured candidates.
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1434,14 +1434,14 @@ paths:
               schema:
                 description: Google API unavailable or not configured
           description: ''
-  /api/clients/all/:
+  /api/companies/all/:
     get:
-      operationId: clients_all_list
-      description: Returns a list of all clients with basic information (id and name)
-        for dropdowns and search.
-      summary: List all clients
+      operationId: companies_all_list
+      description: Returns a list of all companies with basic information (id and
+        name) for dropdowns and search.
+      summary: List all companies
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -1451,21 +1451,21 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ClientNameOnly'
+                  $ref: '#/components/schemas/CompanyNameOnly'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/contact-methods/:
+  /api/companies/contact-methods/:
     get:
-      operationId: clients_contact_methods_list
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_list
+      description: CRUD API for canonical company/contact phone and email methods.
       parameters:
         - in: query
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
@@ -1487,7 +1487,7 @@ paths:
           schema:
             type: integer
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -1498,10 +1498,10 @@ paths:
                 $ref: '#/components/schemas/PaginatedClientContactMethodList'
           description: ''
     post:
-      operationId: clients_contact_methods_create
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_create
+      description: CRUD API for canonical company/contact phone and email methods.
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1523,10 +1523,10 @@ paths:
               schema:
                 $ref: '#/components/schemas/ClientContactMethod'
           description: ''
-  /api/clients/contact-methods/{id}/:
+  /api/companies/contact-methods/{id}/:
     get:
-      operationId: clients_contact_methods_retrieve
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_retrieve
+      description: CRUD API for canonical company/contact phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1536,7 +1536,7 @@ paths:
           description: A UUID string identifying this Client Contact Method.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -1547,8 +1547,8 @@ paths:
                 $ref: '#/components/schemas/ClientContactMethod'
           description: ''
     put:
-      operationId: clients_contact_methods_update
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_update
+      description: CRUD API for canonical company/contact phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1558,7 +1558,7 @@ paths:
           description: A UUID string identifying this Client Contact Method.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1581,8 +1581,8 @@ paths:
                 $ref: '#/components/schemas/ClientContactMethod'
           description: ''
     patch:
-      operationId: clients_contact_methods_partial_update
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_partial_update
+      description: CRUD API for canonical company/contact phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1592,7 +1592,7 @@ paths:
           description: A UUID string identifying this Client Contact Method.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1614,8 +1614,8 @@ paths:
                 $ref: '#/components/schemas/ClientContactMethod'
           description: ''
     delete:
-      operationId: clients_contact_methods_destroy
-      description: CRUD API for canonical client/contact phone and email methods.
+      operationId: companies_contact_methods_destroy
+      description: CRUD API for canonical company/contact phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1625,25 +1625,25 @@ paths:
           description: A UUID string identifying this Client Contact Method.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
         '204':
           description: No response body
-  /api/clients/contacts/:
+  /api/companies/contacts/:
     get:
-      operationId: clients_contacts_list
-      description: List all contacts, optionally filtered by client_id.
+      operationId: companies_contacts_list
+      description: List all contacts, optionally filtered by company_id.
       parameters:
         - in: query
-          name: client_id
+          name: company_id
           schema:
             type: string
             format: uuid
-          description: Filter contacts by client UUID
+          description: Filter contacts by company UUID
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -1656,22 +1656,22 @@ paths:
                   $ref: '#/components/schemas/ClientContact'
           description: ''
     post:
-      operationId: clients_contacts_create
+      operationId: companies_contacts_create
       description: |-
         ViewSet for ClientContact CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/contacts/           - list all contacts
-        - POST   /api/clients/contacts/           - create contact
-        - GET    /api/clients/contacts/<id>/      - retrieve contact
-        - PUT    /api/clients/contacts/<id>/      - full update
-        - PATCH  /api/clients/contacts/<id>/      - partial update
-        - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/contacts/           - list all contacts
+        - POST   /api/companies/contacts/           - create contact
+        - GET    /api/companies/contacts/<id>/      - retrieve contact
+        - PUT    /api/companies/contacts/<id>/      - full update
+        - PATCH  /api/companies/contacts/<id>/      - partial update
+        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - client_id: Filter contacts by client UUID
+        - company_id: Filter contacts by company UUID
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1693,22 +1693,22 @@ paths:
               schema:
                 $ref: '#/components/schemas/ClientContact'
           description: ''
-  /api/clients/contacts/{id}/:
+  /api/companies/contacts/{id}/:
     get:
-      operationId: clients_contacts_retrieve
+      operationId: companies_contacts_retrieve
       description: |-
         ViewSet for ClientContact CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/contacts/           - list all contacts
-        - POST   /api/clients/contacts/           - create contact
-        - GET    /api/clients/contacts/<id>/      - retrieve contact
-        - PUT    /api/clients/contacts/<id>/      - full update
-        - PATCH  /api/clients/contacts/<id>/      - partial update
-        - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/contacts/           - list all contacts
+        - POST   /api/companies/contacts/           - create contact
+        - GET    /api/companies/contacts/<id>/      - retrieve contact
+        - PUT    /api/companies/contacts/<id>/      - full update
+        - PATCH  /api/companies/contacts/<id>/      - partial update
+        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - client_id: Filter contacts by client UUID
+        - company_id: Filter contacts by company UUID
       parameters:
         - in: path
           name: id
@@ -1718,7 +1718,7 @@ paths:
           description: A UUID string identifying this Client Contact.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -1729,20 +1729,20 @@ paths:
                 $ref: '#/components/schemas/ClientContact'
           description: ''
     put:
-      operationId: clients_contacts_update
+      operationId: companies_contacts_update
       description: |-
         ViewSet for ClientContact CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/contacts/           - list all contacts
-        - POST   /api/clients/contacts/           - create contact
-        - GET    /api/clients/contacts/<id>/      - retrieve contact
-        - PUT    /api/clients/contacts/<id>/      - full update
-        - PATCH  /api/clients/contacts/<id>/      - partial update
-        - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/contacts/           - list all contacts
+        - POST   /api/companies/contacts/           - create contact
+        - GET    /api/companies/contacts/<id>/      - retrieve contact
+        - PUT    /api/companies/contacts/<id>/      - full update
+        - PATCH  /api/companies/contacts/<id>/      - partial update
+        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - client_id: Filter contacts by client UUID
+        - company_id: Filter contacts by company UUID
       parameters:
         - in: path
           name: id
@@ -1752,7 +1752,7 @@ paths:
           description: A UUID string identifying this Client Contact.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1775,20 +1775,20 @@ paths:
                 $ref: '#/components/schemas/ClientContact'
           description: ''
     patch:
-      operationId: clients_contacts_partial_update
+      operationId: companies_contacts_partial_update
       description: |-
         ViewSet for ClientContact CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/contacts/           - list all contacts
-        - POST   /api/clients/contacts/           - create contact
-        - GET    /api/clients/contacts/<id>/      - retrieve contact
-        - PUT    /api/clients/contacts/<id>/      - full update
-        - PATCH  /api/clients/contacts/<id>/      - partial update
-        - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/contacts/           - list all contacts
+        - POST   /api/companies/contacts/           - create contact
+        - GET    /api/companies/contacts/<id>/      - retrieve contact
+        - PUT    /api/companies/contacts/<id>/      - full update
+        - PATCH  /api/companies/contacts/<id>/      - partial update
+        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - client_id: Filter contacts by client UUID
+        - company_id: Filter contacts by company UUID
       parameters:
         - in: path
           name: id
@@ -1798,7 +1798,7 @@ paths:
           description: A UUID string identifying this Client Contact.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -1820,20 +1820,20 @@ paths:
                 $ref: '#/components/schemas/ClientContact'
           description: ''
     delete:
-      operationId: clients_contacts_destroy
+      operationId: companies_contacts_destroy
       description: |-
         ViewSet for ClientContact CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/contacts/           - list all contacts
-        - POST   /api/clients/contacts/           - create contact
-        - GET    /api/clients/contacts/<id>/      - retrieve contact
-        - PUT    /api/clients/contacts/<id>/      - full update
-        - PATCH  /api/clients/contacts/<id>/      - partial update
-        - DELETE /api/clients/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/contacts/           - list all contacts
+        - POST   /api/companies/contacts/           - create contact
+        - GET    /api/companies/contacts/<id>/      - retrieve contact
+        - PUT    /api/companies/contacts/<id>/      - full update
+        - PATCH  /api/companies/contacts/<id>/      - partial update
+        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - client_id: Filter contacts by client UUID
+        - company_id: Filter contacts by company UUID
       parameters:
         - in: path
           name: id
@@ -1843,31 +1843,31 @@ paths:
           description: A UUID string identifying this Client Contact.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
         '204':
           description: No response body
-  /api/clients/create/:
+  /api/companies/create/:
     post:
-      operationId: clients_create_create
-      description: Creates a new client in Xero first, then syncs locally. Requires
+      operationId: companies_create_create
+      description: Creates a new company in Xero first, then syncs locally. Requires
         valid Xero authentication.
-      summary: Create a new client
+      summary: Create a new company
       tags:
-        - Clients
+        - Companies
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientCreateRequest'
+              $ref: '#/components/schemas/CompanyCreateRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientCreateRequest'
+              $ref: '#/components/schemas/CompanyCreateRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientCreateRequest'
+              $ref: '#/components/schemas/CompanyCreateRequest'
         required: true
       security:
         - cookieAuth: []
@@ -1876,35 +1876,35 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientCreateResponse'
+                $ref: '#/components/schemas/CompanyCreateResponse'
           description: ''
         '400':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '401':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '409':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientDuplicateErrorResponse'
+                $ref: '#/components/schemas/CompanyDuplicateErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/jobs/{job_id}/contact/:
+  /api/companies/jobs/{job_id}/contact/:
     get:
-      operationId: clients_jobs_contact_retrieve
+      operationId: companies_jobs_contact_retrieve
       description: Retrieve contact information for a specific job.
       summary: Get job contact
       parameters:
@@ -1916,7 +1916,7 @@ paths:
           description: UUID of the job
           required: true
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -1930,16 +1930,16 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
     put:
-      operationId: clients_jobs_contact_update
+      operationId: companies_jobs_contact_update
       description: Update the contact person associated with a specific job.
       summary: Update job contact
       parameters:
@@ -1951,7 +1951,7 @@ paths:
           description: UUID of the job
           required: true
       tags:
-        - Clients
+        - Companies
       requestBody:
         content:
           application/json:
@@ -1977,23 +1977,23 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/pickup-addresses/:
+  /api/companies/pickup-addresses/:
     get:
-      operationId: clients_pickup_addresses_list
+      operationId: companies_pickup_addresses_list
       description: List all pickup addresses, optionally filtered by supplier_id.
       parameters:
         - in: query
@@ -2003,7 +2003,7 @@ paths:
             format: uuid
           description: Filter addresses by supplier UUID
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -2016,22 +2016,22 @@ paths:
                   $ref: '#/components/schemas/SupplierPickupAddress'
           description: ''
     post:
-      operationId: clients_pickup_addresses_create
+      operationId: companies_pickup_addresses_create
       description: |-
         ViewSet for SupplierPickupAddress CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/pickup-addresses/           - list all addresses
-        - POST   /api/clients/pickup-addresses/           - create address
-        - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-        - PUT    /api/clients/pickup-addresses/<id>/      - full update
-        - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-        - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/pickup-addresses/           - list all addresses
+        - POST   /api/companies/pickup-addresses/           - create address
+        - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+        - PUT    /api/companies/pickup-addresses/<id>/      - full update
+        - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+        - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - supplier_id: Filter addresses by supplier (client) UUID
+        - supplier_id: Filter addresses by supplier (company) UUID
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -2053,22 +2053,22 @@ paths:
               schema:
                 $ref: '#/components/schemas/SupplierPickupAddress'
           description: ''
-  /api/clients/pickup-addresses/{id}/:
+  /api/companies/pickup-addresses/{id}/:
     get:
-      operationId: clients_pickup_addresses_retrieve
+      operationId: companies_pickup_addresses_retrieve
       description: |-
         ViewSet for SupplierPickupAddress CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/pickup-addresses/           - list all addresses
-        - POST   /api/clients/pickup-addresses/           - create address
-        - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-        - PUT    /api/clients/pickup-addresses/<id>/      - full update
-        - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-        - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/pickup-addresses/           - list all addresses
+        - POST   /api/companies/pickup-addresses/           - create address
+        - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+        - PUT    /api/companies/pickup-addresses/<id>/      - full update
+        - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+        - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - supplier_id: Filter addresses by supplier (client) UUID
+        - supplier_id: Filter addresses by supplier (company) UUID
       parameters:
         - in: path
           name: id
@@ -2078,7 +2078,7 @@ paths:
           description: A UUID string identifying this Supplier Pickup Address.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
@@ -2089,20 +2089,20 @@ paths:
                 $ref: '#/components/schemas/SupplierPickupAddress'
           description: ''
     put:
-      operationId: clients_pickup_addresses_update
+      operationId: companies_pickup_addresses_update
       description: |-
         ViewSet for SupplierPickupAddress CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/pickup-addresses/           - list all addresses
-        - POST   /api/clients/pickup-addresses/           - create address
-        - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-        - PUT    /api/clients/pickup-addresses/<id>/      - full update
-        - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-        - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/pickup-addresses/           - list all addresses
+        - POST   /api/companies/pickup-addresses/           - create address
+        - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+        - PUT    /api/companies/pickup-addresses/<id>/      - full update
+        - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+        - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - supplier_id: Filter addresses by supplier (client) UUID
+        - supplier_id: Filter addresses by supplier (company) UUID
       parameters:
         - in: path
           name: id
@@ -2112,7 +2112,7 @@ paths:
           description: A UUID string identifying this Supplier Pickup Address.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -2135,20 +2135,20 @@ paths:
                 $ref: '#/components/schemas/SupplierPickupAddress'
           description: ''
     patch:
-      operationId: clients_pickup_addresses_partial_update
+      operationId: companies_pickup_addresses_partial_update
       description: |-
         ViewSet for SupplierPickupAddress CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/pickup-addresses/           - list all addresses
-        - POST   /api/clients/pickup-addresses/           - create address
-        - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-        - PUT    /api/clients/pickup-addresses/<id>/      - full update
-        - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-        - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/pickup-addresses/           - list all addresses
+        - POST   /api/companies/pickup-addresses/           - create address
+        - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+        - PUT    /api/companies/pickup-addresses/<id>/      - full update
+        - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+        - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - supplier_id: Filter addresses by supplier (client) UUID
+        - supplier_id: Filter addresses by supplier (company) UUID
       parameters:
         - in: path
           name: id
@@ -2158,7 +2158,7 @@ paths:
           description: A UUID string identifying this Supplier Pickup Address.
           required: true
       tags:
-        - clients
+        - companies
       requestBody:
         content:
           application/json:
@@ -2180,20 +2180,20 @@ paths:
                 $ref: '#/components/schemas/SupplierPickupAddress'
           description: ''
     delete:
-      operationId: clients_pickup_addresses_destroy
+      operationId: companies_pickup_addresses_destroy
       description: |-
         ViewSet for SupplierPickupAddress CRUD operations.
 
         Endpoints:
-        - GET    /api/clients/pickup-addresses/           - list all addresses
-        - POST   /api/clients/pickup-addresses/           - create address
-        - GET    /api/clients/pickup-addresses/<id>/      - retrieve address
-        - PUT    /api/clients/pickup-addresses/<id>/      - full update
-        - PATCH  /api/clients/pickup-addresses/<id>/      - partial update
-        - DELETE /api/clients/pickup-addresses/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/pickup-addresses/           - list all addresses
+        - POST   /api/companies/pickup-addresses/           - create address
+        - GET    /api/companies/pickup-addresses/<id>/      - retrieve address
+        - PUT    /api/companies/pickup-addresses/<id>/      - full update
+        - PATCH  /api/companies/pickup-addresses/<id>/      - partial update
+        - DELETE /api/companies/pickup-addresses/<id>/      - soft delete (sets is_active=False)
 
         Query Parameters:
-        - supplier_id: Filter addresses by supplier (client) UUID
+        - supplier_id: Filter addresses by supplier (company) UUID
       parameters:
         - in: path
           name: id
@@ -2203,17 +2203,17 @@ paths:
           description: A UUID string identifying this Supplier Pickup Address.
           required: true
       tags:
-        - clients
+        - companies
       security:
         - cookieAuth: []
       responses:
         '204':
           description: No response body
-  /api/clients/search/:
+  /api/companies/search/:
     get:
-      operationId: clients_search_retrieve
-      description: Lists/searches clients with pagination and sorting.
-      summary: Search clients
+      operationId: companies_search_retrieve
+      description: Lists/searches companies with pagination and sorting.
+      summary: Search companies
       parameters:
         - in: query
           name: page
@@ -2230,7 +2230,7 @@ paths:
           schema:
             type: string
           description: Search query (case-insensitive substring match). If empty, returns
-            all clients.
+            all companies.
         - in: query
           name: sort_by
           schema:
@@ -2242,7 +2242,7 @@ paths:
             type: string
           description: "Sort direction: 'asc' or 'desc' (default 'asc')"
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -2250,17 +2250,17 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientSearchResponse'
+                $ref: '#/components/schemas/CompanySearchResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/clients/supplier-aliases/{alias_id}/:
+  /api/companies/supplier-aliases/{alias_id}/:
     delete:
-      operationId: clients_supplier_aliases_destroy
+      operationId: companies_supplier_aliases_destroy
       description: Deactivate a supplier search alias.
       summary: Deactivate supplier search alias
       parameters:
@@ -2271,7 +2271,7 @@ paths:
             format: uuid
           required: true
       tags:
-        - Clients
+        - Companies
       security:
         - cookieAuth: []
       responses:
@@ -2574,14 +2574,14 @@ paths:
       operationId: crm_phone_calls_list
       parameters:
         - in: query
-          name: client
+          name: client_match
           schema:
             type: string
-            format: uuid
         - in: query
-          name: client_match
+          name: company
           schema:
             type: string
+            format: uuid
         - in: query
           name: contact
           schema:
@@ -3147,7 +3147,7 @@ paths:
   /api/job/data-quality/duplicate-phones/:
     get:
       operationId: check_duplicate_phones
-      description: List phone numbers owned by more than one client, or client numbers
+      description: List phone numbers owned by more than one company, or company numbers
         that are actually internal company lines.
       summary: Check duplicate phone ownership
       tags:
@@ -4924,10 +4924,10 @@ paths:
       description: Endpoint for advanced job search - API endpoint.
       parameters:
         - in: query
-          name: client_name
+          name: company_name
           schema:
             type: string
-          description: Filter by client name
+          description: Filter by company name
         - in: query
           name: contact_person
           schema:
@@ -4978,7 +4978,7 @@ paths:
           schema:
             type: string
           description: Universal search - searches across job number, name, description,
-            and client name with OR logic
+            and company name with OR logic
         - in: query
           name: rejected_flag
           schema:
@@ -7659,7 +7659,7 @@ paths:
       description: |-
         Return latest price upload status per supplier.
 
-        Minimal-impact: read-only query over existing Client and SupplierPriceList
+        Minimal-impact: read-only query over existing Company and SupplierPriceList
         models. No migrations required.
       tags:
         - purchasing
@@ -7868,7 +7868,7 @@ paths:
   /api/search-events/click/:
     post:
       operationId: search_events_click_create
-      description: Records a selected result from client, Kanban, or stock search.
+      description: Records a selected result from company, Kanban, or stock search.
       summary: Log search result selection
       tags:
         - Search telemetry
@@ -8121,7 +8121,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
   /api/timesheets/payroll/pay-runs/create:
     post:
@@ -8155,19 +8155,19 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '409':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
   /api/timesheets/payroll/pay-runs/refresh:
     post:
@@ -8189,7 +8189,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
   /api/timesheets/payroll/post-staff-week/:
     post:
@@ -8226,7 +8226,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
   /api/timesheets/staff/:
     get:
@@ -8312,13 +8312,13 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
         '500':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientErrorResponse'
+                $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
   /api/workflow/ai-providers/:
     get:
@@ -9957,9 +9957,9 @@ components:
         job_number:
           type: string
           description: Job number
-        client_name:
+        company_name:
           type: string
-          description: Client name or 'Shop Job'
+          description: Company name or 'Shop Job'
         archived_date:
           type: string
           format: date
@@ -9994,7 +9994,7 @@ components:
           description: Total job value (invoiced amount or quote/actual revenue)
       required:
         - archived_date
-        - client_name
+        - company_name
         - current_status
         - issue
         - job_id
@@ -10187,10 +10187,10 @@ components:
           type: string
           format: uuid
           readOnly: true
-        client:
+        company:
           type: string
           format: uuid
-          description: The client this contact belongs to
+          description: The company this contact belongs to
         name:
           type: string
           description: Full name of the contact person
@@ -10208,7 +10208,7 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the client
+          description: Indicates if this is the primary contact for the company
         notes:
           type: string
           nullable: true
@@ -10227,7 +10227,7 @@ components:
           format: date-time
           readOnly: true
       required:
-        - client
+        - company
         - created_at
         - id
         - is_active
@@ -10235,20 +10235,20 @@ components:
         - updated_at
     ClientContactMethod:
       type: object
-      description: Serializer for canonical client/contact phone and email methods.
+      description: Serializer for canonical company/contact phone and email methods.
       properties:
         id:
           type: string
           format: uuid
           readOnly: true
-        client:
+        company:
           type: string
           format: uuid
           nullable: true
-        owner_client:
+        owner_company:
           type: string
           readOnly: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
         contact:
@@ -10283,20 +10283,20 @@ components:
           format: date-time
           readOnly: true
       required:
-        - client_name
+        - company_name
         - contact_name
         - created_at
         - id
         - method_type
         - normalized_value
-        - owner_client
+        - owner_company
         - updated_at
         - value
     ClientContactMethodRequest:
       type: object
-      description: Serializer for canonical client/contact phone and email methods.
+      description: Serializer for canonical company/contact phone and email methods.
       properties:
-        client:
+        company:
           type: string
           format: uuid
           nullable: true
@@ -10333,10 +10333,10 @@ components:
       type: object
       description: Serializer for ClientContact model.
       properties:
-        client:
+        company:
           type: string
           format: uuid
-          description: The client this contact belongs to
+          description: The company this contact belongs to
         name:
           type: string
           minLength: 1
@@ -10355,17 +10355,17 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the client
+          description: Indicates if this is the primary contact for the company
         notes:
           type: string
           nullable: true
           description: Additional notes about this contact
       required:
-        - client
+        - company
         - name
-    ClientCreateRequest:
+    CompanyCreateRequest:
       type: object
-      description: Serializer for client creation request
+      description: Serializer for company creation request
       properties:
         name:
           type: string
@@ -10386,609 +10386,335 @@ components:
           default: true
       required:
         - name
-    ClientCreateResponse:
+    CompanyCreateResponse:
       type: object
-      description: Serializer for client creation response
+      description: Serializer for company creation response
       properties:
         success:
           type: boolean
-        client:
-          $ref: '#/components/schemas/ClientSearchResult'
+        company:
+          $ref: '#/components/schemas/CompanySearchResult'
         message:
           type: string
       required:
-        - client
+        - company
         - message
         - success
-    ClientDetailResponse:
+    CompanyDefaults:
       type: object
-      description: Serializer for client detail response
       properties:
         id:
+          type: integer
+          readOnly: true
+        logo_url:
           type: string
-        name:
+          nullable: true
+          readOnly: true
+        logo_wide_url:
           type: string
-        email:
+          nullable: true
+          readOnly: true
+        company_name:
           type: string
-        address:
+          readOnly: true
+        company_acronym:
           type: string
-        is_account_customer:
-          type: boolean
-        is_supplier:
-          type: boolean
-        allow_jobs:
-          type: boolean
-        xero_contact_id:
+          nullable: true
+          description: Short acronym for the company (e.g., 'MSM' for Morris Sheetmetal)
+          maxLength: 10
+        time_markup:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+        materials_markup:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+        wage_rate:
+          type: number
+          format: double
+          maximum: 10000
+          minimum: -10000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+        annual_leave_loading:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          description: Percentage added to base_wage_rate to get costing wage_rate
+            (20.00 = 20%)
+        workshop_efficiency_factor:
+          type: number
+          format: double
+          maximum: 10
+          minimum: -10
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          description: Fraction of clocked workshop hours that count as schedulable
+            productive output (e.g. 0.750 = 75%). Accounts for breaks, tool changes,
+            idle time. Applied to per-day capacity in the workshop scheduler after
+            subtracting booked time/leave.
+        financial_year_start_month:
+          type: integer
+          maximum: 2147483647
+          minimum: -2147483648
+          description: Month the financial year starts (1=January, 4=April, 7=July,
+            etc.)
+        starting_job_number:
+          type: integer
+          maximum: 2147483647
+          minimum: -2147483648
+          description: Helper field to set the starting job number based on the latest
+            paper job
+        starting_po_number:
+          type: integer
+          maximum: 2147483647
+          minimum: -2147483648
+          description: Helper field to set the starting purchase order number
+        po_prefix:
           type: string
-        xero_tenant_id:
+          description: Prefix for purchase order numbers (e.g., PO-, JO-)
+          maxLength: 10
+        master_quote_template_url:
           type: string
-        primary_contact_name:
+          format: uri
+          nullable: true
+          description: URL to the master Google Sheets quote template
+          maxLength: 200
+        master_quote_template_id:
           type: string
-        primary_contact_email:
+          nullable: true
+          description: Google Sheets ID for the quote template
+          maxLength: 100
+        gdrive_quotes_folder_url:
           type: string
-        additional_contact_persons:
-          type: array
-          items: {}
-        xero_last_modified:
+          format: uri
+          nullable: true
+          description: URL to the Google Drive folder for storing quotes
+          maxLength: 200
+        gdrive_quotes_folder_id:
           type: string
-          format: date-time
           nullable: true
-        xero_last_synced:
+          description: Google Drive folder ID for storing quotes
+          maxLength: 100
+        google_shared_drive_id:
           type: string
-          format: date-time
           nullable: true
-        xero_archived:
-          type: boolean
-        xero_merged_into_id:
+          description: Google Shared Drive ID for the company shared drive
+          maxLength: 100
+        gdrive_how_we_work_folder_id:
           type: string
-        merged_into:
+          nullable: true
+          description: Folder ID for '01 - How we work' (policies, basics)
+          maxLength: 100
+        gdrive_sops_folder_id:
           type: string
           nullable: true
-        django_created_at:
+          description: Folder ID for '02 - SOPs' (standard operating procedures)
+          maxLength: 100
+        gdrive_reference_library_folder_id:
           type: string
-          format: date-time
-        django_updated_at:
+          nullable: true
+          description: Folder ID for '03 - Reference Library' (reference documents,
+            forms, registers)
+          maxLength: 100
+        accounting_provider:
           type: string
-          format: date-time
-        last_invoice_date:
+          description: "Active accounting integration: 'xero' or 'myob'"
+          maxLength: 20
+        xero_tenant_id:
           type: string
-          format: date-time
           nullable: true
-        total_spend:
-          type: string
-      required:
-        - address
-        - allow_jobs
-        - django_created_at
-        - django_updated_at
-        - email
-        - id
-        - is_account_customer
-        - is_supplier
-        - last_invoice_date
-        - merged_into
-        - name
-        - primary_contact_email
-        - primary_contact_name
-        - total_spend
-        - xero_archived
-        - xero_contact_id
-        - xero_last_modified
-        - xero_last_synced
-        - xero_merged_into_id
-        - xero_tenant_id
-    ClientDuplicateErrorResponse:
-      type: object
-      description: Serializer for client duplicate error response
-      properties:
-        success:
-          type: boolean
-          default: false
-        error:
+          description: The Xero tenant ID to use for this company
+          maxLength: 100
+        xero_shortcode:
           type: string
-        existing_client:
-          type: object
-          additionalProperties: {}
-      required:
-        - error
-        - existing_client
-    ClientErrorResponse:
-      type: object
-      description: Serializer for client error responses
-      properties:
-        success:
+          nullable: true
+          description: Xero organisation shortcode for deep linking (e.g., '!8-5Xl')
+          maxLength: 20
+        enable_xero_sync:
           type: boolean
-          default: false
-        error:
-          type: string
-        details:
+          description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
+            False; seed_xero_from_database sets True after prod IDs are cleared.
+        xero_automated_day_floor:
+          type: integer
+          maximum: 2147483647
+          minimum: 0
+          description: Reserve this many Xero daily API calls for user-initiated work.
+            Automated sync aborts when the active Xero app reports remaining daily
+            calls at or below this value.
+        xero_payroll_calendar_name:
           type: string
-      required:
-        - error
-    ClientJobHeader:
-      type: object
-      description: Serializer for job header in client jobs list.
-      properties:
-        job_id:
+          description: Name of Xero Payroll calendar to use (e.g., 'Weekly 2025')
+          maxLength: 100
+        xero_payroll_calendar_id:
           type: string
           format: uuid
-        job_number:
-          type: integer
-        name:
-          type: string
-        client:
-          type: object
-          additionalProperties: {}
           nullable: true
-        status:
-          type: string
-        pricing_methodology:
+          description: Cached Xero Payroll calendar ID (set by xero --setup command)
+        xero_payroll_start_date:
           type: string
+          format: date
           nullable: true
-        speed_quality_tradeoff:
-          type: string
-        fully_invoiced:
-          type: boolean
-        has_quote_in_xero:
+          description: Date Xero payroll went live — reconciliation ignores data before
+            this
+        weekend_timesheets_enabled:
           type: boolean
-        is_fixed_price:
+          description: Show Saturday and Sunday in timesheet views (7-day week). Off
+            = 5-day Mon-Fri.
+        job_delta_soft_fail:
           type: boolean
-        quote_acceptance_date:
+          description: When enabled, job delta checksum mismatches are logged and
+            recorded without blocking the save. Disable to reject stale updates.
+        mon_start:
           type: string
-          format: date-time
-          nullable: true
-        paid:
-          type: boolean
-        rejected_flag:
-          type: boolean
-        min_people:
-          type: integer
-        max_people:
-          type: integer
-      required:
-        - client
-        - fully_invoiced
-        - has_quote_in_xero
-        - is_fixed_price
-        - job_id
-        - job_number
-        - max_people
-        - min_people
-        - name
-        - paid
-        - pricing_methodology
-        - quote_acceptance_date
-        - rejected_flag
-        - speed_quality_tradeoff
-        - status
-    ClientJobsResponse:
-      type: object
-      description: Serializer for client jobs list response
-      properties:
-        results:
-          type: array
-          items:
-            $ref: '#/components/schemas/ClientJobHeader'
-      required:
-        - results
-    ClientNameOnly:
-      type: object
-      properties:
-        id:
+          format: time
+        mon_end:
           type: string
-          format: uuid
-          readOnly: true
-        name:
+          format: time
+        tue_start:
           type: string
-          readOnly: true
-      required:
-        - id
-        - name
-    ClientSearchResponse:
-      type: object
-      description: Serializer for paginated client search response
-      properties:
-        results:
-          type: array
-          items:
-            $ref: '#/components/schemas/ClientSearchResult'
-        count:
-          type: integer
-        page:
-          type: integer
-        page_size:
-          type: integer
-        total_pages:
-          type: integer
-      required:
-        - count
-        - page
-        - page_size
-        - results
-        - total_pages
-    ClientSearchResult:
-      type: object
-      description: Serializer for individual client search result
-      properties:
-        id:
+          format: time
+        tue_end:
           type: string
-        name:
+          format: time
+        wed_start:
           type: string
-        email:
+          format: time
+        wed_end:
           type: string
-        address:
+          format: time
+        thu_start:
           type: string
-        is_account_customer:
-          type: boolean
-        is_supplier:
-          type: boolean
-        allow_jobs:
-          type: boolean
-        xero_contact_id:
+          format: time
+        thu_end:
           type: string
-        last_invoice_date:
+          format: time
+        fri_start:
+          type: string
+          format: time
+        fri_end:
+          type: string
+          format: time
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+        updated_at:
+          type: string
+          format: date-time
+          readOnly: true
+        last_xero_sync:
           type: string
           format: date-time
           nullable: true
-        total_spend:
+          description: The last time Xero data was synchronized
+        last_xero_deep_sync:
           type: string
-      required:
-        - address
-        - allow_jobs
-        - email
-        - id
-        - is_account_customer
-        - is_supplier
-        - last_invoice_date
-        - name
-        - total_spend
-        - xero_contact_id
-    ClientUpdateRequest:
-      type: object
-      description: Serializer for client update request
-      properties:
-        name:
+          format: date-time
+          nullable: true
+          description: The last time a deep Xero sync was performed (looking back
+            90 days)
+        address_line1:
           type: string
-          minLength: 1
+          nullable: true
+          description: Street address line 1
           maxLength: 255
-        email:
+        address_line2:
           type: string
-          format: email
-        address:
+          nullable: true
+          description: Street address line 2 (optional)
+          maxLength: 255
+        suburb:
           type: string
-        is_account_customer:
-          type: boolean
-        allow_jobs:
-          type: boolean
-    ClientUpdateResponse:
-      type: object
-      description: Serializer for client update response
-      properties:
-        success:
-          type: boolean
-        client:
-          $ref: '#/components/schemas/ClientDetailResponse'
-        message:
+          nullable: true
+          description: Suburb (for NZ addresses)
+          maxLength: 100
+        city:
           type: string
-      required:
-        - client
-        - message
-        - success
-    CompanyDefaults:
-      type: object
-      properties:
-        id:
-          type: integer
-          readOnly: true
-        logo_url:
+          nullable: true
+          description: City
+          maxLength: 100
+        post_code:
           type: string
           nullable: true
-          readOnly: true
-        logo_wide_url:
+          description: Postal/ZIP code
+          maxLength: 20
+        country:
+          type: string
+          description: Country name
+          maxLength: 100
+        company_email:
           type: string
+          format: email
           nullable: true
-          readOnly: true
-        company_name:
+          description: Company contact email address
+          maxLength: 254
+        company_url:
           type: string
-          readOnly: true
-        company_acronym:
+          format: uri
+          nullable: true
+          description: Company website URL
+          maxLength: 200
+        test_company_name:
           type: string
           nullable: true
-          description: Short acronym for the company (e.g., 'MSM' for Morris Sheetmetal)
-          maxLength: 10
-        time_markup:
+          description: Name of the test company used for testing (e.g., 'ABC Carpet
+            Cleaning TEST IGNORE'). This company's name is preserved during data backports.
+          maxLength: 255
+        kpi_daily_billable_hours_green:
           type: number
           format: double
           maximum: 1000
           minimum: -1000
           exclusiveMaximum: true
           exclusiveMinimum: true
-        materials_markup:
+          title: Daily billable hours (green)
+          description: Daily total billable hours across all staff above which the
+            day is green
+        kpi_daily_billable_hours_amber:
           type: number
           format: double
           maximum: 1000
           minimum: -1000
           exclusiveMaximum: true
           exclusiveMinimum: true
-        wage_rate:
+          title: Daily billable hours (amber)
+          description: Daily total billable hours across all staff above which the
+            day is amber
+        kpi_daily_gp_target:
           type: number
           format: double
-          maximum: 10000
-          minimum: -10000
+          maximum: 100000000
+          minimum: -100000000
           exclusiveMaximum: true
           exclusiveMinimum: true
-        annual_leave_loading:
+          title: Daily gross profit target
+          description: Daily gross profit target in dollars
+        kpi_daily_shop_hours_percentage:
           type: number
           format: double
           maximum: 1000
           minimum: -1000
           exclusiveMaximum: true
           exclusiveMinimum: true
-          description: Percentage added to base_wage_rate to get costing wage_rate
-            (20.00 = 20%)
-        workshop_efficiency_factor:
+          title: Daily shop hours percentage target
+          description: Target percentage of daily hours spent on shop (non-billable)
+            jobs
+        kpi_job_gp_target_percentage:
           type: number
           format: double
-          maximum: 10
-          minimum: -10
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          description: Fraction of clocked workshop hours that count as schedulable
-            productive output (e.g. 0.750 = 75%). Accounts for breaks, tool changes,
-            idle time. Applied to per-day capacity in the workshop scheduler after
-            subtracting booked time/leave.
-        financial_year_start_month:
-          type: integer
-          maximum: 2147483647
-          minimum: -2147483648
-          description: Month the financial year starts (1=January, 4=April, 7=July,
-            etc.)
-        starting_job_number:
-          type: integer
-          maximum: 2147483647
-          minimum: -2147483648
-          description: Helper field to set the starting job number based on the latest
-            paper job
-        starting_po_number:
-          type: integer
-          maximum: 2147483647
-          minimum: -2147483648
-          description: Helper field to set the starting purchase order number
-        po_prefix:
-          type: string
-          description: Prefix for purchase order numbers (e.g., PO-, JO-)
-          maxLength: 10
-        master_quote_template_url:
-          type: string
-          format: uri
-          nullable: true
-          description: URL to the master Google Sheets quote template
-          maxLength: 200
-        master_quote_template_id:
-          type: string
-          nullable: true
-          description: Google Sheets ID for the quote template
-          maxLength: 100
-        gdrive_quotes_folder_url:
-          type: string
-          format: uri
-          nullable: true
-          description: URL to the Google Drive folder for storing quotes
-          maxLength: 200
-        gdrive_quotes_folder_id:
-          type: string
-          nullable: true
-          description: Google Drive folder ID for storing quotes
-          maxLength: 100
-        google_shared_drive_id:
-          type: string
-          nullable: true
-          description: Google Shared Drive ID for the company shared drive
-          maxLength: 100
-        gdrive_how_we_work_folder_id:
-          type: string
-          nullable: true
-          description: Folder ID for '01 - How we work' (policies, basics)
-          maxLength: 100
-        gdrive_sops_folder_id:
-          type: string
-          nullable: true
-          description: Folder ID for '02 - SOPs' (standard operating procedures)
-          maxLength: 100
-        gdrive_reference_library_folder_id:
-          type: string
-          nullable: true
-          description: Folder ID for '03 - Reference Library' (reference documents,
-            forms, registers)
-          maxLength: 100
-        accounting_provider:
-          type: string
-          description: "Active accounting integration: 'xero' or 'myob'"
-          maxLength: 20
-        xero_tenant_id:
-          type: string
-          nullable: true
-          description: The Xero tenant ID to use for this company
-          maxLength: 100
-        xero_shortcode:
-          type: string
-          nullable: true
-          description: Xero organisation shortcode for deep linking (e.g., '!8-5Xl')
-          maxLength: 20
-        enable_xero_sync:
-          type: boolean
-          description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
-            False; seed_xero_from_database sets True after prod IDs are cleared.
-        xero_automated_day_floor:
-          type: integer
-          maximum: 2147483647
-          minimum: 0
-          description: Reserve this many Xero daily API calls for user-initiated work.
-            Automated sync aborts when the active Xero app reports remaining daily
-            calls at or below this value.
-        xero_payroll_calendar_name:
-          type: string
-          description: Name of Xero Payroll calendar to use (e.g., 'Weekly 2025')
-          maxLength: 100
-        xero_payroll_calendar_id:
-          type: string
-          format: uuid
-          nullable: true
-          description: Cached Xero Payroll calendar ID (set by xero --setup command)
-        xero_payroll_start_date:
-          type: string
-          format: date
-          nullable: true
-          description: Date Xero payroll went live — reconciliation ignores data before
-            this
-        weekend_timesheets_enabled:
-          type: boolean
-          description: Show Saturday and Sunday in timesheet views (7-day week). Off
-            = 5-day Mon-Fri.
-        job_delta_soft_fail:
-          type: boolean
-          description: When enabled, job delta checksum mismatches are logged and
-            recorded without blocking the save. Disable to reject stale updates.
-        mon_start:
-          type: string
-          format: time
-        mon_end:
-          type: string
-          format: time
-        tue_start:
-          type: string
-          format: time
-        tue_end:
-          type: string
-          format: time
-        wed_start:
-          type: string
-          format: time
-        wed_end:
-          type: string
-          format: time
-        thu_start:
-          type: string
-          format: time
-        thu_end:
-          type: string
-          format: time
-        fri_start:
-          type: string
-          format: time
-        fri_end:
-          type: string
-          format: time
-        created_at:
-          type: string
-          format: date-time
-          readOnly: true
-        updated_at:
-          type: string
-          format: date-time
-          readOnly: true
-        last_xero_sync:
-          type: string
-          format: date-time
-          nullable: true
-          description: The last time Xero data was synchronized
-        last_xero_deep_sync:
-          type: string
-          format: date-time
-          nullable: true
-          description: The last time a deep Xero sync was performed (looking back
-            90 days)
-        address_line1:
-          type: string
-          nullable: true
-          description: Street address line 1
-          maxLength: 255
-        address_line2:
-          type: string
-          nullable: true
-          description: Street address line 2 (optional)
-          maxLength: 255
-        suburb:
-          type: string
-          nullable: true
-          description: Suburb (for NZ addresses)
-          maxLength: 100
-        city:
-          type: string
-          nullable: true
-          description: City
-          maxLength: 100
-        post_code:
-          type: string
-          nullable: true
-          description: Postal/ZIP code
-          maxLength: 20
-        country:
-          type: string
-          description: Country name
-          maxLength: 100
-        company_email:
-          type: string
-          format: email
-          nullable: true
-          description: Company contact email address
-          maxLength: 254
-        company_url:
-          type: string
-          format: uri
-          nullable: true
-          description: Company website URL
-          maxLength: 200
-        test_client_name:
-          type: string
-          nullable: true
-          description: Name of the test client used for testing (e.g., 'ABC Carpet
-            Cleaning TEST IGNORE'). This client's name is preserved during data backports.
-          maxLength: 255
-        kpi_daily_billable_hours_green:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily billable hours (green)
-          description: Daily total billable hours across all staff above which the
-            day is green
-        kpi_daily_billable_hours_amber:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily billable hours (amber)
-          description: Daily total billable hours across all staff above which the
-            day is amber
-        kpi_daily_gp_target:
-          type: number
-          format: double
-          maximum: 100000000
-          minimum: -100000000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily gross profit target
-          description: Daily gross profit target in dollars
-        kpi_daily_shop_hours_percentage:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily shop hours percentage target
-          description: Target percentage of daily hours spent on shop (non-billable)
-            jobs
-        kpi_job_gp_target_percentage:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
+          maximum: 1000
+          minimum: -1000
           exclusiveMaximum: true
           exclusiveMinimum: true
           title: Target GP % per job
@@ -11020,17 +10746,17 @@ components:
           exclusiveMinimum: true
           description: Target daily hours of newly-approved work flowing into the
             shop, used by the Sales Pipeline scoreboard
-        shop_client:
+        shop_company:
           type: string
           format: uuid
-          description: Internal client used for tracking shop work.
+          description: Internal company used for tracking shop work.
       required:
         - company_name
         - created_at
         - id
         - logo_url
         - logo_wide_url
-        - shop_client
+        - shop_company
         - updated_at
     CompanyDefaultsJobDetail:
       type: object
@@ -11258,154 +10984,428 @@ components:
           format: time
         last_xero_sync:
           type: string
-          format: date-time
-          nullable: true
-          description: The last time Xero data was synchronized
-        last_xero_deep_sync:
+          format: date-time
+          nullable: true
+          description: The last time Xero data was synchronized
+        last_xero_deep_sync:
+          type: string
+          format: date-time
+          nullable: true
+          description: The last time a deep Xero sync was performed (looking back
+            90 days)
+        address_line1:
+          type: string
+          nullable: true
+          description: Street address line 1
+          maxLength: 255
+        address_line2:
+          type: string
+          nullable: true
+          description: Street address line 2 (optional)
+          maxLength: 255
+        suburb:
+          type: string
+          nullable: true
+          description: Suburb (for NZ addresses)
+          maxLength: 100
+        city:
+          type: string
+          nullable: true
+          description: City
+          maxLength: 100
+        post_code:
+          type: string
+          nullable: true
+          description: Postal/ZIP code
+          maxLength: 20
+        country:
+          type: string
+          minLength: 1
+          description: Country name
+          maxLength: 100
+        company_email:
+          type: string
+          format: email
+          nullable: true
+          description: Company contact email address
+          maxLength: 254
+        company_url:
+          type: string
+          format: uri
+          nullable: true
+          description: Company website URL
+          maxLength: 200
+        test_company_name:
+          type: string
+          nullable: true
+          description: Name of the test company used for testing (e.g., 'ABC Carpet
+            Cleaning TEST IGNORE'). This company's name is preserved during data backports.
+          maxLength: 255
+        kpi_daily_billable_hours_green:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily billable hours (green)
+          description: Daily total billable hours across all staff above which the
+            day is green
+        kpi_daily_billable_hours_amber:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily billable hours (amber)
+          description: Daily total billable hours across all staff above which the
+            day is amber
+        kpi_daily_gp_target:
+          type: number
+          format: double
+          maximum: 100000000
+          minimum: -100000000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily gross profit target
+          description: Daily gross profit target in dollars
+        kpi_daily_shop_hours_percentage:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily shop hours percentage target
+          description: Target percentage of daily hours spent on shop (non-billable)
+            jobs
+        kpi_job_gp_target_percentage:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Target GP % per job
+          description: Target gross profit percentage for individual jobs
+        kpi_daily_gp_green:
+          type: number
+          format: double
+          maximum: 100000000
+          minimum: -100000000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily GP (green)
+          description: Daily gross profit above which the day is green
+        kpi_daily_gp_amber:
+          type: number
+          format: double
+          maximum: 100000000
+          minimum: -100000000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          title: Daily GP (amber)
+          description: Daily gross profit above which the day is amber
+        daily_approved_hours_target:
+          type: number
+          format: double
+          maximum: 1000
+          minimum: -1000
+          exclusiveMaximum: true
+          exclusiveMinimum: true
+          description: Target daily hours of newly-approved work flowing into the
+            shop, used by the Sales Pipeline scoreboard
+        shop_company:
+          type: string
+          format: uuid
+          description: Internal company used for tracking shop work.
+      required:
+        - shop_company
+    CompanyDefaultsSchema:
+      type: object
+      description: Serializer for the complete schema response.
+      properties:
+        sections:
+          type: array
+          items:
+            $ref: '#/components/schemas/SettingsSection'
+      required:
+        - sections
+    CompanyDetailResponse:
+      type: object
+      description: Serializer for company detail response
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+        address:
+          type: string
+        is_account_customer:
+          type: boolean
+        is_supplier:
+          type: boolean
+        allow_jobs:
+          type: boolean
+        xero_contact_id:
+          type: string
+        xero_tenant_id:
+          type: string
+        primary_contact_name:
+          type: string
+        primary_contact_email:
+          type: string
+        additional_contact_persons:
+          type: array
+          items: {}
+        xero_last_modified:
+          type: string
+          format: date-time
+          nullable: true
+        xero_last_synced:
+          type: string
+          format: date-time
+          nullable: true
+        xero_archived:
+          type: boolean
+        xero_merged_into_id:
+          type: string
+        merged_into:
+          type: string
+          nullable: true
+        django_created_at:
+          type: string
+          format: date-time
+        django_updated_at:
+          type: string
+          format: date-time
+        last_invoice_date:
+          type: string
+          format: date-time
+          nullable: true
+        total_spend:
+          type: string
+      required:
+        - address
+        - allow_jobs
+        - django_created_at
+        - django_updated_at
+        - email
+        - id
+        - is_account_customer
+        - is_supplier
+        - last_invoice_date
+        - merged_into
+        - name
+        - primary_contact_email
+        - primary_contact_name
+        - total_spend
+        - xero_archived
+        - xero_contact_id
+        - xero_last_modified
+        - xero_last_synced
+        - xero_merged_into_id
+        - xero_tenant_id
+    CompanyDuplicateErrorResponse:
+      type: object
+      description: Serializer for company duplicate error response
+      properties:
+        success:
+          type: boolean
+          default: false
+        error:
+          type: string
+        existing_company:
+          type: object
+          additionalProperties: {}
+      required:
+        - error
+        - existing_company
+    CompanyErrorResponse:
+      type: object
+      description: Serializer for company error responses
+      properties:
+        success:
+          type: boolean
+          default: false
+        error:
+          type: string
+        details:
+          type: string
+      required:
+        - error
+    CompanyJobHeader:
+      type: object
+      description: Serializer for job header in company jobs list.
+      properties:
+        job_id:
+          type: string
+          format: uuid
+        job_number:
+          type: integer
+        name:
+          type: string
+        company:
+          type: object
+          additionalProperties: {}
+          nullable: true
+        status:
+          type: string
+        pricing_methodology:
+          type: string
+          nullable: true
+        speed_quality_tradeoff:
+          type: string
+        fully_invoiced:
+          type: boolean
+        has_quote_in_xero:
+          type: boolean
+        is_fixed_price:
+          type: boolean
+        quote_acceptance_date:
+          type: string
+          format: date-time
+          nullable: true
+        paid:
+          type: boolean
+        rejected_flag:
+          type: boolean
+        min_people:
+          type: integer
+        max_people:
+          type: integer
+      required:
+        - company
+        - fully_invoiced
+        - has_quote_in_xero
+        - is_fixed_price
+        - job_id
+        - job_number
+        - max_people
+        - min_people
+        - name
+        - paid
+        - pricing_methodology
+        - quote_acceptance_date
+        - rejected_flag
+        - speed_quality_tradeoff
+        - status
+    CompanyJobsResponse:
+      type: object
+      description: Serializer for company jobs list response
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompanyJobHeader'
+      required:
+        - results
+    CompanyNameOnly:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+      required:
+        - id
+        - name
+    CompanySearchResponse:
+      type: object
+      description: Serializer for paginated company search response
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompanySearchResult'
+        count:
+          type: integer
+        page:
+          type: integer
+        page_size:
+          type: integer
+        total_pages:
+          type: integer
+      required:
+        - count
+        - page
+        - page_size
+        - results
+        - total_pages
+    CompanySearchResult:
+      type: object
+      description: Serializer for individual company search result
+      properties:
+        id:
+          type: string
+        name:
           type: string
-          format: date-time
-          nullable: true
-          description: The last time a deep Xero sync was performed (looking back
-            90 days)
-        address_line1:
+        email:
           type: string
-          nullable: true
-          description: Street address line 1
-          maxLength: 255
-        address_line2:
+        address:
           type: string
-          nullable: true
-          description: Street address line 2 (optional)
-          maxLength: 255
-        suburb:
+        is_account_customer:
+          type: boolean
+        is_supplier:
+          type: boolean
+        allow_jobs:
+          type: boolean
+        xero_contact_id:
           type: string
-          nullable: true
-          description: Suburb (for NZ addresses)
-          maxLength: 100
-        city:
+        last_invoice_date:
           type: string
+          format: date-time
           nullable: true
-          description: City
-          maxLength: 100
-        post_code:
+        total_spend:
           type: string
-          nullable: true
-          description: Postal/ZIP code
-          maxLength: 20
-        country:
+      required:
+        - address
+        - allow_jobs
+        - email
+        - id
+        - is_account_customer
+        - is_supplier
+        - last_invoice_date
+        - name
+        - total_spend
+        - xero_contact_id
+    CompanyUpdateRequest:
+      type: object
+      description: Serializer for company update request
+      properties:
+        name:
           type: string
           minLength: 1
-          description: Country name
-          maxLength: 100
-        company_email:
+          maxLength: 255
+        email:
           type: string
           format: email
-          nullable: true
-          description: Company contact email address
-          maxLength: 254
-        company_url:
-          type: string
-          format: uri
-          nullable: true
-          description: Company website URL
-          maxLength: 200
-        test_client_name:
-          type: string
-          nullable: true
-          description: Name of the test client used for testing (e.g., 'ABC Carpet
-            Cleaning TEST IGNORE'). This client's name is preserved during data backports.
-          maxLength: 255
-        kpi_daily_billable_hours_green:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily billable hours (green)
-          description: Daily total billable hours across all staff above which the
-            day is green
-        kpi_daily_billable_hours_amber:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily billable hours (amber)
-          description: Daily total billable hours across all staff above which the
-            day is amber
-        kpi_daily_gp_target:
-          type: number
-          format: double
-          maximum: 100000000
-          minimum: -100000000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily gross profit target
-          description: Daily gross profit target in dollars
-        kpi_daily_shop_hours_percentage:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily shop hours percentage target
-          description: Target percentage of daily hours spent on shop (non-billable)
-            jobs
-        kpi_job_gp_target_percentage:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Target GP % per job
-          description: Target gross profit percentage for individual jobs
-        kpi_daily_gp_green:
-          type: number
-          format: double
-          maximum: 100000000
-          minimum: -100000000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily GP (green)
-          description: Daily gross profit above which the day is green
-        kpi_daily_gp_amber:
-          type: number
-          format: double
-          maximum: 100000000
-          minimum: -100000000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          title: Daily GP (amber)
-          description: Daily gross profit above which the day is amber
-        daily_approved_hours_target:
-          type: number
-          format: double
-          maximum: 1000
-          minimum: -1000
-          exclusiveMaximum: true
-          exclusiveMinimum: true
-          description: Target daily hours of newly-approved work flowing into the
-            shop, used by the Sales Pipeline scoreboard
-        shop_client:
+        address:
           type: string
-          format: uuid
-          description: Internal client used for tracking shop work.
-      required:
-        - shop_client
-    CompanyDefaultsSchema:
+        is_account_customer:
+          type: boolean
+        allow_jobs:
+          type: boolean
+    CompanyUpdateResponse:
       type: object
-      description: Serializer for the complete schema response.
+      description: Serializer for company update response
       properties:
-        sections:
-          type: array
-          items:
-            $ref: '#/components/schemas/SettingsSection'
+        success:
+          type: boolean
+        company:
+          $ref: '#/components/schemas/CompanyDetailResponse'
+        message:
+          type: string
       required:
-        - sections
+        - company
+        - message
+        - success
     CompleteJob:
       type: object
       properties:
@@ -11420,7 +11420,7 @@ components:
         name:
           type: string
           maxLength: 100
-        client_name:
+        company_name:
           type: string
           readOnly: true
         updated_at:
@@ -11430,7 +11430,7 @@ components:
         job_status:
           type: string
       required:
-        - client_name
+        - company_name
         - id
         - job_number
         - job_status
@@ -12225,14 +12225,14 @@ components:
           description: Contact-method id
         owner_kind:
           type: string
-          description: "'client' or 'contact'"
+          description: "'company' or 'contact'"
         owner_name:
           type: string
           description: Human-readable owner
         effective_client_id:
           type: string
           nullable: true
-          description: Client the number resolves to
+          description: Company the number resolves to
       required:
         - effective_client_id
         - method_id
@@ -12244,10 +12244,10 @@ components:
       properties:
         cross_client:
           type: integer
-          description: Numbers owned by more than one client
+          description: Numbers owned by more than one company
         internal_line:
           type: integer
-          description: Client numbers that are actually internal company lines
+          description: Company numbers that are actually internal company lines
       required:
         - cross_client
         - internal_line
@@ -12728,7 +12728,7 @@ components:
         iterates the unresolved rows, computes each message's hash, and cascades
         the resolve across every row whose hash matches.
 
-        Using a fingerprint (not the message string) avoids client-side
+        Using a fingerprint (not the message string) avoids company-side
         whitespace mangling: the frontend's global axios interceptor calls
         trimStringsDeep on outbound payloads, which would strip trailing
         whitespace and prevent a later exact match.
@@ -12951,11 +12951,11 @@ components:
         name:
           type: string
           maxLength: 100
-        client_id:
+        company_id:
           type: string
           format: uuid
           nullable: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
           nullable: true
@@ -13081,7 +13081,7 @@ components:
           readOnly: true
         shop_job:
           type: boolean
-          description: Indicates if this is a shop job (belongs to shop client).
+          description: Indicates if this is a shop job (belongs to shop company).
           readOnly: true
         rejected_flag:
           type: boolean
@@ -13123,7 +13123,7 @@ components:
           type: boolean
           description: Whether this job requires urgent rates and priority handling
       required:
-        - client_name
+        - company_name
         - contact_name
         - created_at
         - default_xero_pay_item_name
@@ -13170,7 +13170,7 @@ components:
           type: integer
         name:
           type: string
-        client_name:
+        company_name:
           type: string
         status:
           type: string
@@ -13181,7 +13181,7 @@ components:
         timing_data:
           $ref: '#/components/schemas/JobAgingTimingData'
       required:
-        - client_name
+        - company_name
         - financial_data
         - id
         - job_number
@@ -13261,7 +13261,7 @@ components:
           type: integer
         job_name:
           type: string
-        client:
+        company:
           type: string
         hours:
           type: number
@@ -13275,7 +13275,7 @@ components:
         is_billable:
           type: boolean
       required:
-        - client
+        - company
         - cost
         - hours
         - is_billable
@@ -13388,7 +13388,7 @@ components:
           type: string
           minLength: 1
           maxLength: 255
-        client_id:
+        company_id:
           type: string
           format: uuid
         description:
@@ -13423,7 +13423,7 @@ components:
           type: boolean
           default: false
       required:
-        - client_id
+        - company_id
         - estimated_materials
         - estimated_time
         - name
@@ -13872,10 +13872,10 @@ components:
         name:
           type: string
           maxLength: 100
-        client_name:
+        company_name:
           type: string
           readOnly: true
-          default: No Client
+          default: No Company
         status:
           $ref: '#/components/schemas/JobStatusEnum'
         is_stock_holding:
@@ -13885,7 +13885,7 @@ components:
           type: string
           readOnly: true
       required:
-        - client_name
+        - company_name
         - id
         - is_stock_holding
         - job_display_name
@@ -13899,12 +13899,12 @@ components:
         job_id:
           type: string
           format: uuid
-        client_id:
+        company_id:
           type: string
           format: uuid
           readOnly: true
           nullable: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
           nullable: true
@@ -14022,8 +14022,8 @@ components:
           type: boolean
           description: Whether this job requires urgent rates and priority handling
       required:
-        - client_id
-        - client_name
+        - company_id
+        - company_name
         - contact_id
         - contact_name
         - default_xero_pay_item_id
@@ -14131,9 +14131,9 @@ components:
         job_name:
           type: string
           description: Job description
-        client_name:
+        company_name:
           type: string
-          description: Client name
+          description: Company name
         pricing_type:
           type: string
           description: Pricing methodology key
@@ -14168,7 +14168,7 @@ components:
           description: Variance as % of baseline
       required:
         - actual
-        - client_name
+        - company_name
         - completion_date
         - estimate
         - job_id
@@ -14502,11 +14502,11 @@ components:
         name:
           type: string
           maxLength: 100
-        client_id:
+        company_id:
           type: string
           format: uuid
           nullable: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
           nullable: true
@@ -14632,7 +14632,7 @@ components:
           readOnly: true
         shop_job:
           type: boolean
-          description: Indicates if this is a shop job (belongs to shop client).
+          description: Indicates if this is a shop job (belongs to shop company).
           readOnly: true
         rejected_flag:
           type: boolean
@@ -14674,7 +14674,7 @@ components:
           type: boolean
           description: Whether this job requires urgent rates and priority handling
       required:
-        - client_name
+        - company_name
         - contact_name
         - created_at
         - default_xero_pay_item_name
@@ -14882,7 +14882,7 @@ components:
           type: string
         job_name:
           type: string
-        client_name:
+        company_name:
           type: string
         billable_hours:
           type: number
@@ -14908,7 +14908,7 @@ components:
       required:
         - adjustment_profit
         - billable_hours
-        - client_name
+        - company_name
         - cost
         - job_id
         - job_name
@@ -15115,7 +15115,7 @@ components:
         description:
           type: string
           nullable: true
-        client_name:
+        company_name:
           type: string
         contact_person:
           type: string
@@ -15173,7 +15173,7 @@ components:
       required:
         - badge_color
         - badge_label
-        - client_name
+        - company_name
         - contact_person
         - created_at
         - created_by_id
@@ -15225,7 +15225,7 @@ components:
           nullable: true
         job_number:
           type: integer
-        client_name:
+        company_name:
           type: string
         contact_person:
           type: string
@@ -15278,7 +15278,7 @@ components:
         max_people:
           type: integer
       required:
-        - client_name
+        - company_name
         - contact_person
         - created_at
         - created_by_id
@@ -15686,7 +15686,7 @@ components:
         name:
           type: string
           maxLength: 100
-        client_name:
+        company_name:
           type: string
           readOnly: true
           nullable: true
@@ -15723,7 +15723,7 @@ components:
           type: boolean
           readOnly: true
       required:
-        - client_name
+        - company_name
         - default_xero_pay_item_id
         - default_xero_pay_item_name
         - estimated_hours
@@ -15822,7 +15822,7 @@ components:
           type: integer
         job_name:
           type: string
-        client_name:
+        company_name:
           type: string
         history:
           type: array
@@ -15835,7 +15835,7 @@ components:
           type: number
           format: double
       required:
-        - client_name
+        - company_name
         - history
         - job_id
         - job_name
@@ -16128,9 +16128,9 @@ components:
             update.
     PatchedClientContactMethodRequest:
       type: object
-      description: Serializer for canonical client/contact phone and email methods.
+      description: Serializer for canonical company/contact phone and email methods.
       properties:
-        client:
+        company:
           type: string
           format: uuid
           nullable: true
@@ -16156,10 +16156,10 @@ components:
       type: object
       description: Serializer for ClientContact model.
       properties:
-        client:
+        company:
           type: string
           format: uuid
-          description: The client this contact belongs to
+          description: The company this contact belongs to
         name:
           type: string
           minLength: 1
@@ -16178,28 +16178,11 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the client
+          description: Indicates if this is the primary contact for the company
         notes:
           type: string
           nullable: true
           description: Additional notes about this contact
-    PatchedClientUpdateRequest:
-      type: object
-      description: Serializer for client update request
-      properties:
-        name:
-          type: string
-          minLength: 1
-          maxLength: 255
-        email:
-          type: string
-          format: email
-        address:
-          type: string
-        is_account_customer:
-          type: boolean
-        allow_jobs:
-          type: boolean
     PatchedCompanyDefaultsRequest:
       type: object
       properties:
@@ -16457,11 +16440,11 @@ components:
           nullable: true
           description: Company website URL
           maxLength: 200
-        test_client_name:
+        test_company_name:
           type: string
           nullable: true
-          description: Name of the test client used for testing (e.g., 'ABC Carpet
-            Cleaning TEST IGNORE'). This client's name is preserved during data backports.
+          description: Name of the test company used for testing (e.g., 'ABC Carpet
+            Cleaning TEST IGNORE'). This company's name is preserved during data backports.
           maxLength: 255
         kpi_daily_billable_hours_green:
           type: number
@@ -16538,10 +16521,27 @@ components:
           exclusiveMinimum: true
           description: Target daily hours of newly-approved work flowing into the
             shop, used by the Sales Pipeline scoreboard
-        shop_client:
+        shop_company:
           type: string
           format: uuid
-          description: Internal client used for tracking shop work.
+          description: Internal company used for tracking shop work.
+    PatchedCompanyUpdateRequest:
+      type: object
+      description: Serializer for company update request
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        email:
+          type: string
+          format: email
+        address:
+          type: string
+        is_account_customer:
+          type: boolean
+        allow_jobs:
+          type: boolean
     PatchedCostLineCreateUpdateRequest:
       type: object
       description: Serializer for CostLine creation and updates - full write capabilities
@@ -17038,7 +17038,7 @@ components:
       type: object
       description: Serializer for SupplierPickupAddress model (delivery/pickup locations).
       properties:
-        client:
+        company:
           type: string
           format: uuid
           description: The supplier this pickup address belongs to
@@ -17159,7 +17159,7 @@ components:
         List / detail / PATCH serializer for XeroApp.
 
         client_secret and webhook_key are write-only — never returned. The
-        webhook signing key is comparable in sensitivity to the client secret
+        webhook signing key is comparable in sensitivity to the company secret
         (anyone holding it can forge webhook deliveries that we'd verify as
         authentic), so it gets the same treatment. access_token /
         refresh_token are not surfaced at all; instead a derived has_tokens
@@ -17606,12 +17606,12 @@ components:
           exclusiveMinimum: true
           readOnly: true
           nullable: true
-        client:
+        company:
           type: string
           format: uuid
           readOnly: true
           nullable: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
         contact:
@@ -17667,8 +17667,8 @@ components:
         - call_time
         - call_type
         - charge
-        - client
-        - client_name
+        - company
+        - company_name
         - contact
         - contact_name
         - description
@@ -17846,9 +17846,9 @@ components:
         - number
     PhoneNumberAssignmentRequest:
       type: object
-      description: Request body for assigning a call's external number to a client.
+      description: Request body for assigning a call's external number to a company.
       properties:
-        client:
+        company:
           type: string
           format: uuid
         contact:
@@ -17863,7 +17863,7 @@ components:
           default: ''
           maxLength: 255
       required:
-        - client
+        - company
     PhoneProviderSettings:
       type: object
       properties:
@@ -18617,10 +18617,10 @@ components:
           type: string
         name:
           type: string
-        client:
+        company:
           type: string
       required:
-        - client
+        - company
         - job_number
         - name
     PurchaseOrderLastNumberResponse:
@@ -18713,7 +18713,7 @@ components:
           type: integer
           readOnly: true
           nullable: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
           nullable: true
@@ -18723,10 +18723,10 @@ components:
           nullable: true
         times_used:
           type: integer
-          description: Always emit a numeric usage count for generated client validation.
+          description: Always emit a numeric usage count for generated company validation.
           readOnly: true
       required:
-        - client_name
+        - company_name
         - description
         - id
         - job_id
@@ -19212,7 +19212,7 @@ components:
           type: integer
         job_name:
           type: string
-        client_name:
+        company_name:
           type: string
         rdti_type:
           type: string
@@ -19226,7 +19226,7 @@ components:
           type: number
           format: double
       required:
-        - client_name
+        - company_name
         - cost
         - hours
         - job_id
@@ -19568,7 +19568,7 @@ components:
           type: integer
         name:
           type: string
-        client_name:
+        company_name:
           type: string
         hours:
           type: number
@@ -19579,7 +19579,7 @@ components:
         days_in_stage:
           type: integer
       required:
-        - client_name
+        - company_name
         - days_in_stage
         - hours
         - id
@@ -19733,7 +19733,7 @@ components:
           type: integer
         name:
           type: string
-        client_name:
+        company_name:
           type: string
         remaining_hours:
           type: number
@@ -19769,7 +19769,7 @@ components:
         - anticipated_staff
         - anticipated_start_date
         - assigned_staff
-        - client_name
+        - company_name
         - delivery_date
         - id
         - is_late
@@ -20646,7 +20646,7 @@ components:
           type: integer
         job_name:
           type: string
-        client_name:
+        company_name:
           type: string
         billable_hours:
           type: number
@@ -20671,7 +20671,7 @@ components:
           format: double
       required:
         - billable_hours
-        - client_name
+        - company_name
         - cost
         - job_id
         - job_name
@@ -21111,7 +21111,7 @@ components:
           nullable: true
         times_used:
           type: integer
-          description: Always emit a numeric usage count for generated client validation.
+          description: Always emit a numeric usage count for generated company validation.
           readOnly: true
       required:
         - description
@@ -21275,7 +21275,7 @@ components:
           type: string
           format: uuid
           readOnly: true
-        client:
+        company:
           type: string
           format: uuid
           description: The supplier this pickup address belongs to
@@ -21359,7 +21359,7 @@ components:
           readOnly: true
       required:
         - city
-        - client
+        - company
         - created_at
         - formatted_address
         - id
@@ -21371,7 +21371,7 @@ components:
       type: object
       description: Serializer for SupplierPickupAddress model (delivery/pickup locations).
       properties:
-        client:
+        company:
           type: string
           format: uuid
           description: The supplier this pickup address belongs to
@@ -21443,7 +21443,7 @@ components:
           description: Additional notes (e.g., opening hours, access instructions)
       required:
         - city
-        - client
+        - company
         - name
         - street
     SupplierPriceStatusItem:
@@ -21490,13 +21490,13 @@ components:
         - total_count
     SupplierSearchAlias:
       type: object
-      description: Supplier search alias attached to a client/contact.
+      description: Supplier search alias attached to a company/contact.
       properties:
         id:
           type: string
           format: uuid
           readOnly: true
-        client:
+        company:
           type: string
           format: uuid
           readOnly: true
@@ -21516,7 +21516,7 @@ components:
           readOnly: true
       required:
         - alias
-        - client
+        - company
         - created_at
         - id
         - is_active
@@ -21714,7 +21714,7 @@ components:
         Architecture principle: Job data comes from CostSet->Job relationship,
         NOT from metadata. This ensures data consistency and follows SRP:
         - Metadata = timesheet-specific data (staff, date, billable, etc.)
-        - Relationship = job data (job_id, job_number, job_name, client)
+        - Relationship = job data (job_id, job_number, job_name, company)
 
         Benefits:
         - No data duplication
@@ -21843,9 +21843,9 @@ components:
         job_name:
           type: string
           readOnly: true
-        client_name:
+        company_name:
           type: string
-          description: Get client name with safe null handling
+          description: Get company name with safe null handling
           readOnly: true
         charge_out_rate:
           type: number
@@ -21867,7 +21867,7 @@ components:
         - accounting_date
         - approved
         - charge_out_rate
-        - client_name
+        - company_name
         - created_at
         - desc
         - entry_seq
@@ -21957,7 +21957,7 @@ components:
           type: integer
         name:
           type: string
-        client_name:
+        company_name:
           type: string
         delivery_date:
           type: string
@@ -21969,7 +21969,7 @@ components:
         reason:
           type: string
       required:
-        - client_name
+        - company_name
         - delivery_date
         - id
         - job_number
@@ -22044,7 +22044,7 @@ components:
           type: integer
         name:
           type: string
-        client:
+        company:
           type: string
         status:
           type: string
@@ -22084,7 +22084,7 @@ components:
       required:
         - adjust_cost
         - adjust_rev
-        - client
+        - company
         - gross_wip
         - invoiced
         - job_number
@@ -22172,7 +22172,7 @@ components:
           type: integer
         name:
           type: string
-        client:
+        company:
           type: string
           nullable: true
         description:
@@ -22530,7 +22530,7 @@ components:
           nullable: true
         job_number:
           type: integer
-        client_name:
+        company_name:
           type: string
         contact_person:
           type: string
@@ -22540,7 +22540,7 @@ components:
           items:
             $ref: '#/components/schemas/KanbanJobPerson'
       required:
-        - client_name
+        - company_name
         - contact_person
         - description
         - id
@@ -22594,7 +22594,7 @@ components:
         job_name:
           type: string
           readOnly: true
-        client_name:
+        company_name:
           type: string
           readOnly: true
         description:
@@ -22652,7 +22652,7 @@ components:
       required:
         - accounting_date
         - bill_rate_multiplier
-        - client_name
+        - company_name
         - created_at
         - description
         - end_time
@@ -22761,7 +22761,7 @@ components:
         List / detail / PATCH serializer for XeroApp.
 
         client_secret and webhook_key are write-only — never returned. The
-        webhook signing key is comparable in sensitivity to the client secret
+        webhook signing key is comparable in sensitivity to the company secret
         (anyone holding it can forge webhook deliveries that we'd verify as
         authentic), so it gets the same treatment. access_token /
         refresh_token are not surfaced at all; instead a derived has_tokens
@@ -22961,7 +22961,7 @@ components:
         List / detail / PATCH serializer for XeroApp.
 
         client_secret and webhook_key are write-only — never returned. The
-        webhook signing key is comparable in sensitivity to the client secret
+        webhook signing key is comparable in sensitivity to the company secret
         (anyone holding it can forge webhook deliveries that we'd verify as
         authentic), so it gets the same treatment. access_token /
         refresh_token are not surfaced at all; instead a derived has_tokens
@@ -23038,9 +23038,9 @@ components:
           items:
             type: string
           description: Informational messages.
-        client:
+        company:
           type: string
-          description: Name of the client.
+          description: Name of the company.
         total_excl_tax:
           type: number
           format: double
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index 377279b14..1ec27738e 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -10,7 +10,7 @@ const KPIJobBreakdown = z.object({
   job_id: z.string(),
   job_number: z.string(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   billable_hours: z.number(),
   revenue: z.number(),
   cost: z.number(),
@@ -121,7 +121,7 @@ const JobAgingJobData = z.object({
   id: z.string(),
   job_number: z.number().int(),
   name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   status: z.string(),
   status_display: z.string(),
   financial_data: JobAgingFinancialData,
@@ -209,7 +209,7 @@ const RDTISpendJobDetail = z.object({
   job_id: z.string(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   rdti_type: z.string(),
   hours: z.number(),
   cost: z.number(),
@@ -270,7 +270,7 @@ const SalesPipelineSnapshotJob = z.object({
   id: z.string(),
   job_number: z.number().int(),
   name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   hours: z.number(),
   value: z.number(),
   days_in_stage: z.number().int(),
@@ -360,7 +360,7 @@ const StaffPerformanceJobBreakdown = z.object({
   job_id: z.string(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   billable_hours: z.number(),
   non_billable_hours: z.number(),
   total_hours: z.number(),
@@ -397,7 +397,7 @@ const StaffPerformanceResponse = z.object({
 const WIPJob = z.object({
   job_number: z.number().int(),
   name: z.string(),
-  client: z.string(),
+  company: z.string(),
   status: z.string(),
   time_cost: z.number(),
   time_rev: z.number(),
@@ -623,7 +623,7 @@ const GroupedErrorResolveRequestRequest = z.object({
 })
 const GroupedErrorResolveResponse = z.object({ updated: z.number().int() })
 const BuildId = z.object({ build_id: z.string() })
-const ClientDetailResponse = z.object({
+const CompanyDetailResponse = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string(),
@@ -646,16 +646,16 @@ const ClientDetailResponse = z.object({
   last_invoice_date: z.string().datetime({ offset: true }).nullable(),
   total_spend: z.string(),
 })
-const ClientErrorResponse = z.object({
+const CompanyErrorResponse = z.object({
   success: z.boolean().optional().default(false),
   error: z.string(),
   details: z.string().optional(),
 })
-const ClientJobHeader = z.object({
+const CompanyJobHeader = z.object({
   job_id: z.string().uuid(),
   job_number: z.number().int(),
   name: z.string(),
-  client: z.object({}).partial().passthrough().nullable(),
+  company: z.object({}).partial().passthrough().nullable(),
   status: z.string(),
   pricing_methodology: z.string().nullable(),
   speed_quality_tradeoff: z.string(),
@@ -668,10 +668,10 @@ const ClientJobHeader = z.object({
   min_people: z.number().int(),
   max_people: z.number().int(),
 })
-const ClientJobsResponse = z.object({ results: z.array(ClientJobHeader) })
+const CompanyJobsResponse = z.object({ results: z.array(CompanyJobHeader) })
 const SupplierSearchAlias = z.object({
   id: z.string().uuid(),
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   alias: z.string().max(255),
   is_active: z.boolean(),
   created_at: z.string().datetime({ offset: true }),
@@ -680,7 +680,7 @@ const SupplierSearchAlias = z.object({
 const SupplierSearchAliasCreateRequest = z.object({
   alias: z.string().min(1).max(255),
 })
-const ClientUpdateRequest = z
+const CompanyUpdateRequest = z
   .object({
     name: z.string().min(1).max(255),
     email: z.string().email(),
@@ -689,12 +689,12 @@ const ClientUpdateRequest = z
     allow_jobs: z.boolean(),
   })
   .partial()
-const ClientUpdateResponse = z.object({
+const CompanyUpdateResponse = z.object({
   success: z.boolean(),
-  client: ClientDetailResponse,
+  company: CompanyDetailResponse,
   message: z.string(),
 })
-const PatchedClientUpdateRequest = z
+const PatchedCompanyUpdateRequest = z
   .object({
     name: z.string().min(1).max(255),
     email: z.string().email(),
@@ -703,14 +703,14 @@ const PatchedClientUpdateRequest = z
     allow_jobs: z.boolean(),
   })
   .partial()
-const ClientNameOnly = z.object({ id: z.string().uuid(), name: z.string() })
+const CompanyNameOnly = z.object({ id: z.string().uuid(), name: z.string() })
 const MethodTypeEnum = z.enum(['phone', 'email'])
 const ClientContactMethodSourceEnum = z.enum(['imported', 'local'])
 const ClientContactMethod = z.object({
   id: z.string().uuid(),
-  client: z.string().uuid().nullish(),
-  owner_client: z.string(),
-  client_name: z.string(),
+  company: z.string().uuid().nullish(),
+  owner_company: z.string(),
+  company_name: z.string(),
   contact: z.string().uuid().nullish(),
   contact_name: z.string(),
   method_type: MethodTypeEnum,
@@ -730,7 +730,7 @@ const PaginatedClientContactMethodList = z.object({
   total_pages: z.number().int(),
 })
 const ClientContactMethodRequest = z.object({
-  client: z.string().uuid().nullish(),
+  company: z.string().uuid().nullish(),
   contact: z.string().uuid().nullish(),
   method_type: MethodTypeEnum,
   value: z.string().min(1).max(255),
@@ -740,7 +740,7 @@ const ClientContactMethodRequest = z.object({
 })
 const PatchedClientContactMethodRequest = z
   .object({
-    client: z.string().uuid().nullable(),
+    company: z.string().uuid().nullable(),
     contact: z.string().uuid().nullable(),
     method_type: MethodTypeEnum,
     value: z.string().min(1).max(255),
@@ -751,7 +751,7 @@ const PatchedClientContactMethodRequest = z
   .partial()
 const ClientContact = z.object({
   id: z.string().uuid(),
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   name: z.string().max(255),
   email: z.string().max(254).email().nullish(),
   position: z.string().max(255).nullish(),
@@ -762,7 +762,7 @@ const ClientContact = z.object({
   updated_at: z.string().datetime({ offset: true }),
 })
 const ClientContactRequest = z.object({
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   name: z.string().min(1).max(255),
   email: z.string().max(254).email().nullish(),
   position: z.string().max(255).nullish(),
@@ -771,7 +771,7 @@ const ClientContactRequest = z.object({
 })
 const PatchedClientContactRequest = z
   .object({
-    client: z.string().uuid(),
+    company: z.string().uuid(),
     name: z.string().min(1).max(255),
     email: z.string().max(254).email().nullable(),
     position: z.string().max(255).nullable(),
@@ -779,14 +779,14 @@ const PatchedClientContactRequest = z
     notes: z.string().nullable(),
   })
   .partial()
-const ClientCreateRequest = z.object({
+const CompanyCreateRequest = z.object({
   name: z.string().min(1).max(255),
   email: z.string().email().nullish(),
   address: z.string().nullish(),
   is_account_customer: z.boolean().optional().default(true),
   allow_jobs: z.boolean().optional().default(true),
 })
-const ClientSearchResult = z.object({
+const CompanySearchResult = z.object({
   id: z.string(),
   name: z.string(),
   email: z.string(),
@@ -798,15 +798,15 @@ const ClientSearchResult = z.object({
   last_invoice_date: z.string().datetime({ offset: true }).nullable(),
   total_spend: z.string(),
 })
-const ClientCreateResponse = z.object({
+const CompanyCreateResponse = z.object({
   success: z.boolean(),
-  client: ClientSearchResult,
+  company: CompanySearchResult,
   message: z.string(),
 })
-const ClientDuplicateErrorResponse = z.object({
+const CompanyDuplicateErrorResponse = z.object({
   success: z.boolean().optional().default(false),
   error: z.string(),
-  existing_client: z.object({}).partial().passthrough(),
+  existing_company: z.object({}).partial().passthrough(),
 })
 const JobContactResponse = z.object({
   id: z.string().uuid(),
@@ -826,7 +826,7 @@ const JobContactUpdateRequest = z.object({
 })
 const SupplierPickupAddress = z.object({
   id: z.string().uuid(),
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   name: z.string().max(255),
   street: z.string().max(255),
   suburb: z.string().max(100).nullish(),
@@ -845,7 +845,7 @@ const SupplierPickupAddress = z.object({
   formatted_address: z.string(),
 })
 const SupplierPickupAddressRequest = z.object({
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   name: z.string().min(1).max(255),
   street: z.string().min(1).max(255),
   suburb: z.string().max(100).nullish(),
@@ -861,7 +861,7 @@ const SupplierPickupAddressRequest = z.object({
 })
 const PatchedSupplierPickupAddressRequest = z
   .object({
-    client: z.string().uuid(),
+    company: z.string().uuid(),
     name: z.string().min(1).max(255),
     street: z.string().min(1).max(255),
     suburb: z.string().max(100).nullable(),
@@ -876,8 +876,8 @@ const PatchedSupplierPickupAddressRequest = z
     notes: z.string().nullable(),
   })
   .partial()
-const ClientSearchResponse = z.object({
-  results: z.array(ClientSearchResult),
+const CompanySearchResponse = z.object({
+  results: z.array(CompanySearchResult),
   count: z.number().int(),
   page: z.number().int(),
   page_size: z.number().int(),
@@ -938,7 +938,7 @@ const CompanyDefaults = z.object({
   country: z.string().max(100).optional(),
   company_email: z.string().max(254).email().nullish(),
   company_url: z.string().max(200).url().nullish(),
-  test_client_name: z.string().max(255).nullish(),
+  test_company_name: z.string().max(255).nullish(),
   kpi_daily_billable_hours_green: z.number().gt(-1000).lt(1000).optional(),
   kpi_daily_billable_hours_amber: z.number().gt(-1000).lt(1000).optional(),
   kpi_daily_gp_target: z.number().gt(-100000000).lt(100000000).optional(),
@@ -947,7 +947,7 @@ const CompanyDefaults = z.object({
   kpi_daily_gp_green: z.number().gt(-100000000).lt(100000000).optional(),
   kpi_daily_gp_amber: z.number().gt(-100000000).lt(100000000).optional(),
   daily_approved_hours_target: z.number().gt(-1000).lt(1000).optional(),
-  shop_client: z.string().uuid(),
+  shop_company: z.string().uuid(),
 })
 const CompanyDefaultsRequest = z.object({
   logo: z.instanceof(File).nullish(),
@@ -1000,7 +1000,7 @@ const CompanyDefaultsRequest = z.object({
   country: z.string().min(1).max(100).optional(),
   company_email: z.string().max(254).email().nullish(),
   company_url: z.string().max(200).url().nullish(),
-  test_client_name: z.string().max(255).nullish(),
+  test_company_name: z.string().max(255).nullish(),
   kpi_daily_billable_hours_green: z.number().gt(-1000).lt(1000).optional(),
   kpi_daily_billable_hours_amber: z.number().gt(-1000).lt(1000).optional(),
   kpi_daily_gp_target: z.number().gt(-100000000).lt(100000000).optional(),
@@ -1009,7 +1009,7 @@ const CompanyDefaultsRequest = z.object({
   kpi_daily_gp_green: z.number().gt(-100000000).lt(100000000).optional(),
   kpi_daily_gp_amber: z.number().gt(-100000000).lt(100000000).optional(),
   daily_approved_hours_target: z.number().gt(-1000).lt(1000).optional(),
-  shop_client: z.string().uuid(),
+  shop_company: z.string().uuid(),
 })
 const PatchedCompanyDefaultsRequest = z
   .object({
@@ -1063,7 +1063,7 @@ const PatchedCompanyDefaultsRequest = z
     country: z.string().min(1).max(100),
     company_email: z.string().max(254).email().nullable(),
     company_url: z.string().max(200).url().nullable(),
-    test_client_name: z.string().max(255).nullable(),
+    test_company_name: z.string().max(255).nullable(),
     kpi_daily_billable_hours_green: z.number().gt(-1000).lt(1000),
     kpi_daily_billable_hours_amber: z.number().gt(-1000).lt(1000),
     kpi_daily_gp_target: z.number().gt(-100000000).lt(100000000),
@@ -1072,7 +1072,7 @@ const PatchedCompanyDefaultsRequest = z
     kpi_daily_gp_green: z.number().gt(-100000000).lt(100000000),
     kpi_daily_gp_amber: z.number().gt(-100000000).lt(100000000),
     daily_approved_hours_target: z.number().gt(-1000).lt(1000),
-    shop_client: z.string().uuid(),
+    shop_company: z.string().uuid(),
   })
   .partial()
 const SettingsField = z.object({
@@ -1130,8 +1130,8 @@ const PhoneCallRecord = z.object({
   destination_endpoint_label: z.string(),
   duration_seconds: z.number().int(),
   charge: z.number().gt(-100000000).lt(100000000).nullable(),
-  client: z.string().uuid().nullable(),
-  client_name: z.string(),
+  company: z.string().uuid().nullable(),
+  company_name: z.string(),
   contact: z.string().uuid().nullable(),
   contact_name: z.string(),
   job: z.string().uuid().nullable(),
@@ -1152,7 +1152,7 @@ const PaginatedPhoneCallRecordList = z.object({
   total_pages: z.number().int(),
 })
 const PhoneNumberAssignmentRequest = z.object({
-  client: z.string().uuid(),
+  company: z.string().uuid(),
   contact: z.string().uuid().nullish(),
   is_primary: z.boolean().optional().default(false),
   label: z.string().max(255).optional().default(''),
@@ -1319,7 +1319,7 @@ const DataIntegrityResponse = z.object({
 const ArchivedJobIssue = z.object({
   job_id: z.string(),
   job_number: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   archived_date: z.string(),
   current_status: z.string(),
   issue: z.string(),
@@ -1370,7 +1370,7 @@ const CompleteJob = z.object({
   id: z.string().uuid(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
   name: z.string().max(100),
-  client_name: z.string(),
+  company_name: z.string(),
   updated_at: z.string().datetime({ offset: true }),
   job_status: z.string(),
 })
@@ -1389,7 +1389,7 @@ const ArchiveJobsResponse = z.object({
 })
 const JobCreateRequest = z.object({
   name: z.string().min(1).max(255),
-  client_id: z.string().uuid(),
+  company_id: z.string().uuid(),
   description: z.string().optional(),
   order_number: z.string().optional(),
   notes: z.string().optional(),
@@ -1486,8 +1486,8 @@ const NullEnum = z.unknown()
 const Job = z.object({
   id: z.string().uuid(),
   name: z.string().max(100),
-  client_id: z.string().uuid().nullish(),
-  client_name: z.string().nullable(),
+  company_id: z.string().uuid().nullish(),
+  company_name: z.string().nullable(),
   contact_id: z.string().uuid().nullish(),
   contact_name: z.string().nullable(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
@@ -1699,8 +1699,8 @@ const JobStatusEnum = z.enum([
 ])
 const JobHeaderResponse = z.object({
   job_id: z.string().uuid(),
-  client_id: z.string().uuid().nullable(),
-  client_name: z.string().nullable(),
+  company_id: z.string().uuid().nullable(),
+  company_name: z.string().nullable(),
   contact_id: z.string().uuid().nullable(),
   contact_name: z.string().nullable(),
   quoted: z.boolean(),
@@ -1825,8 +1825,8 @@ const CostSetSummaryOnly = z.object({
 const JobSummary = z.object({
   id: z.string().uuid(),
   name: z.string().max(100),
-  client_id: z.string().uuid().nullish(),
-  client_name: z.string().nullable(),
+  company_id: z.string().uuid().nullish(),
+  company_name: z.string().nullable(),
   contact_id: z.string().uuid().nullish(),
   contact_name: z.string().nullable(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
@@ -1967,7 +1967,7 @@ const KanbanJob = z.object({
   name: z.string(),
   description: z.string().nullable(),
   job_number: z.number().int(),
-  client_name: z.string(),
+  company_name: z.string(),
   contact_person: z.string(),
   people: z.array(KanbanJobPerson),
   status: z.string(),
@@ -2035,7 +2035,7 @@ const KanbanColumnJob = z.object({
   job_number: z.number().int(),
   name: z.string(),
   description: z.string().nullable(),
-  client_name: z.string(),
+  company_name: z.string(),
   contact_person: z.string(),
   people: z.array(KanbanJobPerson),
   status: z.string(),
@@ -2093,7 +2093,7 @@ const WeeklyMetrics = z.object({
   job_id: z.string().uuid(),
   job_number: z.number().int(),
   name: z.string(),
-  client: z.string().nullish(),
+  company: z.string().nullish(),
   description: z.string().nullish(),
   status: z.string(),
   people: z.array(z.object({}).partial().passthrough()),
@@ -2106,7 +2106,7 @@ const WorkshopJob = z.object({
   name: z.string(),
   description: z.string().nullable(),
   job_number: z.number().int(),
-  client_name: z.string(),
+  company_name: z.string(),
   contact_person: z.string().nullable(),
   people: z.array(KanbanJobPerson),
 })
@@ -2154,7 +2154,7 @@ const MonthEndJob = z.object({
   job_id: z.string().uuid(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   history: z.array(MonthEndJobHistory),
   total_hours: z.number(),
   total_dollars: z.number(),
@@ -2190,7 +2190,7 @@ const JobProfitabilityItem = z.object({
   job_id: z.string(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   pricing_type: z.string(),
   pricing_type_display: z.string(),
   completion_date: z.string().nullable(),
@@ -2253,7 +2253,7 @@ const TimesheetCostLine = z.object({
   job_id: z.string(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   charge_out_rate: z.number(),
   wage_rate: z.number(),
   xero_pay_item_name: z.string().min(1),
@@ -2312,7 +2312,7 @@ const WorkshopTimesheetEntry = z.object({
   job_id: z.string().uuid(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   description: z.string(),
   hours: z.number().gt(-100000).lt(100000),
   accounting_date: z.string(),
@@ -2372,7 +2372,7 @@ const ScheduledJob = z.object({
   id: z.string().uuid(),
   job_number: z.number().int(),
   name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   remaining_hours: z.number(),
   delivery_date: z.string().nullable(),
   anticipated_start_date: z.string().nullable(),
@@ -2387,7 +2387,7 @@ const UnscheduledJob = z.object({
   id: z.string().uuid(),
   job_number: z.number().int(),
   name: z.string(),
-  client_name: z.string(),
+  company_name: z.string(),
   delivery_date: z.string().nullable(),
   remaining_hours: z.number(),
   reason: z.string(),
@@ -2600,7 +2600,7 @@ const JobForPurchasing = z.object({
   id: z.string().uuid(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
   name: z.string().max(100),
-  client_name: z.string().default('No Client'),
+  company_name: z.string().default('No Company'),
   status: JobStatusEnum.optional(),
   is_stock_holding: z.boolean(),
   job_display_name: z.string(),
@@ -2680,7 +2680,7 @@ const ProductMappingValidateResponse = z.object({
 const PurchaseOrderJob = z.object({
   job_number: z.string(),
   name: z.string(),
-  client: z.string(),
+  company: z.string(),
 })
 const PurchaseOrderList = z.object({
   id: z.string().uuid(),
@@ -2761,7 +2761,7 @@ const PurchaseOrderLine = z.object({
   location: z.string().max(255).nullish(),
   job_id: z.string().uuid().nullable(),
   job_number: z.number().int().nullable(),
-  client_name: z.string().nullable(),
+  company_name: z.string().nullable(),
   job_name: z.string().nullable(),
   times_used: z.number().int(),
 })
@@ -3135,7 +3135,7 @@ const JobBreakdown = z.object({
   job_id: z.string(),
   job_number: z.number().int(),
   job_name: z.string(),
-  client: z.string(),
+  company: z.string(),
   hours: z.number(),
   revenue: z.number(),
   cost: z.number(),
@@ -3194,7 +3194,7 @@ const ModernTimesheetJob = z.object({
   id: z.string().uuid(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
   name: z.string().max(100),
-  client_name: z.string().nullable(),
+  company_name: z.string().nullable(),
   status: JobStatusEnum.optional(),
   labour_rates: z.array(JobLabourRate),
   has_actual_costset: z.boolean(),
@@ -3479,7 +3479,7 @@ const XeroDocumentSuccessResponse = z.object({
   xero_id: z.string().uuid(),
   online_url: z.string().url().optional(),
   messages: z.array(z.string()).optional(),
-  client: z.string().optional(),
+  company: z.string().optional(),
   total_excl_tax: z.number().gt(-10000000000).lt(10000000000).optional(),
   total_incl_tax: z.number().gt(-10000000000).lt(10000000000).optional(),
   action: z.string().optional(),
@@ -3581,16 +3581,16 @@ export const schemas = {
   GroupedErrorResolveRequestRequest,
   GroupedErrorResolveResponse,
   BuildId,
-  ClientDetailResponse,
-  ClientErrorResponse,
-  ClientJobHeader,
-  ClientJobsResponse,
+  CompanyDetailResponse,
+  CompanyErrorResponse,
+  CompanyJobHeader,
+  CompanyJobsResponse,
   SupplierSearchAlias,
   SupplierSearchAliasCreateRequest,
-  ClientUpdateRequest,
-  ClientUpdateResponse,
-  PatchedClientUpdateRequest,
-  ClientNameOnly,
+  CompanyUpdateRequest,
+  CompanyUpdateResponse,
+  PatchedCompanyUpdateRequest,
+  CompanyNameOnly,
   MethodTypeEnum,
   ClientContactMethodSourceEnum,
   ClientContactMethod,
@@ -3600,16 +3600,16 @@ export const schemas = {
   ClientContact,
   ClientContactRequest,
   PatchedClientContactRequest,
-  ClientCreateRequest,
-  ClientSearchResult,
-  ClientCreateResponse,
-  ClientDuplicateErrorResponse,
+  CompanyCreateRequest,
+  CompanySearchResult,
+  CompanyCreateResponse,
+  CompanyDuplicateErrorResponse,
   JobContactResponse,
   JobContactUpdateRequest,
   SupplierPickupAddress,
   SupplierPickupAddressRequest,
   PatchedSupplierPickupAddressRequest,
-  ClientSearchResponse,
+  CompanySearchResponse,
   CompanyDefaults,
   CompanyDefaultsRequest,
   PatchedCompanyDefaultsRequest,
@@ -4223,7 +4223,7 @@ Returns:
           z
             .object({
               date: z.string(),
-              client_name: z.string(),
+              company_name: z.string(),
               job_number: z.number().int().nullable(),
               job_name: z.string().nullable(),
               invoice_numbers: z.string().nullable(),
@@ -4768,63 +4768,63 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'get',
-    path: '/api/clients/:client_id/',
-    alias: 'clients_retrieve',
-    description: `Retrieve detailed information for a specific client.`,
+    path: '/api/companies/:company_id/',
+    alias: 'companies_retrieve',
+    description: `Retrieve detailed information for a specific company.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
     ],
-    response: ClientDetailResponse,
+    response: CompanyDetailResponse,
     errors: [
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'get',
-    path: '/api/clients/:client_id/jobs/',
-    alias: 'clients_jobs_retrieve',
-    description: `Retrieve all jobs for a specific client.`,
+    path: '/api/companies/:company_id/jobs/',
+    alias: 'companies_jobs_retrieve',
+    description: `Retrieve all jobs for a specific company.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
     ],
-    response: ClientJobsResponse,
+    response: CompanyJobsResponse,
     errors: [
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'get',
-    path: '/api/clients/:client_id/supplier-aliases/',
-    alias: 'clients_supplier_aliases_list',
-    description: `List and create search aliases for a client/supplier contact.`,
+    path: '/api/companies/:company_id/supplier-aliases/',
+    alias: 'companies_supplier_aliases_list',
+    description: `List and create search aliases for a company/supplier contact.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
@@ -4833,9 +4833,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'post',
-    path: '/api/clients/:client_id/supplier-aliases/',
-    alias: 'clients_supplier_aliases_create',
-    description: `List and create search aliases for a client/supplier contact.`,
+    path: '/api/companies/:company_id/supplier-aliases/',
+    alias: 'companies_supplier_aliases_create',
+    description: `List and create search aliases for a company/supplier contact.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -4844,7 +4844,7 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         schema: z.object({ alias: z.string().min(1).max(255) }),
       },
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
@@ -4853,76 +4853,76 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'put',
-    path: '/api/clients/:client_id/update/',
-    alias: 'clients_update_update',
-    description: `Update an existing client&#x27;s information.`,
+    path: '/api/companies/:company_id/update/',
+    alias: 'companies_update_update',
+    description: `Update an existing company&#x27;s information.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientUpdateRequest,
+        schema: CompanyUpdateRequest,
       },
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
     ],
-    response: ClientUpdateResponse,
+    response: CompanyUpdateResponse,
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'patch',
-    path: '/api/clients/:client_id/update/',
-    alias: 'clients_update_partial_update',
-    description: `Partially update an existing client&#x27;s information.`,
+    path: '/api/companies/:company_id/update/',
+    alias: 'companies_update_partial_update',
+    description: `Partially update an existing company&#x27;s information.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: PatchedClientUpdateRequest,
+        schema: PatchedCompanyUpdateRequest,
       },
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Path',
         schema: z.string().uuid(),
       },
     ],
-    response: ClientUpdateResponse,
+    response: CompanyUpdateResponse,
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'post',
-    path: '/api/clients/addresses/validate/',
-    alias: 'clients_addresses_validate_create',
+    path: '/api/companies/addresses/validate/',
+    alias: 'companies_addresses_validate_create',
     description: `Validate an address and return structured candidates.`,
     requestFormat: 'json',
     parameters: [
@@ -4965,27 +4965,27 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'get',
-    path: '/api/clients/all/',
-    alias: 'clients_all_list',
-    description: `Returns a list of all clients with basic information (id and name) for dropdowns and search.`,
+    path: '/api/companies/all/',
+    alias: 'companies_all_list',
+    description: `Returns a list of all companies with basic information (id and name) for dropdowns and search.`,
     requestFormat: 'json',
-    response: z.array(ClientNameOnly),
+    response: z.array(CompanyNameOnly),
     errors: [
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'get',
-    path: '/api/clients/contact-methods/',
-    alias: 'clients_contact_methods_list',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/',
+    alias: 'companies_contact_methods_list',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Query',
         schema: z.string().uuid().optional(),
       },
@@ -5014,9 +5014,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'post',
-    path: '/api/clients/contact-methods/',
-    alias: 'clients_contact_methods_create',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/',
+    alias: 'companies_contact_methods_create',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5029,9 +5029,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'get',
-    path: '/api/clients/contact-methods/:id/',
-    alias: 'clients_contact_methods_retrieve',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/:id/',
+    alias: 'companies_contact_methods_retrieve',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5044,9 +5044,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'put',
-    path: '/api/clients/contact-methods/:id/',
-    alias: 'clients_contact_methods_update',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/:id/',
+    alias: 'companies_contact_methods_update',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5064,9 +5064,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'patch',
-    path: '/api/clients/contact-methods/:id/',
-    alias: 'clients_contact_methods_partial_update',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/:id/',
+    alias: 'companies_contact_methods_partial_update',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5084,9 +5084,9 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'delete',
-    path: '/api/clients/contact-methods/:id/',
-    alias: 'clients_contact_methods_destroy',
-    description: `CRUD API for canonical client/contact phone and email methods.`,
+    path: '/api/companies/contact-methods/:id/',
+    alias: 'companies_contact_methods_destroy',
+    description: `CRUD API for canonical company/contact phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5099,13 +5099,13 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'get',
-    path: '/api/clients/contacts/',
-    alias: 'clients_contacts_list',
-    description: `List all contacts, optionally filtered by client_id.`,
+    path: '/api/companies/contacts/',
+    alias: 'companies_contacts_list',
+    description: `List all contacts, optionally filtered by company_id.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_id',
+        name: 'company_id',
         type: 'Query',
         schema: z.string().uuid().optional(),
       },
@@ -5114,20 +5114,20 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
   },
   {
     method: 'post',
-    path: '/api/clients/contacts/',
-    alias: 'clients_contacts_create',
+    path: '/api/companies/contacts/',
+    alias: 'companies_contacts_create',
     description: `ViewSet for ClientContact CRUD operations.
 
 Endpoints:
-- GET    /api/clients/contacts/           - list all contacts
-- POST   /api/clients/contacts/           - create contact
-- GET    /api/clients/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/clients/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/clients/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/clients/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/contacts/           - list all contacts
+- POST   /api/companies/contacts/           - create contact
+- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
+- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
+- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
+- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- client_id: Filter contacts by client UUID`,
+- company_id: Filter contacts by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5140,20 +5140,20 @@ Query Parameters:
   },
   {
     method: 'get',
-    path: '/api/clients/contacts/:id/',
-    alias: 'clients_contacts_retrieve',
+    path: '/api/companies/contacts/:id/',
+    alias: 'companies_contacts_retrieve',
     description: `ViewSet for ClientContact CRUD operations.
 
 Endpoints:
-- GET    /api/clients/contacts/           - list all contacts
-- POST   /api/clients/contacts/           - create contact
-- GET    /api/clients/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/clients/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/clients/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/clients/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/contacts/           - list all contacts
+- POST   /api/companies/contacts/           - create contact
+- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
+- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
+- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
+- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- client_id: Filter contacts by client UUID`,
+- company_id: Filter contacts by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5166,20 +5166,20 @@ Query Parameters:
   },
   {
     method: 'put',
-    path: '/api/clients/contacts/:id/',
-    alias: 'clients_contacts_update',
+    path: '/api/companies/contacts/:id/',
+    alias: 'companies_contacts_update',
     description: `ViewSet for ClientContact CRUD operations.
 
 Endpoints:
-- GET    /api/clients/contacts/           - list all contacts
-- POST   /api/clients/contacts/           - create contact
-- GET    /api/clients/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/clients/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/clients/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/clients/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/contacts/           - list all contacts
+- POST   /api/companies/contacts/           - create contact
+- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
+- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
+- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
+- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- client_id: Filter contacts by client UUID`,
+- company_id: Filter contacts by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5197,20 +5197,20 @@ Query Parameters:
   },
   {
     method: 'patch',
-    path: '/api/clients/contacts/:id/',
-    alias: 'clients_contacts_partial_update',
+    path: '/api/companies/contacts/:id/',
+    alias: 'companies_contacts_partial_update',
     description: `ViewSet for ClientContact CRUD operations.
 
 Endpoints:
-- GET    /api/clients/contacts/           - list all contacts
-- POST   /api/clients/contacts/           - create contact
-- GET    /api/clients/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/clients/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/clients/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/clients/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/contacts/           - list all contacts
+- POST   /api/companies/contacts/           - create contact
+- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
+- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
+- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
+- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- client_id: Filter contacts by client UUID`,
+- company_id: Filter contacts by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5228,20 +5228,20 @@ Query Parameters:
   },
   {
     method: 'delete',
-    path: '/api/clients/contacts/:id/',
-    alias: 'clients_contacts_destroy',
+    path: '/api/companies/contacts/:id/',
+    alias: 'companies_contacts_destroy',
     description: `ViewSet for ClientContact CRUD operations.
 
 Endpoints:
-- GET    /api/clients/contacts/           - list all contacts
-- POST   /api/clients/contacts/           - create contact
-- GET    /api/clients/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/clients/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/clients/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/clients/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/contacts/           - list all contacts
+- POST   /api/companies/contacts/           - create contact
+- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
+- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
+- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
+- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- client_id: Filter contacts by client UUID`,
+- company_id: Filter contacts by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5254,41 +5254,41 @@ Query Parameters:
   },
   {
     method: 'post',
-    path: '/api/clients/create/',
-    alias: 'clients_create_create',
-    description: `Creates a new client in Xero first, then syncs locally. Requires valid Xero authentication.`,
+    path: '/api/companies/create/',
+    alias: 'companies_create_create',
+    description: `Creates a new company in Xero first, then syncs locally. Requires valid Xero authentication.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientCreateRequest,
+        schema: CompanyCreateRequest,
       },
     ],
-    response: ClientCreateResponse,
+    response: CompanyCreateResponse,
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 401,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 409,
-        schema: ClientDuplicateErrorResponse,
+        schema: CompanyDuplicateErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'get',
-    path: '/api/clients/jobs/:job_id/contact/',
-    alias: 'clients_jobs_contact_retrieve',
+    path: '/api/companies/jobs/:job_id/contact/',
+    alias: 'companies_jobs_contact_retrieve',
     description: `Retrieve contact information for a specific job.`,
     requestFormat: 'json',
     parameters: [
@@ -5302,18 +5302,18 @@ Query Parameters:
     errors: [
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'put',
-    path: '/api/clients/jobs/:job_id/contact/',
-    alias: 'clients_jobs_contact_update',
+    path: '/api/companies/jobs/:job_id/contact/',
+    alias: 'companies_jobs_contact_update',
     description: `Update the contact person associated with a specific job.`,
     requestFormat: 'json',
     parameters: [
@@ -5332,22 +5332,22 @@ Query Parameters:
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 404,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'get',
-    path: '/api/clients/pickup-addresses/',
-    alias: 'clients_pickup_addresses_list',
+    path: '/api/companies/pickup-addresses/',
+    alias: 'companies_pickup_addresses_list',
     description: `List all pickup addresses, optionally filtered by supplier_id.`,
     requestFormat: 'json',
     parameters: [
@@ -5361,20 +5361,20 @@ Query Parameters:
   },
   {
     method: 'post',
-    path: '/api/clients/pickup-addresses/',
-    alias: 'clients_pickup_addresses_create',
+    path: '/api/companies/pickup-addresses/',
+    alias: 'companies_pickup_addresses_create',
     description: `ViewSet for SupplierPickupAddress CRUD operations.
 
 Endpoints:
-- GET    /api/clients/pickup-addresses/           - list all addresses
-- POST   /api/clients/pickup-addresses/           - create address
-- GET    /api/clients/pickup-addresses/&lt;id&gt;/      - retrieve address
-- PUT    /api/clients/pickup-addresses/&lt;id&gt;/      - full update
-- PATCH  /api/clients/pickup-addresses/&lt;id&gt;/      - partial update
-- DELETE /api/clients/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/pickup-addresses/           - list all addresses
+- POST   /api/companies/pickup-addresses/           - create address
+- GET    /api/companies/pickup-addresses/&lt;id&gt;/      - retrieve address
+- PUT    /api/companies/pickup-addresses/&lt;id&gt;/      - full update
+- PATCH  /api/companies/pickup-addresses/&lt;id&gt;/      - partial update
+- DELETE /api/companies/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- supplier_id: Filter addresses by supplier (client) UUID`,
+- supplier_id: Filter addresses by supplier (company) UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5387,20 +5387,20 @@ Query Parameters:
   },
   {
     method: 'get',
-    path: '/api/clients/pickup-addresses/:id/',
-    alias: 'clients_pickup_addresses_retrieve',
+    path: '/api/companies/pickup-addresses/:id/',
+    alias: 'companies_pickup_addresses_retrieve',
     description: `ViewSet for SupplierPickupAddress CRUD operations.
 
 Endpoints:
-- GET    /api/clients/pickup-addresses/           - list all addresses
-- POST   /api/clients/pickup-addresses/           - create address
-- GET    /api/clients/pickup-addresses/&lt;id&gt;/      - retrieve address
-- PUT    /api/clients/pickup-addresses/&lt;id&gt;/      - full update
-- PATCH  /api/clients/pickup-addresses/&lt;id&gt;/      - partial update
-- DELETE /api/clients/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/pickup-addresses/           - list all addresses
+- POST   /api/companies/pickup-addresses/           - create address
+- GET    /api/companies/pickup-addresses/&lt;id&gt;/      - retrieve address
+- PUT    /api/companies/pickup-addresses/&lt;id&gt;/      - full update
+- PATCH  /api/companies/pickup-addresses/&lt;id&gt;/      - partial update
+- DELETE /api/companies/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- supplier_id: Filter addresses by supplier (client) UUID`,
+- supplier_id: Filter addresses by supplier (company) UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5413,20 +5413,20 @@ Query Parameters:
   },
   {
     method: 'put',
-    path: '/api/clients/pickup-addresses/:id/',
-    alias: 'clients_pickup_addresses_update',
+    path: '/api/companies/pickup-addresses/:id/',
+    alias: 'companies_pickup_addresses_update',
     description: `ViewSet for SupplierPickupAddress CRUD operations.
 
 Endpoints:
-- GET    /api/clients/pickup-addresses/           - list all addresses
-- POST   /api/clients/pickup-addresses/           - create address
-- GET    /api/clients/pickup-addresses/&lt;id&gt;/      - retrieve address
-- PUT    /api/clients/pickup-addresses/&lt;id&gt;/      - full update
-- PATCH  /api/clients/pickup-addresses/&lt;id&gt;/      - partial update
-- DELETE /api/clients/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/pickup-addresses/           - list all addresses
+- POST   /api/companies/pickup-addresses/           - create address
+- GET    /api/companies/pickup-addresses/&lt;id&gt;/      - retrieve address
+- PUT    /api/companies/pickup-addresses/&lt;id&gt;/      - full update
+- PATCH  /api/companies/pickup-addresses/&lt;id&gt;/      - partial update
+- DELETE /api/companies/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- supplier_id: Filter addresses by supplier (client) UUID`,
+- supplier_id: Filter addresses by supplier (company) UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5444,20 +5444,20 @@ Query Parameters:
   },
   {
     method: 'patch',
-    path: '/api/clients/pickup-addresses/:id/',
-    alias: 'clients_pickup_addresses_partial_update',
+    path: '/api/companies/pickup-addresses/:id/',
+    alias: 'companies_pickup_addresses_partial_update',
     description: `ViewSet for SupplierPickupAddress CRUD operations.
 
 Endpoints:
-- GET    /api/clients/pickup-addresses/           - list all addresses
-- POST   /api/clients/pickup-addresses/           - create address
-- GET    /api/clients/pickup-addresses/&lt;id&gt;/      - retrieve address
-- PUT    /api/clients/pickup-addresses/&lt;id&gt;/      - full update
-- PATCH  /api/clients/pickup-addresses/&lt;id&gt;/      - partial update
-- DELETE /api/clients/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/pickup-addresses/           - list all addresses
+- POST   /api/companies/pickup-addresses/           - create address
+- GET    /api/companies/pickup-addresses/&lt;id&gt;/      - retrieve address
+- PUT    /api/companies/pickup-addresses/&lt;id&gt;/      - full update
+- PATCH  /api/companies/pickup-addresses/&lt;id&gt;/      - partial update
+- DELETE /api/companies/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- supplier_id: Filter addresses by supplier (client) UUID`,
+- supplier_id: Filter addresses by supplier (company) UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5475,20 +5475,20 @@ Query Parameters:
   },
   {
     method: 'delete',
-    path: '/api/clients/pickup-addresses/:id/',
-    alias: 'clients_pickup_addresses_destroy',
+    path: '/api/companies/pickup-addresses/:id/',
+    alias: 'companies_pickup_addresses_destroy',
     description: `ViewSet for SupplierPickupAddress CRUD operations.
 
 Endpoints:
-- GET    /api/clients/pickup-addresses/           - list all addresses
-- POST   /api/clients/pickup-addresses/           - create address
-- GET    /api/clients/pickup-addresses/&lt;id&gt;/      - retrieve address
-- PUT    /api/clients/pickup-addresses/&lt;id&gt;/      - full update
-- PATCH  /api/clients/pickup-addresses/&lt;id&gt;/      - partial update
-- DELETE /api/clients/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/pickup-addresses/           - list all addresses
+- POST   /api/companies/pickup-addresses/           - create address
+- GET    /api/companies/pickup-addresses/&lt;id&gt;/      - retrieve address
+- PUT    /api/companies/pickup-addresses/&lt;id&gt;/      - full update
+- PATCH  /api/companies/pickup-addresses/&lt;id&gt;/      - partial update
+- DELETE /api/companies/pickup-addresses/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- supplier_id: Filter addresses by supplier (client) UUID`,
+- supplier_id: Filter addresses by supplier (company) UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5501,9 +5501,9 @@ Query Parameters:
   },
   {
     method: 'get',
-    path: '/api/clients/search/',
-    alias: 'clients_search_retrieve',
-    description: `Lists/searches clients with pagination and sorting.`,
+    path: '/api/companies/search/',
+    alias: 'companies_search_retrieve',
+    description: `Lists/searches companies with pagination and sorting.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5532,18 +5532,18 @@ Query Parameters:
         schema: z.string().optional(),
       },
     ],
-    response: ClientSearchResponse,
+    response: CompanySearchResponse,
     errors: [
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
   {
     method: 'delete',
-    path: '/api/clients/supplier-aliases/:alias_id/',
-    alias: 'clients_supplier_aliases_destroy',
+    path: '/api/companies/supplier-aliases/:alias_id/',
+    alias: 'companies_supplier_aliases_destroy',
     description: `Deactivate a supplier search alias.`,
     requestFormat: 'json',
     parameters: [
@@ -5752,14 +5752,14 @@ DELETE: Clear a logo field and remove the file from disk.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client',
+        name: 'client_match',
         type: 'Query',
-        schema: z.string().uuid().optional(),
+        schema: z.string().optional(),
       },
       {
-        name: 'client_match',
+        name: 'company',
         type: 'Query',
-        schema: z.string().optional(),
+        schema: z.string().uuid().optional(),
       },
       {
         name: 'contact',
@@ -6140,7 +6140,7 @@ POST /job/rest/cost_lines/&lt;cost_line_id&gt;/approve`,
     method: 'get',
     path: '/api/job/data-quality/duplicate-phones/',
     alias: 'check_duplicate_phones',
-    description: `List phone numbers owned by more than one client, or client numbers that are actually internal company lines.`,
+    description: `List phone numbers owned by more than one company, or company numbers that are actually internal company lines.`,
     requestFormat: 'json',
     response: DuplicatePhonesResponse,
     errors: [
@@ -7343,7 +7343,7 @@ Expected JSON:
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_name',
+        name: 'company_name',
         type: 'Query',
         schema: z.string().optional(),
       },
@@ -9227,7 +9227,7 @@ Custom Actions:
     alias: 'getSupplierPriceStatus',
     description: `Return latest price upload status per supplier.
 
-Minimal-impact: read-only query over existing Client and SupplierPriceList
+Minimal-impact: read-only query over existing Company and SupplierPriceList
 models. No migrations required.`,
     requestFormat: 'json',
     response: SupplierPriceStatusResponse,
@@ -9388,7 +9388,7 @@ Supports pagination via &#x60;&#x60;limit&#x60;&#x60;/&#x60;&#x60;offset&#x60;&#
     method: 'post',
     path: '/api/search-events/click/',
     alias: 'search_events_click_create',
-    description: `Records a selected result from client, Kanban, or stock search.`,
+    description: `Records a selected result from company, Kanban, or stock search.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -9552,7 +9552,7 @@ Returns:
     errors: [
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
@@ -9573,15 +9573,15 @@ Returns:
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 409,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
@@ -9595,7 +9595,7 @@ Returns:
     errors: [
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
@@ -9618,7 +9618,7 @@ Use GET /api/payroll/post-staff-week/stream/{task_id}/ to receive SSE progress.`
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
@@ -9681,11 +9681,11 @@ Returns:
     errors: [
       {
         status: 400,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
       {
         status: 500,
-        schema: ClientErrorResponse,
+        schema: CompanyErrorResponse,
       },
     ],
   },
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index b66a3f507..535303973 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -1,17 +1,6 @@
 apps/job/services/kanban_categorization_service.py:0: error: Missing type arguments for generic type "List"  [type-arg]
 apps/job/services/kanban_categorization_service.py:0: error: Missing type arguments for generic type "List"  [type-arg]
 apps/workflow/tests/fixtures/xero_responses.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
-apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.InvoicePayload.date" is not valid as a type  [valid-type]
-apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
-apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
-apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.QuotePayload.date" is not valid as a type  [valid-type]
-apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
-apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
-apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.POPayload.date" is not valid as a type  [valid-type]
-apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
-apps/workflow/accounting/types.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/accounting/types.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/views/xero/xero_helpers.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_helpers.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_helpers.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
@@ -28,8 +17,8 @@ apps/job/services/delta_checksum.py:0: error: Incompatible types in assignment (
 apps/job/services/delta_checksum.py:0: error: Argument 1 to "join" of "str" has incompatible type "Decimal"; expected "Iterable[str]"  [arg-type]
 apps/accounts/staff_anonymization.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/accounts/staff_anonymization.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/client/utils.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/services/geocoding_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/company/utils.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/services/geocoding_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/job/tests/test_delta_checksum.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_delta_checksum.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_delta_checksum.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -44,6 +33,28 @@ apps/job/tests/test_delta_checksum.py:0: error: Function is missing a return typ
 apps/job/tests/test_delta_checksum.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_delta_checksum.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_delta_checksum.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/services/providers/mistral_provider.py:0: error: Argument 1 to "_parse_price_from_string" of "MistralPriceExtractionProvider" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "encode_pdf" in typed context  [no-untyped-call]
+apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
+apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
+apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
+apps/quoting/tests/test_ocr_fixtures.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests/test_ocr_fixtures.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/tests/test_ocr_fixtures.py:0: error: Call to untyped function "_ocr_response" in typed context  [no-untyped-call]
+apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
+apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.InvoicePayload.date" is not valid as a type  [valid-type]
+apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
+apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.QuotePayload.date" is not valid as a type  [valid-type]
+apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+apps/workflow/accounting/types.py:0: error: Name "date" is not defined  [name-defined]
+apps/workflow/accounting/types.py:0: error: Variable "apps.workflow.accounting.types.POPayload.date" is not valid as a type  [valid-type]
+apps/workflow/accounting/types.py:0: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#variables-vs-type-aliases
+apps/workflow/accounting/types.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/accounting/types.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 docketworks/settings.py:0: error: Item "None" of "str | None" has no attribute "lower"  [union-attr]
 docketworks/settings.py:0: error: Item "None" of "str | None" has no attribute "lower"  [union-attr]
 docketworks/settings.py:0: error: Item "None" of "str | None" has no attribute "lower"  [union-attr]
@@ -79,11 +90,11 @@ apps/accounting/models/invoice.py:0: error: Incompatible return value type (got
 apps/accounting/models/invoice.py:0: error: Generator has incompatible item type "Any | Decimal"; expected "bool"  [misc]
 apps/accounting/models/invoice.py:0: error: "BaseXeroInvoiceDocument" has no attribute "line_items"  [attr-defined]
 apps/job/helpers.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/client/models.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/models.py:0: error: Missing type arguments for generic type "QuerySet"  [type-arg]
-apps/client/models.py:0: error: Need type annotation for "CLIENTCONTACT_INTERNAL_FIELDS" (hint: "CLIENTCONTACT_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
-apps/client/models.py:0: error: Incompatible type for lookup 'client_id': (got "UUID | None", expected "UUID | str")  [misc]
-apps/client/models.py:0: error: Need type annotation for "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS" (hint: "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
+apps/company/models.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/models.py:0: error: Missing type arguments for generic type "QuerySet"  [type-arg]
+apps/company/models.py:0: error: Need type annotation for "CLIENTCONTACT_INTERNAL_FIELDS" (hint: "CLIENTCONTACT_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
+apps/company/models.py:0: error: Incompatible type for lookup 'company_id': (got "UUID | None", expected "UUID | str")  [misc]
+apps/company/models.py:0: error: Need type annotation for "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS" (hint: "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
 apps/workflow/models/company_defaults.py:0: error: Call to untyped function "_recompute_all_staff_wage_rates" in typed context  [no-untyped-call]
 apps/job/services/file_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/services/file_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -253,12 +264,57 @@ docketworks/celery.py:0: error: Module "celery.signals" has no attribute "task_p
 docketworks/celery.py:0: error: Module "celery.signals" has no attribute "task_prerun"  [attr-defined]
 docketworks/celery.py:0: error: Untyped decorator makes function "_nplusone_setup" untyped  [untyped-decorator]
 docketworks/celery.py:0: error: Untyped decorator makes function "_nplusone_teardown" untyped  [untyped-decorator]
+apps/workflow/services/request.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/workflow/services/request.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/job/services/time_entry_rates.py:0: error: Item "None" of "Any | None" has no attribute "xero_id"  [union-attr]
+apps/job/services/time_entry_rates.py:0: error: Item "None" of "Any | None" has no attribute "name"  [union-attr]
+apps/job/services/time_entry_rates.py:0: error: Incompatible return value type (got "Any | None", expected "XeroPayItem")  [return-value]
+apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/company/tests/test_get_company_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_get_company_for_xero.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_get_company_for_xero.py:0: error: Call to untyped function "_make_company" in typed context  [no-untyped-call]
+apps/workflow/management/commands/sync_sequences.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/services/session_replay_service.py:0: error: Argument 1 to "Path" has incompatible type "str | None"; expected "str | PathLike[str]"  [arg-type]
 apps/workflow/services/session_replay_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/services/search_telemetry.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/services/search_telemetry.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/services/request.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
-apps/workflow/services/request.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Returning Any from function declared to return "dict[Any, Any]"  [no-any-return]
 apps/workflow/api/xero/client.py:0: error: Class cannot subclass "RESTClientObject" (has type "Any")  [misc]
 apps/workflow/api/xero/client.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/client.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -297,6 +353,28 @@ apps/workflow/accounting/provider.py:0: error: Missing type arguments for generi
 apps/timesheet/services/xero_hours.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/timesheet/services/xero_hours.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/timesheet/services/xero_hours.py:0: error: Incompatible return value type (got "dict[str | None, Staff]", expected "dict[str, Staff]")  [return-value]
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
 apps/quoting/services/pdf_data_validation.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/quoting/services/pdf_data_validation.py:0: note: Use "-> None" if function does not return a value
 apps/quoting/services/pdf_data_validation.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
@@ -340,10 +418,9 @@ apps/job/tests/test_job_delta_rejection_resolution.py:0: error: Function is miss
 apps/job/tests/test_job_delta_rejection_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/_pdf_golden_fixtures.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/job/tests/_pdf_golden_fixtures.py:0: error: Incompatible types in assignment (expression has type "Company", variable has type "CompanyDefaults")  [assignment]
+apps/job/tests/_pdf_golden_fixtures.py:0: error: Incompatible type for "company" of "ClientContact" (got "CompanyDefaults", expected "Company | Combinable")  [misc]
 apps/job/tests/_pdf_golden_fixtures.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
-apps/job/services/time_entry_rates.py:0: error: Item "None" of "Any | None" has no attribute "xero_id"  [union-attr]
-apps/job/services/time_entry_rates.py:0: error: Item "None" of "Any | None" has no attribute "name"  [union-attr]
-apps/job/services/time_entry_rates.py:0: error: Incompatible return value type (got "Any | None", expected "XeroPayItem")  [return-value]
 apps/job/services/job_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/services/job_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/services/job_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
@@ -403,34 +480,68 @@ apps/job/importers/quote_spreadsheet.py:0: error: Function is missing a type ann
 apps/job/importers/google_sheets.py:0: error: Call to untyped function "from_service_account_file" of "Credentials" in typed context  [no-untyped-call]
 apps/crm/services/phone_call_service.py:0: error: Module "django.utils.timezone" does not explicitly export attribute "timedelta"  [attr-defined]
 apps/crm/services/phone_call_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/crm/services/phone_call_service.py:0: error: Dict entry 0 has incompatible type "str": "Client"; expected "str": "ClientContact | None"  [dict-item]
+apps/crm/services/phone_call_service.py:0: error: Dict entry 0 has incompatible type "str": "Company"; expected "str": "ClientContact | None"  [dict-item]
 apps/crm/services/phone_call_service.py:0: error: Item "None" of "ClientContact | None" has no attribute "is_active"  [union-attr]
-apps/crm/services/phone_call_service.py:0: error: Item "None" of "ClientContact | None" has no attribute "client_id"  [union-attr]
-apps/crm/services/phone_call_service.py:0: error: Item "None" of "Client | None" has no attribute "allow_jobs"  [union-attr]
+apps/crm/services/phone_call_service.py:0: error: Item "None" of "ClientContact | None" has no attribute "company_id"  [union-attr]
+apps/crm/services/phone_call_service.py:0: error: Item "None" of "Company | None" has no attribute "allow_jobs"  [union-attr]
 apps/accounting/services/sales_pipeline_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/accounting/services/sales_pipeline_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types in assignment (expression has type "float | None", target has type "float")  [assignment]
 apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types in assignment (expression has type "float | None", target has type "float")  [assignment]
 apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types in assignment (expression has type "float | None", target has type "float")  [assignment]
-apps/accounting/services/sales_pipeline_service.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/accounting/services/sales_pipeline_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/accounting/services/invoice_calculation.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
+apps/company/services/company_merge_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/management/commands/merge_companies.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/management/commands/merge_companies.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/services/providers/gemini_provider.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "bool", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "bool", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "int", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "Any | None", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "int", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "list[dict[str, object]]", target has type "Sequence[str]")  [assignment]
+apps/quoting/services/providers/gemini_provider.py:0: error: Need type annotation for "supplier_info" (hint: "supplier_info: dict[<type>, <type>] = ...")  [var-annotated]
+apps/quoting/services/providers/gemini_provider.py:0: error: Missing type arguments for generic type "List"  [type-arg]
+apps/quoting/services/providers/gemini_provider.py:0: error: Argument "config" to "generate_content" of "Models" has incompatible type "dict[str, object]"; expected "GenerateContentConfig | GenerateContentConfigDict | None"  [arg-type]
+apps/quoting/services/providers/gemini_provider.py:0: error: Call to untyped function "log_token_usage" in typed context  [no-untyped-call]
+apps/purchasing/services/quote_to_po_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/purchasing/services/quote_to_po_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/services/quote_to_po_service.py:0: error: Dict entry 0 has incompatible type "str": "dict[str, str]"; expected "str": "str"  [dict-item]
+apps/purchasing/services/quote_to_po_service.py:0: error: Dict entry 0 has incompatible type "str": "dict[str, str]"; expected "str": "str"  [dict-item]
+apps/purchasing/services/quote_to_po_service.py:0: error: Argument "contents" to "generate_content" of "Models" has incompatible type "list[dict[str, str]]"; expected "Content | ContentDict | str | Image | File | FileDict | Part | PartDict | list[str | Image | File | FileDict | Part | PartDict] | list[Content | ContentDict | str | Image | File | FileDict | Part | PartDict | list[str | Image | File | FileDict | Part | PartDict]]"  [arg-type]
+apps/purchasing/services/quote_to_po_service.py:0: error: Call to untyped function "log_token_usage" in typed context  [no-untyped-call]
+apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "clean_json_response" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/services/llm_service.py:0: error: Module "litellm" does not explicitly export attribute "set_verbose"  [attr-defined]
+apps/workflow/services/llm_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Call to untyped function "get_default" of "AIProvider" in typed context  [no-untyped-call]
+apps/workflow/services/llm_service.py:0: error: No overload variant of "get" of "dict" matches argument types "str", "str"  [call-overload]
+apps/workflow/services/llm_service.py:0: note: Possible overload variants:
+apps/workflow/services/llm_service.py:0: note: def get(self, AIProviderTypes, None = ..., /) -> str | None
+apps/workflow/services/llm_service.py:0: note: def get(self, AIProviderTypes, str, /) -> str
+apps/workflow/services/llm_service.py:0: note: def [_T] get(self, AIProviderTypes, _T, /) -> str | _T
+apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Returning Any from function declared to return "dict[Any, Any]"  [no-any-return]
+apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/services/dev_demo_export_scrubber.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/job/services/month_end_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
-apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/month_end_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
-apps/job/services/month_end_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/tests/test_xero_pay_item.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_pay_item.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_xero_pay_item.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_pay_item.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_instance_templates.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_instance_templates.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_xero_app_model.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_app_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_app_model.py:0: note: Use "-> None" if function does not return a value
@@ -451,37 +562,6 @@ apps/workflow/tests/test_xero_app_model.py:0: error: Function is missing a retur
 apps/workflow/tests/test_xero_app_model.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_xero_app_model.py:0: error: Call to untyped function "_row" in typed context  [no-untyped-call]
 apps/workflow/tests/test_xero_app_model.py:0: error: Call to untyped function "_row" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/client/tests/test_get_client_for_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_get_client_for_xero.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_get_client_for_xero.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
 apps/workflow/management/commands/create_service_api_key.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/create_service_api_key.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/timesheet/management/commands/reassign_time_entries.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -502,10 +582,131 @@ apps/job/management/commands/set_paid_flag_jobs.py:0: error: Function is missing
 apps/job/management/commands/set_paid_flag_jobs.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/management/commands/create_shop_jobs.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/management/commands/create_shop_jobs.py:0: error: Unexpected attribute "shop_job" for model "Job"  [misc]
-apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/management/commands/backfill_kanban_search_telemetry.py:0: error: Returning Any from function declared to return "dict[Any, Any]"  [no-any-return]
+apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_procedure_model.py:0: error: Item "None" of "Procedure | None" has no attribute "title"  [union-attr]
+apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/tests/test_form_model.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
+apps/process/services/form_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/process/services/form_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "delete" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Call to untyped function "get_default_cost_set_summary" in typed context  [no-untyped-call]
+apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/workshop_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/utils.py:0: error: Missing type arguments for generic type "QuerySet"  [type-arg]
+apps/accounts/utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/utils.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/tests/test_relabel_client_app.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/utils.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/search_telemetry_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/workflow/search_telemetry_serializers.py:0: error: Incompatible types in assignment (expression has type "CharField", base class "Field" defined the type as "Callable[..., Any] | str | None")  [assignment]
+apps/workflow/search_telemetry_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/workflow/exception_handlers.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/exception_handlers.py:0: error: Argument "user_id" to "persist_app_error" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/exception_handlers.py:0: error: Argument "session_replay_id" to "persist_app_error" has incompatible type "Any | None"; expected "str"  [arg-type]
+apps/workflow/exception_handlers.py:0: error: Argument "additional_context" to "persist_app_error" has incompatible type "dict[str, Any] | None"; expected "dict[Any, Any]"  [arg-type]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Incompatible types in assignment (expression has type "ListField", base class "Serializer" defined the type as "ReturnDict[Any, Any]")  [assignment]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers_scheduled_tasks.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/quoting/serializers_scheduled_tasks.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/job/permissions.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/permissions.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/serializers/quote_spreadsheet_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/company/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/workflow/views/build_id_view.py:0: error: Missing type arguments for generic type "list"  [type-arg]
+apps/workflow/api/reports/pnl.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/month_end_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
+apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/month_end_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/month_end_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
+apps/job/services/month_end_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/tests/test_error_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_error_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_error_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -551,28 +752,6 @@ apps/timesheet/management/commands/create_overtime_entries.py:0: error: Item "Co
 apps/timesheet/management/commands/create_overtime_entries.py:0: error: Item "Staff" of "str | Any | date | Decimal | CostSet | Staff" has no attribute "startswith"  [union-attr]
 apps/timesheet/management/commands/create_overtime_entries.py:0: error: Invalid index type "str | Any | date | Decimal | CostSet | Staff" for "dict[str, int]"; expected type "str"  [index]
 apps/timesheet/management/commands/create_overtime_entries.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/tests_utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests_utils.py:0: note: Use "-> None" if function does not return a value
 apps/quoting/mcp.py:0: error: Class cannot subclass "ModelQueryToolset" (has type "Any")  [misc]
 apps/quoting/mcp.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/quoting/mcp.py:0: error: Class cannot subclass "MCPToolset" (has type "Any")  [misc]
@@ -585,34 +764,12 @@ apps/quoting/mcp.py:0: note: Use https://github.com/hauntsaninja/no_implicit_opt
 apps/quoting/mcp.py:0: error: Incompatible default for parameter "labor_hours" (default has type "None", parameter has type "float")  [assignment]
 apps/quoting/mcp.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
 apps/quoting/mcp.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
-apps/quoting/mcp.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/quoting/mcp.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/quoting/mcp.py:0: error: Incompatible types in assignment (expression has type "float", variable has type "int")  [assignment]
 apps/quoting/mcp.py:0: error: Incompatible default for parameter "supplier_name" (default has type "None", parameter has type "str")  [assignment]
 apps/quoting/mcp.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
 apps/quoting/mcp.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
 apps/quoting/mcp.py:0: error: Need type annotation for "supplier_prices" (hint: "supplier_prices: dict[<type>, <type>] = ...")  [var-annotated]
-apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_procedure_model.py:0: error: Item "None" of "Procedure | None" has no attribute "title"  [union-attr]
-apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_procedure_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_procedure_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/tests/test_form_model.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/tests/test_form_model.py:0: note: Use "-> None" if function does not return a value
-apps/process/services/form_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/process/services/form_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/operations/services/scheduler_service.py:0: error: Missing type arguments for generic type "frozenset"  [type-arg]
 apps/operations/services/scheduler_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/operations/services/scheduler_service.py:0: error: Missing type arguments for generic type "frozenset"  [type-arg]
@@ -622,25 +779,6 @@ apps/operations/services/scheduler_service.py:0: error: Invalid index type "UUID
 apps/operations/services/scheduler_service.py:0: error: Invalid index type "UUID" for "dict[int, float]"; expected type "int"  [index]
 apps/operations/services/scheduler_service.py:0: error: Invalid index type "UUID" for "dict[int, float]"; expected type "int"  [index]
 apps/operations/services/scheduler_service.py:0: error: Missing type arguments for generic type "frozenset"  [type-arg]
-apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "_format_time" of "WorkshopTimesheetService" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "delete" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Call to untyped function "get_default_cost_set_summary" in typed context  [no-untyped-call]
-apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/workshop_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/services/job_profitability_report.py:0: error: Call to untyped function "_get_queryset" in typed context  [no-untyped-call]
 apps/job/services/job_profitability_report.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/services/job_profitability_report.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
@@ -702,20 +840,8 @@ apps/workflow/services/db_scrubber.py:0: error: Argument 1 to "add" of "set" has
 apps/job/services/data_integrity_service.py:0: error: Missing return statement  [return]
 apps/job/services/data_integrity_service.py:0: error: Dict entry 4 has incompatible type "str": "list[str]"; expected "str": "str"  [dict-item]
 apps/job/services/data_integrity_service.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/client/services/client_merge_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/accounting/services/wip_service.py:0: error: Argument "key" to "sorted" has incompatible type "Callable[[dict[str, object]], object]"; expected "Callable[[dict[str, object]], SupportsDunderLT[Any] | SupportsDunderGT[Any]]"  [arg-type]
 apps/accounting/services/wip_service.py:0: error: Incompatible return value type (got "object", expected "SupportsDunderLT[Any] | SupportsDunderGT[Any]")  [return-value]
-apps/accounts/utils.py:0: error: Missing type arguments for generic type "QuerySet"  [type-arg]
-apps/accounts/utils.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/utils.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_dev_demo_export.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_dev_demo_export.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/sync_sequences.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
@@ -734,10 +860,62 @@ apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped funct
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_base_manager.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/views/xero/xero_base_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_base_manager.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/views/xero/xero_base_manager.py:0: error: Call to untyped function "validate_for_xero" in typed context  [no-untyped-call]
+apps/quoting/services/ai_price_extraction.py:0: error: Incompatible default for parameter "model_name" (default has type "None", parameter has type "str")  [assignment]
+apps/quoting/services/ai_price_extraction.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
+apps/quoting/services/ai_price_extraction.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
+apps/quoting/services/ai_price_extraction.py:0: error: Incompatible return value type (got "MistralPriceExtractionProvider", expected "PriceExtractionProvider")  [return-value]
+apps/quoting/services/ai_price_extraction.py:0: error: Incompatible return value type (got "GeminiPriceExtractionProvider", expected "PriceExtractionProvider")  [return-value]
+apps/quoting/services/ai_price_extraction.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/services/ai_price_extraction.py:0: error: No overload variant of "get" of "dict" matches argument types "str", "int"  [call-overload]
+apps/quoting/services/ai_price_extraction.py:0: note: Possible overload variants:
+apps/quoting/services/ai_price_extraction.py:0: note: def get(self, AIProviderTypes, None = ..., /) -> int | None
+apps/quoting/services/ai_price_extraction.py:0: note: def get(self, AIProviderTypes, int, /) -> int
+apps/quoting/services/ai_price_extraction.py:0: note: def [_T] get(self, AIProviderTypes, _T, /) -> int | _T
+apps/quoting/services/ai_price_extraction.py:0: error: Call to untyped function "get_prioritized_active_providers" in typed context  [no-untyped-call]
+apps/process/services/safety_ai_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/services/safety_ai_service.py:0: note: Use "-> None" if function does not return a value
+apps/process/services/safety_ai_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
+apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "list[str]"  [no-any-return]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "list[dict[str, str]]"  [no-any-return]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
+apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
+apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_dev_demo_export.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_dev_demo_export.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_dev_demo_export.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/process/tests/test_form_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/process/tests/test_form_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/process/tests/test_form_service.py:0: note: Use "-> None" if function does not return a value
@@ -756,41 +934,6 @@ apps/process/tests/test_form_service.py:0: error: Call to untyped function "_mak
 apps/process/tests/test_form_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/process/tests/test_form_service.py:0: note: Use "-> None" if function does not return a value
 apps/process/tests/test_form_service.py:0: error: Call to untyped function "_make_service" in typed context  [no-untyped-call]
-apps/job/services/quote_sync_service.py:0: error: Call to untyped function "_copy_estimate_to_quote_costset" in typed context  [no-untyped-call]
-apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/quote_sync_service.py:0: error: "<typing special form>" has no attribute "LABOR"  [attr-defined]
-apps/job/services/quote_sync_service.py:0: error: "<typing special form>" has no attribute "MATERIAL"  [attr-defined]
-apps/job/services/quote_sync_service.py:0: error: Argument "quantity" to "DraftLine" has incompatible type "float | int"; expected "Decimal"  [arg-type]
-apps/job/services/quote_sync_service.py:0: error: Argument "unit_cost" to "DraftLine" has incompatible type "float | int"; expected "Decimal"  [arg-type]
-apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/quote_sync_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/quote_sync_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Item "None" of "type[InvoiceLineItem] | type[BillLineItem] | type[CreditNoteLineItem] | None" has no attribute "objects"  [union-attr]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Argument after ** must have string keys  [arg-type]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Unsupported operand types for + ("str" and "None")  [operator]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Right operand is of type "Any | None"
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_clients" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_invoices" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_bills" in typed context  [no-untyped-call]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_credit_notes" in typed context  [no-untyped-call]
-apps/client/management/commands/merge_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/management/commands/merge_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/utils.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/timesheet/services/weekly_timesheet_service.py:0: error: Need type annotation for "lines_by_staff_day" (hint: "lines_by_staff_day: dict[<type>, <type>] = ...")  [var-annotated]
 apps/timesheet/services/weekly_timesheet_service.py:0: error: Missing type arguments for generic type "list"  [type-arg]
 apps/timesheet/services/daily_timesheet_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -813,17 +956,17 @@ apps/timesheet/services/daily_timesheet_service.py:0: error: Missing type argume
 apps/timesheet/services/daily_timesheet_service.py:0: error: Argument 1 to "_calculate_percentage" of "DailyTimesheetService" has incompatible type "int"; expected "Decimal"  [arg-type]
 apps/timesheet/services/daily_timesheet_service.py:0: error: Argument 2 to "_calculate_percentage" of "DailyTimesheetService" has incompatible type "int"; expected "Decimal"  [arg-type]
 apps/accounting/services/core.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/accounting/services/core.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/accounting/services/core.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "int | str | Any"
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "int | str | Any"
-apps/accounting/services/core.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/accounting/services/core.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "int | str | Any"
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "int | str | Any"
-apps/accounting/services/core.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/accounting/services/core.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "int | str | Any"
 apps/accounting/services/core.py:0: error: Unsupported operand types for + ("str" and "float")  [operator]
@@ -918,6 +1061,25 @@ apps/accounting/services/core.py:0: error: Unsupported left operand type for / (
 apps/accounting/services/core.py:0: note: Both left and right operands are unions
 apps/accounting/services/core.py:0: error: Unsupported operand types for > ("str" and "int")  [operator]
 apps/accounting/services/core.py:0: note: Left operand is of type "float | Any | str"
+apps/job/services/kanban_service.py:0: error: Incompatible types in assignment (expression has type "list[Job]", variable has type "JobQuerySet")  [assignment]
+apps/job/services/kanban_service.py:0: error: Argument 1 to "_rank_kanban_search_candidates" of "KanbanService" has incompatible type "list[Job@AnnotatedWith[TypedDict({'trigram_score': Any})]]"; expected "list[Job]"  [arg-type]
+apps/job/services/kanban_service.py:0: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
+apps/job/services/kanban_service.py:0: note: Consider using "Sequence" instead, which is covariant
+apps/job/services/kanban_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
+apps/job/services/kanban_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
+apps/job/services/kanban_service.py:0: error: Value of type "list[dict[str, int | str | Any | None]] | int | dict[str, Any] | str | Any | None" is not indexable  [index]
+apps/job/services/kanban_service.py:0: error: Invalid index type "slice[None, int, None]" for "dict[str, Any]"; expected type "str"  [index]
+apps/job/services/kanban_service.py:0: error: Call to untyped function "filter_kanban_jobs" of "KanbanService" in typed context  [no-untyped-call]
+apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "QuerySet[Job, Job]"  [no-any-return]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "float"  [no-any-return]
+apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "float"  [no-any-return]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/kanban_service.py:0: error: Call to untyped function "filter_kanban_jobs" of "KanbanService" in typed context  [no-untyped-call]
+apps/job/services/kanban_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/testing.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/testing.py:0: note: Use "-> None" if function does not return a value
 apps/testing.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -983,13 +1145,6 @@ apps/workflow/serializers.py:0: error: Missing type arguments for generic type "
 apps/workflow/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/workflow/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/workflow/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/workflow/search_telemetry_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/workflow/search_telemetry_serializers.py:0: error: Incompatible types in assignment (expression has type "CharField", base class "Field" defined the type as "Callable[..., Any] | str | None")  [assignment]
-apps/workflow/search_telemetry_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/workflow/exception_handlers.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/exception_handlers.py:0: error: Argument "user_id" to "persist_app_error" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/exception_handlers.py:0: error: Argument "session_replay_id" to "persist_app_error" has incompatible type "Any | None"; expected "str"  [arg-type]
-apps/workflow/exception_handlers.py:0: error: Argument "additional_context" to "persist_app_error" has incompatible type "dict[str, Any] | None"; expected "dict[Any, Any]"  [arg-type]
 apps/workflow/tests/test_xero_app_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_app_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_app_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -1138,30 +1293,12 @@ apps/workflow/tests/test_app_error_grouped_view.py:0: error: Function is missing
 apps/workflow/tests/test_app_error_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_app_error_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_app_error_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Incompatible types in assignment (expression has type "ListField", base class "Serializer" defined the type as "ReturnDict[Any, Any]")  [assignment]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/payroll_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/timesheet/serializers/daily_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers_scheduled_tasks.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/quoting/serializers_scheduled_tasks.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/quoting/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/purchasing/tests/test_supplier_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/purchasing/tests/test_supplier_search.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/purchasing/tests/test_supplier_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -1222,31 +1359,17 @@ apps/process/tests/test_form_api.py:0: error: Function is missing a type annotat
 apps/process/tests/test_form_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/process/tests/test_form_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/process/tests/test_form_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/procedure_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/process/serializers/form_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/operations/serializers/workshop_schedule_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/permissions.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/permissions.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_job_delta_rejection_grouped_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/serializers/quote_spreadsheet_serializer.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
 apps/job/serializers/kanban_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/kanban_serializer.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/serializers/kanban_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
@@ -1301,144 +1424,20 @@ apps/job/serializers/job_file_serializer.py:0: error: Missing type arguments for
 apps/job/serializers/data_quality_report_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/data_quality_report_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/data_quality_report_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/client/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/accounting/serializers/rdti_spend_serializers.py:0: error: Incompatible types in assignment (expression has type "CharField", base class "Field" defined the type as "str | _StrPromise | None")  [assignment]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quoted"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quoted"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument "client_external_id" to "QuotePayload" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_client" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Incompatible type for "xero_id" of "Quote" (got "str | None", expected "str | UUID")  [misc]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_client" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "Decimal"  [arg-type]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "str | None"  [arg-type]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Argument "supplier_external_id" to "POPayload" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "validate_for_xero_sync" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_po_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_po_manager.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Cannot resolve keyword 'created_at' into field. Choices are: amount_due, billing_metadata, client, client_id, date, django_created_at, django_updated_at, due_date, id, job, job_id, line_items, number, online_url, raw_json, status, tax, total_excl_tax, total_incl_tax, xero_id, xero_last_modified, xero_last_synced, xero_tenant_id  [misc]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "paid"  [union-attr]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument "client_external_id" to "InvoicePayload" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_client" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 1 to "_attach_workshop_pdf" of "XeroInvoiceManager" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_client" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
-apps/quoting/services/providers/gemini_provider.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "bool", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "bool", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "int", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "Any | None", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "int", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Incompatible types in assignment (expression has type "list[dict[str, object]]", target has type "Sequence[str]")  [assignment]
-apps/quoting/services/providers/gemini_provider.py:0: error: Need type annotation for "supplier_info" (hint: "supplier_info: dict[<type>, <type>] = ...")  [var-annotated]
-apps/quoting/services/providers/gemini_provider.py:0: error: Missing type arguments for generic type "List"  [type-arg]
-apps/quoting/services/providers/gemini_provider.py:0: error: Argument "config" to "generate_content" of "Models" has incompatible type "dict[str, object]"; expected "GenerateContentConfig | GenerateContentConfigDict | None"  [arg-type]
-apps/quoting/services/providers/gemini_provider.py:0: error: Call to untyped function "log_token_usage" in typed context  [no-untyped-call]
-apps/purchasing/services/quote_to_po_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/purchasing/services/quote_to_po_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/services/quote_to_po_service.py:0: error: Dict entry 0 has incompatible type "str": "dict[str, str]"; expected "str": "str"  [dict-item]
-apps/purchasing/services/quote_to_po_service.py:0: error: Dict entry 0 has incompatible type "str": "dict[str, str]"; expected "str": "str"  [dict-item]
-apps/purchasing/services/quote_to_po_service.py:0: error: Argument "contents" to "generate_content" of "Models" has incompatible type "list[dict[str, str]]"; expected "Content | ContentDict | str | Image | File | FileDict | Part | PartDict | list[str | Image | File | FileDict | Part | PartDict] | list[Content | ContentDict | str | Image | File | FileDict | Part | PartDict | list[str | Image | File | FileDict | Part | PartDict]]"  [arg-type]
-apps/purchasing/services/quote_to_po_service.py:0: error: Call to untyped function "log_token_usage" in typed context  [no-untyped-call]
-apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "clean_json_response" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/purchasing/services/quote_to_po_service.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/services/kanban_service.py:0: error: Incompatible types in assignment (expression has type "list[Job]", variable has type "JobQuerySet")  [assignment]
-apps/job/services/kanban_service.py:0: error: Argument 1 to "_rank_kanban_search_candidates" of "KanbanService" has incompatible type "list[Job@AnnotatedWith[TypedDict({'trigram_score': Any})]]"; expected "list[Job]"  [arg-type]
-apps/job/services/kanban_service.py:0: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
-apps/job/services/kanban_service.py:0: note: Consider using "Sequence" instead, which is covariant
-apps/job/services/kanban_service.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
-apps/job/services/kanban_service.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
-apps/job/services/kanban_service.py:0: error: Value of type "list[dict[str, int | str | Any | None]] | int | dict[str, Any] | str | Any | None" is not indexable  [index]
-apps/job/services/kanban_service.py:0: error: Invalid index type "slice[None, int, None]" for "dict[str, Any]"; expected type "str"  [index]
-apps/job/services/kanban_service.py:0: error: Call to untyped function "filter_kanban_jobs" of "KanbanService" in typed context  [no-untyped-call]
-apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "QuerySet[Job, Job]"  [no-any-return]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "float"  [no-any-return]
-apps/job/services/kanban_service.py:0: error: Returning Any from function declared to return "float"  [no-any-return]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/kanban_service.py:0: error: Call to untyped function "filter_kanban_jobs" of "KanbanService" in typed context  [no-untyped-call]
-apps/job/services/kanban_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Missing return statement  [return]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Key expression in dictionary comprehension has incompatible type "str | None"; expected type "str"  [misc]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
-apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
+apps/company/views/supplier_pickup_address_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
+apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/contact_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
+apps/company/views/contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/contact_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/contact_method_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
+apps/company/views/contact_method_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/views/contact_method_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/contact_method_viewset.py:0: error: Incompatible type for lookup 'contact_id': (got "str", expected "ClientContact | UUID | None")  [misc]
 apps/workflow/views/data_versions_view.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/views/build_id_view.py:0: error: Missing type arguments for generic type "list"  [type-arg]
-apps/workflow/api/reports/pnl.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/reports/job_movement.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/reports/job_movement.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/reports/job_movement.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -1519,12 +1518,156 @@ apps/job/serializers/costing_serializer.py:0: error: Missing type arguments for
 apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "start_date"  [union-attr]
 apps/accounting/views/sales_forecast_view.py:0: error: Argument 1 to "_get_total_invoiced_for_job" of "SalesForecastMonthDetailAPIView" has incompatible type "Job | None"; expected "Job"  [arg-type]
 apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "latest_actual"  [union-attr]
-apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "client"  [union-attr]
-apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Client | Any | None" has no attribute "name"  [union-attr]
+apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "company"  [union-attr]
+apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Company | Any | None" has no attribute "name"  [union-attr]
 apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "job_number"  [union-attr]
 apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "name"  [union-attr]
 apps/accounting/views/sales_forecast_view.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
 apps/accounting/views/sales_forecast_view.py:0: error: Argument "row_date" to "build_row" has incompatible type "Any | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_base_manager.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/views/xero/xero_base_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_base_manager.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/views/xero/xero_base_manager.py:0: error: Call to untyped function "validate_for_xero" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "_hydrate_company_search_results" of "CompanyRestService" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Missing return statement  [return]
+apps/company/services/company_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "_hydrate_company_search_results" of "CompanyRestService" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "_hydrate_company_search_results" of "CompanyRestService" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Value of type "list[dict[str, Any]] | int | Any | str | None" is not indexable  [index]
+apps/company/services/company_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
+apps/company/services/company_rest_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/views/company_rest_views.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/company/views/company_rest_views.py:0: error: Argument 1 to "get_company_by_id" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
+apps/company/views/company_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/company_rest_views.py:0: error: Argument 1 to "update_company" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
+apps/company/views/company_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/company_rest_views.py:0: error: Incompatible types in assignment (expression has type "CompanyDuplicateErrorResponseSerializer", variable has type "CompanyErrorResponseSerializer")  [assignment]
+apps/company/views/company_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/views/company_rest_views.py:0: error: Argument 1 to "get_job_contact" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
+apps/company/views/company_rest_views.py:0: error: Argument 1 to "update_job_contact" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
+apps/company/views/company_rest_views.py:0: error: Argument 3 to "update_job_contact" of "CompanyRestService" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
+apps/company/views/company_rest_views.py:0: error: Argument 1 to "get_company_jobs" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: note: Use "-> None" if function does not return a value
+apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_company_invoice_summary.py:0: note: Use "-> None" if function does not return a value
+apps/job/services/quote_mode_controller.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/quote_mode_controller.py:0: note: Use "-> None" if function does not return a value
+apps/job/services/quote_mode_controller.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/quote_mode_controller.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
+apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/job/services/quote_mode_controller.py:0: error: Cannot call function of unknown type  [operator]
+apps/job/services/quote_mode_controller.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
+apps/job/services/quote_mode_controller.py:0: error: Incompatible return value type (got "None", expected "str")  [return-value]
+apps/job/services/mcp_chat_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
+apps/job/services/mcp_chat_service.py:0: error: Dict entry 1 has incompatible type "str": "str | None"; expected "str": "str"  [dict-item]
+apps/job/services/mcp_chat_service.py:0: error: Dict entry 2 has incompatible type "str": "list[dict[str, dict[str, Any | str] | Any | str]]"; expected "str": "str"  [dict-item]
+apps/job/services/quote_sync_service.py:0: error: Call to untyped function "_copy_estimate_to_quote_costset" in typed context  [no-untyped-call]
+apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/quote_sync_service.py:0: error: "<typing special form>" has no attribute "LABOR"  [attr-defined]
+apps/job/services/quote_sync_service.py:0: error: "<typing special form>" has no attribute "MATERIAL"  [attr-defined]
+apps/job/services/quote_sync_service.py:0: error: Argument "quantity" to "DraftLine" has incompatible type "float | int"; expected "Decimal"  [arg-type]
+apps/job/services/quote_sync_service.py:0: error: Argument "unit_cost" to "DraftLine" has incompatible type "float | int"; expected "Decimal"  [arg-type]
+apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/quote_sync_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/services/quote_sync_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/quote_sync_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Item "None" of "type[InvoiceLineItem] | type[BillLineItem] | type[CreditNoteLineItem] | None" has no attribute "objects"  [union-attr]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Argument after ** must have string keys  [arg-type]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Unsupported operand types for + ("str" and "None")  [operator]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Right operand is of type "Any | None"
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_companies" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_invoices" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_bills" in typed context  [no-untyped-call]
+apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "reprocess_credit_notes" in typed context  [no-untyped-call]
+apps/job/views/data_integrity_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/data_integrity_views.py:0: error: Missing return statement  [return]
+apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/services/pdf_import_service.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: "object" has no attribute "append"  [attr-defined]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Incompatible return value type (got "None", expected "SupplierProduct")  [return-value]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
+apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/services/pdf_import_service.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: error: Incompatible types in assignment (expression has type "WebDriver", variable has type "None")  [assignment]
+apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "setup_driver" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "login" of "BaseScraper" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "get_product_urls" of "BaseScraper" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "scrape_product" of "BaseScraper" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "save_products" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "save_products" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Call to untyped function "cleanup" in typed context  [no-untyped-call]
+apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/services/procedure_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/services/procedure_service.py:0: note: Use "-> None" if function does not return a value
+apps/process/services/procedure_service.py:0: error: Call to untyped function "SafetyAIService" in typed context  [no-untyped-call]
+apps/process/services/procedure_service.py:0: error: Call to untyped function "GoogleDocsService" in typed context  [no-untyped-call]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Missing return statement  [return]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Key expression in dictionary comprehension has incompatible type "str | None"; expected type "str"  [misc]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
+apps/accounting/services/payroll_reconciliation_service.py:0: error: Invalid index type "str | None" for "dict[str, dict[str, Any]]"; expected type "str"  [index]
 apps/workflow/tests/test_company_defaults_schema.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_company_defaults_schema.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_company_defaults_schema.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -1598,7 +1741,6 @@ apps/workflow/tests/test_company_defaults_api.py:0: error: "_MonkeyPatchedWSGIRe
 apps/timesheet/tests/test_weekly_timesheet_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/timesheet/tests/test_weekly_timesheet_service.py:0: note: Use "-> None" if function does not return a value
 apps/timesheet/tests/test_weekly_timesheet_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/timesheet/tests/test_weekly_timesheet_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/timesheet/tests/test_weekly_timesheet_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/timesheet/tests/test_weekly_timesheet_service.py:0: note: Use "-> None" if function does not return a value
 apps/timesheet/tests/test_permissions.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -1654,7 +1796,6 @@ apps/timesheet/tests/test_jobs_api_filter.py:0: error: Call to untyped function
 apps/timesheet/tests/test_jobs_api_filter.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
 apps/timesheet/tests/test_daily_timesheet_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/timesheet/tests/test_daily_timesheet_service.py:0: note: Use "-> None" if function does not return a value
-apps/timesheet/tests/test_daily_timesheet_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/timesheet/tests/test_daily_timesheet_service.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
 apps/timesheet/tests/test_daily_timesheet_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/timesheet/tests/test_daily_timesheet_service.py:0: note: Use "-> None" if function does not return a value
@@ -2028,7 +2169,6 @@ apps/job/tests/test_mcp_tool_integration.py:0: error: Function is missing a retu
 apps/job/tests/test_mcp_tool_integration.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_job_quote_chat_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_job_quote_chat_model.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_quote_chat_model.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_job_quote_chat_model.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_job_quote_chat_model.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_job_latest_costsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -2104,7 +2244,6 @@ apps/job/tests/test_delivery_docket_service.py:0: error: Function is missing a r
 apps/job/tests/test_delivery_docket_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_delivery_docket_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_delivery_docket_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_costline_schema_validation.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_costline_schema_validation.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/job/tests/test_costline_schema_validation.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
 apps/job/tests/test_costline_schema_validation.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
@@ -2167,19 +2306,19 @@ apps/crm/tests/test_phone_call_service.py:0: error: Function is missing a return
 apps/crm/tests/test_phone_call_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/crm/tests/test_phone_call_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/crm/tests/test_phone_call_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/tests/test_client_merge_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/tests/test_client_merge_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/client/tests/test_client_merge_service.py:0: error: Value of type "Any | None" is not indexable  [index]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "get_final_client" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "get_final_client" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Call to untyped function "get_final_client" in typed context  [no-untyped-call]
-apps/client/tests/test_client_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_merge_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/tests/test_company_merge_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/company/tests/test_company_merge_service.py:0: error: Value of type "Any | None" is not indexable  [index]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "get_final_company" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "get_final_company" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Call to untyped function "get_final_company" in typed context  [no-untyped-call]
+apps/company/tests/test_company_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_merge_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/accounts/tests/test_staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/accounts/tests/test_staff_api.py:0: note: Use "-> None" if function does not return a value
 apps/accounts/tests/test_displayable_staff.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -2329,7 +2468,6 @@ apps/accounting/tests/test_invoice_calculation.py:0: error: Call to untyped func
 apps/accounting/tests/test_invoice_calculation.py:0: error: Call to untyped function "_add_revenue_line" in typed context  [no-untyped-call]
 apps/accounting/tests/test_core_nplusone.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/accounting/tests/test_core_nplusone.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_core_nplusone.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/accounting/tests/test_core_nplusone.py:0: error: Module "django.utils.timezone" does not explicitly export attribute "datetime"  [attr-defined]
 apps/accounting/tests/test_core_nplusone.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
 apps/accounting/tests/test_core_nplusone.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -2337,116 +2475,6 @@ apps/accounting/tests/test_core_nplusone.py:0: error: Function is missing a retu
 apps/accounting/tests/test_core_nplusone.py:0: note: Use "-> None" if function does not return a value
 apps/accounting/tests/test_core_nplusone.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/accounting/tests/test_core_nplusone.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/views/company_defaults_logo_api.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "_remove_if_user_uploaded" in typed context  [no-untyped-call]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "_remove_if_user_uploaded" in typed context  [no-untyped-call]
-apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/operations/views/workshop_schedule_view.py:0: error: Incompatible types in assignment (expression has type "list[JobProjection]", variable has type "QuerySet[JobProjection, JobProjection]")  [assignment]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/session_replay_view.py:0: error: Call to untyped function "has_permission" in typed context  [no-untyped-call]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/views/job_profitability_report_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_profitability_report_views.py:0: error: Missing return statement  [return]
-apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_files_collection_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/views/job_files_collection_view.py:0: error: "Callable[[str], None]" has no attribute "delay"  [attr-defined]
-apps/job/views/job_files_collection_view.py:0: error: Argument "user_id" to "persist_app_error" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_files_collection_view.py:0: error: Call to untyped function "save_file" in typed context  [no-untyped-call]
-apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_thumbnail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/job/views/data_quality_report_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/data_integrity_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/data_integrity_views.py:0: error: Missing return statement  [return]
-apps/client/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/views/supplier_search_alias_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "_hydrate_client_search_results" of "ClientRestService" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Missing return statement  [return]
-apps/client/services/client_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "_hydrate_client_search_results" of "ClientRestService" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "_hydrate_client_search_results" of "ClientRestService" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Value of type "list[dict[str, Any]] | int | Any | str | None" is not indexable  [index]
-apps/client/services/client_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
-apps/client/services/client_rest_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "_FakeProvider" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "_FakeProvider", variable has type "AccountingProvider")  [assignment]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Cannot assign to a method  [method-assign]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "def _attach_workshop_pdf(self, external_id: str) -> None", variable has type "def _attach_workshop_pdf(self, invoice_external_id: str) -> str | None")  [assignment]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "_FakeProvider" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "XeroQuoteManager" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "_FakeProvider", variable has type "AccountingProvider")  [assignment]
 apps/job/tests/test_kanban_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_kanban_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -2492,8 +2520,8 @@ apps/job/tests/test_kanban_search.py:0: error: Function is missing a return type
 apps/job/tests/test_kanban_search.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_kanban_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_search.py:0: error: Call to untyped function "untracked_update" in typed context  [no-untyped-call]
-apps/job/tests/test_kanban_search.py:0: error: Incompatible type for "client" of "Invoice" (got "Client | None", expected "Client | Combinable")  [misc]
-apps/job/tests/test_kanban_search.py:0: error: Incompatible type for "client" of "Quote" (got "Client | None", expected "Client | Combinable")  [misc]
+apps/job/tests/test_kanban_search.py:0: error: Incompatible type for "company" of "Invoice" (got "Company | None", expected "Company | Combinable")  [misc]
+apps/job/tests/test_kanban_search.py:0: error: Incompatible type for "company" of "Quote" (got "Company | None", expected "Company | Combinable")  [misc]
 apps/job/tests/test_kanban_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_search.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_kanban_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -2554,9 +2582,7 @@ apps/job/tests/test_kanban_search.py:0: error: Function is missing a return type
 apps/job/tests/test_kanban_search.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_reorder_priority.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_kanban_reorder_priority.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_kanban_reorder_priority.py:0: error: Incompatible type for "client" of "Job" (got "django.test.client.Client", expected "apps.client.models.Client | Combinable | None")  [misc]
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_kanban_reorder_priority.py:0: note: Use "-> None" if function does not return a value
@@ -2585,38 +2611,169 @@ apps/job/tests/test_kanban_reorder_priority.py:0: error: Function is missing a r
 apps/job/tests/test_kanban_reorder_priority.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
 apps/job/tests/test_kanban_reorder_priority.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/workflow/api/reports/payroll_reconciliation.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/job/mixins.py:0: error: Missing type arguments for generic type "GenericAPIView"  [type-arg]
-apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/mixins.py:0: error: Call to untyped function "get_job_by_number" in typed context  [no-untyped-call]
-apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/mixins.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Argument "default" to "DecimalField" has incompatible type "int"; expected "Decimal | Callable[[], Decimal] | _Empty | None"  [arg-type]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Argument "default" to "DecimalField" has incompatible type "int"; expected "Decimal | Callable[[], Decimal] | _Empty | None"  [arg-type]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/session_replay_view.py:0: error: Call to untyped function "has_permission" in typed context  [no-untyped-call]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/session_replay_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "_remove_if_user_uploaded" in typed context  [no-untyped-call]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "_remove_if_user_uploaded" in typed context  [no-untyped-call]
+apps/workflow/views/company_defaults_logo_api.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/company_defaults_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/operations/views/workshop_schedule_view.py:0: error: Incompatible types in assignment (expression has type "list[JobProjection]", variable has type "QuerySet[JobProjection, JobProjection]")  [assignment]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/timesheet/serializers/modern_timesheet_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/views/job_profitability_report_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_profitability_report_views.py:0: error: Missing return statement  [return]
+apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_files_collection_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/job/views/job_files_collection_view.py:0: error: "Callable[[str], None]" has no attribute "delay"  [attr-defined]
+apps/job/views/job_files_collection_view.py:0: error: Argument "user_id" to "persist_app_error" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_files_collection_view.py:0: error: Call to untyped function "save_file" in typed context  [no-untyped-call]
+apps/job/views/job_files_collection_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_thumbnail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/job/views/job_file_detail_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_file_detail_view.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/job/views/data_quality_report_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Returning Any from function declared to return "bool"  [no-any-return]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Call to untyped function "get_raw_token_from_cookie" in typed context  [no-untyped-call]
+apps/workflow/authentication.py:0: error: "AbstractBaseUser" has no attribute "is_currently_active"  [attr-defined]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Call to untyped function "mark_used" in typed context  [no-untyped-call]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/authentication.py:0: error: Call to untyped function "mark_used" in typed context  [no-untyped-call]
+apps/workflow/extensions.py:0: error: Call to untyped function "__init_subclass__" in typed context  [no-untyped-call]
+apps/workflow/extensions.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/accounts/serializers.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
+apps/accounts/serializers.py:0: error: "to_internal_value" undefined in superclass  [misc]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/accounts/serializers.py:0: error: Returning Any from function declared to return "Staff"  [no-any-return]
+apps/accounts/serializers.py:0: error: Returning Any from function declared to return "Staff"  [no-any-return]
+apps/accounts/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/job/mixins.py:0: error: Missing type arguments for generic type "GenericAPIView"  [type-arg]
+apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/mixins.py:0: error: Call to untyped function "get_job_by_number" in typed context  [no-untyped-call]
+apps/job/mixins.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/mixins.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/workflow/views/xero_pay_item_viewset.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
+apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
+apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "RetrieveAPIView"  [type-arg]
+apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
+apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/ai_provider_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
+apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/views_scheduled_tasks.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
+apps/quoting/views_scheduled_tasks.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Missing type arguments for generic type "GenericViewSet"  [type-arg]
+apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Call to untyped function "_apply_category_filter" in typed context  [no-untyped-call]
+apps/process/views/form_viewsets.py:0: error: Call to untyped function "_apply_common_filters" in typed context  [no-untyped-call]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Argument "document_type" to "create_form" of "FormService" has incompatible type "Sequence[str]"; expected "str"  [arg-type]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Call to untyped function "update" of "FormViewSet" in typed context  [no-untyped-call]
+apps/process/views/form_viewsets.py:0: error: Missing type arguments for generic type "GenericViewSet"  [type-arg]
+apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Call to untyped function "get_form" in typed context  [no-untyped-call]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "_get_all_url_patterns" in typed context  [no-untyped-call]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Missing type arguments for generic type "set"  [type-arg]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "SchemaGenerator" in typed context  [no-untyped-call]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "get_schema" in typed context  [no-untyped-call]
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_api_schema_coverage.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "_get_all_url_patterns" in typed context  [no-untyped-call]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Argument "default" to "DecimalField" has incompatible type "int"; expected "Decimal | Callable[[], Decimal] | _Empty | None"  [arg-type]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Argument "default" to "DecimalField" has incompatible type "int"; expected "Decimal | Callable[[], Decimal] | _Empty | None"  [arg-type]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
+apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/purchasing/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
@@ -2760,760 +2917,96 @@ apps/job/serializers/job_serializer.py:0: error: Missing type arguments for gene
 apps/job/serializers/job_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/job_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/job_serializer.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/job/views/workshop_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/job/views/workshop_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
-apps/job/views/workshop_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/workshop_view.py:0: error: Incompatible type for lookup 'people__id': (got "UUID | None", expected "UUID | str")  [misc]
-apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/workshop_view.py:0: error: Argument "job_id" to "persist_app_error" has incompatible type "Any | None"; expected "str"  [arg-type]
-apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/client_rest_views.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/client/views/client_rest_views.py:0: error: Argument 1 to "get_client_by_id" of "ClientRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/client/views/client_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/client_rest_views.py:0: error: Argument 1 to "update_client" of "ClientRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/client/views/client_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/client_rest_views.py:0: error: Incompatible types in assignment (expression has type "ClientDuplicateErrorResponseSerializer", variable has type "ClientErrorResponseSerializer")  [assignment]
-apps/client/views/client_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/client_rest_views.py:0: error: Argument 1 to "get_job_contact" of "ClientRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/client/views/client_rest_views.py:0: error: Argument 1 to "update_job_contact" of "ClientRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/client/views/client_rest_views.py:0: error: Argument 3 to "update_job_contact" of "ClientRestService" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
-apps/client/views/client_rest_views.py:0: error: Argument 1 to "get_client_jobs" of "ClientRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_fts_search.py:0: error: Incompatible types in assignment (expression has type "None", variable has type "Staff | AnonymousUser")  [assignment]
-apps/client/tests/test_client_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounting/views/kpi_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/authentication.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Returning Any from function declared to return "bool"  [no-any-return]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Call to untyped function "get_raw_token_from_cookie" in typed context  [no-untyped-call]
-apps/workflow/authentication.py:0: error: "AbstractBaseUser" has no attribute "is_currently_active"  [attr-defined]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Call to untyped function "mark_used" in typed context  [no-untyped-call]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/authentication.py:0: error: Call to untyped function "mark_used" in typed context  [no-untyped-call]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/accounts/serializers.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
-apps/accounts/serializers.py:0: error: "to_internal_value" undefined in superclass  [misc]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/accounts/serializers.py:0: error: Returning Any from function declared to return "Staff"  [no-any-return]
-apps/accounts/serializers.py:0: error: Returning Any from function declared to return "Staff"  [no-any-return]
-apps/accounts/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/accounts/serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
-apps/workflow/views/xero_pay_item_viewset.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
-apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
-apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "RetrieveAPIView"  [type-arg]
-apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/app_error_view.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
-apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/app_error_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/ai_provider_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
-apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/views/ai_provider_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/views_scheduled_tasks.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
-apps/quoting/views_scheduled_tasks.py:0: error: Missing type arguments for generic type "ReadOnlyModelViewSet"  [type-arg]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Missing type arguments for generic type "GenericViewSet"  [type-arg]
-apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Call to untyped function "_apply_category_filter" in typed context  [no-untyped-call]
-apps/process/views/form_viewsets.py:0: error: Call to untyped function "_apply_common_filters" in typed context  [no-untyped-call]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Argument "document_type" to "create_form" of "FormService" has incompatible type "Sequence[str]"; expected "str"  [arg-type]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Call to untyped function "update" of "FormViewSet" in typed context  [no-untyped-call]
-apps/process/views/form_viewsets.py:0: error: Missing type arguments for generic type "GenericViewSet"  [type-arg]
-apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Call to untyped function "get_form" in typed context  [no-untyped-call]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/views/form_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/supplier_pickup_address_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
-apps/client/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/supplier_pickup_address_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/client_contact_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
-apps/client/views/client_contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/client_contact_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/client_contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/client_contact_method_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
-apps/client/views/client_contact_method_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/views/client_contact_method_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/views/client_contact_method_viewset.py:0: error: Incompatible type for lookup 'contact_id': (got "str", expected "ClientContact | UUID | None")  [misc]
-apps/purchasing/views/supplier_search_rest_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_serializers.py:0: error: "PurchaseOrder" has no attribute "detail_lines"  [attr-defined]
-apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_serializers.py:0: error: "PurchaseOrder" has no attribute "detail_lines"  [attr-defined]
-apps/purchasing/services/stock_search_service.py:0: error: Argument 1 to "add" of "set" has incompatible type "tuple[float, ...]"; expected "tuple[float, float]"  [arg-type]
-apps/purchasing/services/stock_search_service.py:0: error: Argument 1 to "add" of "set" has incompatible type "tuple[float, ...]"; expected "tuple[float, float]"  [arg-type]
-apps/purchasing/services/stock_search_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/services/stock_search_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/purchasing/services/stock_search_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
-apps/purchasing/services/stock_search_service.py:0: error: Missing return statement  [return]
-apps/purchasing/services/stock_search_service.py:0: error: Missing return statement  [return]
-apps/purchasing/services/stock_search_service.py:0: error: Incompatible types in assignment (expression has type "QuerySet[Stock, Stock]", variable has type "list[Stock]")  [assignment]
-apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Dict entry 0 has incompatible type "str": "str | _StrPromise"; expected "str": "str"  [dict-item]
-apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Call to untyped function "delete" in typed context  [no-untyped-call]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_costline_views.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/job/views/workshop_pdf_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/month_end_rest_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/month_end_rest_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/month_end_rest_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "id"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "meta"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "quantity"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "unit_cost"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "calculated_total_cost"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostSet | None" has no attribute "rev"  [union-attr]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/delivery_docket_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/archive_completed_jobs_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
-apps/job/views/archive_completed_jobs_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/archive_completed_jobs_view.py:0: error: Call to untyped function "get_paid_complete_jobs" in typed context  [no-untyped-call]
-apps/job/views/archive_completed_jobs_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/archive_completed_jobs_view.py:0: error: Call to untyped function "archive_complete_jobs" in typed context  [no-untyped-call]
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: error: Call to untyped function "date_to_datetime" in typed context  [no-untyped-call]
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: note: Use "-> None" if function does not return a value
-apps/client/tests/test_client_invoice_summary.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/client/tests/test_client_invoice_summary.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/middleware.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
-apps/accounts/views/user_profile_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/accounts/views/token_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/views/token_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
-apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
-apps/accounts/views/token_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/views/token_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
-apps/accounts/views/staff_views.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
-apps/accounts/views/staff_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/views/staff_views.py:0: error: Call to untyped function "get_queryset" in typed context  [no-untyped-call]
-apps/accounts/views/staff_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/views/staff_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/views/staff_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/views/staff_api.py:0: error: Missing type arguments for generic type "ListCreateAPIView"  [type-arg]
-apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/views/staff_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/accounts/views/staff_api.py:0: error: Missing type arguments for generic type "RetrieveUpdateDestroyAPIView"  [type-arg]
-apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/views/staff_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/extensions.py:0: error: Call to untyped function "__init_subclass__" in typed context  [no-untyped-call]
-apps/workflow/extensions.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/views/stock_search_rest_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
-apps/job/tests/test_modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_modern_timesheet_views.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_modern_timesheet_views.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
-apps/job/tests/test_modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_modern_timesheet_views.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_modern_timesheet_views.py:0: error: Item "None" of "XeroPayItem | None" has no attribute "name"  [union-attr]
-apps/job/views/kanban_view_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/kanban_view_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/kanban_view_api.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
-apps/job/views/kanban_view_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/kanban_view_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/kanban_view_api.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
-apps/job/views/kanban_view_api.py:0: error: "str" has no attribute "HTTP_500_INTERNAL_SERVER_ERROR"  [attr-defined]
-apps/job/views/kanban_view_api.py:0: error: Incompatible types in assignment (expression has type "list[str]", target has type "str")  [assignment]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: "JobQuoteChatSerializer" has no attribute "get"  [attr-defined]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_message_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_message_or_404" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
-apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costing_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_costing_views.py:0: error: Call to untyped function "_archive_quote_data" in typed context  [no-untyped-call]
-apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/assign_job_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/assign_job_view.py:0: error: Call to untyped function "assign_staff_to_job" of "JobStaffService" in typed context  [no-untyped-call]
-apps/job/views/assign_job_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/assign_job_view.py:0: error: Call to untyped function "remove_staff_from_job" of "JobStaffService" in typed context  [no-untyped-call]
-apps/job/services/job_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/job_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/job_rest_service.py:0: error: Missing return statement  [return]
-apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
-apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
-apps/job/services/job_rest_service.py:0: error: "ValueError" has no attribute "delta_rejection_context"  [attr-defined]
-apps/job/services/job_rest_service.py:0: error: Assignment to variable "exc" outside except: block  [misc]
-apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
-apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
-apps/job/services/job_rest_service.py:0: error: Incompatible type for lookup 'client_id': (got "UUID | Any | None", expected "UUID | str")  [misc]
-apps/job/services/job_rest_service.py:0: error: Missing return statement  [return]
-apps/job/services/job_rest_service.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
-apps/job/services/job_rest_service.py:0: error: Argument "key" to "sort" of "list" has incompatible type "Callable[[dict[str, int | datetime | UUID | str | Any | None]], int | datetime | UUID | str | Any | None]"; expected "Callable[[dict[str, int | datetime | UUID | str | Any | None]], SupportsDunderLT[Any] | SupportsDunderGT[Any]]"  [arg-type]
-apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "int | datetime | UUID | str | Any | None", expected "SupportsDunderLT[Any] | SupportsDunderGT[Any]")  [return-value]
-apps/job/services/job_rest_service.py:0: error: Incompatible default for parameter "week" (default has type "None", parameter has type "date")  [assignment]
-apps/job/services/job_rest_service.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
-apps/job/services/job_rest_service.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
-apps/job/services/job_rest_service.py:0: error: "Job" has no attribute "pricings"  [attr-defined]
-apps/workflow/tests/test_access_logging_middleware.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_access_logging_middleware.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "_get_all_url_patterns" in typed context  [no-untyped-call]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Missing type arguments for generic type "set"  [type-arg]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "SchemaGenerator" in typed context  [no-untyped-call]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "get_schema" in typed context  [no-untyped-call]
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/tests/test_api_schema_coverage.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_api_schema_coverage.py:0: error: Call to untyped function "_get_all_url_patterns" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
-apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Argument 1 to "get_weekly_metrics" of "JobRestService" has incompatible type "date | None"; expected "date"  [arg-type]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: "type[Job]" has no attribute "STATUS_CHOICES"  [attr-defined]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_rest_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_rest_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
-apps/job/tests/test_event_deduplication.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "staff"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_after"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_after"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "schema_version"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "change_id"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_meta"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_checksum"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "event_type"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "detail"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "event_type"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "detail"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "description"  [union-attr]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "untracked_update" in typed context  [no-untyped-call]
-apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
-apps/workflow/services/llm_service.py:0: error: Module "litellm" does not explicitly export attribute "set_verbose"  [attr-defined]
-apps/workflow/services/llm_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Call to untyped function "get_default" of "AIProvider" in typed context  [no-untyped-call]
-apps/workflow/services/llm_service.py:0: error: No overload variant of "get" of "dict" matches argument types "str", "str"  [call-overload]
-apps/workflow/services/llm_service.py:0: note: Possible overload variants:
-apps/workflow/services/llm_service.py:0: note: def get(self, AIProviderTypes, None = ..., /) -> str | None
-apps/workflow/services/llm_service.py:0: note: def get(self, AIProviderTypes, str, /) -> str
-apps/workflow/services/llm_service.py:0: note: def [_T] get(self, AIProviderTypes, _T, /) -> str | _T
-apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Returning Any from function declared to return "dict[Any, Any]"  [no-any-return]
-apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/services/llm_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/process/services/safety_ai_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/services/safety_ai_service.py:0: note: Use "-> None" if function does not return a value
-apps/process/services/safety_ai_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
-apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "list[str]"  [no-any-return]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "list[dict[str, str]]"  [no-any-return]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "get"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Item "str" of "dict[Any, Any] | str" has no attribute "setdefault"  [union-attr]
-apps/process/services/safety_ai_service.py:0: error: Incompatible return value type (got "dict[Any, Any] | str", expected "dict[str, Any]")  [return-value]
-apps/job/services/quote_mode_controller.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/job/services/quote_mode_controller.py:0: note: Use "-> None" if function does not return a value
-apps/job/services/quote_mode_controller.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/quote_mode_controller.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
-apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/quote_mode_controller.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/job/services/quote_mode_controller.py:0: error: Cannot call function of unknown type  [operator]
-apps/job/services/quote_mode_controller.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
-apps/job/services/quote_mode_controller.py:0: error: Incompatible return value type (got "None", expected "str")  [return-value]
-apps/job/services/mcp_chat_service.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
-apps/job/services/mcp_chat_service.py:0: error: Dict entry 1 has incompatible type "str": "str | None"; expected "str": "str"  [dict-item]
-apps/job/services/mcp_chat_service.py:0: error: Dict entry 2 has incompatible type "str": "list[dict[str, dict[str, Any | str] | Any | str]]"; expected "str": "str"  [dict-item]
-apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/services/pdf_import_service.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: "object" has no attribute "append"  [attr-defined]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Incompatible return value type (got "None", expected "SupplierProduct")  [return-value]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
-apps/quoting/services/pdf_import_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/services/pdf_import_service.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: error: Incompatible types in assignment (expression has type "WebDriver", variable has type "None")  [assignment]
-apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/scrapers/base.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/scrapers/base.py:0: note: Use "-> None" if function does not return a value
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "setup_driver" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "login" of "BaseScraper" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "get_product_urls" of "BaseScraper" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "scrape_product" of "BaseScraper" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "save_products" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "save_products" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Call to untyped function "cleanup" in typed context  [no-untyped-call]
-apps/quoting/scrapers/base.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/process/services/procedure_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/process/services/procedure_service.py:0: note: Use "-> None" if function does not return a value
-apps/process/services/procedure_service.py:0: error: Call to untyped function "SafetyAIService" in typed context  [no-untyped-call]
-apps/process/services/procedure_service.py:0: error: Call to untyped function "GoogleDocsService" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quoted"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quoted"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument "client_external_id" to "QuotePayload" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Incompatible type for "xero_id" of "Quote" (got "str | None", expected "str | UUID")  [misc]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
+apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "Decimal"  [arg-type]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Argument 1 to "DocumentLineItem" has incompatible type "**dict[str, object]"; expected "str | None"  [arg-type]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Argument "supplier_external_id" to "POPayload" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "validate_for_xero_sync" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_po_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_po_manager.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Cannot resolve keyword 'created_at' into field. Choices are: amount_due, billing_metadata, company, company_id, date, django_created_at, django_updated_at, due_date, id, job, job_id, line_items, number, online_url, raw_json, status, tax, total_excl_tax, total_incl_tax, xero_id, xero_last_modified, xero_last_synced, xero_tenant_id  [misc]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "paid"  [union-attr]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument "client_external_id" to "InvoicePayload" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 1 to "_attach_workshop_pdf" of "XeroInvoiceManager" has incompatible type "str | None"; expected "str"  [arg-type]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
+apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/company/tests/test_company_fts_search.py:0: error: Incompatible types in assignment (expression has type "None", variable has type "Staff | AnonymousUser")  [assignment]
+apps/company/tests/test_company_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/services/chat_service.py:0: error: Call to untyped function "QuoteModeController" in typed context  [no-untyped-call]
-apps/job/services/chat_service.py:0: error: Item "None" of "Client | None" has no attribute "name"  [union-attr]
+apps/job/services/chat_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/job/services/chat_service.py:0: error: Returning Any from function declared to return "str"  [no-any-return]
 apps/job/services/chat_service.py:0: error: Cannot call function of unknown type  [operator]
+apps/quoting/views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/quoting/views.py:0: error: Call to untyped function "PDFDataValidationService" in typed context  [no-untyped-call]
+apps/quoting/views.py:0: error: Call to untyped function "PDFImportService" in typed context  [no-untyped-call]
 apps/quoting/scrapers/steel_and_tube.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/quoting/scrapers/steel_and_tube.py:0: error: "None" has no attribute "get"  [attr-defined]
 apps/quoting/scrapers/steel_and_tube.py:0: error: Value of type variable "D" of "WebDriverWait" cannot be "None"  [type-var]
@@ -3617,6 +3110,7 @@ apps/process/views/procedure_viewsets.py:0: error: Function is missing a type an
 apps/process/views/procedure_viewsets.py:0: error: Call to untyped function "SafetyAIService" in typed context  [no-untyped-call]
 apps/process/views/procedure_viewsets.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/process/views/procedure_viewsets.py:0: error: Call to untyped function "SafetyAIService" in typed context  [no-untyped-call]
+apps/process/urls_rest.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/process/tests/test_procedure_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/process/tests/test_procedure_service.py:0: error: Call to untyped function "ProcedureService" in typed context  [no-untyped-call]
 apps/process/tests/test_procedure_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3628,7 +3122,113 @@ apps/process/tests/test_procedure_service.py:0: error: Call to untyped function
 apps/process/tests/test_procedure_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/process/tests/test_procedure_service.py:0: note: Use "-> None" if function does not return a value
 apps/process/tests/test_procedure_service.py:0: error: Call to untyped function "_make_service" in typed context  [no-untyped-call]
-apps/job/views/job_quote_chat_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/api/reports/payroll_reconciliation.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/job/views/workshop_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/job/views/workshop_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
+apps/job/views/workshop_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/workshop_view.py:0: error: Incompatible type for lookup 'people__id': (got "UUID | None", expected "UUID | str")  [misc]
+apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/workshop_view.py:0: error: Argument "job_id" to "persist_app_error" has incompatible type "Any | None"; expected "str"  [arg-type]
+apps/job/views/workshop_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/middleware.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/middleware.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
+apps/accounts/views/user_profile_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/accounts/views/token_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/views/token_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
+apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
+apps/accounts/views/token_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/views/token_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
+apps/accounts/views/token_view.py:0: error: Item "None" of "Any | None" has no attribute "total_seconds"  [union-attr]
+apps/accounts/views/staff_views.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
+apps/accounts/views/staff_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/views/staff_views.py:0: error: Call to untyped function "get_queryset" in typed context  [no-untyped-call]
+apps/accounts/views/staff_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/views/staff_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/views/staff_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/views/staff_api.py:0: error: Missing type arguments for generic type "ListCreateAPIView"  [type-arg]
+apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/views/staff_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/views/staff_api.py:0: error: Missing type arguments for generic type "RetrieveUpdateDestroyAPIView"  [type-arg]
+apps/accounts/views/staff_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/views/staff_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/views/supplier_search_rest_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_serializers.py:0: error: "PurchaseOrder" has no attribute "detail_lines"  [attr-defined]
+apps/purchasing/tests/test_serializers.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_serializers.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_serializers.py:0: error: "PurchaseOrder" has no attribute "detail_lines"  [attr-defined]
+apps/purchasing/services/stock_search_service.py:0: error: Argument 1 to "add" of "set" has incompatible type "tuple[float, ...]"; expected "tuple[float, float]"  [arg-type]
+apps/purchasing/services/stock_search_service.py:0: error: Argument 1 to "add" of "set" has incompatible type "tuple[float, ...]"; expected "tuple[float, float]"  [arg-type]
+apps/purchasing/services/stock_search_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/services/stock_search_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/purchasing/services/stock_search_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
+apps/purchasing/services/stock_search_service.py:0: error: Missing return statement  [return]
+apps/purchasing/services/stock_search_service.py:0: error: Missing return statement  [return]
+apps/purchasing/services/stock_search_service.py:0: error: Incompatible types in assignment (expression has type "QuerySet[Stock, Stock]", variable has type "list[Stock]")  [assignment]
+apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Dict entry 0 has incompatible type "str": "str | _StrPromise"; expected "str": "str"  [dict-item]
+apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Call to untyped function "delete" in typed context  [no-untyped-call]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_costline_views.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/job/views/workshop_pdf_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/month_end_rest_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/month_end_rest_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/month_end_rest_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "id"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "meta"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "quantity"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "unit_cost"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostLine@AnnotatedWith[TypedDict({'calculated_total_cost': Any, 'calculated_total_rev': Any})] | None" has no attribute "calculated_total_cost"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Item "None" of "CostSet | None" has no attribute "rev"  [union-attr]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/modern_timesheet_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/delivery_docket_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/archive_completed_jobs_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
+apps/job/views/archive_completed_jobs_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/archive_completed_jobs_view.py:0: error: Call to untyped function "get_paid_complete_jobs" in typed context  [no-untyped-call]
+apps/job/views/archive_completed_jobs_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/archive_completed_jobs_view.py:0: error: Call to untyped function "archive_complete_jobs" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "_FakeProvider" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "_FakeProvider", variable has type "AccountingProvider")  [assignment]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Cannot assign to a method  [method-assign]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "def _attach_workshop_pdf(self, external_id: str) -> None", variable has type "def _attach_workshop_pdf(self, invoice_external_id: str) -> str | None")  [assignment]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_document_raw_json.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "_FakeProvider" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Call to untyped function "XeroQuoteManager" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_document_raw_json.py:0: error: Incompatible types in assignment (expression has type "_FakeProvider", variable has type "AccountingProvider")  [assignment]
 apps/job/tests/test_quote_modes.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_quote_modes.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_quote_modes.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3664,7 +3264,6 @@ apps/job/tests/test_chat_service.py:0: note: PEP 484 prohibits implicit Optional
 apps/job/tests/test_chat_service.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3675,7 +3274,6 @@ apps/job/tests/test_chat_service.py:0: error: Function is missing a return type
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: "Client" has no attribute "name"  [attr-defined]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3688,7 +3286,6 @@ apps/job/tests/test_chat_service.py:0: error: Function is missing a return type
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -3697,7 +3294,6 @@ apps/job/tests/test_chat_service.py:0: error: Function is missing a type annotat
 apps/job/tests/test_chat_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3710,17 +3306,14 @@ apps/job/tests/test_chat_service.py:0: error: Function is missing a return type
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_service.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_service.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/test_chat_performance.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_performance.py:0: note: Use "-> None" if function does not return a value
-apps/job/tests/test_chat_performance.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/job/tests/test_chat_performance.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/tests/test_chat_performance.py:0: note: Use "-> None" if function does not return a value
 apps/job/tests/test_chat_performance.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3750,16 +3343,16 @@ apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annota
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "clean_json" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "serialize_xero_object" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_clients" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_clients" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_client_from_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "get_or_fetch_client" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "sync_company_from_xero_contact" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "get_or_fetch_company" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_client_from_xero_contact" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_company_from_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -3777,10 +3370,10 @@ apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annota
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_client_from_xero_contact" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_company_from_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_client_from_xero_contact" in typed context  [no-untyped-call]
+apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "resolve_company_from_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/transforms.py:0: error: Incompatible type for "po_number" of "PurchaseOrder" (got "Any | None", expected "str | int | Combinable")  [misc]
 apps/workflow/api/xero/transforms.py:0: error: Incompatible type for "order_date" of "PurchaseOrder" (got "Any | None", expected "str | date | Combinable")  [misc]
@@ -3816,7 +3409,7 @@ apps/workflow/api/xero/stock_sync.py:0: error: Function is missing a return type
 apps/workflow/api/xero/stock_sync.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
 apps/workflow/api/xero/push.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/push.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/api/xero/push.py:0: error: Call to untyped function "get_or_fetch_client" in typed context  [no-untyped-call]
+apps/workflow/api/xero/push.py:0: error: Call to untyped function "get_or_fetch_company" in typed context  [no-untyped-call]
 apps/workflow/api/xero/push.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/api/xero/push.py:0: error: Call to untyped function "sync_time_entries_bulk" in typed context  [no-untyped-call]
 apps/workflow/api/xero/push.py:0: error: Call to untyped function "sync_expense_entries_bulk" in typed context  [no-untyped-call]
@@ -3876,7 +3469,7 @@ apps/workflow/api/xero/seed.py:0: error: Unsupported operand types for + ("objec
 apps/workflow/api/xero/seed.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/seed.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/seed.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/api/xero/seed.py:0: error: Call to untyped function "get_final_client" in typed context  [no-untyped-call]
+apps/workflow/api/xero/seed.py:0: error: Call to untyped function "get_final_company" in typed context  [no-untyped-call]
 apps/workflow/api/xero/seed.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/seed.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/seed.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
@@ -3917,6 +3510,18 @@ apps/workflow/api/xero/sync.py:0: error: Call to untyped function "deep_sync_xer
 apps/workflow/api/xero/sync.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
 apps/workflow/api/xero/sync.py:0: error: Call to untyped function "one_way_sync_all_xero_data" in typed context  [no-untyped-call]
 apps/workflow/api/xero/sync.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Call to untyped function "_draft" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Call to untyped function "_draft" in typed context  [no-untyped-call]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/purchasing/services/delivery_receipt_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/purchasing/services/delivery_receipt_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
 apps/purchasing/services/delivery_receipt_service.py:0: error: Missing type arguments for generic type "Dict"  [type-arg]
@@ -3935,15 +3540,218 @@ apps/purchasing/services/delivery_receipt_service.py:0: error: Call to untyped f
 apps/purchasing/services/delivery_receipt_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/purchasing/services/delivery_receipt_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/purchasing/services/delivery_receipt_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
-apps/process/urls_rest.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/quote_sync_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
-apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
-apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
-apps/job/views/quote_sync_views.py:0: error: Dict entry 0 has incompatible type "str": "bool"; expected "str": "str"  [dict-item]
-apps/job/views/quote_sync_views.py:0: error: Incompatible types in assignment (expression has type "ApplyQuoteErrorResponseSerializer", variable has type "QuoteSyncErrorResponseSerializer")  [assignment]
-apps/job/views/quote_sync_views.py:0: error: Dict entry 0 has incompatible type "str": "bool"; expected "str": "str"  [dict-item]
-apps/job/views/quote_sync_views.py:0: error: Incompatible types in assignment (expression has type "ApplyQuoteErrorResponseSerializer", variable has type "QuoteSyncErrorResponseSerializer")  [assignment]
+apps/accounting/views/kpi_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: "SalesPipelineServiceFixturesMixin" has no attribute "test_staff"  [attr-defined]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/accounting/tests/test_sales_pipeline_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounting/tests/test_sales_pipeline_service.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/tests/test_access_logging_middleware.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/tests/test_access_logging_middleware.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/views/stock_search_rest_view.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: note: Use "-> None" if function does not return a value
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/purchasing/tests/test_stock_fts_search.py:0: error: Call to untyped function "_stock" in typed context  [no-untyped-call]
+apps/job/tests/test_modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_modern_timesheet_views.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_modern_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_modern_timesheet_views.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_modern_timesheet_views.py:0: error: Item "None" of "XeroPayItem | None" has no attribute "name"  [union-attr]
+apps/job/views/kanban_view_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/kanban_view_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/kanban_view_api.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
+apps/job/views/kanban_view_api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/kanban_view_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/kanban_view_api.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
+apps/job/views/kanban_view_api.py:0: error: "str" has no attribute "HTTP_500_INTERNAL_SERVER_ERROR"  [attr-defined]
+apps/job/views/kanban_view_api.py:0: error: Incompatible types in assignment (expression has type "list[str]", target has type "str")  [assignment]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: "JobQuoteChatSerializer" has no attribute "get"  [attr-defined]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_message_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_message_or_404" in typed context  [no-untyped-call]
+apps/job/views/job_quote_chat_views.py:0: error: Call to untyped function "get_job_or_404_response" in typed context  [no-untyped-call]
+apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costing_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_costing_views.py:0: error: Call to untyped function "_archive_quote_data" in typed context  [no-untyped-call]
+apps/job/views/job_costing_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/assign_job_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/assign_job_view.py:0: error: Call to untyped function "assign_staff_to_job" of "JobStaffService" in typed context  [no-untyped-call]
+apps/job/views/assign_job_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/assign_job_view.py:0: error: Call to untyped function "remove_staff_from_job" of "JobStaffService" in typed context  [no-untyped-call]
+apps/job/services/job_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/job_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/services/job_rest_service.py:0: error: Missing return statement  [return]
+apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
+apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "ReturnDict[Any, Any]", expected "list[dict[str, Any]]")  [return-value]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: Value of type "JobDeltaRejection@AnnotatedWith[TypedDict({'occurrence_count': int, 'first_seen': Any, 'last_seen': Any, 'latest_id': Any})]" is not indexable  [index]
+apps/job/services/job_rest_service.py:0: error: "ValueError" has no attribute "delta_rejection_context"  [attr-defined]
+apps/job/services/job_rest_service.py:0: error: Assignment to variable "exc" outside except: block  [misc]
+apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
+apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
+apps/job/services/job_rest_service.py:0: error: Incompatible type for lookup 'company_id': (got "UUID | Any | None", expected "UUID | str")  [misc]
+apps/job/services/job_rest_service.py:0: error: Missing return statement  [return]
+apps/job/services/job_rest_service.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
+apps/job/services/job_rest_service.py:0: error: Argument "key" to "sort" of "list" has incompatible type "Callable[[dict[str, int | datetime | UUID | str | Any | None]], int | datetime | UUID | str | Any | None]"; expected "Callable[[dict[str, int | datetime | UUID | str | Any | None]], SupportsDunderLT[Any] | SupportsDunderGT[Any]]"  [arg-type]
+apps/job/services/job_rest_service.py:0: error: Incompatible return value type (got "int | datetime | UUID | str | Any | None", expected "SupportsDunderLT[Any] | SupportsDunderGT[Any]")  [return-value]
+apps/job/services/job_rest_service.py:0: error: Incompatible default for parameter "week" (default has type "None", parameter has type "date")  [assignment]
+apps/job/services/job_rest_service.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
+apps/job/services/job_rest_service.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
+apps/job/services/job_rest_service.py:0: error: "Job" has no attribute "pricings"  [attr-defined]
+apps/job/views/job_quote_chat_api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/views/xero_apps_view.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/workflow/views/xero_apps_view.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
 apps/workflow/views/xero_apps_view.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3956,16 +3764,12 @@ apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Incompatible types in assignment (expression has type "apps.client.models.Client", variable has type "django.test.client.Client")  [assignment]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "resolve_client_from_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: "Client" has no attribute "id"  [attr-defined]
+apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "resolve_company_from_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "resolve_client_from_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: "Client" has no attribute "id"  [attr-defined]
+apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "resolve_company_from_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "_extract_required_fields_xero" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: "Client" has no attribute "id"  [attr-defined]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Call to untyped function "transform_quote" in typed context  [no-untyped-call]
 apps/workflow/tests/test_xero_transform_contact_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -3977,18 +3781,6 @@ apps/workflow/tests/test_xero_tenant_id.py:0: error: Function is missing a retur
 apps/workflow/tests/test_xero_tenant_id.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_xero_tenant_id.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_tenant_id.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Call to untyped function "_draft" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Call to untyped function "_draft" in typed context  [no-untyped-call]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_pay_run_flow.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_xero_payroll_leave.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -3997,29 +3789,29 @@ apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type an
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_raw_json" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_clients"  [attr-defined]
-apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_clients" in typed context  [no-untyped-call]
+apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
+apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_clients"  [attr-defined]
-apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_clients" in typed context  [no-untyped-call]
+apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
+apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
-apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_clients"  [attr-defined]
-apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_clients" in typed context  [no-untyped-call]
+apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
+apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_create_response" in typed context  [no-untyped-call]
-apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "sync_client_to_xero" in typed context  [no-untyped-call]
+apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "sync_company_to_xero" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_create_response" in typed context  [no-untyped-call]
-apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "sync_client_to_xero" in typed context  [no-untyped-call]
+apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "sync_company_to_xero" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
-apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "create_client_contact_in_xero" in typed context  [no-untyped-call]
+apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "create_company_contact_in_xero" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "_make_client" in typed context  [no-untyped-call]
 apps/workflow/tests/test_push_contacts.py:0: error: Call to untyped function "bulk_create_contacts_in_xero" in typed context  [no-untyped-call]
@@ -4059,8 +3851,8 @@ apps/workflow/accounting/xero/provider.py:0: error: Too many arguments for "get_
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "create_client_contact_in_xero" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "sync_client_to_xero" in typed context  [no-untyped-call]
+apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "create_company_contact_in_xero" in typed context  [no-untyped-call]
+apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "sync_company_to_xero" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_build_line_items" of "XeroAccountingProvider" in typed context  [no-untyped-call]
@@ -4124,6 +3916,13 @@ apps/timesheet/views/api.py:0: error: Function is missing a type annotation  [no
 apps/timesheet/views/api.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/timesheet/views/api.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/timesheet/views/api.py:0: error: Call to untyped function "generate_payroll_events" in typed context  [no-untyped-call]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Incompatible return value type (got "str | None", expected "str")  [return-value]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
+apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
 apps/purchasing/services/purchasing_rest_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/purchasing/services/purchasing_rest_service.py:0: error: Call to untyped function (unknown) in typed context  [no-untyped-call]
 apps/purchasing/services/purchasing_rest_service.py:0: error: Argument 2 to "_create_line" of "PurchasingRestService" has incompatible type "Any | None"; expected "str"  [arg-type]
@@ -4139,14 +3938,74 @@ apps/purchasing/services/purchasing_rest_service.py:0: error: Call to untyped fu
 apps/purchasing/services/purchasing_rest_service.py:0: error: Incompatible return value type (got "QuerySet[Stock, Stock]", expected "list[dict[str, Any]]")  [return-value]
 apps/purchasing/services/purchasing_rest_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/purchasing/services/purchasing_rest_service.py:0: error: Call to untyped function "get_stock_holding_job" of "Stock" in typed context  [no-untyped-call]
-apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/services/providers/mistral_provider.py:0: error: Argument 1 to "_parse_price_from_string" of "MistralPriceExtractionProvider" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "encode_pdf" in typed context  [no-untyped-call]
-apps/quoting/services/providers/mistral_provider.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
-apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
-apps/quoting/services/providers/mistral_provider.py:0: error: Call to untyped function "ocr_response_to_dict" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Module "drf_spectacular.utils" does not explicitly export attribute "OpenApiTypes"  [attr-defined]
+apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Returning Any from function declared to return "dict[str, Any]"  [no-any-return]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Call to untyped function "get_serializer_class" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Argument 1 to "get_weekly_metrics" of "JobRestService" has incompatible type "date | None"; expected "date"  [arg-type]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Call to untyped function "calculate_profit_margin" in typed context  [no-untyped-call]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: "type[Job]" has no attribute "STATUS_CHOICES"  [attr-defined]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/job_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_rest_service.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_rest_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_rest_service.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_delta_rejection_grouping.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
+apps/job/tests/test_event_deduplication.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_event_deduplication.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_event_deduplication.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tasks.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_single_contact"  [attr-defined]
 apps/workflow/tasks.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_single_invoice"  [attr-defined]
 apps/workflow/tasks.py:0: error: Call to untyped function "sync_single_contact" in typed context  [no-untyped-call]
@@ -4167,7 +4026,7 @@ apps/workflow/views/xero/xero_view.py:0: error: Call to untyped function "get_me
 apps/workflow/views/xero/xero_view.py:0: error: Incompatible return value type (got "JsonResponse", expected "StreamingHttpResponse")  [return-value]
 apps/workflow/views/xero/xero_view.py:0: error: Call to untyped function "generate_xero_sync_events" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [return]
-apps/workflow/views/xero/xero_view.py:0: error: Argument "client" to "XeroInvoiceManager" has incompatible type "Client | None"; expected "Client"  [arg-type]
+apps/workflow/views/xero/xero_view.py:0: error: Argument "company" to "XeroInvoiceManager" has incompatible type "Company | None"; expected "Company"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Argument "staff" to "XeroInvoiceManager" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Incompatible types in assignment (expression has type "XeroDocumentErrorResponseSerializer", variable has type "XeroDocumentSuccessResponseSerializer")  [assignment]
 apps/workflow/views/xero/xero_view.py:0: error: Argument 2 to "error" has incompatible type "object"; expected "str | _StrPromise"  [arg-type]
@@ -4179,7 +4038,7 @@ apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [retur
 apps/workflow/views/xero/xero_view.py:0: error: Call to untyped function "XeroQuoteManager" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_view.py:0: error: Incompatible types in assignment (expression has type "XeroDocumentErrorResponseSerializer", variable has type "XeroDocumentSuccessResponseSerializer")  [assignment]
 apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [return]
-apps/workflow/views/xero/xero_view.py:0: error: Argument "client" to "XeroInvoiceManager" has incompatible type "Client | None"; expected "Client"  [arg-type]
+apps/workflow/views/xero/xero_view.py:0: error: Argument "company" to "XeroInvoiceManager" has incompatible type "Company | None"; expected "Company"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Argument "staff" to "XeroInvoiceManager" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Argument "xero_invoice_id" to "XeroInvoiceManager" has incompatible type "UUID"; expected "str | None"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
@@ -4207,13 +4066,116 @@ apps/workflow/views/xero/xero_view.py:0: error: Function is missing a type annot
 apps/workflow/views/xero/xero_view.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_view.py:0: error: Missing type arguments for generic type "ListAPIView"  [type-arg]
 apps/workflow/views/xero/xero_view.py:0: error: Missing type arguments for generic type "RetrieveAPIView"  [type-arg]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Incompatible return value type (got "str | None", expected "str")  [return-value]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
-apps/timesheet/services/payroll_employee_sync.py:0: error: Call to untyped function "_hours_between" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Incompatible types in assignment (expression has type "str | None", target has type "str")  [assignment]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_reset_scrub_schema" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run_pipe" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_reset_scrub_schema" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run" in typed context  [no-untyped-call]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clear_production_xero_ids" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_accounts" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_contacts" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_projects" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_employees" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_invoices" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_quotes" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_stock_items" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "seed_companies_to_xero" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "seed_jobs_to_xero" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "fetch_xero_entity_lookup" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_batch_create_invoices" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_get_invoice_line_unit_amount" of "Command" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "convert_to_pascal_case" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_build_invoice_payload" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "fetch_xero_entity_lookup" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_batch_create_quotes" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "convert_to_pascal_case" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_build_quote_payload" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Item "None" of "str | None" has no attribute "endswith"  [union-attr]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "run_setup" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_users" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_employees" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_rates" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_calendars" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_leave_types" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_pay_runs" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "configure_payroll" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "import_staff" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "link_staff" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "create_staff" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_tenants" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_tenants" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_employees_simple_dev" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "_print_link_staff_summary" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Call to untyped function "_print_create_staff_summary" in typed context  [no-untyped-call]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/tests/test_localdate_regression.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_localdate_regression.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_localdate_regression.py:0: error: Function is missing a return type annotation  [no-untyped-def]
@@ -4321,21 +4283,156 @@ apps/purchasing/views/purchasing_rest_views.py:0: error: Function is missing a t
 apps/purchasing/views/purchasing_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/purchasing/views/purchasing_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/purchasing/views/purchasing_rest_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/tests/test_ocr_fixtures.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/tests/test_ocr_fixtures.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/tests/test_ocr_fixtures.py:0: error: Call to untyped function "_ocr_response" in typed context  [no-untyped-call]
-apps/quoting/services/ai_price_extraction.py:0: error: Incompatible default for parameter "model_name" (default has type "None", parameter has type "str")  [assignment]
-apps/quoting/services/ai_price_extraction.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
-apps/quoting/services/ai_price_extraction.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase
-apps/quoting/services/ai_price_extraction.py:0: error: Incompatible return value type (got "MistralPriceExtractionProvider", expected "PriceExtractionProvider")  [return-value]
-apps/quoting/services/ai_price_extraction.py:0: error: Incompatible return value type (got "GeminiPriceExtractionProvider", expected "PriceExtractionProvider")  [return-value]
-apps/quoting/services/ai_price_extraction.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/quoting/services/ai_price_extraction.py:0: error: No overload variant of "get" of "dict" matches argument types "str", "int"  [call-overload]
-apps/quoting/services/ai_price_extraction.py:0: note: Possible overload variants:
-apps/quoting/services/ai_price_extraction.py:0: note: def get(self, AIProviderTypes, None = ..., /) -> int | None
-apps/quoting/services/ai_price_extraction.py:0: note: def get(self, AIProviderTypes, int, /) -> int
-apps/quoting/services/ai_price_extraction.py:0: note: def [_T] get(self, AIProviderTypes, _T, /) -> int | _T
-apps/quoting/services/ai_price_extraction.py:0: error: Call to untyped function "get_prioritized_active_providers" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "staff"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_after"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_after"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Value of type "Any | None" is not indexable  [index]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_before"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Argument 2 to "assertIn" of "TestCase" has incompatible type "Any | None"; expected "Iterable[Any] | Container[Any]"  [arg-type]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "schema_version"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "change_id"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_meta"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "delta_checksum"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "event_type"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_event" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "detail"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/job/tests/test_job_event_tracking.py:0: note: Use "-> None" if function does not return a value
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "_make_job" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "event_type"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "detail"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Item "None" of "JobEvent | None" has no attribute "description"  [union-attr]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "untracked_update" in typed context  [no-untyped-call]
+apps/job/tests/test_job_event_tracking.py:0: error: Call to untyped function "update" in typed context  [no-untyped-call]
+apps/job/views/quote_sync_views.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
+apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
+apps/job/views/quote_sync_views.py:0: error: Call to untyped function "draft_line_to_dict" in typed context  [no-untyped-call]
+apps/job/views/quote_sync_views.py:0: error: Dict entry 0 has incompatible type "str": "bool"; expected "str": "str"  [dict-item]
+apps/job/views/quote_sync_views.py:0: error: Incompatible types in assignment (expression has type "ApplyQuoteErrorResponseSerializer", variable has type "QuoteSyncErrorResponseSerializer")  [assignment]
+apps/job/views/quote_sync_views.py:0: error: Dict entry 0 has incompatible type "str": "bool"; expected "str": "str"  [dict-item]
+apps/job/views/quote_sync_views.py:0: error: Incompatible types in assignment (expression has type "ApplyQuoteErrorResponseSerializer", variable has type "QuoteSyncErrorResponseSerializer")  [assignment]
 apps/workflow/xero_webhooks.py:0: error: "Callable[[str, dict[str, Any]], None]" has no attribute "delay"  [attr-defined]
 apps/workflow/tests/test_xero_quota_floor.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_quota_floor.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -4454,17 +4551,6 @@ apps/workflow/tests/test_xero_po_manager.py:0: error: "type[XeroPurchaseOrderMan
 apps/workflow/tests/test_xero_po_manager.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_po_manager.py:0: error: "XeroPurchaseOrderManagerConstructionTests" has no attribute "purchase_order"  [attr-defined]
 apps/workflow/tests/test_xero_app_active.py:0: error: Value of type "dict[str, Any] | None" is not indexable  [index]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Incompatible types in assignment (expression has type "str | None", target has type "str")  [assignment]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_reset_scrub_schema" in typed context  [no-untyped-call]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run_pipe" in typed context  [no-untyped-call]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run" in typed context  [no-untyped-call]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_reset_scrub_schema" in typed context  [no-untyped-call]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Call to untyped function "_run" in typed context  [no-untyped-call]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/export_dev_demo_dump.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/backport_data_backup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/backport_data_backup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/backport_data_backup.py:0: error: Call to untyped function "analyze_fields" in typed context  [no-untyped-call]
@@ -4486,124 +4572,10 @@ apps/workflow/management/commands/backport_data_backup.py:0: error: Call to unty
 apps/workflow/management/commands/backport_data_backup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/backport_data_backup.py:0: error: Call to untyped function "collect_field_samples" in typed context  [no-untyped-call]
 apps/workflow/management/commands/backport_data_backup.py:0: error: Call to untyped function "collect_field_samples" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clear_production_xero_ids" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_accounts" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_contacts" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_projects" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_employees" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_invoices" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_quotes" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_stock_items" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "seed_clients_to_xero" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "seed_jobs_to_xero" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "fetch_xero_entity_lookup" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_batch_create_invoices" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_get_invoice_line_unit_amount" of "Command" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "convert_to_pascal_case" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_build_invoice_payload" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "fetch_xero_entity_lookup" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_batch_create_quotes" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "convert_to_pascal_case" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "clean_payload" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_build_quote_payload" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Item "None" of "str | None" has no attribute "endswith"  [union-attr]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_column_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Call to untyped function "_table_exists" in typed context  [no-untyped-call]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/seed_xero_from_database.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/views.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/quoting/views.py:0: error: Call to untyped function "PDFDataValidationService" in typed context  [no-untyped-call]
-apps/quoting/views.py:0: error: Call to untyped function "PDFImportService" in typed context  [no-untyped-call]
-apps/workflow/apps.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/workflow/apps.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_seed_xero_from_database.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_seed_xero_from_database.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_seed_xero_from_database.py:0: error: Incompatible types in assignment (expression has type "StringIO", variable has type "OutputWrapper")  [assignment]
 apps/workflow/tests/test_seed_xero_from_database.py:0: error: Call to untyped function "clear_production_xero_ids" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "run_setup" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_users" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_employees" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_rates" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_calendars" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_leave_types" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_payroll_pay_runs" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "configure_payroll" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "import_staff" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "link_staff" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "create_staff" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_tenants" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_tenants" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "get_employees_simple_dev" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: note: Use "-> None" if function does not return a value
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "_print_link_staff_summary" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Call to untyped function "_print_create_staff_summary" in typed context  [no-untyped-call]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/timesheet/api/daily_timesheet_views.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
-apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
-apps/accounts/tests/test_auth_observability.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
-apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
-apps/accounts/tests/test_auth_observability.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
-apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
-apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_xero_setup_command.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_setup_command.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_setup_command.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -4625,3 +4597,15 @@ apps/workflow/tests/test_xero_setup_command.py:0: error: Cannot assign to a meth
 apps/workflow/tests/test_xero_setup_command.py:0: error: Call to untyped function "run_setup" in typed context  [no-untyped-call]
 apps/workflow/tests/test_xero_setup_command.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_xero_setup_command.py:0: note: Use "-> None" if function does not return a value
+apps/workflow/apps.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
+apps/workflow/apps.py:0: error: Function is missing a type annotation  [no-untyped-def]
+apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
+apps/accounts/tests/test_auth_observability.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
+apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
+apps/accounts/tests/test_auth_observability.py:0: error: Call to untyped function "authenticate" in typed context  [no-untyped-call]
+apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
+apps/accounts/tests/test_auth_observability.py:0: error: Function is missing a return type annotation  [no-untyped-def]
+apps/accounts/tests/test_auth_observability.py:0: note: Use "-> None" if function does not return a value
diff --git a/scripts/analyze_client_contacts.py b/scripts/analyze_client_contacts.py
index bd3b68285..ec48db783 100644
--- a/scripts/analyze_client_contacts.py
+++ b/scripts/analyze_client_contacts.py
@@ -19,7 +19,7 @@
 
 from django.db.models import Count
 
-from apps.client.models import Client, ClientContact
+from apps.company.models import ClientContact, Company
 from apps.job.models import Job
 
 
@@ -38,7 +38,7 @@ def analyze_empty_names(verbose: bool) -> None:
         logging.info("Sample records (first 10):")
         for contact in empty_name_contacts[:10]:
             logging.info("  - ID: %s", contact.id)
-            logging.info("    Client: %s", contact.client.name)
+            logging.info("    Company: %s", contact.company.name)
             logging.info("    Name: '%s' (length: %d)", contact.name, len(contact.name))
             logging.info("    Email: %s", contact.email or "None")
 
@@ -48,11 +48,11 @@ def analyze_empty_names(verbose: bool) -> None:
 
 
 def analyze_duplicates(verbose: bool) -> None:
-    """Analyze duplicate ClientContact records (same client + name)."""
+    """Analyze duplicate ClientContact records (same company + name)."""
     logging.info("2. DUPLICATE CONTACT ANALYSIS")
 
     duplicates = (
-        ClientContact.objects.values("client", "name")
+        ClientContact.objects.values("company", "name")
         .annotate(count=Count("id"))
         .filter(count__gt=1)
         .order_by("-count")
@@ -60,7 +60,7 @@ def analyze_duplicates(verbose: bool) -> None:
 
     total_duplicate_groups = duplicates.count()
     logging.info(
-        "Total duplicate (client, name) combinations: %d", total_duplicate_groups
+        "Total duplicate (company, name) combinations: %d", total_duplicate_groups
     )
 
     if total_duplicate_groups == 0:
@@ -73,17 +73,17 @@ def analyze_duplicates(verbose: bool) -> None:
     if verbose:
         logging.info("Top 10 duplicate groups:")
         for i, dup in enumerate(duplicates[:10], 1):
-            client = Client.objects.get(id=dup["client"])
+            company = Company.objects.get(id=dup["company"])
             logging.info(
-                "%d. Client: %s — Contact: '%s' — %d copies",
+                "%d. Company: %s — Contact: '%s' — %d copies",
                 i,
-                client.name,
+                company.name,
                 dup["name"],
                 dup["count"],
             )
 
             contacts = ClientContact.objects.filter(
-                client_id=dup["client"], name=dup["name"]
+                company_id=dup["company"], name=dup["name"]
             ).order_by("-created_at")
 
             for contact in contacts[:5]:
@@ -105,7 +105,7 @@ def analyze_duplicates(verbose: bool) -> None:
 
     logging.info("--- SUMMARY ---")
     logging.info("Empty/whitespace name contacts: %d", empty_count)
-    logging.info("Duplicate (client, name) combinations: %d", total_duplicate_groups)
+    logging.info("Duplicate (company, name) combinations: %d", total_duplicate_groups)
     logging.info("Total duplicate records to be removed: %d", total_duplicate_records)
     logging.info(
         "Total records after cleanup: %d",
diff --git a/scripts/fix_test_client.py b/scripts/fix_test_client.py
deleted file mode 100644
index 059b59e70..000000000
--- a/scripts/fix_test_client.py
+++ /dev/null
@@ -1,34 +0,0 @@
-#!/usr/bin/env python
-"""Create the test client (CompanyDefaults.test_client_name) when missing.
-
-Idempotent restore-time mutation. Pairs with
-scripts/restore_checks/check_test_client.py, which is now read-only.
-"""
-
-import os
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
-
-import django
-
-django.setup()
-
-from django.utils import timezone
-
-from apps.client.models import Client
-from apps.workflow.models import CompanyDefaults
-
-cd = CompanyDefaults.get_solo()
-client = Client.objects.filter(name=cd.test_client_name).first()
-
-if client:
-    print(f"Test client already exists: {client.name} (ID: {client.id})")
-else:
-    client = Client(
-        name=cd.test_client_name,
-        is_account_customer=False,
-        xero_last_modified=timezone.now(),
-        xero_last_synced=timezone.now(),
-    )
-    client.save()
-    print(f"Created test client: {client.name} (ID: {client.id})")
diff --git a/scripts/fix_test_company.py b/scripts/fix_test_company.py
new file mode 100644
index 000000000..4beb1847f
--- /dev/null
+++ b/scripts/fix_test_company.py
@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+"""Create the test company (CompanyDefaults.test_company_name) when missing.
+
+Idempotent restore-time mutation. Pairs with
+scripts/restore_checks/check_test_company.py, which is now read-only.
+"""
+
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from django.utils import timezone
+
+from apps.company.models import Company
+from apps.workflow.models import CompanyDefaults
+
+cd = CompanyDefaults.get_solo()
+company = Company.objects.filter(name=cd.test_company_name).first()
+
+if company:
+    print(f"Test company already exists: {company.name} (ID: {company.id})")
+else:
+    company = Company(
+        name=cd.test_company_name,
+        is_account_customer=False,
+        xero_last_modified=timezone.now(),
+        xero_last_synced=timezone.now(),
+    )
+    company.save()
+    print(f"Created test company: {company.name} (ID: {company.id})")
diff --git a/scripts/geocode_addresses.py b/scripts/geocode_addresses.py
index 8897fddd1..ae16f4e5e 100644
--- a/scripts/geocode_addresses.py
+++ b/scripts/geocode_addresses.py
@@ -21,8 +21,8 @@
 
 django.setup()
 
-from apps.client.models import SupplierPickupAddress
-from apps.client.services.geocoding_service import (
+from apps.company.models import SupplierPickupAddress
+from apps.company.services.geocoding_service import (
     GeocodingError,
     GeocodingNotConfiguredError,
     geocode_address,
@@ -99,7 +99,7 @@ def main() -> None:
 
     for i, address in enumerate(addresses, 1):
         freetext = build_freetext_address(address)
-        logging.info("[%d/%d] %s", i, total, address.client.name)
+        logging.info("[%d/%d] %s", i, total, address.company.name)
         logging.info("  Input: %s", freetext)
 
         if args.dry_run:
diff --git a/scripts/integration/verify_xero_batch_order.py b/scripts/integration/verify_xero_batch_order.py
index 2010edab1..d78a27db3 100644
--- a/scripts/integration/verify_xero_batch_order.py
+++ b/scripts/integration/verify_xero_batch_order.py
@@ -2,7 +2,7 @@
 """Verify that Xero's create_contacts API preserves submission order.
 
 The bulk_create_contacts_in_xero path in apps/workflow/api/xero/push.py
-maps response contacts back to local Client rows by zip-by-index. That
+maps response contacts back to local Company rows by zip-by-index. That
 is correct iff Xero echoes contacts back in the same order they were
 sent. The Xero SDK does not document this guarantee, so we validate it
 on demand against a real dev tenant.
diff --git a/scripts/integration/verify_xero_client_quote_contract.py b/scripts/integration/verify_xero_client_quote_contract.py
index 7332de9d4..c051d4abd 100644
--- a/scripts/integration/verify_xero_client_quote_contract.py
+++ b/scripts/integration/verify_xero_client_quote_contract.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-"""Verify the public app API and Xero agree on client/quote contact data.
+"""Verify the public app API and Xero agree on company/quote contact data.
 
 App writes go through the configured public app URL. Xero verification uses
 official Xero SDK read APIs. This creates real local records and real Xero
@@ -153,19 +153,19 @@ def assert_contact_contract(contact, expected: dict[str, str]) -> None:
     "is_account_customer": True,
     "allow_jobs": True,
 }
-log.info("client request: %s", json.dumps(client_payload, sort_keys=True))
-client = app_request("POST", "/api/clients/create/", json=client_payload)["client"]
-assert client["email"] == client_payload["email"], client
-assert client["phone"] == client_payload["phone"], client
-assert client["address"] == client_payload["address"], client
-assert client["xero_contact_id"], client
-
-created_contact = xero_contact(client["xero_contact_id"])
+log.info("company request: %s", json.dumps(client_payload, sort_keys=True))
+company = app_request("POST", "/api/companies/create/", json=client_payload)["company"]
+assert company["email"] == client_payload["email"], company
+assert company["phone"] == client_payload["phone"], company
+assert company["address"] == client_payload["address"], company
+assert company["xero_contact_id"], company
+
+created_contact = xero_contact(company["xero_contact_id"])
 assert_contact_contract(created_contact, client_payload)
 
 job_payload = {
     "name": f"Xero Contract Job {run_id}",
-    "client_id": client["id"],
+    "client_id": company["id"],
     "description": "Xero contract smoke test",
     "pricing_methodology": "fixed_price",
     "estimated_materials": "1000.00",
@@ -176,23 +176,23 @@ def assert_contact_contract(contact, expected: dict[str, str]) -> None:
 job_id = job["job_id"]
 
 job_readback = app_request("GET", f"/api/job/jobs/{job_id}/")["data"]["job"]
-assert job_readback["client_id"] == client["id"], job_readback
+assert job_readback["client_id"] == company["id"], job_readback
 
 quote = app_request(
     "POST", f"/api/xero/create_quote/{job_id}", json={"breakdown": False}
 )
 quote_readback = xero_quote(quote["xero_id"])
-assert str(quote_readback.contact.contact_id) == client["xero_contact_id"], (
+assert str(quote_readback.contact.contact_id) == company["xero_contact_id"], (
     quote_readback.contact.contact_id,
-    client["xero_contact_id"],
+    company["xero_contact_id"],
 )
 
-contact_after_quote = xero_contact(client["xero_contact_id"])
+contact_after_quote = xero_contact(company["xero_contact_id"])
 assert_contact_contract(contact_after_quote, client_payload)
 
 log.info("PASS")
-log.info("client_id=%s", client["id"])
-log.info("xero_contact_id=%s", client["xero_contact_id"])
+log.info("client_id=%s", company["id"])
+log.info("xero_contact_id=%s", company["xero_contact_id"])
 log.info("job_id=%s", job_id)
 log.info("xero_quote_id=%s", quote["xero_id"])
 log.info("email=%s", client_payload["email"])
diff --git a/scripts/push_clients_to_xero.py b/scripts/push_companies_to_xero.py
similarity index 56%
rename from scripts/push_clients_to_xero.py
rename to scripts/push_companies_to_xero.py
index 059aeccc3..bb6104817 100644
--- a/scripts/push_clients_to_xero.py
+++ b/scripts/push_companies_to_xero.py
@@ -1,13 +1,13 @@
 #!/usr/bin/env python
 """
-Push database clients to Xero as contacts.
+Push database companies to Xero as contacts.
 
 This script is designed to run after production restore and Xero sync.
-It finds clients that are referenced by jobs or purchase orders but don't
+It finds companies that are referenced by jobs or purchase orders but don't
 have xero_contact_id values, and creates them as contacts in Xero.
 
 Usage:
-    python scripts/push_clients_to_xero.py [--dry-run] [--force]
+    python scripts/push_companies_to_xero.py [--dry-run] [--force]
 
 Options:
     --dry-run   Show what would be created without making changes
@@ -28,8 +28,8 @@
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
 django.setup()
 
-from apps.client.models import Client
-from apps.workflow.api.xero.sync import sync_client_to_xero
+from apps.company.models import Company
+from apps.workflow.api.xero.sync import sync_company_to_xero
 from apps.workflow.services.error_persistence import persist_app_error
 
 
@@ -72,67 +72,71 @@ def confirm_operation(force=False, dry_run=False):
     print()
 
 
-def find_clients_to_push():
-    """Find clients that need to be pushed to Xero."""
-    # Clients referenced by jobs
-    clients_with_jobs = Client.objects.filter(
+def find_companies_to_push():
+    """Find companies that need to be pushed to Xero."""
+    # Companies referenced by jobs
+    companies_with_jobs = Company.objects.filter(
         jobs__isnull=False, xero_contact_id__isnull=True
     ).distinct()
 
-    # Clients referenced by purchase orders
-    clients_with_pos = Client.objects.filter(
+    # Companies referenced by purchase orders
+    companies_with_pos = Company.objects.filter(
         purchase_orders__isnull=False, xero_contact_id__isnull=True
     ).distinct()
 
     # Combine and deduplicate
-    all_clients = (clients_with_jobs | clients_with_pos).distinct().order_by("name")
+    all_companies = (
+        (companies_with_jobs | companies_with_pos).distinct().order_by("name")
+    )
 
-    return all_clients
+    return all_companies
 
 
-def push_clients_to_xero(clients, dry_run=False):
-    """Push clients to Xero and track results."""
+def push_companies_to_xero(companies, dry_run=False):
+    """Push companies to Xero and track results."""
     results = {"success": [], "failed": [], "skipped": []}
 
-    for i, client in enumerate(clients, 1):
-        print(f"📤 ({i}/{len(clients)}) Processing: {client.name}")
+    for i, company in enumerate(companies, 1):
+        print(f"📤 ({i}/{len(companies)}) Processing: {company.name}")
 
-        # Validate client has required data
+        # Validate company has required data
         try:
-            if not client.validate_for_xero():
+            if not company.validate_for_xero():
                 print("  ⚠️  Skipping - missing required data for Xero")
-                results["skipped"].append((client, "Missing required data"))
+                results["skipped"].append((company, "Missing required data"))
                 continue
         except Exception as e:
             print(f"  ❌ Validation error: {e}")
-            results["failed"].append((client, f"Validation error: {e}"))
+            results["failed"].append((company, f"Validation error: {e}"))
             continue
 
         if dry_run:
-            print(f"  ✅ Would create contact: {client.name}")
-            results["success"].append((client, "Would create (dry run)"))
+            print(f"  ✅ Would create contact: {company.name}")
+            results["success"].append((company, "Would create (dry run)"))
             continue
 
         # Attempt to push to Xero
         try:
-            success = sync_client_to_xero(client)
+            success = sync_company_to_xero(company)
             if success:
-                print(f"  ✅ Created in Xero with ID: {client.xero_contact_id}")
-                results["success"].append((client, client.xero_contact_id))
+                print(f"  ✅ Created in Xero with ID: {company.xero_contact_id}")
+                results["success"].append((company, company.xero_contact_id))
             else:
                 print("  ❌ Failed to create in Xero")
-                results["failed"].append((client, "sync_client_to_xero returned False"))
+                results["failed"].append(
+                    (company, "sync_company_to_xero returned False")
+                )
         except Exception as e:
             print(f"  ❌ Error creating in Xero: {e}")
             persist_app_error(
                 e,
                 additional_context={
-                    "operation": "push_clients_to_xero",
-                    "client_id": str(client.id),
-                    "client_name": client.name,
+                    "operation": "push_companies_to_xero",
+                    "company_id": str(company.id),
+                    "company_name": company.name,
                 },
             )
-            results["failed"].append((client, str(e)))
+            results["failed"].append((company, str(e)))
 
     return results
 
@@ -144,41 +148,41 @@ def main():
     force = "--force" in sys.argv
 
     mode_text = "DRY RUN - " if dry_run else ""
-    print(f"🚀 {mode_text}Push Database Clients to Xero")
+    print(f"🚀 {mode_text}Push Database Companies to Xero")
     print("=" * 50)
 
     # Safety confirmation
     confirm_operation(force=force, dry_run=dry_run)
 
-    # Find clients that need to be pushed
-    print("🔍 Finding clients that need to be pushed to Xero...")
-    clients_to_push = find_clients_to_push()
+    # Find companies that need to be pushed
+    print("🔍 Finding companies that need to be pushed to Xero...")
+    companies_to_push = find_companies_to_push()
 
-    if not clients_to_push:
-        print("✅ No clients need to be pushed to Xero.")
+    if not companies_to_push:
+        print("✅ No companies need to be pushed to Xero.")
         print(
-            "All clients with jobs or purchase orders already have xero_contact_id values."
+            "All companies with jobs or purchase orders already have xero_contact_id values."
         )
         return
 
-    print(f"📋 Found {len(clients_to_push)} clients to push:")
-    for client in clients_to_push[:10]:  # Show first 10
-        job_count = client.jobs.count()
-        po_count = client.purchase_orders.count()
-        print(f"  • {client.name} (Jobs: {job_count}, POs: {po_count})")
+    print(f"📋 Found {len(companies_to_push)} companies to push:")
+    for company in companies_to_push[:10]:  # Show first 10
+        job_count = company.jobs.count()
+        po_count = company.purchase_orders.count()
+        print(f"  • {company.name} (Jobs: {job_count}, POs: {po_count})")
 
-    if len(clients_to_push) > 10:
-        print(f"  ... and {len(clients_to_push) - 10} more")
+    if len(companies_to_push) > 10:
+        print(f"  ... and {len(companies_to_push) - 10} more")
 
     print()
 
-    # Push clients to Xero
+    # Push companies to Xero
     action_text = "Simulating push of" if dry_run else "Pushing"
-    print(f"🚀 {action_text} {len(clients_to_push)} clients to Xero...")
+    print(f"🚀 {action_text} {len(companies_to_push)} companies to Xero...")
     print()
 
     with transaction.atomic():
-        results = push_clients_to_xero(clients_to_push, dry_run=dry_run)
+        results = push_companies_to_xero(companies_to_push, dry_run=dry_run)
 
     # Report results
     print()
@@ -190,15 +194,15 @@ def main():
 
     if results["failed"]:
         print()
-        print("❌ Failed clients:")
-        for client, reason in results["failed"]:
-            print(f"  • {client.name}: {reason}")
+        print("❌ Failed companies:")
+        for company, reason in results["failed"]:
+            print(f"  • {company.name}: {reason}")
 
     if results["skipped"]:
         print()
-        print("⚠️  Skipped clients:")
-        for client, reason in results["skipped"]:
-            print(f"  • {client.name}: {reason}")
+        print("⚠️  Skipped companies:")
+        for company, reason in results["skipped"]:
+            print(f"  • {company.name}: {reason}")
 
     if not dry_run and results["success"]:
         print()
@@ -211,7 +215,7 @@ def main():
         print("🔍 Dry run complete - no changes made")
         print("Run without --dry-run to actually create contacts in Xero")
     else:
-        print("🎉 Client push to Xero complete!")
+        print("🎉 Company push to Xero complete!")
 
 
 if __name__ == "__main__":
diff --git a/scripts/restore_checks/check_django_orm.py b/scripts/restore_checks/check_django_orm.py
index 2658f2ebd..77aeb4089 100644
--- a/scripts/restore_checks/check_django_orm.py
+++ b/scripts/restore_checks/check_django_orm.py
@@ -10,12 +10,12 @@
 django.setup()
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 
 print(f"Jobs: {Job.objects.count()}")
 print(f"Staff: {Staff.objects.count()}")
-print(f"Clients: {Client.objects.count()}")
+print(f"Companies: {Company.objects.count()}")
 
 job = Job.objects.first()
 if job:
diff --git a/scripts/restore_checks/check_shop_client.py b/scripts/restore_checks/check_shop_client.py
deleted file mode 100644
index c93bbc050..000000000
--- a/scripts/restore_checks/check_shop_client.py
+++ /dev/null
@@ -1,22 +0,0 @@
-#!/usr/bin/env python
-"""Verify shop client has correct name."""
-
-import os
-import sys
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
-
-import django
-
-django.setup()
-
-from apps.client.models import Client
-
-SHOP_CLIENT_ID = "00000000-0000-0000-0000-000000000001"
-
-try:
-    shop = Client.objects.get(id=SHOP_CLIENT_ID)
-    print(f"Shop client: {shop.name}")
-except Client.DoesNotExist:
-    print(f"ERROR: Shop client with ID {SHOP_CLIENT_ID} not found")
-    sys.exit(1)
diff --git a/scripts/restore_checks/check_shop_company.py b/scripts/restore_checks/check_shop_company.py
new file mode 100644
index 000000000..ba1022a31
--- /dev/null
+++ b/scripts/restore_checks/check_shop_company.py
@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+"""Verify shop company has correct name."""
+
+import os
+import sys
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from apps.company.models import Company
+
+SHOP_COMPANY_ID = "00000000-0000-0000-0000-000000000001"
+
+try:
+    shop = Company.objects.get(id=SHOP_COMPANY_ID)
+    print(f"Shop company: {shop.name}")
+except Company.DoesNotExist:
+    print(f"ERROR: Shop company with ID {SHOP_COMPANY_ID} not found")
+    sys.exit(1)
diff --git a/scripts/restore_checks/check_test_client.py b/scripts/restore_checks/check_test_client.py
deleted file mode 100644
index 09904c853..000000000
--- a/scripts/restore_checks/check_test_client.py
+++ /dev/null
@@ -1,26 +0,0 @@
-#!/usr/bin/env python
-"""Verify the test client (CompanyDefaults.test_client_name) exists. Read-only."""
-
-import os
-import sys
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
-
-import django
-
-django.setup()
-
-from apps.client.models import Client
-from apps.workflow.models import CompanyDefaults
-
-cd = CompanyDefaults.get_solo()
-client = Client.objects.filter(name=cd.test_client_name).first()
-
-if not client:
-    print(
-        f"ERROR: Test client {cd.test_client_name!r} not found — "
-        "run scripts/fix_test_client.py first"
-    )
-    sys.exit(1)
-
-print(f"Test client: {client.name} (ID: {client.id})")
diff --git a/scripts/restore_checks/check_test_company.py b/scripts/restore_checks/check_test_company.py
new file mode 100644
index 000000000..832b9a6c3
--- /dev/null
+++ b/scripts/restore_checks/check_test_company.py
@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+"""Verify the test company (CompanyDefaults.test_company_name) exists. Read-only."""
+
+import os
+import sys
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from apps.company.models import Company
+from apps.workflow.models import CompanyDefaults
+
+cd = CompanyDefaults.get_solo()
+company = Company.objects.filter(name=cd.test_company_name).first()
+
+if not company:
+    print(
+        f"ERROR: Test company {cd.test_company_name!r} not found — "
+        "run scripts/fix_test_company.py first"
+    )
+    sys.exit(1)
+
+print(f"Test company: {company.name} (ID: {company.id})")
diff --git a/scripts/restore_checks/check_xero_seed.py b/scripts/restore_checks/check_xero_seed.py
index 74c4802ef..6d1755257 100644
--- a/scripts/restore_checks/check_xero_seed.py
+++ b/scripts/restore_checks/check_xero_seed.py
@@ -10,18 +10,18 @@
 django.setup()
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.purchasing.models import Stock
 
-clients_with_xero = Client.objects.filter(xero_contact_id__isnull=False).count()
+companies_with_xero = Company.objects.filter(xero_contact_id__isnull=False).count()
 jobs_with_xero = Job.objects.filter(xero_project_id__isnull=False).count()
 stock_with_xero = Stock.objects.filter(xero_id__isnull=False, is_active=True).count()
 staff_with_xero = Staff.objects.filter(
     xero_user_id__isnull=False, date_left__isnull=True
 ).count()
 
-print(f"Clients linked to Xero: {clients_with_xero}")
+print(f"Companies linked to Xero: {companies_with_xero}")
 print(f"Jobs linked to Xero: {jobs_with_xero}")
 print(f"Stock items synced to Xero: {stock_with_xero}")
 print(f"Staff linked to Xero Payroll: {staff_with_xero}")
diff --git a/scripts/restore_checks/fix_shop_client.py b/scripts/restore_checks/fix_shop_client.py
deleted file mode 100644
index a4aa23138..000000000
--- a/scripts/restore_checks/fix_shop_client.py
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env python
-"""Fix shop client name after production restore (anonymized during backup)."""
-
-import os
-import sys
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
-
-import django
-
-django.setup()
-
-from apps.client.models import Client
-
-SHOP_CLIENT_ID = "00000000-0000-0000-0000-000000000001"
-NEW_NAME = "Demo Company Shop"
-
-try:
-    shop_client = Client.objects.get(id=SHOP_CLIENT_ID)
-    old_name = shop_client.name
-    shop_client.name = NEW_NAME
-    shop_client.save()
-
-    print("Updated shop client:")
-    print(f"  Old name: {old_name}")
-    print(f"  New name: {shop_client.name}")
-    print(f"  ID: {shop_client.id}")
-    print(f"  Job count: {shop_client.jobs.count()}")
-except Client.DoesNotExist:
-    print(f"ERROR: Shop client with ID {SHOP_CLIENT_ID} not found")
-    sys.exit(1)
diff --git a/scripts/restore_checks/fix_shop_company.py b/scripts/restore_checks/fix_shop_company.py
new file mode 100644
index 000000000..ddd61d29b
--- /dev/null
+++ b/scripts/restore_checks/fix_shop_company.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+"""Fix shop company name after production restore (anonymized during backup)."""
+
+import os
+import sys
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from apps.company.models import Company
+
+SHOP_COMPANY_ID = "00000000-0000-0000-0000-000000000001"
+NEW_NAME = "Demo Company Shop"
+
+try:
+    shop_company = Company.objects.get(id=SHOP_COMPANY_ID)
+    old_name = shop_company.name
+    shop_company.name = NEW_NAME
+    shop_company.save()
+
+    print("Updated shop company:")
+    print(f"  Old name: {old_name}")
+    print(f"  New name: {shop_company.name}")
+    print(f"  ID: {shop_company.id}")
+    print(f"  Job count: {shop_company.jobs.count()}")
+except Company.DoesNotExist:
+    print(f"ERROR: Shop company with ID {SHOP_COMPANY_ID} not found")
+    sys.exit(1)
diff --git a/scripts/restore_checks/test_serializers.py b/scripts/restore_checks/test_serializers.py
index cc673457f..025ec5f10 100644
--- a/scripts/restore_checks/test_serializers.py
+++ b/scripts/restore_checks/test_serializers.py
@@ -39,7 +39,7 @@
 from django.test import RequestFactory
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import CostLine, CostSet, Job
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine
 
@@ -162,7 +162,7 @@ def test_job_serializer(self) -> Dict[str, Any]:
             .select_related(
                 "contact",
                 "created_by",
-                "client",
+                "company",
                 "latest_estimate",
                 "latest_quote",
                 "latest_actual",
@@ -185,7 +185,7 @@ def test_kanban_serializer(self) -> Dict[str, Any]:
             Job.objects.filter(
                 status__in=["quoting", "in_progress", "ready_for_delivery"]
             )
-            .select_related("contact", "client", "created_by")
+            .select_related("contact", "company", "created_by")
             .prefetch_related("people")
         )
         context = KanbanService.build_serialization_context(jobs)
@@ -213,10 +213,10 @@ def test_costing_serializer(self) -> Dict[str, Any]:
 
     def test_client_serializer(self) -> Dict[str, Any]:
         """Test ClientSerializer with sample of clients"""
-        from apps.client.serializers import ClientSerializer
+        from apps.company.serializers import ClientSerializer
 
         # Test sample of clients to avoid overwhelming output
-        queryset = Client.objects.all()[:500]
+        queryset = Company.objects.all()[:500]
 
         return self._test_serializer_batch(
             ClientSerializer, queryset, "ClientSerializer (Sample)"
@@ -240,7 +240,7 @@ def test_purchase_order_serializer(self) -> Dict[str, Any]:
             .prefetch_related(
                 Prefetch(
                     "po_lines",
-                    queryset=PurchaseOrderLine.objects.select_related("job__client"),
+                    queryset=PurchaseOrderLine.objects.select_related("job__company"),
                     to_attr="detail_lines",
                 )
             )
@@ -289,7 +289,7 @@ def run_all_tests(self, specific_serializer: str = None) -> Dict[str, Any]:
             "job": self.test_job_serializer,
             "kanban": self.test_kanban_serializer,
             "costing": self.test_costing_serializer,
-            "client": self.test_client_serializer,
+            "company": self.test_client_serializer,
             "staff": self.test_staff_serializer,
             "purchase_order": self.test_purchase_order_serializer,
             "timesheet": self.test_modern_timesheet_serializer,
@@ -374,7 +374,7 @@ def main():
         "--serializer",
         "-s",
         type=str,
-        help="Test specific serializer (job, kanban, costing, client, staff, purchase_order, timesheet)",
+        help="Test specific serializer (job, kanban, costing, company, staff, purchase_order, timesheet)",
     )
 
     args = parser.parse_args()
diff --git a/scripts/server/deploy.sh b/scripts/server/deploy.sh
index 91c1b5c00..492224778 100755
--- a/scripts/server/deploy.sh
+++ b/scripts/server/deploy.sh
@@ -335,6 +335,13 @@ for instance in "${TARGETS[@]}"; do
     switch_instance_release "$instance" "$TARGET_SHA"
     chown -h "$inst_user:$inst_user" "$instance_dir/app"
 
+    log "  Running relabel_client_app (KAN-278 one-time DB surgery)..."
+    if ! "$SCRIPT_DIR/dw-run.sh" "$instance" python manage.py relabel_client_app; then
+        log "  ERROR: relabel_client_app failed for $instance — services remain stopped"
+        FAILED_INSTANCES+=("$instance")
+        continue
+    fi
+
     log "  Running migrate..."
     if "$SCRIPT_DIR/dw-run.sh" "$instance" python manage.py migrate --no-input; then
         log "  Migration complete for $instance"
diff --git a/scripts/test_full_quote_conversation.py b/scripts/test_full_quote_conversation.py
index bd5e511d2..0509367aa 100644
--- a/scripts/test_full_quote_conversation.py
+++ b/scripts/test_full_quote_conversation.py
@@ -99,7 +99,7 @@ def main():
         return 1
 
     print(f"\nTesting with job: {job.job_number} - {job.name}")
-    print(f"Client: {job.client.name}")
+    print(f"Company: {job.company.name}")
 
     # Clear existing chat
     deleted = JobQuoteChat.objects.filter(job=job).delete()
diff --git a/scripts/test_quote_import.py b/scripts/test_quote_import.py
index b17c8d0c6..65731ac6b 100644
--- a/scripts/test_quote_import.py
+++ b/scripts/test_quote_import.py
@@ -22,7 +22,7 @@
 
 from django.conf import settings
 
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.job.services.import_quote_service import (
     QuoteImportError,
@@ -37,14 +37,14 @@ def get_or_create_test_job() -> Job:
     if test_job:
         return test_job
 
-    client = Client.objects.first()
-    if not client:
-        logging.info("Creating test client...")
-        client = Client.objects.create(name="Test Client", account_ref="TEST001")
+    company = Company.objects.first()
+    if not company:
+        logging.info("Creating test company...")
+        company = Company.objects.create(name="Test Company", account_ref="TEST001")
 
     test_job = Job.objects.create(
         name="Quote Import Test Job",
-        client=client,
+        company=company,
         status="quoting",
         description="Test job for quote import service testing",
     )
diff --git a/scripts/validate_restore_progress.py b/scripts/validate_restore_progress.py
index fbb60f07c..758f5d69b 100644
--- a/scripts/validate_restore_progress.py
+++ b/scripts/validate_restore_progress.py
@@ -15,7 +15,7 @@
 django.setup()
 
 from apps.accounts.models import Staff
-from apps.client.models import Client
+from apps.company.models import Company
 from apps.job.models import Job
 from apps.workflow.models import CompanyDefaults, XeroToken
 
@@ -27,13 +27,13 @@ def check_basic_restore():
     # Check database has data
     job_count = Job.objects.count()
     staff_count = Staff.objects.count()
-    client_count = Client.objects.count()
+    company_count = Company.objects.count()
 
     checks.append(
         (
             "Database populated",
-            job_count > 0 and staff_count > 0 and client_count > 0,
-            f"Jobs: {job_count}, Staff: {staff_count}, Clients: {client_count}",
+            job_count > 0 and staff_count > 0 and company_count > 0,
+            f"Jobs: {job_count}, Staff: {staff_count}, Companies: {company_count}",
         )
     )
 
@@ -62,15 +62,15 @@ def check_basic_restore():
         )
     )
 
-    # Check shop client
-    shop_exists = Client.objects.filter(
+    # Check shop company
+    shop_exists = Company.objects.filter(
         id="00000000-0000-0000-0000-000000000001"
     ).exists()
     checks.append(
         (
-            "Shop client exists",
+            "Shop company exists",
             shop_exists,
-            "Shop client found" if shop_exists else "Not found",
+            "Shop company found" if shop_exists else "Not found",
         )
     )
 
@@ -105,14 +105,14 @@ def check_xero_config():
         checks.append(("Xero tenant ID set", False, "Company defaults not found"))
 
     # Check if Xero IDs are cleared (they should be null or have new IDs)
-    clients_with_xero = Client.objects.filter(xero_contact_id__isnull=False).count()
+    companies_with_xero = Company.objects.filter(xero_contact_id__isnull=False).count()
     jobs_with_xero = Job.objects.filter(xero_project_id__isnull=False).count()
 
     checks.append(
         (
             "Xero sync status",
             True,
-            f"Clients with Xero ID: {clients_with_xero}, Jobs with Xero ID: {jobs_with_xero}",
+            f"Companies with Xero ID: {companies_with_xero}, Jobs with Xero ID: {jobs_with_xero}",
         )
     )
 

From 6b4992c8f5a978f854f5d3ba1a9cd9d4eb6c5288 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Mon, 6 Jul 2026 22:54:49 +1200
Subject: [PATCH 03/73] KAN-278 refactor: rename client to company across
 frontend

Hand-written frontend sweep matching the regenerated API client:
- api.clients_* -> api.companies_*, schemas.Client* -> schemas.Company*,
  client_id/client_name -> company_id/company_name
- File renames: CompanyLookup.vue, CreateCompanyModal.vue,
  CompanyDropdown.vue, InlineEditCompany.vue, useCompanyLookup.ts,
  companyService.ts, companyStore.ts, company-wrapper.ts
- Route /crm/clients -> /crm/companies (typed-router regenerated)
- data-automation-id values + Playwright specs updated in lockstep
- Kept: src/api/client.ts (HTTP client), schemas.ClientContact* (backend
  class names unchanged until Stage B), Xero OAuth client_id, and the
  Step-3 persisted values (domain: 'client', source: 'client_lookup',
  client_match, cross_client/effective_client_id)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/components/AdvancedSearchDialog.vue   |  16 +-
 frontend/src/components/AppNavbar.vue         |   8 +-
 .../components/CompanyDefaultsFormModal.vue   |  16 +-
 ...ClientDropdown.vue => CompanyDropdown.vue} |  54 ++--
 .../{ClientLookup.vue => CompanyLookup.vue}   | 154 +++++-----
 .../src/components/ContactSelectionModal.vue  |  12 +-
 frontend/src/components/ContactSelector.vue   |  50 ++--
 ...ClientModal.vue => CreateCompanyModal.vue} | 190 ++++++------
 frontend/src/components/JobCard.vue           |   4 +-
 frontend/src/components/KanbanColumn.vue      |   2 +-
 frontend/src/components/SectionForm.vue       |  32 +-
 ...ntLookup.test.ts => CompanyLookup.test.ts} |  38 +--
 .../components/__tests__/SectionForm.test.ts  |  32 +-
 .../src/components/board/ActiveJobCard.vue    |   2 +-
 .../src/components/board/WorkshopModeView.vue |   8 +-
 .../src/components/crm/PhoneCallTable.vue     |  38 +--
 .../src/components/crm/PhoneNumberManager.vue | 110 +++----
 .../PhoneCallTable.recording.test.ts          |   6 +-
 .../src/components/job/JobAttachmentsTab.vue  |  10 +-
 .../src/components/job/JobQuotingChatTab.vue  |   2 +-
 .../src/components/job/JobSettingsTab.vue     | 280 +++++++++---------
 .../JobSettingsTab.labourRate.test.ts         |  10 +-
 .../__tests__/JobSettingsTab.urgent.test.ts   |  10 +-
 .../src/components/kpi/KPIDayDetailsModal.vue |   2 +-
 .../components/kpi/KPILabourDetailsModal.vue  |   2 +-
 .../purchasing/AddressAutocompleteInput.vue   |   2 +-
 .../src/components/purchasing/JobSelect.vue   |   6 +-
 .../components/purchasing/PoLinesTable.vue    |   4 +-
 .../components/purchasing/PoSummaryCard.vue   |  12 +-
 ...neEditClient.vue => InlineEditCompany.vue} |  72 ++---
 .../timesheet/SmartTimesheetTable.vue         |  12 +-
 .../components/timesheet/StaffDetailModal.vue |   6 +-
 .../components/timesheet/SummaryDrawer.vue    |   2 +-
 .../timesheet/TimesheetJobPicker.vue          |   8 +-
 .../timesheet/WeeklyMetricsModal.vue          |   6 +-
 .../SmartTimesheetTable.billReset.test.ts     |   4 +-
 .../SmartTimesheetTable.urgent.test.ts        |   6 +-
 .../TimesheetJobPicker.urgent.test.ts         |   2 +-
 .../components/workshop/WorkshopJobHeader.vue |   4 +-
 .../workshop/WorkshopJobPickerDrawer.vue      |   6 +-
 .../workshop/WorkshopTimesheetLegacyTable.vue |   2 +-
 .../composables/__tests__/useErrorApi.test.ts |   2 +-
 .../__tests__/useOptimizedKanban.test.ts      |  16 +-
 ...useClientLookup.ts => useCompanyLookup.ts} | 134 ++++-----
 .../src/composables/useContactManagement.ts   |  72 ++---
 frontend/src/composables/useJobAutosave.ts    |   8 +-
 .../src/composables/useJobHeaderAutosave.ts   |  40 +--
 .../src/composables/useJobNotifications.ts    |   2 +-
 .../src/composables/useOptimizedKanban.ts     |   4 +-
 .../composables/usePickupAddressManagement.ts |  14 +-
 .../composables/useWorkshopTimesheetJobs.ts   |   4 +-
 frontend/src/constants/advanced-filters.ts    |   4 +-
 .../{client-wrapper.ts => company-wrapper.ts} |   6 +-
 frontend/src/pages/crm/calls.vue              |  68 ++---
 .../crm/{clients => companies}/(index).vue    | 142 ++++-----
 .../pages/crm/{clients => companies}/[id].vue | 158 +++++-----
 frontend/src/pages/jobs/[id]/(index).vue      |  46 +--
 frontend/src/pages/jobs/create.vue            | 104 +++----
 frontend/src/pages/kanban.vue                 |   2 +-
 frontend/src/pages/purchasing/po/(index).vue  |   2 +-
 frontend/src/pages/purchasing/po/[id].vue     |   4 +-
 frontend/src/pages/quoting/chat.vue           |   6 +-
 .../reports/data-quality/archived-jobs.vue    |  18 +-
 .../reports/data-quality/duplicate-phones.vue |   2 +-
 frontend/src/pages/reports/job-aging.vue      |   8 +-
 frontend/src/pages/reports/job-movement.vue   |   4 +-
 .../src/pages/reports/job-profitability.vue   |  18 +-
 frontend/src/pages/reports/rdti-spend.vue     |  16 +-
 frontend/src/pages/reports/sales-forecast.vue |  12 +-
 frontend/src/pages/reports/wip.vue            |  10 +-
 frontend/src/pages/schedule.vue               |  10 +-
 frontend/src/pages/timesheets/entry.vue       |   4 +-
 .../admin-company-defaults-service.ts         |   2 +-
 frontend/src/services/clientService.ts        |  65 ----
 frontend/src/services/companyService.ts       |  65 ++++
 .../src/services/job-aging-report.service.ts  |   6 +-
 frontend/src/services/job.service.ts          |  12 +-
 frontend/src/services/kpi.service.ts          |   2 +-
 .../services/sales-pipeline-report.service.ts |   2 +-
 frontend/src/services/wip-report.service.ts   |   6 +-
 frontend/src/stores/__tests__/jobs.test.ts    |   2 +-
 frontend/src/stores/clientStore.ts            | 230 --------------
 frontend/src/stores/companyStore.ts           | 230 ++++++++++++++
 frontend/src/stores/jobs.ts                   |   6 +-
 frontend/src/typed-router.d.ts                |  20 +-
 frontend/src/types/job-aging.types.ts         |   2 +-
 frontend/src/types/job-movement.types.ts      |   2 +-
 frontend/src/types/sales-forecast.types.ts    |   2 +-
 .../src/utils/__tests__/timesheetCalc.test.ts |   2 +-
 frontend/src/utils/iconRegistry.ts            |   2 +-
 frontend/src/views/AdminArchiveJobsView.vue   |   4 +-
 frontend/src/views/WorkshopKanbanView.vue     |   2 +-
 frontend/src/views/WorkshopView.vue           |   4 +-
 .../__tests__/AdminErrorView.resolved.test.ts |   2 +-
 .../views/__tests__/QuotingChatView.test.ts   |   4 +-
 frontend/src/views/jobColumns.ts              |  10 +-
 frontend/tests/company-defaults.spec.ts       |   6 +-
 .../tests/crm/phone-call-job-link.spec.ts     |   4 +-
 frontend/tests/fixtures/auth.ts               |  18 +-
 frontend/tests/fixtures/helpers.ts            |  56 ++--
 ...ts => create-job-with-new-company.spec.ts} | 100 +++----
 frontend/tests/job/create-job.spec.ts         |  42 +--
 frontend/tests/job/edit-job-settings.spec.ts  |  84 +++---
 .../tests/purchasing/pickup-address.spec.ts   |  16 +-
 .../purchasing/supplier-alias-search.spec.ts  |  42 +--
 .../{clients.spec.ts => companies.spec.ts}    |  78 ++---
 frontend/tests/scripts/db-backup-utils.ts     |  16 +-
 frontend/tests/scripts/e2e-reset.ts           |   2 +-
 frontend/tests/scripts/global-teardown.ts     |   2 +-
 .../timesheet/urgent-job-defaults.spec.ts     |  26 +-
 110 files changed, 1683 insertions(+), 1675 deletions(-)
 rename frontend/src/components/{ClientDropdown.vue => CompanyDropdown.vue} (66%)
 rename frontend/src/components/{ClientLookup.vue => CompanyLookup.vue} (60%)
 rename frontend/src/components/{CreateClientModal.vue => CreateCompanyModal.vue} (66%)
 rename frontend/src/components/__tests__/{ClientLookup.test.ts => CompanyLookup.test.ts} (54%)
 rename frontend/src/components/shared/{InlineEditClient.vue => InlineEditCompany.vue} (56%)
 rename frontend/src/composables/{useClientLookup.ts => useCompanyLookup.ts} (54%)
 rename frontend/src/constants/{client-wrapper.ts => company-wrapper.ts} (70%)
 rename frontend/src/pages/crm/{clients => companies}/(index).vue (58%)
 rename frontend/src/pages/crm/{clients => companies}/[id].vue (80%)
 delete mode 100644 frontend/src/services/clientService.ts
 create mode 100644 frontend/src/services/companyService.ts
 delete mode 100644 frontend/src/stores/clientStore.ts
 create mode 100644 frontend/src/stores/companyStore.ts
 rename frontend/tests/job/{create-job-with-new-client.spec.ts => create-job-with-new-company.spec.ts} (57%)
 rename frontend/tests/reports/{clients.spec.ts => companies.spec.ts} (55%)

diff --git a/frontend/src/components/AdvancedSearchDialog.vue b/frontend/src/components/AdvancedSearchDialog.vue
index c65375ba4..71d1e10ec 100644
--- a/frontend/src/components/AdvancedSearchDialog.vue
+++ b/frontend/src/components/AdvancedSearchDialog.vue
@@ -14,10 +14,10 @@
             v-model="localFilters.q"
             type="text"
             class="w-full px-3 py-2 border border-blue-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent text-sm"
-            placeholder="Search job number, name, description, or client..."
+            placeholder="Search job number, name, description, or company..."
           />
           <p class="mt-1 text-xs text-blue-600">
-            Searches across job number, name, description, and client name
+            Searches across job number, name, description, and company name
           </p>
         </div>
 
@@ -48,11 +48,11 @@
           </div>
 
           <div>
-            <ClientLookup
-              id="client"
-              label="Client"
-              v-model="localFilters.client_name"
-              placeholder="Search for a client..."
+            <CompanyLookup
+              id="company"
+              label="Company"
+              v-model="localFilters.company_name"
+              placeholder="Search for a company..."
               :search-mode="true"
             />
           </div>
@@ -172,7 +172,7 @@
 
 <script setup lang="ts">
 import { ref, watch } from 'vue'
-import ClientLookup from '@/components/ClientLookup.vue'
+import CompanyLookup from '@/components/CompanyLookup.vue'
 import StaffDropdown from '@/components/StaffDropdown.vue'
 import StatusMultiSelect from '@/components/StatusMultiSelect.vue'
 import {
diff --git a/frontend/src/components/AppNavbar.vue b/frontend/src/components/AppNavbar.vue
index 4bcbaf66a..c64e4af4d 100644
--- a/frontend/src/components/AppNavbar.vue
+++ b/frontend/src/components/AppNavbar.vue
@@ -221,10 +221,10 @@
                 class="absolute top-full left-0 mt-1 w-56 bg-white rounded-md shadow-lg border border-gray-200 z-[60]"
               >
                 <router-link
-                  to="/crm/clients"
+                  to="/crm/companies"
                   class="flex items-center px-4 py-2 text-sm text-gray-700 hover:text-blue-600 hover:bg-blue-50 font-medium transition-all"
                 >
-                  <Users class="w-4 h-4 mr-2" /> Clients
+                  <Users class="w-4 h-4 mr-2" /> Companies
                 </router-link>
                 <router-link
                   v-if="userInfo.is_superuser"
@@ -730,11 +730,11 @@
                   <div v-if="mobileSections.crm" class="overflow-hidden">
                     <div class="px-3 pb-2 space-y-1">
                       <router-link
-                        to="/crm/clients"
+                        to="/crm/companies"
                         class="flex items-center px-2 py-1.5 text-sm text-gray-600 hover:text-blue-600 hover:bg-blue-50 rounded transition-all"
                         @click="closeMobileMenu"
                       >
-                        <Users class="w-4 h-4 mr-2" /> Clients
+                        <Users class="w-4 h-4 mr-2" /> Companies
                       </router-link>
                       <router-link
                         v-if="userInfo.is_superuser"
diff --git a/frontend/src/components/CompanyDefaultsFormModal.vue b/frontend/src/components/CompanyDefaultsFormModal.vue
index 3d526fab2..752db7bdc 100644
--- a/frontend/src/components/CompanyDefaultsFormModal.vue
+++ b/frontend/src/components/CompanyDefaultsFormModal.vue
@@ -31,10 +31,10 @@
             <input v-model="form.po_prefix" class="input" required />
           </div>
           <div>
-            <label class="block text-sm font-medium mb-1">Shop Client</label>
-            <select v-model="form.shop_client" class="input" required>
-              <option v-for="client in clientOptions" :key="client.id" :value="client.id">
-                {{ client.name }}
+            <label class="block text-sm font-medium mb-1">Shop Company</label>
+            <select v-model="form.shop_company" class="input" required>
+              <option v-for="company in companyOptions" :key="company.id" :value="company.id">
+                {{ company.name }}
               </option>
             </select>
           </div>
@@ -70,20 +70,20 @@ import { schemas } from '@/api/generated/api'
 import type { z } from 'zod'
 
 type CompanyDefaultsForm = z.infer<typeof schemas.CompanyDefaults>
-type ClientOption = z.infer<typeof schemas.ClientNameOnly>
+type CompanyOption = z.infer<typeof schemas.CompanyNameOnly>
 
 const props = defineProps<{ defaults: CompanyDefaultsForm }>()
 const emit = defineEmits(['close', 'saved'])
 const form = ref<CompanyDefaultsForm>({ ...props.defaults })
-const clientOptions = ref<ClientOption[]>([])
+const companyOptions = ref<CompanyOption[]>([])
 const error = ref('')
 const isLoading = ref(false)
 
 onMounted(async () => {
   try {
-    clientOptions.value = await api.clients_all_list()
+    companyOptions.value = await api.companies_all_list()
   } catch {
-    error.value = 'Failed to load clients.'
+    error.value = 'Failed to load companies.'
   }
 })
 
diff --git a/frontend/src/components/ClientDropdown.vue b/frontend/src/components/CompanyDropdown.vue
similarity index 66%
rename from frontend/src/components/ClientDropdown.vue
rename to frontend/src/components/CompanyDropdown.vue
index 53eeff3f8..27cd3e925 100644
--- a/frontend/src/components/ClientDropdown.vue
+++ b/frontend/src/components/CompanyDropdown.vue
@@ -11,10 +11,10 @@
         class="w-full p-2 border border-gray-200 rounded-md appearance-none bg-white text-gray-900 focus:outline-none focus:border-blue-500 focus:ring-1 focus:ring-blue-500 disabled:bg-gray-50 disabled:cursor-not-allowed transition-colors"
         @change="handleChange"
       >
-        <option v-if="isLoading" value="">Loading clients...</option>
+        <option v-if="isLoading" value="">Loading companies...</option>
         <option v-else value="">{{ placeholder }}</option>
-        <option v-for="client in clientOptions" :key="client.id" :value="client.id">
-          {{ client.name }}
+        <option v-for="company in companyOptions" :key="company.id" :value="company.id">
+          {{ company.name }}
         </option>
       </select>
 
@@ -36,44 +36,44 @@ import { schemas } from '@/api/generated/api'
 import { api } from '@/api/client'
 import { z } from 'zod'
 
-type Client = z.infer<typeof schemas.ClientNameOnly>
+type Company = z.infer<typeof schemas.CompanyNameOnly>
 
 interface Props {
   id: string
   label: string
   placeholder?: string
   modelValue?: string
-  createdClient?: Client | null
+  createdCompany?: Company | null
 }
 
 interface Emits {
   (e: 'update:modelValue', value: string): void
-  (e: 'selected-client', client: Client | null): void
+  (e: 'selected-company', company: Company | null): void
 }
 
 const props = withDefaults(defineProps<Props>(), {
-  placeholder: 'Any Client',
-  createdClient: null,
+  placeholder: 'Any Company',
+  createdCompany: null,
 })
 
 const emit = defineEmits<Emits>()
 
-const clientOptions = ref<Client[]>([])
+const companyOptions = ref<Company[]>([])
 const selectedValue = ref<string>(props.modelValue || '')
 const isLoading = ref(false)
 const error = ref<string | null>(null)
 const selectEl = ref<HTMLSelectElement | null>(null)
 
-const loadClientOptions = async (): Promise<void> => {
+const loadCompanyOptions = async (): Promise<void> => {
   try {
     isLoading.value = true
     error.value = null
-    const data = await api.clients_all_list()
-    clientOptions.value = data
+    const data = await api.companies_all_list()
+    companyOptions.value = data
   } catch (err) {
-    error.value = err instanceof Error ? err.message : 'Failed to load client options'
-    console.error('Error loading client options:', err)
-    toast.error('Failed to load clients')
+    error.value = err instanceof Error ? err.message : 'Failed to load company options'
+    console.error('Error loading company options:', err)
+    toast.error('Failed to load companies')
   } finally {
     isLoading.value = false
   }
@@ -81,29 +81,29 @@ const loadClientOptions = async (): Promise<void> => {
 
 const handleChange = (): void => {
   emit('update:modelValue', selectedValue.value)
-  const client = clientOptions.value.find((c: Client) => c.id === selectedValue.value) || null
-  emit('selected-client', client)
+  const company = companyOptions.value.find((c: Company) => c.id === selectedValue.value) || null
+  emit('selected-company', company)
 }
 
-function upsertClientInOptions(c: Client) {
-  const idx = clientOptions.value.findIndex((x: Client) => x.id === c.id)
+function upsertCompanyInOptions(c: Company) {
+  const idx = companyOptions.value.findIndex((x: Company) => x.id === c.id)
   if (idx === -1) {
-    clientOptions.value = [c, ...clientOptions.value]
+    companyOptions.value = [c, ...companyOptions.value]
   } else {
-    clientOptions.value[idx] = c
+    companyOptions.value[idx] = c
   }
 }
 
-async function closeAndSelect(client: Client) {
-  upsertClientInOptions(client)
-  selectedValue.value = client.id
+async function closeAndSelect(company: Company) {
+  upsertCompanyInOptions(company)
+  selectedValue.value = company.id
   handleChange()
   await nextTick()
   selectEl.value?.blur()
 }
 
 watch(
-  () => props.createdClient,
+  () => props.createdCompany,
   (c) => {
     if (!c) return
     closeAndSelect(c)
@@ -119,12 +119,12 @@ watch(
 )
 
 defineExpose({
-  reload: loadClientOptions,
+  reload: loadCompanyOptions,
   focus: () => selectEl.value?.focus(),
   blur: () => selectEl.value?.blur(),
 })
 
 onMounted(() => {
-  loadClientOptions()
+  loadCompanyOptions()
 })
 </script>
diff --git a/frontend/src/components/ClientLookup.vue b/frontend/src/components/CompanyLookup.vue
similarity index 60%
rename from frontend/src/components/ClientLookup.vue
rename to frontend/src/components/CompanyLookup.vue
index 3a270e37d..0bf5d3e5b 100644
--- a/frontend/src/components/ClientLookup.vue
+++ b/frontend/src/components/CompanyLookup.vue
@@ -14,7 +14,7 @@
           type="text"
           :placeholder="placeholder"
           :required="required"
-          data-automation-id="ClientLookup-input"
+          data-automation-id="CompanyLookup-input"
           class="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent"
           @input="handleInput"
           @focus="handleFocus"
@@ -24,7 +24,7 @@
         />
 
         <div
-          v-if="isLoading || isCreatingQuickClient"
+          v-if="isLoading || isCreatingQuickCompany"
           class="absolute right-3 top-1/2 transform -translate-y-1/2"
         >
           <div class="animate-spin rounded-full h-4 w-4 border-b-2 border-blue-600"></div>
@@ -32,30 +32,30 @@
 
         <div
           v-if="showSuggestions && (suggestions.length > 0 || searchQuery.length >= 3)"
-          data-automation-id="ClientLookup-results"
+          data-automation-id="CompanyLookup-results"
           class="absolute z-50 w-full mt-1 bg-white border border-gray-300 rounded-md shadow-lg max-h-60 overflow-y-auto"
         >
           <div
-            v-for="(client, index) in suggestions"
-            :key="client.id"
+            v-for="(company, index) in suggestions"
+            :key="company.id"
             role="option"
-            :data-automation-id="`ClientLookup-option-${client.id}`"
+            :data-automation-id="`CompanyLookup-option-${company.id}`"
             class="px-4 py-2 hover:bg-blue-50 cursor-pointer border-b border-gray-100 last:border-b-0"
-            @mousedown.prevent="selectClient(client, index + 1)"
+            @mousedown.prevent="selectCompany(company, index + 1)"
           >
-            <div class="font-medium text-gray-900">{{ client.name }}</div>
+            <div class="font-medium text-gray-900">{{ company.name }}</div>
           </div>
 
           <div
             v-if="searchQuery.length >= 3"
             class="px-4 py-2 hover:bg-green-50 cursor-pointer border-t border-gray-200 text-green-700 font-medium"
-            data-automation-id="ClientLookup-create-new"
+            data-automation-id="CompanyLookup-create-new"
             @mousedown.prevent="handleCreateNew"
           >
             <div class="flex items-center justify-between">
               <div class="flex items-center">
                 <Plus class="w-4 h-4 mr-2" />
-                Add new {{ supplierLookup.value ? 'supplier' : 'client' }} "{{ searchQuery }}"
+                Add new {{ supplierLookup.value ? 'supplier' : 'company' }} "{{ searchQuery }}"
               </div>
               <div class="text-xs text-gray-500">or press Ctrl+Enter</div>
             </div>
@@ -65,7 +65,7 @@
             v-if="suggestions.length === 0 && searchQuery.length >= 3 && !isLoading"
             class="px-4 py-2 text-gray-500 text-center"
           >
-            No clients found
+            No companies found
           </div>
         </div>
       </div>
@@ -78,8 +78,10 @@
               ? 'bg-green-100 text-green-800 border border-green-200'
               : 'bg-red-100 text-red-800 border border-red-200',
           ]"
-          :title="hasValidXeroId ? 'Client has Xero ID' : 'Client missing Xero ID'"
-          :data-automation-id="xeroValid ? 'ClientLookup-xero-valid' : 'ClientLookup-xero-invalid'"
+          :title="hasValidXeroId ? 'Company has Xero ID' : 'Company missing Xero ID'"
+          :data-automation-id="
+            xeroValid ? 'CompanyLookup-xero-valid' : 'CompanyLookup-xero-invalid'
+          "
           v-if="!searchMode"
         >
           <component :is="xeroValid ? CheckCircle : XCircle" class="w-3 h-3" />
@@ -88,18 +90,18 @@
       </div>
     </div>
 
-    <div v-if="selectedClient && !editMode" class="mt-2 p-2 bg-blue-50 rounded border">
-      <div class="text-sm font-medium text-blue-900">{{ selectedClient.name }}</div>
-      <div v-if="selectedClient.email" class="text-xs text-blue-700">
-        {{ selectedClient.email }}
+    <div v-if="selectedCompany && !editMode" class="mt-2 p-2 bg-blue-50 rounded border">
+      <div class="text-sm font-medium text-blue-900">{{ selectedCompany.name }}</div>
+      <div v-if="selectedCompany.email" class="text-xs text-blue-700">
+        {{ selectedCompany.email }}
       </div>
     </div>
 
-    <CreateClientModal
+    <CreateCompanyModal
       :is-open="showCreateModal"
       :initial-name="searchQuery"
       @update:is-open="showCreateModal = $event"
-      @client-created="handleClientCreated"
+      @company-created="handleCompanyCreated"
     />
   </div>
 </template>
@@ -107,9 +109,9 @@
 <script setup lang="ts">
 import { ref, watch, onMounted, computed } from 'vue'
 import { Plus, CheckCircle, XCircle } from 'lucide-vue-next'
-import { logClientSearchClick, useClientLookup } from '@/composables/useClientLookup'
-import CreateClientModal from '@/components/CreateClientModal.vue'
-import type { Client } from '@/composables/useClientLookup'
+import { logCompanySearchClick, useCompanyLookup } from '@/composables/useCompanyLookup'
+import CreateCompanyModal from '@/components/CreateCompanyModal.vue'
+import type { Company } from '@/composables/useCompanyLookup'
 import { api } from '@/api/client'
 import { toast } from 'vue-sonner'
 import { debugLog } from '../utils/debug'
@@ -126,7 +128,7 @@ const props = withDefaults(
     editMode?: boolean
   }>(),
   {
-    placeholder: 'Search for a client...',
+    placeholder: 'Search for a company...',
     required: false,
     modelValue: '',
     supplierLookup: () => ({ value: false }),
@@ -136,7 +138,7 @@ const props = withDefaults(
 
 const emit = defineEmits<{
   'update:modelValue': [value: string]
-  'update:selectedClient': [client: Client | null]
+  'update:selectedCompany': [company: Company | null]
   'update:selectedId': [id: string]
 }>()
 
@@ -145,20 +147,20 @@ const {
   suggestions,
   isLoading,
   showSuggestions,
-  selectedClient,
+  selectedCompany,
   hasValidXeroId,
   handleInputChange,
-  selectClient: selectClientFromComposable,
+  selectCompany: selectCompanyFromComposable,
   hideSuggestions,
-  preserveSelectedClient,
-} = useClientLookup({ supplierLookup: props.supplierLookup })
+  preserveSelectedCompany,
+} = useCompanyLookup({ supplierLookup: props.supplierLookup })
 
-// Simple check: does the selected client have a Xero ID?
+// Simple check: does the selected company have a Xero ID?
 const xeroValid = computed(() => hasValidXeroId.value)
 
 const showCreateModal = ref(false)
 const inputEl = ref<HTMLInputElement | null>(null) // Template ref for the input element
-const isCreatingQuickClient = ref(false)
+const isCreatingQuickCompany = ref(false)
 
 const blurTimeout = ref<ReturnType<typeof setTimeout> | null>(null)
 
@@ -206,14 +208,14 @@ const handleBlur = () => {
   }, 200)
 }
 
-const selectClient = (client: Client, rank: number | null = null) => {
+const selectCompany = (company: Company, rank: number | null = null) => {
   const query = searchQuery.value
-  preserveSelectedClient()
-  selectClientFromComposable(client)
-  logClientSearchClick(client, query, rank, 'client_lookup')
-  emit('update:modelValue', client.name)
-  emit('update:selectedClient', client)
-  emit('update:selectedId', client.id)
+  preserveSelectedCompany()
+  selectCompanyFromComposable(company)
+  logCompanySearchClick(company, query, rank, 'client_lookup')
+  emit('update:modelValue', company.name)
+  emit('update:selectedCompany', company)
+  emit('update:selectedId', company.id)
   showSuggestions.value = false
 }
 
@@ -226,65 +228,65 @@ const handleKeydown = async (event: KeyboardEvent) => {
   if (event.ctrlKey && event.key === 'Enter') {
     event.preventDefault()
 
-    const clientName = searchQuery.value.trim()
-    if (clientName.length >= 3) {
-      await createQuickClient(clientName)
+    const companyName = searchQuery.value.trim()
+    if (companyName.length >= 3) {
+      await createQuickCompany(companyName)
     }
   }
 }
 
-const createQuickClient = async (clientName: string) => {
-  if (isCreatingQuickClient.value) return
+const createQuickCompany = async (companyName: string) => {
+  if (isCreatingQuickCompany.value) return
 
-  isCreatingQuickClient.value = true
+  isCreatingQuickCompany.value = true
 
   try {
-    const clientData = {
-      name: clientName,
+    const companyData = {
+      name: companyName,
       email: null,
       address: '',
       is_account_customer: false,
     }
 
-    const result = await api.clients_create_create(clientData)
+    const result = await api.companies_create_create(companyData)
 
-    if (result.success && result.client) {
-      if (!result.client.xero_contact_id) {
-        throw new Error('Client was created but does not have a Xero ID')
+    if (result.success && result.company) {
+      if (!result.company.xero_contact_id) {
+        throw new Error('Company was created but does not have a Xero ID')
       }
 
-      const newClient: Client = {
-        ...result.client,
-        email: result.client.email ?? '',
-        address: result.client.address ?? '',
-        xero_contact_id: result.client.xero_contact_id ?? '',
+      const newCompany: Company = {
+        ...result.company,
+        email: result.company.email ?? '',
+        address: result.company.address ?? '',
+        xero_contact_id: result.company.xero_contact_id ?? '',
       }
 
-      selectClient(newClient)
-      searchQuery.value = newClient.name
-      emit('update:modelValue', newClient.name)
+      selectCompany(newCompany)
+      searchQuery.value = newCompany.name
+      emit('update:modelValue', newCompany.name)
 
-      toast.success(`Client "${clientName}" created successfully!`, {
+      toast.success(`Company "${companyName}" created successfully!`, {
         position: 'bottom-left',
       })
     } else {
-      throw new Error(result.message || 'Failed to create client')
+      throw new Error(result.message || 'Failed to create company')
     }
   } catch (error) {
-    toast.error(`Failed to create client: ${error instanceof Error ? error.message : error}`, {
+    toast.error(`Failed to create company: ${error instanceof Error ? error.message : error}`, {
       position: 'bottom-left',
     })
-    console.error('Quick client creation error:', error)
+    console.error('Quick company creation error:', error)
   } finally {
-    isCreatingQuickClient.value = false
+    isCreatingQuickCompany.value = false
   }
 }
 
-const handleClientCreated = (client: Client) => {
-  selectClient(client)
+const handleCompanyCreated = (company: Company) => {
+  selectCompany(company)
 
-  searchQuery.value = client.name
-  emit('update:modelValue', client.name)
+  searchQuery.value = company.name
+  emit('update:modelValue', company.name)
 
   closeLookup()
 }
@@ -294,29 +296,29 @@ watch(
   (newValue) => {
     if (newValue !== searchQuery.value) {
       searchQuery.value = newValue
-      // Preserve selected client when dialog reopens
-      preserveSelectedClient()
+      // Preserve selected company when dialog reopens
+      preserveSelectedCompany()
     }
   },
   { immediate: true },
 )
 
-watch(selectedClient, (newClient, oldClient) => {
+watch(selectedCompany, (newCompany, oldCompany) => {
   // Only emit if this is a real change, not during initial loading
-  if (newClient?.id !== oldClient?.id) {
-    if (newClient) {
-      emit('update:selectedClient', newClient)
-      emit('update:selectedId', newClient.id)
+  if (newCompany?.id !== oldCompany?.id) {
+    if (newCompany) {
+      emit('update:selectedCompany', newCompany)
+      emit('update:selectedId', newCompany.id)
     } else {
-      emit('update:selectedClient', null)
+      emit('update:selectedCompany', null)
       emit('update:selectedId', '')
     }
   }
 })
 
-// Preserve client selection when component mounts
+// Preserve company selection when component mounts
 onMounted(() => {
   debugLog('Props value: ', props)
-  preserveSelectedClient(props.modelValue || '')
+  preserveSelectedCompany(props.modelValue || '')
 })
 </script>
diff --git a/frontend/src/components/ContactSelectionModal.vue b/frontend/src/components/ContactSelectionModal.vue
index 6bf166d80..322220a7c 100644
--- a/frontend/src/components/ContactSelectionModal.vue
+++ b/frontend/src/components/ContactSelectionModal.vue
@@ -7,8 +7,10 @@
         <DialogHeader class="flex-shrink-0 pb-4 border-b border-gray-200">
           <DialogTitle class="text-lg font-semibold">Select Contact</DialogTitle>
           <DialogDescription class="text-sm text-gray-600">
-            Client:
-            <span class="font-medium text-gray-900">{{ clientName || 'No client selected' }}</span>
+            Company:
+            <span class="font-medium text-gray-900">{{
+              companyName || 'No company selected'
+            }}</span>
           </DialogDescription>
         </DialogHeader>
 
@@ -38,7 +40,7 @@
                   v-if="contactToDelete?.is_primary"
                   class="text-sm text-amber-600 font-medium mb-4"
                 >
-                  This is the primary contact for this client.
+                  This is the primary contact for this company.
                 </p>
                 <div class="flex gap-3 justify-center">
                   <button
@@ -299,8 +301,8 @@ type ClientContact = z.infer<typeof schemas.ClientContact>
 
 const props = defineProps<{
   isOpen: boolean
-  clientId: string
-  clientName: string
+  companyId: string
+  companyName: string
   contacts: ClientContact[]
   selectedContact: ClientContact | null
   isLoading: boolean
diff --git a/frontend/src/components/ContactSelector.vue b/frontend/src/components/ContactSelector.vue
index 318d63eb9..0fcbf5877 100644
--- a/frontend/src/components/ContactSelector.vue
+++ b/frontend/src/components/ContactSelector.vue
@@ -25,7 +25,7 @@
         data-automation-id="ContactSelector-modal-button"
         class="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition-colors"
         @click="handleOpenModal"
-        :disabled="!clientId"
+        :disabled="!companyId"
       >
         <Users class="w-4 h-4" />
       </button>
@@ -42,13 +42,13 @@
       </button>
     </div>
 
-    <p v-if="!clientId" class="mt-1 text-xs text-gray-500">Please select a client first</p>
+    <p v-if="!companyId" class="mt-1 text-xs text-gray-500">Please select a company first</p>
   </div>
 
   <ContactSelectionModal
     :is-open="isModalOpen"
-    :client-id="clientId"
-    :client-name="clientName"
+    :company-id="companyId"
+    :company-name="companyName"
     :contacts="activeContacts"
     :selected-contact="selectedContact"
     :is-loading="isLoading"
@@ -83,8 +83,8 @@ const props = withDefaults(
     label: string
     placeholder?: string
     optional?: boolean
-    clientId: string
-    clientName: string
+    companyId: string
+    companyName: string
     modelValue?: string
     initialContactId?: string
   }>(),
@@ -132,20 +132,20 @@ let loadToken = 0
 
 const handleOpenModal = async () => {
   debugLog('ContactSelector - handleOpenModal called:', {
-    clientId: props.clientId,
-    clientName: props.clientName,
+    companyId: props.companyId,
+    companyName: props.companyName,
     initialContactId: props.initialContactId,
     contacts: contacts.value,
     selectedContact: selectedContact.value,
     newContactForm: newContactForm.value,
   })
 
-  if (!props.clientId) {
-    debugLog('Cannot open contact modal without client')
+  if (!props.companyId) {
+    debugLog('Cannot open contact modal without company')
     return
   }
 
-  await openModal(props.clientId, props.clientName)
+  await openModal(props.companyId, props.companyName)
   debugLog('ContactSelector - after openModal:', {
     isModalOpen: isModalOpen.value,
     contacts: contacts.value,
@@ -237,22 +237,22 @@ const clearSelection = () => {
 
 const selectPrimaryContact = async () => {
   debugLog('ContactSelector - selectPrimaryContact called', {
-    clientId: props.clientId,
+    companyId: props.companyId,
     contactsLength: contacts.value.length,
   })
 
-  if (!props.clientId) {
-    debugLog('Cannot select primary contact without client', {
-      clientId: props.clientId,
-      propsClientId: props.clientId,
+  if (!props.companyId) {
+    debugLog('Cannot select primary contact without company', {
+      companyId: props.companyId,
+      propsCompanyId: props.companyId,
     })
     return
   }
 
   // Load contacts if not already loaded
   if (contacts.value.length === 0) {
-    debugLog('Loading contacts for client:', props.clientId)
-    await loadContactsOnly(props.clientId)
+    debugLog('Loading contacts for company:', props.companyId)
+    await loadContactsOnly(props.companyId)
   }
 
   // Find and select the primary contact (without closing modal)
@@ -307,9 +307,9 @@ watch(
 )
 
 watch(
-  () => [props.clientId, props.initialContactId],
-  async ([clientId, initialId]) => {
-    debugLog('ContactSelector - unified watch:', { clientId, initialId })
+  () => [props.companyId, props.initialContactId],
+  async ([companyId, initialId]) => {
+    debugLog('ContactSelector - unified watch:', { companyId, initialId })
 
     // Quando mudar o cliente: limpe estado local (sem emitir)
     suppressEmit.value = true
@@ -318,8 +318,8 @@ watch(
     contacts.value = []
     suppressEmit.value = false
 
-    if (!clientId) {
-      debugLog('Client ID vazio; nada a carregar.')
+    if (!companyId) {
+      debugLog('Company ID vazio; nada a carregar.')
       return
     }
 
@@ -327,14 +327,14 @@ watch(
     const token = ++loadToken
 
     // Carrega contatos do cliente atual
-    await loadContactsOnly(clientId)
+    await loadContactsOnly(companyId)
     if (token !== loadToken) return // request antigo, ignora
 
     // Selection priority:
     // 1) If initialId provided → select that contact
     // 2) Else if primary contact exists → select primary
     // 3) Else → clear selection
-    // NOTE: suppressEmit=true prevents API calls during initialization/client change
+    // NOTE: suppressEmit=true prevents API calls during initialization/company change
     // (auto-selection should not trigger saves - only user actions should)
     const decideAndSelect = () => {
       const choose =
diff --git a/frontend/src/components/CreateClientModal.vue b/frontend/src/components/CreateCompanyModal.vue
similarity index 66%
rename from frontend/src/components/CreateClientModal.vue
rename to frontend/src/components/CreateCompanyModal.vue
index 49791553c..c528e288b 100644
--- a/frontend/src/components/CreateClientModal.vue
+++ b/frontend/src/components/CreateCompanyModal.vue
@@ -2,12 +2,12 @@
   <Dialog :open="isOpen" @update:open="handleDialogChange">
     <DialogContent class="sm:max-w-md">
       <DialogHeader>
-        <DialogTitle>{{ editMode ? 'Edit Client' : 'Add New Client' }}</DialogTitle>
+        <DialogTitle>{{ editMode ? 'Edit Company' : 'Add New Company' }}</DialogTitle>
         <DialogDescription>
           {{
             editMode
-              ? 'Update client information. All fields except name are optional.'
-              : 'Create a new client. All fields except name are optional.'
+              ? 'Update company information. All fields except name are optional.'
+              : 'Create a new company. All fields except name are optional.'
           }}
         </DialogDescription>
       </DialogHeader>
@@ -18,12 +18,12 @@
             <XCircle class="h-5 w-5 text-red-400" />
           </div>
           <div class="ml-3">
-            <p class="text-sm font-medium text-red-800">Error creating client</p>
+            <p class="text-sm font-medium text-red-800">Error creating company</p>
             <p class="mt-1 text-sm text-red-700">{{ errorMessage }}</p>
-            <div v-if="duplicateClientInfo" class="mt-2 text-xs text-gray-700">
-              Existing client in Xero: <b>{{ duplicateClientInfo.name }}</b>
+            <div v-if="duplicateCompanyInfo" class="mt-2 text-xs text-gray-700">
+              Existing company in Xero: <b>{{ duplicateCompanyInfo.name }}</b>
               <span
-                v-if="duplicateClientInfo.xero_contact_id"
+                v-if="duplicateCompanyInfo.xero_contact_id"
                 class="ml-2 px-2 py-0.5 bg-blue-100 text-blue-800 rounded"
                 >Xero</span
               >
@@ -33,22 +33,22 @@
       </div>
 
       <form
-        v-if="!blockedNoXeroId && !duplicateClientInfo"
+        v-if="!blockedNoXeroId && !duplicateCompanyInfo"
         @submit.prevent="handleSubmit"
         class="space-y-4"
       >
         <div>
-          <label for="clientName" class="block text-sm font-medium text-gray-700 mb-1">
-            Client Name <span class="text-red-500">*</span>
+          <label for="companyName" class="block text-sm font-medium text-gray-700 mb-1">
+            Company Name <span class="text-red-500">*</span>
           </label>
           <input
-            id="clientName"
+            id="companyName"
             v-model="formData.name"
             type="text"
             required
             class="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent"
             :class="{ 'border-red-300': fieldErrors.name }"
-            placeholder="Enter client name"
+            placeholder="Enter company name"
           />
           <p v-if="fieldErrors.name" class="mt-1 text-sm text-red-600">
             {{ fieldErrors.name }}
@@ -56,16 +56,16 @@
         </div>
 
         <div>
-          <label for="clientEmail" class="block text-sm font-medium text-gray-700 mb-1">
+          <label for="companyEmail" class="block text-sm font-medium text-gray-700 mb-1">
             Email
           </label>
           <input
-            id="clientEmail"
+            id="companyEmail"
             v-model="formData.email"
             type="email"
             class="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent"
             :class="{ 'border-red-300': fieldErrors.email }"
-            placeholder="client@example.com"
+            placeholder="company@example.com"
           />
           <p v-if="fieldErrors.email" class="mt-1 text-sm text-red-600">
             {{ fieldErrors.email }}
@@ -73,16 +73,16 @@
         </div>
 
         <div>
-          <label for="clientAddress" class="block text-sm font-medium text-gray-700 mb-1">
+          <label for="companyAddress" class="block text-sm font-medium text-gray-700 mb-1">
             Address
           </label>
           <textarea
-            id="clientAddress"
+            id="companyAddress"
             v-model="formData.address"
             rows="2"
             class="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent"
             :class="{ 'border-red-300': fieldErrors.address }"
-            placeholder="Client address"
+            placeholder="Company address"
           />
           <p v-if="fieldErrors.address" class="mt-1 text-sm text-red-600">
             {{ fieldErrors.address }}
@@ -126,8 +126,8 @@
                   ? 'Updating...'
                   : 'Creating...'
                 : editMode
-                  ? 'Update Client'
-                  : 'Create Client'
+                  ? 'Update Company'
+                  : 'Create Company'
             }}
           </Button>
         </DialogFooter>
@@ -135,11 +135,11 @@
 
       <div v-else class="flex flex-col items-center gap-4 py-6">
         <p class="text-sm text-gray-700" v-if="blockedNoXeroId">
-          The client was created but does not have a Xero ID. This client cannot be used until it is
-          synced with Xero.
+          The company was created but does not have a Xero ID. This company cannot be used until it
+          is synced with Xero.
         </p>
-        <p class="text-sm text-gray-700" v-if="duplicateClientInfo">
-          This client already exists in Xero and cannot be created again.
+        <p class="text-sm text-gray-700" v-if="duplicateCompanyInfo">
+          This company already exists in Xero and cannot be created again.
         </p>
         <div class="flex gap-2">
           <Button type="button" variant="outline" @click="handleAddOther">Add other</Button>
@@ -165,33 +165,33 @@ import {
 import { Button } from '@/components/ui/button'
 import { api } from '@/api/client'
 import { z } from 'zod'
-import type { Client } from '@/composables/useClientLookup'
+import type { Company } from '@/composables/useCompanyLookup'
 import { schemas } from '@/api/generated/api'
 import { isAxiosError } from 'axios'
 import { normalizeOptionalString } from '@/utils/sanitize'
 
 // Use generated types from Zodios API
-type ClientCreateRequestSchema = typeof schemas.ClientCreateRequest
-type ClientUpdateRequest = z.input<typeof schemas.ClientUpdateRequest>
-type ClientCreateInput = z.input<typeof schemas.ClientCreateRequest>
-type ClientUpdateInput = z.input<typeof schemas.ClientUpdateRequest>
-type ClientCreateResponse = z.infer<typeof schemas.ClientCreateResponse>
-type ClientUpdateResponse = z.infer<typeof schemas.ClientUpdateResponse>
-const clientSchema: ClientCreateRequestSchema = schemas.ClientCreateRequest
-type ClientFormPayload = {
-  name: ClientCreateInput['name']
-  email?: ClientUpdateInput['email']
-  address?: ClientUpdateInput['address']
-  is_account_customer: NonNullable<ClientCreateInput['is_account_customer']>
-  allow_jobs: NonNullable<ClientCreateInput['allow_jobs']>
+type CompanyCreateRequestSchema = typeof schemas.CompanyCreateRequest
+type CompanyUpdateRequest = z.input<typeof schemas.CompanyUpdateRequest>
+type CompanyCreateInput = z.input<typeof schemas.CompanyCreateRequest>
+type CompanyUpdateInput = z.input<typeof schemas.CompanyUpdateRequest>
+type CompanyCreateResponse = z.infer<typeof schemas.CompanyCreateResponse>
+type CompanyUpdateResponse = z.infer<typeof schemas.CompanyUpdateResponse>
+const companySchema: CompanyCreateRequestSchema = schemas.CompanyCreateRequest
+type CompanyFormPayload = {
+  name: CompanyCreateInput['name']
+  email?: CompanyUpdateInput['email']
+  address?: CompanyUpdateInput['address']
+  is_account_customer: NonNullable<CompanyCreateInput['is_account_customer']>
+  allow_jobs: NonNullable<CompanyCreateInput['allow_jobs']>
 }
 
 interface Props {
   isOpen: boolean
   initialName?: string
   editMode?: boolean
-  clientId?: string
-  clientData?: {
+  companyId?: string
+  companyData?: {
     name: string
     email: string
     address: string
@@ -203,8 +203,8 @@ interface Props {
 const props = withDefaults(defineProps<Props>(), {
   initialName: '',
   editMode: false,
-  clientId: '',
-  clientData: () => ({
+  companyId: '',
+  companyData: () => ({
     name: '',
     email: '',
     address: '',
@@ -215,10 +215,10 @@ const props = withDefaults(defineProps<Props>(), {
 
 const emit = defineEmits<{
   'update:isOpen': [value: boolean]
-  'client-created': [client: Client]
+  'company-created': [company: Company]
 }>()
 
-const formData = reactive<ClientFormPayload>({
+const formData = reactive<CompanyFormPayload>({
   name: '',
   email: '',
   address: '',
@@ -230,7 +230,7 @@ const isLoading = ref(false)
 const errorMessage = ref('')
 const fieldErrors = ref<Record<string, string>>({})
 const blockedNoXeroId = ref(false)
-const duplicateClientInfo = ref<{ name: string; xero_contact_id: string } | null>(null)
+const duplicateCompanyInfo = ref<{ name: string; xero_contact_id: string } | null>(null)
 
 const isFormValid = computed(() => {
   if (!formData.name.trim()) return false
@@ -256,7 +256,7 @@ const validateForm = (): boolean => {
     const cleanedData = cleanOptionalFields(plainFormData)
     console.log('🧹 Cleaned data for validation:', cleanedData)
 
-    clientSchema.parse(cleanedData)
+    companySchema.parse(cleanedData)
     console.log('✅ Schema validation passed')
     return true
   } catch (error: unknown) {
@@ -291,7 +291,7 @@ const handleSubmit = async () => {
   isLoading.value = true
   errorMessage.value = ''
   blockedNoXeroId.value = false
-  duplicateClientInfo.value = null
+  duplicateCompanyInfo.value = null
 
   try {
     // Convert reactive object to plain object for Zodios
@@ -306,28 +306,28 @@ const handleSubmit = async () => {
 
     // Validate the cleaned data manually first
     try {
-      clientSchema.parse(cleanedData)
+      companySchema.parse(cleanedData)
       console.log('Manual validation passed')
     } catch (validationError) {
       console.log('Manual validation failed:', validationError)
       throw validationError
     }
 
-    if (props.editMode && props.clientId) {
-      // Update existing client
-      const updatePayload: ClientUpdateRequest = { ...cleanedData }
-      const result = await api.clients_update_update(updatePayload, {
-        params: { client_id: props.clientId },
+    if (props.editMode && props.companyId) {
+      // Update existing company
+      const updatePayload: CompanyUpdateRequest = { ...cleanedData }
+      const result = await api.companies_update_update(updatePayload, {
+        params: { company_id: props.companyId },
       })
-      handleClientResponse(result, true)
+      handleCompanyResponse(result, true)
     } else {
-      // Create new client
-      const result = await api.clients_create_create(cleanedData)
-      handleClientResponse(result, false)
+      // Create new company
+      const result = await api.companies_create_create(cleanedData)
+      handleCompanyResponse(result, false)
     }
   } catch (error) {
-    console.error('Error creating client:', error)
-    if (handleDuplicateClientError(error)) {
+    console.error('Error creating company:', error)
+    if (handleDuplicateCompanyError(error)) {
       return
     }
     errorMessage.value = error instanceof Error ? error.message : 'An unexpected error occurred'
@@ -339,14 +339,14 @@ const handleSubmit = async () => {
 const handleAddOther = () => {
   resetForm()
   blockedNoXeroId.value = false
-  duplicateClientInfo.value = null
+  duplicateCompanyInfo.value = null
 }
 
 const handleCancel = () => {
   emit('update:isOpen', false)
 }
 
-const cleanOptionalFields = (data: ClientFormPayload): ClientFormPayload => {
+const cleanOptionalFields = (data: CompanyFormPayload): CompanyFormPayload => {
   return {
     ...data,
     name: data.name.trim(),
@@ -354,66 +354,68 @@ const cleanOptionalFields = (data: ClientFormPayload): ClientFormPayload => {
     address: normalizeOptionalString(data.address),
   }
 }
-const handleClientResponse = (
-  result: ClientCreateResponse | ClientUpdateResponse,
+const handleCompanyResponse = (
+  result: CompanyCreateResponse | CompanyUpdateResponse,
   isEditMode: boolean,
 ) => {
   console.log('?Y"? API response:', result)
 
   if (!result.success) {
-    throw new Error(result.message || `Failed to ${isEditMode ? 'update' : 'create'} client`)
+    throw new Error(result.message || `Failed to ${isEditMode ? 'update' : 'create'} company`)
   }
 
-  if (!result.client) {
-    throw new Error('Missing client in response')
+  if (!result.company) {
+    throw new Error('Missing company in response')
   }
 
-  if (!isEditMode && !result.client.xero_contact_id) {
+  if (!isEditMode && !result.company.xero_contact_id) {
     blockedNoXeroId.value = true
     errorMessage.value =
-      'Client was created but does not have a Xero ID. Please try again or contact support.'
+      'Company was created but does not have a Xero ID. Please try again or contact support.'
     return
   }
 
-  const clientData = normalizeClientResult(result.client)
-  emit('client-created', clientData)
+  const companyData = normalizeCompanyResult(result.company)
+  emit('company-created', companyData)
   emit('update:isOpen', false)
 }
 
-const normalizeClientResult = (
-  clientPayload: ClientCreateResponse['client'] | ClientUpdateResponse['client'],
-): Client => {
-  return schemas.ClientSearchResult.parse({
-    ...clientPayload,
-    email: clientPayload.email ?? '',
-    address: clientPayload.address ?? '',
-    xero_contact_id: clientPayload.xero_contact_id ?? '',
+const normalizeCompanyResult = (
+  companyPayload: CompanyCreateResponse['company'] | CompanyUpdateResponse['company'],
+): Company => {
+  return schemas.CompanySearchResult.parse({
+    ...companyPayload,
+    email: companyPayload.email ?? '',
+    address: companyPayload.address ?? '',
+    xero_contact_id: companyPayload.xero_contact_id ?? '',
   })
 }
 
-const handleDuplicateClientError = (error: unknown): boolean => {
+const handleDuplicateCompanyError = (error: unknown): boolean => {
   if (!isAxiosError(error)) {
     return false
   }
 
   const payload = error.response?.data
-  const parsedDuplicate = schemas.ClientDuplicateErrorResponse.safeParse(payload)
+  const parsedDuplicate = schemas.CompanyDuplicateErrorResponse.safeParse(payload)
 
   if (!parsedDuplicate.success) {
     return false
   }
 
-  const existingClient = parsedDuplicate.data.existing_client as Record<string, unknown> | undefined
+  const existingCompany = parsedDuplicate.data.existing_company as
+    | Record<string, unknown>
+    | undefined
   const nameValue =
-    typeof existingClient?.name === 'string' ? existingClient.name : 'Existing client'
+    typeof existingCompany?.name === 'string' ? existingCompany.name : 'Existing company'
   const xeroIdValue =
-    typeof existingClient?.xero_contact_id === 'string' ? existingClient.xero_contact_id : ''
+    typeof existingCompany?.xero_contact_id === 'string' ? existingCompany.xero_contact_id : ''
 
-  duplicateClientInfo.value = {
+  duplicateCompanyInfo.value = {
     name: nameValue,
     xero_contact_id: xeroIdValue,
   }
-  errorMessage.value = parsedDuplicate.data.error || 'Client already exists in Xero.'
+  errorMessage.value = parsedDuplicate.data.error || 'Company already exists in Xero.'
 
   return true
 }
@@ -442,7 +444,7 @@ watch(
     console.log('👁️ Modal isOpen changed:', isOpen)
     console.log('🏷️ props.initialName:', props.initialName)
     console.log('🔧 props.editMode:', props.editMode)
-    console.log('📋 props.clientData:', props.clientData)
+    console.log('📋 props.companyData:', props.companyData)
 
     if (isOpen) {
       console.log('🔄 Resetting form...')
@@ -450,15 +452,15 @@ watch(
       resetForm()
       console.log('📋 Form after reset:', formData)
 
-      if (props.editMode && props.clientData) {
-        // Pre-populate with existing client data
-        console.log('✏️ Edit mode: Pre-populating with client data')
+      if (props.editMode && props.companyData) {
+        // Pre-populate with existing company data
+        console.log('✏️ Edit mode: Pre-populating with company data')
         Object.assign(formData, {
-          name: props.clientData.name,
-          email: props.clientData.email,
-          address: props.clientData.address,
-          is_account_customer: props.clientData.is_account_customer,
-          allow_jobs: props.clientData.allow_jobs,
+          name: props.companyData.name,
+          email: props.companyData.email,
+          address: props.companyData.address,
+          is_account_customer: props.companyData.is_account_customer,
+          allow_jobs: props.companyData.allow_jobs,
         })
         console.log('📋 Form after pre-population:', formData)
       } else if (props.initialName) {
diff --git a/frontend/src/components/JobCard.vue b/frontend/src/components/JobCard.vue
index 132914183..487c930d2 100644
--- a/frontend/src/components/JobCard.vue
+++ b/frontend/src/components/JobCard.vue
@@ -152,7 +152,7 @@
 
     <!-- Customer name elevated to title -->
     <h4 class="font-semibold text-gray-900 text-[0.98rem] mb-1 leading-tight">
-      {{ job.client_name }}
+      {{ job.company_name }}
     </h4>
 
     <!-- Description (kept line-clamp-2 to avoid tall cards in columns) -->
@@ -164,7 +164,7 @@
       {{ descriptionOrName }}
     </p>
 
-    <!-- Contact only (client line removed by request) -->
+    <!-- Contact only (company line removed by request) -->
     <div v-if="job.contact_person" class="text-[0.8rem] text-gray-600 truncate font-medium">
       <span class="font-semibold">Contact:</span> {{ job.contact_person }}
     </div>
diff --git a/frontend/src/components/KanbanColumn.vue b/frontend/src/components/KanbanColumn.vue
index 05ca191f9..c8f83e268 100644
--- a/frontend/src/components/KanbanColumn.vue
+++ b/frontend/src/components/KanbanColumn.vue
@@ -113,7 +113,7 @@
           <h4 class="font-medium text-gray-700 text-sm mb-1">{{ job.name }}</h4>
           <p class="text-xs text-gray-500 mb-2">{{ job.description }}</p>
           <div class="text-xs text-gray-400">
-            <p>{{ job.client_name }}</p>
+            <p>{{ job.company_name }}</p>
             <p>{{ job.contact_person }}</p>
           </div>
         </div>
diff --git a/frontend/src/components/SectionForm.vue b/frontend/src/components/SectionForm.vue
index 4aaee9df9..98adb3808 100644
--- a/frontend/src/components/SectionForm.vue
+++ b/frontend/src/components/SectionForm.vue
@@ -87,15 +87,15 @@
         </div>
 
         <select
-          v-else-if="field.type === 'client'"
+          v-else-if="field.type === 'company'"
           v-model="localForm[field.key] as string"
           class="h-9 text-sm rounded-md border border-input bg-background px-3 py-1"
           :class="{ 'bg-gray-100 cursor-not-allowed': field.readOnly }"
           :data-automation-id="`SectionForm-${section}-field-${field.key}`"
-          :disabled="field.readOnly || clientOptionsLoading"
+          :disabled="field.readOnly || companyOptionsLoading"
         >
-          <option v-for="client in clientOptions" :key="client.id" :value="client.id">
-            {{ client.name }}
+          <option v-for="company in companyOptions" :key="company.id" :value="company.id">
+            {{ company.name }}
           </option>
         </select>
 
@@ -184,7 +184,7 @@ import {
 import { uploadLogo, deleteLogo } from '@/services/admin-company-defaults-service'
 import { toast } from 'vue-sonner'
 
-type ClientOption = z.infer<typeof schemas.ClientNameOnly>
+type CompanyOption = z.infer<typeof schemas.CompanyNameOnly>
 
 const props = defineProps<{ section: string; modelValue: Record<string, unknown> }>()
 const emit = defineEmits<{ (e: 'update:modelValue', value: Record<string, unknown>): void }>()
@@ -216,8 +216,8 @@ const FIELD_COL_SPAN_OVERRIDES: Record<string, 2> = {
 }
 
 const logoErrors = ref<Record<string, string>>({})
-const clientOptions = ref<ClientOption[]>([])
-const clientOptionsLoading = ref(false)
+const companyOptions = ref<CompanyOption[]>([])
+const companyOptionsLoading = ref(false)
 
 const LOGO_ASPECT_RULES: Record<
   string,
@@ -463,30 +463,30 @@ const sectionFields = computed(() =>
 )
 const isWorkingHours = computed(() => getSpecialHandler(props.section) === 'working_hours')
 
-async function loadClientOptions() {
-  clientOptionsLoading.value = true
+async function loadCompanyOptions() {
+  companyOptionsLoading.value = true
   try {
-    clientOptions.value = await api.clients_all_list()
+    companyOptions.value = await api.companies_all_list()
   } catch (e) {
-    console.error('Client options load failed:', e)
-    toast.error('Failed to load clients')
+    console.error('Company options load failed:', e)
+    toast.error('Failed to load companies')
   } finally {
-    clientOptionsLoading.value = false
+    companyOptionsLoading.value = false
   }
 }
 
 watch(
   sectionFields,
   (fields) => {
-    if (!fields.some((field) => field.type === 'client')) {
+    if (!fields.some((field) => field.type === 'company')) {
       return
     }
 
-    if (clientOptions.value.length > 0) {
+    if (companyOptions.value.length > 0) {
       return
     }
 
-    void loadClientOptions()
+    void loadCompanyOptions()
   },
   { immediate: true },
 )
diff --git a/frontend/src/components/__tests__/ClientLookup.test.ts b/frontend/src/components/__tests__/CompanyLookup.test.ts
similarity index 54%
rename from frontend/src/components/__tests__/ClientLookup.test.ts
rename to frontend/src/components/__tests__/CompanyLookup.test.ts
index 35f2675e4..4163fd925 100644
--- a/frontend/src/components/__tests__/ClientLookup.test.ts
+++ b/frontend/src/components/__tests__/CompanyLookup.test.ts
@@ -2,45 +2,45 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { ref } from 'vue'
 import { mount } from '@vue/test-utils'
 
-vi.mock('@/composables/useClientLookup', () => ({
-  useClientLookup: vi.fn(),
+vi.mock('@/composables/useCompanyLookup', () => ({
+  useCompanyLookup: vi.fn(),
 }))
 
 vi.mock('@/api/client', () => ({
-  api: { clients_create_create: vi.fn() },
+  api: { companies_create_create: vi.fn() },
 }))
 
-vi.mock('@/components/CreateClientModal.vue', () => ({
+vi.mock('@/components/CreateCompanyModal.vue', () => ({
   default: { template: '<div />' },
 }))
 
-import ClientLookup from '../ClientLookup.vue'
-import { useClientLookup, type Client } from '@/composables/useClientLookup'
+import CompanyLookup from '../CompanyLookup.vue'
+import { useCompanyLookup, type Company } from '@/composables/useCompanyLookup'
 
-function buildComposableStub(suggestions: Client[]) {
+function buildComposableStub(suggestions: Company[]) {
   return {
     searchQuery: ref('msm'),
     suggestions: ref(suggestions),
     isLoading: ref(false),
     showSuggestions: ref(true),
-    selectedClient: ref(null),
+    selectedCompany: ref(null),
     contacts: ref([]),
     hasValidXeroId: ref(false),
     displayValue: ref(''),
-    searchClients: vi.fn(),
-    selectClient: vi.fn(),
+    searchCompanies: vi.fn(),
+    selectCompany: vi.fn(),
     loadClientContacts: vi.fn(),
     getPrimaryContact: vi.fn(),
     clearSelection: vi.fn(),
     handleInputChange: vi.fn(),
-    createNewClient: vi.fn(),
+    createNewCompany: vi.fn(),
     hideSuggestions: vi.fn(),
     resetToInitialState: vi.fn(),
-    preserveSelectedClient: vi.fn(),
-  } as unknown as ReturnType<typeof useClientLookup>
+    preserveSelectedCompany: vi.fn(),
+  } as unknown as ReturnType<typeof useCompanyLookup>
 }
 
-const sampleClient: Client = {
+const sampleCompany: Company = {
   id: 'c1',
   name: 'MSM (Shop)',
   email: 'lakeland@gmail.com',
@@ -53,14 +53,14 @@ const sampleClient: Client = {
   total_spend: '0',
 }
 
-describe('ClientLookup option rendering', () => {
+describe('CompanyLookup option rendering', () => {
   beforeEach(() => {
-    vi.mocked(useClientLookup).mockReturnValue(buildComposableStub([sampleClient]))
+    vi.mocked(useCompanyLookup).mockReturnValue(buildComposableStub([sampleCompany]))
   })
 
-  it('renders the client name as the only text inside role="option"', () => {
-    const wrapper = mount(ClientLookup, {
-      props: { id: 'lookup', label: 'Client' },
+  it('renders the company name as the only text inside role="option"', () => {
+    const wrapper = mount(CompanyLookup, {
+      props: { id: 'lookup', label: 'Company' },
     })
 
     const option = wrapper.find('[role="option"]')
diff --git a/frontend/src/components/__tests__/SectionForm.test.ts b/frontend/src/components/__tests__/SectionForm.test.ts
index 03639803d..3f18dc173 100644
--- a/frontend/src/components/__tests__/SectionForm.test.ts
+++ b/frontend/src/components/__tests__/SectionForm.test.ts
@@ -3,13 +3,13 @@ import { describe, expect, it, vi } from 'vitest'
 
 import SectionForm from '@/components/SectionForm.vue'
 
-const { clientsAllList } = vi.hoisted(() => ({
-  clientsAllList: vi.fn(),
+const { companiesAllList } = vi.hoisted(() => ({
+  companiesAllList: vi.fn(),
 }))
 
 vi.mock('@/api/client', () => ({
   api: {
-    clients_all_list: clientsAllList,
+    companies_all_list: companiesAllList,
   },
 }))
 
@@ -17,11 +17,11 @@ vi.mock('@/composables/useSettingsSchema', () => ({
   useSettingsSchema: () => ({
     getFieldsForSection: () => [
       {
-        key: 'shop_client',
-        label: 'Shop Client',
-        type: 'client',
+        key: 'shop_company',
+        label: 'Shop Company',
+        type: 'company',
         required: true,
-        help_text: 'Internal client used for tracking shop work.',
+        help_text: 'Internal company used for tracking shop work.',
         section: 'setup',
         icon: 'span',
         readOnly: false,
@@ -34,8 +34,8 @@ vi.mock('@/composables/useSettingsSchema', () => ({
 }))
 
 describe('SectionForm', () => {
-  it('renders client fields as a selector backed by generated client data', async () => {
-    clientsAllList.mockResolvedValue([
+  it('renders company fields as a selector backed by generated company data', async () => {
+    companiesAllList.mockResolvedValue([
       { id: '00000000-0000-0000-0000-000000000001', name: 'Demo Company Shop' },
       { id: '11111111-1111-1111-1111-111111111111', name: 'Acme Ltd' },
     ])
@@ -44,14 +44,14 @@ describe('SectionForm', () => {
       props: {
         section: 'setup',
         modelValue: {
-          shop_client: '00000000-0000-0000-0000-000000000001',
+          shop_company: '00000000-0000-0000-0000-000000000001',
         },
       },
     })
 
     await flushPromises()
 
-    const selector = wrapper.get('[data-automation-id="SectionForm-setup-field-shop_client"]')
+    const selector = wrapper.get('[data-automation-id="SectionForm-setup-field-shop_company"]')
     expect(selector.element.tagName).toBe('SELECT')
     expect(selector.text()).toContain('Demo Company Shop')
     expect(selector.text()).toContain('Acme Ltd')
@@ -61,19 +61,19 @@ describe('SectionForm', () => {
     const updates = wrapper.emitted('update:modelValue')
     expect(updates?.at(-1)).toEqual([
       {
-        shop_client: '11111111-1111-1111-1111-111111111111',
+        shop_company: '11111111-1111-1111-1111-111111111111',
       },
     ])
   })
 
   it('does not mutate the object passed as modelValue when a field is edited', async () => {
-    clientsAllList.mockResolvedValue([
+    companiesAllList.mockResolvedValue([
       { id: '00000000-0000-0000-0000-000000000001', name: 'Demo Company Shop' },
       { id: '11111111-1111-1111-1111-111111111111', name: 'Acme Ltd' },
     ])
 
     const modelValue = {
-      shop_client: '00000000-0000-0000-0000-000000000001',
+      shop_company: '00000000-0000-0000-0000-000000000001',
     }
 
     const wrapper = mount(SectionForm, {
@@ -85,10 +85,10 @@ describe('SectionForm', () => {
 
     await flushPromises()
 
-    const selector = wrapper.get('[data-automation-id="SectionForm-setup-field-shop_client"]')
+    const selector = wrapper.get('[data-automation-id="SectionForm-setup-field-shop_company"]')
     await selector.setValue('11111111-1111-1111-1111-111111111111')
 
     // The edit must be emitted, never applied in place to the prop object.
-    expect(modelValue.shop_client).toBe('00000000-0000-0000-0000-000000000001')
+    expect(modelValue.shop_company).toBe('00000000-0000-0000-0000-000000000001')
   })
 })
diff --git a/frontend/src/components/board/ActiveJobCard.vue b/frontend/src/components/board/ActiveJobCard.vue
index 2774b8162..eeec99276 100644
--- a/frontend/src/components/board/ActiveJobCard.vue
+++ b/frontend/src/components/board/ActiveJobCard.vue
@@ -59,7 +59,7 @@ const getJobDescription = (job: WorkshopJob) => {
         <div class="text-xl text-black font-semibold flex items-center gap-2">
           <Briefcase class="h-5 w-5 text-gray-500 flex-shrink-0" />
           <span>Customer:</span>
-          <span class="text-gray-600 font-medium">{{ job.client_name }}</span>
+          <span class="text-gray-600 font-medium">{{ job.company_name }}</span>
         </div>
 
         <div class="text-xl text-black font-semibold flex items-start gap-2">
diff --git a/frontend/src/components/board/WorkshopModeView.vue b/frontend/src/components/board/WorkshopModeView.vue
index 08d292d0a..a74235101 100644
--- a/frontend/src/components/board/WorkshopModeView.vue
+++ b/frontend/src/components/board/WorkshopModeView.vue
@@ -43,7 +43,7 @@ const filteredJobs = computed(() => {
   return jobs.value.filter(
     (job) =>
       job.name.toLowerCase().includes(search) ||
-      job.client_name.toLowerCase().includes(search) ||
+      job.company_name.toLowerCase().includes(search) ||
       String(job.job_number).includes(search),
   )
 })
@@ -149,7 +149,7 @@ watch(jobs, (newJobs) => {
         <div class="mx-auto flex h-full w-full max-w-4xl flex-col min-h-0">
           <DrawerHeader>
             <DrawerTitle class="text-xl font-semibold">Select a job</DrawerTitle>
-            <DrawerDescription>Search by job number, name, or client</DrawerDescription>
+            <DrawerDescription>Search by job number, name, or company</DrawerDescription>
           </DrawerHeader>
           <div class="flex-1 overflow-y-auto px-4 pb-4 space-y-3">
             <input
@@ -164,7 +164,7 @@ watch(jobs, (newJobs) => {
                   <tr>
                     <th class="text-left px-3 py-2 font-semibold">Job #</th>
                     <th class="text-left px-3 py-2 font-semibold">Name</th>
-                    <th class="text-left px-3 py-2 font-semibold">Client</th>
+                    <th class="text-left px-3 py-2 font-semibold">Company</th>
                     <th class="text-left px-3 py-2 font-semibold">Action</th>
                   </tr>
                 </thead>
@@ -172,7 +172,7 @@ watch(jobs, (newJobs) => {
                   <tr v-for="job in filteredJobs" :key="job.id" class="border-t hover:bg-muted/50">
                     <td class="px-3 py-2 whitespace-nowrap">#{{ job.job_number }}</td>
                     <td class="px-3 py-2">{{ job.name }}</td>
-                    <td class="px-3 py-2">{{ job.client_name || '-' }}</td>
+                    <td class="px-3 py-2">{{ job.company_name || '-' }}</td>
                     <td class="px-3 py-2">
                       <Button size="sm" class="h-8 px-3" @click="handleJobSelect(job.id)">
                         Select
diff --git a/frontend/src/components/crm/PhoneCallTable.vue b/frontend/src/components/crm/PhoneCallTable.vue
index edeb55f48..79aed3462 100644
--- a/frontend/src/components/crm/PhoneCallTable.vue
+++ b/frontend/src/components/crm/PhoneCallTable.vue
@@ -4,7 +4,7 @@
       <thead class="bg-slate-50 border-b">
         <tr>
           <th class="p-3 text-left font-semibold text-gray-700">Date & Time</th>
-          <th class="p-3 text-left font-semibold text-gray-700">Number / Client</th>
+          <th class="p-3 text-left font-semibold text-gray-700">Number / Company</th>
           <th class="p-3 text-left font-semibold text-gray-700">Our Number</th>
           <th class="p-3 text-left font-semibold text-gray-700">Direction</th>
           <th class="p-3 text-left font-semibold text-gray-700">Duration</th>
@@ -22,12 +22,12 @@
           </td>
           <td class="p-3">
             <div class="font-medium text-gray-900">
-              {{ call.client_name || call.external_number || '-' }}
+              {{ call.company_name || call.external_number || '-' }}
             </div>
             <div class="flex flex-wrap items-center gap-2 text-xs text-gray-500">
               <span>{{ call.contact_name || call.external_number || '-' }}</span>
               <Button
-                v-if="allowNumberAssignment && !call.client && call.external_number"
+                v-if="allowNumberAssignment && !call.company && call.external_number"
                 variant="ghost"
                 size="sm"
                 class="h-6 px-2 text-xs"
@@ -73,7 +73,7 @@
               <div class="basis-full text-xs text-gray-500">{{ call.job_name }}</div>
             </div>
             <Button
-              v-else-if="allowJobLinking && call.client"
+              v-else-if="allowJobLinking && call.company"
               :data-automation-id="`PhoneCallTable-link-job-${call.id}`"
               variant="outline"
               size="sm"
@@ -82,7 +82,7 @@
             >
               Link job
             </Button>
-            <span v-else class="text-xs text-gray-500">Assign client first</span>
+            <span v-else class="text-xs text-gray-500">Assign company first</span>
           </td>
           <td class="p-3 min-w-64">
             <audio
@@ -122,7 +122,7 @@
           </select>
           <div v-if="isLoadingJobs" class="text-sm text-gray-500">Loading jobs...</div>
           <div v-else-if="filteredJobs.length === 0" class="text-sm text-gray-500">
-            No jobs found for this client
+            No jobs found for this company
           </div>
         </div>
         <DialogFooter>
@@ -160,7 +160,7 @@ import { formatDateTime } from '@/utils/string-formatting'
 import type { z } from 'zod'
 
 type PhoneCallRecord = z.infer<typeof schemas.PhoneCallRecord>
-type ClientJobHeader = z.infer<typeof schemas.ClientJobHeader>
+type CompanyJobHeader = z.infer<typeof schemas.CompanyJobHeader>
 
 withDefaults(
   defineProps<{
@@ -184,14 +184,14 @@ const isDialogOpen = ref(false)
 const selectedCall = ref<PhoneCallRecord | null>(null)
 const selectedJobId = ref('')
 const jobSearch = ref('')
-const clientJobs = ref<ClientJobHeader[]>([])
+const companyJobs = ref<CompanyJobHeader[]>([])
 const isLoadingJobs = ref(false)
 const savingCallId = ref<string | null>(null)
 
 const filteredJobs = computed(() => {
   const search = jobSearch.value.trim().toLowerCase()
-  if (!search) return clientJobs.value
-  return clientJobs.value.filter((job) => {
+  if (!search) return companyJobs.value
+  return companyJobs.value.filter((job) => {
     return (
       job.name.toLowerCase().includes(search) ||
       String(job.job_number).includes(search) ||
@@ -201,8 +201,8 @@ const filteredJobs = computed(() => {
 })
 
 async function openJobDialog(call: PhoneCallRecord): Promise<void> {
-  if (!call.client) {
-    toast.error('Assign the call to a client before linking a job')
+  if (!call.company) {
+    toast.error('Assign the call to a company before linking a job')
     return
   }
   selectedCall.value = call
@@ -211,14 +211,14 @@ async function openJobDialog(call: PhoneCallRecord): Promise<void> {
   isDialogOpen.value = true
   isLoadingJobs.value = true
   try {
-    const response = await api.clients_jobs_retrieve({
-      params: { client_id: call.client },
+    const response = await api.companies_jobs_retrieve({
+      params: { company_id: call.company },
     })
-    clientJobs.value = response.results
+    companyJobs.value = response.results
   } catch (error) {
-    toast.error('Failed to load client jobs')
-    console.error('Failed to load client jobs:', error)
-    clientJobs.value = []
+    toast.error('Failed to load company jobs')
+    console.error('Failed to load company jobs:', error)
+    companyJobs.value = []
   } finally {
     isLoadingJobs.value = false
   }
@@ -229,7 +229,7 @@ function closeJobDialog(): void {
   selectedCall.value = null
   selectedJobId.value = ''
   jobSearch.value = ''
-  clientJobs.value = []
+  companyJobs.value = []
 }
 
 function handleDialogOpenChange(open: boolean): void {
diff --git a/frontend/src/components/crm/PhoneNumberManager.vue b/frontend/src/components/crm/PhoneNumberManager.vue
index 031d26cae..a17cad3e1 100644
--- a/frontend/src/components/crm/PhoneNumberManager.vue
+++ b/frontend/src/components/crm/PhoneNumberManager.vue
@@ -9,18 +9,18 @@
     <CardContent class="space-y-4">
       <div class="grid grid-cols-1 gap-3 xl:grid-cols-[1fr_1fr_1fr_auto_auto]">
         <Input v-model="phoneNumber" placeholder="+6490000000" />
-        <div v-if="!fixedClientId" class="flex gap-2">
+        <div v-if="!fixedCompanyId" class="flex gap-2">
           <Input
-            v-model="clientSearch"
-            placeholder="Search clients"
-            @keydown.enter.prevent="searchClients"
+            v-model="companySearch"
+            placeholder="Search companies"
+            @keydown.enter.prevent="searchCompanies"
           />
-          <Button variant="outline" type="button" @click="searchClients">
+          <Button variant="outline" type="button" @click="searchCompanies">
             <Search class="h-4 w-4" />
           </Button>
         </div>
         <div v-else class="rounded-md border border-gray-200 bg-gray-50 px-3 py-2 text-sm">
-          {{ fixedClientName || 'This client' }}
+          {{ fixedCompanyName || 'This company' }}
         </div>
         <Input v-model="phoneLabel" placeholder="Label" />
         <label class="flex items-center gap-2 rounded-md border border-gray-300 px-3 py-2 text-sm">
@@ -30,7 +30,7 @@
         <div class="flex gap-2">
           <Button
             type="button"
-            :disabled="isSaving || !phoneNumber.trim() || !selectedClientId"
+            :disabled="isSaving || !phoneNumber.trim() || !selectedCompanyId"
             @click="savePhoneMethod"
           >
             {{ editingMethodId ? 'Update' : 'Add' }}
@@ -43,20 +43,20 @@
 
       <div class="grid grid-cols-1 gap-3 md:grid-cols-2">
         <select
-          v-if="!fixedClientId"
-          v-model="selectedClientId"
+          v-if="!fixedCompanyId"
+          v-model="selectedCompanyId"
           class="rounded-md border border-gray-300 p-2 text-sm"
-          @change="logSelectedClientSearchClick"
+          @change="logSelectedCompanySearchClick"
         >
-          <option value="">Select client</option>
-          <option v-for="client in clientOptions" :key="client.id" :value="client.id">
-            {{ client.name }}
+          <option value="">Select company</option>
+          <option v-for="company in companyOptions" :key="company.id" :value="company.id">
+            {{ company.name }}
           </option>
         </select>
         <select
           v-model="selectedContactId"
           class="rounded-md border border-gray-300 p-2 text-sm"
-          :disabled="!selectedClientId"
+          :disabled="!selectedCompanyId"
         >
           <option value="">No specific contact</option>
           <option v-for="contact in contactOptions" :key="contact.id" :value="contact.id">
@@ -70,7 +70,7 @@
           <thead class="border-b bg-slate-50">
             <tr>
               <th class="p-3 text-left font-semibold text-gray-700">Phone Number</th>
-              <th class="p-3 text-left font-semibold text-gray-700">Client</th>
+              <th class="p-3 text-left font-semibold text-gray-700">Company</th>
               <th class="p-3 text-left font-semibold text-gray-700">Contact</th>
               <th class="p-3 text-left font-semibold text-gray-700">Label</th>
               <th class="p-3 text-left font-semibold text-gray-700">Primary</th>
@@ -83,7 +83,7 @@
             </tr>
             <tr v-for="method in phoneMethods" :key="method.id" class="border-b last:border-b-0">
               <td class="p-3 font-medium text-gray-900">{{ method.value }}</td>
-              <td class="p-3 text-gray-700">{{ method.client_name }}</td>
+              <td class="p-3 text-gray-700">{{ method.company_name }}</td>
               <td class="p-3 text-gray-700">{{ method.contact_name || '-' }}</td>
               <td class="p-3 text-gray-700">{{ method.label || '-' }}</td>
               <td class="p-3 text-gray-700">{{ method.is_primary ? 'Yes' : '-' }}</td>
@@ -116,7 +116,7 @@ import { Search } from 'lucide-vue-next'
 import { toast } from 'vue-sonner'
 import { api } from '@/api/client'
 import { schemas } from '@/api/generated/api'
-import { useClientLookup } from '@/composables/useClientLookup'
+import { useCompanyLookup } from '@/composables/useCompanyLookup'
 import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
@@ -130,15 +130,15 @@ type PatchedClientContactMethodRequest = z.infer<typeof schemas.PatchedClientCon
 const props = withDefaults(
   defineProps<{
     title?: string
-    fixedClientId?: string
-    fixedClientName?: string
+    fixedCompanyId?: string
+    fixedCompanyName?: string
     initialPhoneNumber?: string
     searchContext?: string
   }>(),
   {
     title: 'Phone Numbers',
-    fixedClientId: '',
-    fixedClientName: '',
+    fixedCompanyId: '',
+    fixedCompanyName: '',
     initialPhoneNumber: '',
     searchContext: 'crm_phone_numbers',
   },
@@ -155,40 +155,40 @@ const isSaving = ref(false)
 const phoneNumber = ref(props.initialPhoneNumber)
 const phoneLabel = ref('')
 const isPrimary = ref(false)
-const selectedClientId = ref(props.fixedClientId)
+const selectedCompanyId = ref(props.fixedCompanyId)
 const selectedContactId = ref('')
 
 const {
-  searchQuery: clientSearch,
-  suggestions: clientOptions,
+  searchQuery: companySearch,
+  suggestions: companyOptions,
   contacts: contactOptions,
-  browseClients,
+  browseCompanies,
   loadClientContacts: loadContacts,
-  logSelectedClientClick,
-} = useClientLookup()
+  logSelectedCompanyClick,
+} = useCompanyLookup()
 
 async function loadPhoneMethods(): Promise<void> {
-  const queries = props.fixedClientId
-    ? { method_type: 'phone', client_id: props.fixedClientId, page: 1, page_size: 50 }
+  const queries = props.fixedCompanyId
+    ? { method_type: 'phone', company_id: props.fixedCompanyId, page: 1, page_size: 50 }
     : { method_type: 'phone', page: 1, page_size: 50 }
-  const response = await api.clients_contact_methods_list({ queries })
+  const response = await api.companies_contact_methods_list({ queries })
   phoneMethods.value = response.results
   phoneMethodCount.value = response.count
 }
 
-async function searchClients(): Promise<void> {
-  if (props.fixedClientId) return
-  await browseClients()
+async function searchCompanies(): Promise<void> {
+  if (props.fixedCompanyId) return
+  await browseCompanies()
 }
 
-function logSelectedClientSearchClick(): void {
-  logSelectedClientClick(selectedClientId.value, props.searchContext)
+function logSelectedCompanySearchClick(): void {
+  logSelectedCompanyClick(selectedCompanyId.value, props.searchContext)
 }
 
 function phoneMethodBody(): ClientContactMethodRequest {
   if (selectedContactId.value) {
     return {
-      client: null,
+      company: null,
       contact: selectedContactId.value,
       method_type: 'phone',
       value: phoneNumber.value,
@@ -198,7 +198,7 @@ function phoneMethodBody(): ClientContactMethodRequest {
     }
   }
   return {
-    client: selectedClientId.value,
+    company: selectedCompanyId.value,
     contact: null,
     method_type: 'phone',
     value: phoneNumber.value,
@@ -209,17 +209,17 @@ function phoneMethodBody(): ClientContactMethodRequest {
 }
 
 async function savePhoneMethod(): Promise<void> {
-  if (!selectedClientId.value || isSaving.value) return
+  if (!selectedCompanyId.value || isSaving.value) return
   isSaving.value = true
   try {
     if (editingMethodId.value) {
       const body: PatchedClientContactMethodRequest = phoneMethodBody()
-      await api.clients_contact_methods_partial_update(body, {
+      await api.companies_contact_methods_partial_update(body, {
         params: { id: editingMethodId.value },
       })
       toast.success('Phone number updated')
     } else {
-      await api.clients_contact_methods_create(phoneMethodBody())
+      await api.companies_contact_methods_create(phoneMethodBody())
       toast.success('Phone number added')
     }
     resetForm()
@@ -239,15 +239,15 @@ async function editMethod(method: ClientContactMethod): Promise<void> {
   phoneNumber.value = method.value
   phoneLabel.value = method.label || ''
   isPrimary.value = Boolean(method.is_primary)
-  selectedClientId.value = method.owner_client
+  selectedCompanyId.value = method.owner_company
   selectedContactId.value = method.contact || ''
-  await loadContacts(method.owner_client)
+  await loadContacts(method.owner_company)
 }
 
 async function deleteMethod(method: ClientContactMethod): Promise<void> {
   if (!window.confirm(`Remove phone number ${method.value}?`)) return
   try {
-    await api.clients_contact_methods_destroy(undefined, { params: { id: method.id } })
+    await api.companies_contact_methods_destroy(undefined, { params: { id: method.id } })
     toast.success('Phone number removed')
     if (editingMethodId.value === method.id) resetForm()
     await loadPhoneMethods()
@@ -264,11 +264,11 @@ function resetForm(): void {
   phoneNumber.value = props.initialPhoneNumber
   phoneLabel.value = ''
   isPrimary.value = false
-  selectedClientId.value = props.fixedClientId
+  selectedCompanyId.value = props.fixedCompanyId
   selectedContactId.value = ''
-  if (!props.fixedClientId) {
-    clientSearch.value = ''
-    clientOptions.value = []
+  if (!props.fixedCompanyId) {
+    companySearch.value = ''
+    companyOptions.value = []
   }
 }
 
@@ -280,10 +280,10 @@ watch(
 )
 
 watch(
-  () => props.fixedClientId,
-  (clientId) => {
-    selectedClientId.value = clientId
-    void loadContacts(clientId)
+  () => props.fixedCompanyId,
+  (companyId) => {
+    selectedCompanyId.value = companyId
+    void loadContacts(companyId)
     void loadPhoneMethods().catch((error) => {
       console.error('Failed to reload phone numbers:', error)
       toast.error('Failed to load phone numbers')
@@ -291,15 +291,15 @@ watch(
   },
 )
 
-watch(selectedClientId, (clientId) => {
-  if (!clientId) {
+watch(selectedCompanyId, (companyId) => {
+  if (!companyId) {
     selectedContactId.value = ''
   }
-  void loadContacts(clientId)
+  void loadContacts(companyId)
 })
 
 onMounted(() => {
-  void loadContacts(selectedClientId.value)
+  void loadContacts(selectedCompanyId.value)
   void loadPhoneMethods().catch((error) => {
     console.error('Failed to load phone numbers:', error)
     toast.error('Failed to load phone numbers')
diff --git a/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts b/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
index d6e29541b..00b476c81 100644
--- a/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
+++ b/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 vi.mock('@/api/client', () => ({
   api: {
-    clients_jobs_retrieve: vi.fn(),
+    companies_jobs_retrieve: vi.fn(),
     linkPhoneCallJob: vi.fn(),
     unlinkPhoneCallJob: vi.fn(),
   },
@@ -22,8 +22,8 @@ function callWithRecording() {
   return {
     id: '11111111-1111-4111-8111-111111111111',
     call_datetime: '2026-06-02T03:13:01Z',
-    client: null,
-    client_name: '',
+    company: null,
+    company_name: '',
     contact_name: '',
     external_number: '+64272255846',
     our_number: '+6496365131',
diff --git a/frontend/src/components/job/JobAttachmentsTab.vue b/frontend/src/components/job/JobAttachmentsTab.vue
index e569ef791..f09a0a0a9 100644
--- a/frontend/src/components/job/JobAttachmentsTab.vue
+++ b/frontend/src/components/job/JobAttachmentsTab.vue
@@ -282,7 +282,7 @@ type JobFile = z.infer<typeof schemas.JobFile> & {
 type UploadStatus = 'preparing' | 'uploading' | 'saving' | 'failed'
 
 type AttachmentRow = JobFile & {
-  clientUploadId?: string
+  companyUploadId?: string
   uploadStatus?: UploadStatus
   uploadProgress?: number
   uploadError?: string
@@ -524,14 +524,14 @@ const compressImage = (
   })
 }
 
-const createClientUploadId = (): string => {
+const createCompanyUploadId = (): string => {
   return globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`
 }
 
 const addPendingUpload = (file: File): AttachmentRow => {
-  const clientUploadId = createClientUploadId()
+  const companyUploadId = createCompanyUploadId()
   const pendingUpload: AttachmentRow = {
-    id: `pending-${clientUploadId}`,
+    id: `pending-${companyUploadId}`,
     filename: file.name,
     mime_type: file.type || undefined,
     uploaded_at: new Date().toISOString(),
@@ -540,7 +540,7 @@ const addPendingUpload = (file: File): AttachmentRow => {
     size: file.size,
     download_url: '',
     thumbnail_url: null,
-    clientUploadId,
+    companyUploadId,
     uploadStatus: 'uploading',
     uploadProgress: 0,
     sourceFile: file,
diff --git a/frontend/src/components/job/JobQuotingChatTab.vue b/frontend/src/components/job/JobQuotingChatTab.vue
index dc98ca3da..3005a51a1 100644
--- a/frontend/src/components/job/JobQuotingChatTab.vue
+++ b/frontend/src/components/job/JobQuotingChatTab.vue
@@ -151,7 +151,7 @@ interface Props {
   jobId: string
   jobName?: string
   jobNumber?: string
-  clientName?: string
+  companyName?: string
 }
 
 const props = defineProps<Props>()
diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index b7c83d459..440980ea6 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -74,40 +74,40 @@
           </CardContent>
         </Card>
 
-        <!-- Client Information Card -->
+        <!-- Company Information Card -->
         <Card class="lg:col-span-1">
           <CardHeader>
-            <CardTitle>Client Information</CardTitle>
-            <CardDescription>Client details and contact information</CardDescription>
+            <CardTitle>Company Information</CardTitle>
+            <CardDescription>Company details and contact information</CardDescription>
           </CardHeader>
           <CardContent class="space-y-4">
             <div>
-              <label class="block text-sm font-medium text-gray-700 mb-2">Client</label>
+              <label class="block text-sm font-medium text-gray-700 mb-2">Company</label>
               <div class="space-y-3">
-                <div v-if="!isChangingClient" class="space-y-2">
+                <div v-if="!isChangingCompany" class="space-y-2">
                   <input
-                    :value="localJobData.client_name"
+                    :value="localJobData.company_name"
                     type="text"
-                    data-automation-id="JobSettingsTab-client-name"
+                    data-automation-id="JobSettingsTab-company-name"
                     class="w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm bg-gray-50 text-gray-600"
                     readonly
                   />
                   <div class="flex gap-2">
                     <button
-                      @click="startClientChange"
+                      @click="startCompanyChange"
                       type="button"
-                      data-automation-id="JobSettingsTab-change-client-btn"
+                      data-automation-id="JobSettingsTab-change-company-btn"
                       class="flex-1 px-3 py-2 border border-blue-300 rounded-md text-sm bg-blue-50 hover:bg-blue-100 text-blue-700 transition-colors"
                     >
-                      Change Client
+                      Change Company
                     </button>
                     <button
-                      @click="editCurrentClient"
+                      @click="editCurrentCompany"
                       type="button"
-                      data-automation-id="JobSettingsTab-edit-client-btn"
+                      data-automation-id="JobSettingsTab-edit-company-btn"
                       class="flex-1 px-3 py-2 border border-green-300 rounded-md text-sm bg-green-50 hover:bg-green-100 text-green-700 transition-colors"
                     >
-                      Edit Client
+                      Edit Company
                     </button>
                   </div>
                 </div>
@@ -115,31 +115,31 @@
                 <div
                   v-else
                   class="space-y-3"
-                  data-automation-id="JobSettingsTab-client-change-panel"
+                  data-automation-id="JobSettingsTab-company-change-panel"
                 >
-                  <ClientLookup
-                    id="clientChange"
+                  <CompanyLookup
+                    id="companyChange"
                     label=""
-                    placeholder="Search for a new client..."
+                    placeholder="Search for a new company..."
                     :required="false"
-                    v-model="newClientName"
-                    @update:selected-id="handleNewClientSelected"
-                    @update:selected-client="handleClientLookupSelected"
+                    v-model="newCompanyName"
+                    @update:selected-id="handleNewCompanySelected"
+                    @update:selected-company="handleCompanyLookupSelected"
                   />
                   <div class="flex gap-2">
                     <button
-                      @click="confirmClientChange"
+                      @click="confirmCompanyChange"
                       type="button"
-                      data-automation-id="JobSettingsTab-confirm-client-btn"
+                      data-automation-id="JobSettingsTab-confirm-company-btn"
                       class="px-4 py-2 bg-green-600 text-white rounded-md text-sm hover:bg-green-700 transition-colors"
-                      :disabled="!newClientId"
+                      :disabled="!newCompanyId"
                     >
                       Confirm
                     </button>
                     <button
-                      @click="cancelClientChange"
+                      @click="cancelCompanyChange"
                       type="button"
-                      data-automation-id="JobSettingsTab-cancel-client-btn"
+                      data-automation-id="JobSettingsTab-cancel-company-btn"
                       class="px-4 py-2 border border-gray-300 text-gray-700 rounded-md text-sm hover:bg-gray-50 transition-colors"
                     >
                       Cancel
@@ -149,9 +149,9 @@
 
                 <p class="text-xs text-gray-500">
                   {{
-                    isChangingClient
-                      ? 'Select a new client for this job'
-                      : 'Change or edit client information'
+                    isChangingCompany
+                      ? 'Select a new company for this job'
+                      : 'Change or edit company information'
                   }}
                 </p>
               </div>
@@ -162,8 +162,8 @@
                 id="contact"
                 label="Contact Person"
                 :optional="true"
-                :client-id="localJobData.client_id || ''"
-                :client-name="localJobData.client_name || ''"
+                :company-id="localJobData.company_id || ''"
+                :company-name="localJobData.company_name || ''"
                 :initial-contact-id="
                   typeof localJobData.contact_id === 'string' ? localJobData.contact_id : undefined
                 "
@@ -351,14 +351,14 @@
       </div>
     </div>
 
-    <!-- Client Edit Modal -->
-    <CreateClientModal
-      :is-open="showEditClientModal"
+    <!-- Company Edit Modal -->
+    <CreateCompanyModal
+      :is-open="showEditCompanyModal"
       :edit-mode="true"
-      :client-id="jobData?.client_id || ''"
-      :client-data="currentClientData"
-      @update:is-open="showEditClientModal = $event"
-      @client-created="handleClientUpdated"
+      :company-id="jobData?.company_id || ''"
+      :company-data="currentCompanyData"
+      @update:is-open="showEditCompanyModal = $event"
+      @company-created="handleCompanyUpdated"
     />
   </div>
 </template>
@@ -372,10 +372,10 @@ import { jobService } from '../../services/job.service'
 import { useJobsStore } from '../../stores/jobs'
 import { createJobAutosave } from '../../composables/useJobAutosave'
 import RichTextEditor from '../RichTextEditor.vue'
-import ClientLookup from '../ClientLookup.vue'
+import CompanyLookup from '../CompanyLookup.vue'
 import ContactSelector from '../ContactSelector.vue'
-import CreateClientModal from '../CreateClientModal.vue'
-import type { Client } from '../../composables/useClientLookup'
+import CreateCompanyModal from '../CreateCompanyModal.vue'
+import type { Company } from '../../composables/useCompanyLookup'
 import { debugLog } from '../../utils/debug'
 import { toast } from 'vue-sonner'
 import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '../../components/ui/card'
@@ -566,13 +566,13 @@ const basicInfo = computed(() => {
 })
 const basicInfoLoading = ref(false)
 
-const isChangingClient = ref(false)
-const newClientId = ref('')
-const newClientName = ref('')
-const selectedNewClient = ref<Client | null>(null)
+const isChangingCompany = ref(false)
+const newCompanyId = ref('')
+const newCompanyName = ref('')
+const selectedNewCompany = ref<Company | null>(null)
 
 const contactDisplayValue = ref('')
-const showEditClientModal = ref(false)
+const showEditCompanyModal = ref(false)
 
 const jobStatusChoices = ref<{ value: string; label: string }[]>([])
 const isInitializing = ref(true)
@@ -632,17 +632,17 @@ const TYPING_TIMEOUT_MS = 1000 // Consider user stopped typing after 1 second
 
 // Status choices are now loaded in the combined onMounted hook above
 
-// FIXME: `allow_jobs` is threaded through here so the edit-client modal
+// FIXME: `allow_jobs` is threaded through here so the edit-company modal
 // can surface/change it, but the job settings tab itself does NOT warn
-// the user when the currently-attached client has `allow_jobs=false`
-// (e.g. the client was archived or merged in Xero after the job was
+// the user when the currently-attached company has `allow_jobs=false`
+// (e.g. the company was archived or merged in Xero after the job was
 // created). The user only discovers the block when trying to create a
-// NEW job for the same client. Fix: add an amber banner near the top
-// of the tab when `currentClientData.allow_jobs === false`, explaining
-// that new jobs cannot be created against this client but the existing
-// job remains editable. Existing jobs on now-blocked clients are a
+// NEW job for the same company. Fix: add an amber banner near the top
+// of the tab when `currentCompanyData.allow_jobs === false`, explaining
+// that new jobs cannot be created against this company but the existing
+// job remains editable. Existing jobs on now-blocked companies are a
 // known backlog -- see the prod snapshot from the merge-reassign PR.
-const currentClientData = ref({
+const currentCompanyData = ref({
   name: '',
   email: '',
   address: '',
@@ -657,11 +657,11 @@ const normalizeNullable = (v: unknown): string | null => {
   return t ? t : null
 }
 
-const resetClientChangeState = () => {
-  isChangingClient.value = false
-  newClientId.value = ''
-  newClientName.value = ''
-  selectedNewClient.value = null
+const resetCompanyChangeState = () => {
+  isChangingCompany.value = false
+  newCompanyId.value = ''
+  newCompanyName.value = ''
+  selectedNewCompany.value = null
 }
 
 // Handle field input changes
@@ -767,8 +767,8 @@ watch(
         job_id: props.jobId || '',
         job_number: props.jobNumber ? Number(props.jobNumber) : 0,
         name: '',
-        client_id: null,
-        client_name: null,
+        company_id: null,
+        company_name: null,
         contact_id: undefined,
         contact_name: undefined,
         status: '' as Job['status'],
@@ -806,8 +806,8 @@ watch(
       job_id: newJobData.job_id,
       job_number: Number(newJobData.job_number),
       name: newJobData.name,
-      client_id: newJobData.client_id,
-      client_name: newJobData.client_name,
+      company_id: newJobData.company_id,
+      company_name: newJobData.company_name,
       status: newJobData.status,
       pricing_methodology: newJobData.pricing_methodology,
       speed_quality_tradeoff: newJobData.speed_quality_tradeoff ?? 'normal',
@@ -831,7 +831,7 @@ watch(
       notes: localJobData.value?.notes ?? '',
     }
 
-    // Keep original snapshot with current state (including separated client/contact fields for delta)
+    // Keep original snapshot with current state (including separated company/contact fields for delta)
     serverBaseline.value = {
       ...localJobData.value,
       description: normalizeNullable(localJobData.value.description),
@@ -847,7 +847,7 @@ watch(
     // Load contact information using the job contacts endpoint
     // IMPORTANT: Do NOT trigger autosave here - this is just loading initial data
     try {
-      const contactResponse = await api.clients_jobs_contact_retrieve({
+      const contactResponse = await api.companies_jobs_contact_retrieve({
         params: { job_id: newJobData.job_id },
       })
       if (contactResponse) {
@@ -1016,8 +1016,8 @@ watch(
       // Update local data when header changes (e.g., from inline edits)
       // IMPORTANT: Don't update basic info fields as they're managed separately
       localJobData.value.name = newHeader.name
-      localJobData.value.client_id = newHeader.client_id
-      localJobData.value.client_name = newHeader.client_name
+      localJobData.value.company_id = newHeader.company_id
+      localJobData.value.company_name = newHeader.company_name
       localJobData.value.status = newHeader.status
       localJobData.value.pricing_methodology = newHeader.pricing_methodology
       localJobData.value.speed_quality_tradeoff = newHeader.speed_quality_tradeoff ?? 'normal'
@@ -1043,104 +1043,104 @@ watch(
   { immediate: true, deep: true },
 )
 
-const startClientChange = () => {
-  isChangingClient.value = true
+const startCompanyChange = () => {
+  isChangingCompany.value = true
 }
 
-const cancelClientChange = () => {
-  resetClientChangeState()
+const cancelCompanyChange = () => {
+  resetCompanyChangeState()
 }
 
-const handleNewClientSelected = (clientId: string) => {
-  newClientId.value = clientId
+const handleNewCompanySelected = (companyId: string) => {
+  newCompanyId.value = companyId
 }
 
-const handleClientLookupSelected = (client: Client | null) => {
-  selectedNewClient.value = client
+const handleCompanyLookupSelected = (company: Company | null) => {
+  selectedNewCompany.value = company
 
-  if (client) {
-    newClientName.value = client.name
+  if (company) {
+    newCompanyName.value = company.name
   }
 }
 
-const confirmClientChange = () => {
-  if (!newClientId.value || !selectedNewClient.value) {
-    debugLog('No new client selected')
+const confirmCompanyChange = () => {
+  if (!newCompanyId.value || !selectedNewCompany.value) {
+    debugLog('No new company selected')
     return
   }
 
   // Capture values before reset
-  const clientId = newClientId.value
-  const clientName = selectedNewClient.value.name
+  const companyId = newCompanyId.value
+  const companyName = selectedNewCompany.value.name
 
-  localJobData.value.client_id = clientId
-  localJobData.value.client_name = clientName
+  localJobData.value.company_id = companyId
+  localJobData.value.company_name = companyName
 
   contactDisplayValue.value = ''
 
-  resetClientChangeState()
+  resetCompanyChangeState()
 
-  // Queue autosave for client change (use captured clientId, not the now-reset ref)
+  // Queue autosave for company change (use captured companyId, not the now-reset ref)
   if (!isInitializing.value && !isHydratingBasicInfo.value && !isSyncingFromStore.value) {
-    autosave.queueChange('client_id', clientId)
+    autosave.queueChange('company_id', companyId)
   }
 
   // Update header immediately for instant reactivity
   if (jobHeader.value) {
     jobsStore.patchHeader(jobHeader.value.job_id, {
-      client_id: clientId,
-      client_name: clientName,
+      company_id: companyId,
+      company_name: companyName,
     })
   }
 }
 
-const editCurrentClient = async () => {
-  if (!jobData.value?.client_id) {
-    debugLog('No current client to edit')
+const editCurrentCompany = async () => {
+  if (!jobData.value?.company_id) {
+    debugLog('No current company to edit')
     return
   }
 
   try {
-    // Fetch current client data from API
-    const clientDetail = await api.clients_retrieve({
-      params: { client_id: jobData.value.client_id },
+    // Fetch current company data from API
+    const companyDetail = await api.companies_retrieve({
+      params: { company_id: jobData.value.company_id },
     })
 
-    // Update currentClientData with fetched data
-    currentClientData.value = {
-      name: clientDetail.name,
-      email: clientDetail.email,
-      address: clientDetail.address,
-      is_account_customer: clientDetail.is_account_customer,
-      allow_jobs: clientDetail.allow_jobs,
+    // Update currentCompanyData with fetched data
+    currentCompanyData.value = {
+      name: companyDetail.name,
+      email: companyDetail.email,
+      address: companyDetail.address,
+      is_account_customer: companyDetail.is_account_customer,
+      allow_jobs: companyDetail.allow_jobs,
     }
 
-    showEditClientModal.value = true
+    showEditCompanyModal.value = true
   } catch (error) {
-    console.error('Error fetching client data:', error)
-    toast.error('Failed to load client data for editing')
+    console.error('Error fetching company data:', error)
+    toast.error('Failed to load company data for editing')
   }
 }
 
-const handleClientUpdated = (updatedClient: Client) => {
-  // Update local job data with new client information
-  localJobData.value.client_name = updatedClient.name
+const handleCompanyUpdated = (updatedCompany: Company) => {
+  // Update local job data with new company information
+  localJobData.value.company_name = updatedCompany.name
 
-  // Reflect name in header immediately (no API call; backend derives client_name)
+  // Reflect name in header immediately (no API call; backend derives company_name)
   if (jobHeader.value) {
     jobsStore.patchHeader(jobHeader.value.job_id, {
-      client_name: updatedClient.name,
+      company_name: updatedCompany.name,
     })
   }
 
-  toast.success('Client updated successfully')
+  toast.success('Company updated successfully')
 }
 
 const handleContactSelected = async (contact: ClientContact | null) => {
   if (contact) {
     // Skip API call if contact is already set to this value
     // This handles:
-    // - Scenario 4: Client change - backend sets contact in response, no duplicate API call needed
+    // - Scenario 4: Company change - backend sets contact in response, no duplicate API call needed
     // - User re-selecting the same contact
     if (localJobData.value.contact_id === contact.id) {
       // Still update display value in case it's stale
@@ -1165,7 +1165,7 @@ const handleContactSelected = async (contact: ClientContact | null) => {
 
     // Save contact directly (not through header autosave)
     try {
-      await api.clients_jobs_contact_update(
+      await api.companies_jobs_contact_update(
         contactToSend as z.input<typeof schemas.JobContactUpdateRequest>,
         {
           params: { job_id: props.jobId },
@@ -1206,7 +1206,7 @@ const autosave = createJobAutosave({
       job_id: data.job_id,
       job_number: data.job_number,
       name: data.name,
-      client_id: data.client_id ?? null,
+      company_id: data.company_id ?? null,
       contact_id: data.contact_id,
       contact_name: data.contact_name,
       job_status: data.status,
@@ -1228,13 +1228,13 @@ const autosave = createJobAutosave({
   },
   applyOptimistic: (patch) => {
     Object.entries(patch).forEach(([k, v]) => {
-      // Apply all fields including separated client/contact fields
+      // Apply all fields including separated company/contact fields
       ;(localJobData.value as Record<string, unknown>)[k] = v as unknown
     })
   },
   rollbackOptimistic: (previous) => {
     Object.entries(previous).forEach(([k, v]) => {
-      // Rollback all fields including separated client/contact fields
+      // Rollback all fields including separated company/contact fields
       ;(localJobData.value as Record<string, unknown>)[k] = v as unknown
     })
   },
@@ -1270,7 +1270,7 @@ const autosave = createJobAutosave({
         }
       }
 
-      // Use the partial update method with client snapshot for before values
+      // Use the partial update method with company snapshot for before values
       const result = await jobService.updateJobHeaderPartial(
         props.jobId,
         partialPayload,
@@ -1314,8 +1314,8 @@ const autosave = createJobAutosave({
         if ('quote_acceptance_date' in payload) {
           next.quote_acceptance_date = (payload.quote_acceptance_date as string | null) ?? undefined
         }
-        if ('client_id' in payload) next.client_id = payload.client_id as string | null
-        if ('client_name' in payload) next.client_name = payload.client_name as string | null
+        if ('company_id' in payload) next.company_id = payload.company_id as string | null
+        if ('company_name' in payload) next.company_name = payload.company_name as string | null
         if ('description' in payload)
           next.description = (payload.description as string | null) ?? null
         if ('delivery_date' in payload)
@@ -1430,15 +1430,15 @@ const autosave = createJobAutosave({
           headerPatch.default_xero_pay_item_name =
             serverJobDetail.default_xero_pay_item_name ?? null
         }
-        if (touchedKeys.includes('client_id') || touchedKeys.includes('client_name')) {
-          nextBaseline.client_id = serverJobDetail.client_id ?? null
-          nextBaseline.client_name = serverJobDetail.client_name ?? null
-          localJobData.value.client_id = serverJobDetail.client_id ?? null
-          localJobData.value.client_name = serverJobDetail.client_name ?? null
-          headerPatch.client_id = serverJobDetail.client_id ?? null
-          headerPatch.client_name = serverJobDetail.client_name ?? null
-
-          // Backend auto-sets contact when client changes - update from response
+        if (touchedKeys.includes('company_id') || touchedKeys.includes('company_name')) {
+          nextBaseline.company_id = serverJobDetail.company_id ?? null
+          nextBaseline.company_name = serverJobDetail.company_name ?? null
+          localJobData.value.company_id = serverJobDetail.company_id ?? null
+          localJobData.value.company_name = serverJobDetail.company_name ?? null
+          headerPatch.company_id = serverJobDetail.company_id ?? null
+          headerPatch.company_name = serverJobDetail.company_name ?? null
+
+          // Backend auto-sets contact when company changes - update from response
           // This prevents a redundant API call when ContactSelector emits
           if (serverJobDetail.contact_id !== undefined) {
             nextBaseline.contact_id = serverJobDetail.contact_id ?? null
@@ -1554,18 +1554,18 @@ const autosave = createJobAutosave({
           headerPatch.default_xero_pay_item_id = payItemId
           headerPatch.default_xero_pay_item_name = payItemName
         }
-        if (touchedKeys.includes('client_id') || touchedKeys.includes('client_name')) {
-          const clientId = coerceNullableString(partialPayload.client_id) ?? ''
-          const clientName = coerceNullableString(partialPayload.client_name) ?? ''
-          nextBaseline.client_id = clientId
-          nextBaseline.client_name = clientName
-          localJobData.value.client_id = clientId
-          localJobData.value.client_name = clientName
-          headerPatch.client_id = clientId
-          headerPatch.client_name = clientName
+        if (touchedKeys.includes('company_id') || touchedKeys.includes('company_name')) {
+          const companyId = coerceNullableString(partialPayload.company_id) ?? ''
+          const companyName = coerceNullableString(partialPayload.company_name) ?? ''
+          nextBaseline.company_id = companyId
+          nextBaseline.company_name = companyName
+          localJobData.value.company_id = companyId
+          localJobData.value.company_name = companyName
+          headerPatch.company_id = companyId
+          headerPatch.company_name = companyName
 
           // Note: When no serverJobDetail, we can't get the auto-set contact
-          // The ContactSelector will re-fetch contacts for the new client
+          // The ContactSelector will re-fetch contacts for the new company
         }
         if (touchedKeys.includes('contact_id')) {
           const contactId = coerceNullableString(partialPayload.contact_id)
@@ -1648,8 +1648,8 @@ onMounted(() => {
           job_id: response.job_id,
           job_number: Number(response.job_number),
           name: response.name,
-          client_id: response.client_id,
-          client_name: response.client_name,
+          company_id: response.company_id,
+          company_name: response.company_name,
           status: response.status,
           pricing_methodology: response.pricing_methodology,
           speed_quality_tradeoff: response.speed_quality_tradeoff ?? 'normal',
@@ -1724,7 +1724,7 @@ watch(
   },
 )
 // pricing_methodology and speed_quality_tradeoff: handlers queue via @change, no watcher queuing needed
-// client: confirmClientChange queues, no watcher queuing needed
+// company: confirmCompanyChange queues, no watcher queuing needed
 
 // Watchers for basic info fields
 watch(
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
index 7ca60c142..57610a6ca 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
@@ -53,8 +53,8 @@ vi.mock('@/api/client', () => ({
       job_id: 'job-1',
       job_number: 101,
       name: 'Rate Job',
-      client_id: null,
-      client_name: null,
+      company_id: null,
+      company_name: null,
       status: 'in_progress',
       pricing_methodology: 'time_materials',
       speed_quality_tradeoff: 'normal',
@@ -69,7 +69,7 @@ vi.mock('@/api/client', () => ({
       is_urgent: false,
     }),
     workflow_xero_pay_items_list: vi.fn().mockResolvedValue([]),
-    clients_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
+    companies_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
   },
 }))
 
@@ -152,9 +152,9 @@ const mountTab = () =>
         CardDescription: passthrough,
         CardContent: passthrough,
         RichTextEditor: { template: '<div />' },
-        ClientLookup: { template: '<div />' },
+        CompanyLookup: { template: '<div />' },
         ContactSelector: { template: '<div />' },
-        CreateClientModal: { template: '<div />' },
+        CreateCompanyModal: { template: '<div />' },
       },
     },
   })
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
index c9f4681df..fd254d611 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
@@ -51,8 +51,8 @@ vi.mock('@/api/client', () => ({
       job_id: 'job-1',
       job_number: 101,
       name: 'Urgent Job',
-      client_id: null,
-      client_name: null,
+      company_id: null,
+      company_name: null,
       status: 'in_progress',
       pricing_methodology: 'time_materials',
       speed_quality_tradeoff: 'normal',
@@ -67,7 +67,7 @@ vi.mock('@/api/client', () => ({
       is_urgent: true,
     }),
     workflow_xero_pay_items_list: vi.fn().mockResolvedValue([]),
-    clients_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
+    companies_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
   },
 }))
 
@@ -146,9 +146,9 @@ describe('JobSettingsTab urgent autosave', () => {
           CardDescription: passthrough,
           CardContent: passthrough,
           RichTextEditor: { template: '<div />' },
-          ClientLookup: { template: '<div />' },
+          CompanyLookup: { template: '<div />' },
           ContactSelector: { template: '<div />' },
-          CreateClientModal: { template: '<div />' },
+          CreateCompanyModal: { template: '<div />' },
         },
       },
     })
diff --git a/frontend/src/components/kpi/KPIDayDetailsModal.vue b/frontend/src/components/kpi/KPIDayDetailsModal.vue
index 036a0e036..f1606f35f 100644
--- a/frontend/src/components/kpi/KPIDayDetailsModal.vue
+++ b/frontend/src/components/kpi/KPIDayDetailsModal.vue
@@ -124,7 +124,7 @@
                 <td class="py-1.5 px-2">
                   <button
                     @click="handleJobClick(job.job_id)"
-                    :title="`${job.job_name} — ${job.client_name}`"
+                    :title="`${job.job_name} — ${job.company_name}`"
                     class="text-blue-600 hover:text-blue-800 hover:underline cursor-pointer"
                   >
                     {{ job.job_number }}
diff --git a/frontend/src/components/kpi/KPILabourDetailsModal.vue b/frontend/src/components/kpi/KPILabourDetailsModal.vue
index 9351d2c72..e00e5a684 100644
--- a/frontend/src/components/kpi/KPILabourDetailsModal.vue
+++ b/frontend/src/components/kpi/KPILabourDetailsModal.vue
@@ -26,7 +26,7 @@
                 {{ formatHours(monthlyData.billable_hours) }}
               </div>
               <div class="text-sm text-blue-600">Billable Hours</div>
-              <div class="text-xs text-gray-500 mt-1">Client chargeable time</div>
+              <div class="text-xs text-gray-500 mt-1">Company chargeable time</div>
             </div>
             <div class="text-center">
               <div class="text-3xl font-bold text-blue-700">{{ formatHours(totalShopHours) }}</div>
diff --git a/frontend/src/components/purchasing/AddressAutocompleteInput.vue b/frontend/src/components/purchasing/AddressAutocompleteInput.vue
index bb1b9b932..775051a39 100644
--- a/frontend/src/components/purchasing/AddressAutocompleteInput.vue
+++ b/frontend/src/components/purchasing/AddressAutocompleteInput.vue
@@ -130,7 +130,7 @@ const searchAddress = async (query: string) => {
   const requestId = ++currentRequestId
   isLoading.value = true
   try {
-    const response = await api.clients_addresses_validate_create({
+    const response = await api.companies_addresses_validate_create({
       address: query,
     })
     if (requestId !== currentRequestId) {
diff --git a/frontend/src/components/purchasing/JobSelect.vue b/frontend/src/components/purchasing/JobSelect.vue
index b7bc1dbf4..ae78b373e 100644
--- a/frontend/src/components/purchasing/JobSelect.vue
+++ b/frontend/src/components/purchasing/JobSelect.vue
@@ -54,10 +54,10 @@
             {{ job.description || job.name || job.job_display_name }}
           </div>
           <div
-            v-if="job.client_name && !isStockHoldingJob(job)"
+            v-if="job.company_name && !isStockHoldingJob(job)"
             class="text-xs text-gray-500 truncate"
           >
-            Client: {{ job.client_name }}
+            Company: {{ job.company_name }}
           </div>
           <div v-if="isStockHoldingJob(job)" class="text-xs text-orange-600 truncate">
             Stock Holding Job
@@ -156,7 +156,7 @@ const filteredJobs = computed(() => {
     const jobNumberMatch = job.job_number?.toString().toLowerCase().includes(term)
     const descriptionMatch = job.description?.toLowerCase().includes(term)
     const nameMatch = job.name?.toLowerCase().includes(term)
-    const clientMatch = job.client_name?.toLowerCase().includes(term)
+    const clientMatch = job.company_name?.toLowerCase().includes(term)
 
     return jobNumberMatch || descriptionMatch || nameMatch || clientMatch
   })
diff --git a/frontend/src/components/purchasing/PoLinesTable.vue b/frontend/src/components/purchasing/PoLinesTable.vue
index 355e4e71f..bab8b412b 100644
--- a/frontend/src/components/purchasing/PoLinesTable.vue
+++ b/frontend/src/components/purchasing/PoLinesTable.vue
@@ -113,7 +113,7 @@ function makeEmptyLine(): PurchaseOrderLine {
     location: undefined,
     job_id: null,
     job_number: null,
-    client_name: null,
+    company_name: null,
     job_name: null,
     times_used: 0,
   }
@@ -312,7 +312,7 @@ const columns = computed<ColumnDef<PurchaseOrderLine>[]>(() => {
                       job_id: job.id,
                       job_number: job.job_number,
                       job_name: job.name,
-                      client_name: job.client_name,
+                      company_name: job.company_name,
                     })
                   }
                 },
diff --git a/frontend/src/components/purchasing/PoSummaryCard.vue b/frontend/src/components/purchasing/PoSummaryCard.vue
index 30810f2ca..0cabddbad 100644
--- a/frontend/src/components/purchasing/PoSummaryCard.vue
+++ b/frontend/src/components/purchasing/PoSummaryCard.vue
@@ -20,7 +20,7 @@ import {
   Mail,
   CalendarIcon,
 } from 'lucide-vue-next'
-import ClientLookup from '@/components/ClientLookup.vue'
+import CompanyLookup from '@/components/CompanyLookup.vue'
 import PickupAddressSelector from '@/components/purchasing/PickupAddressSelector.vue'
 import { schemas } from '@/api/generated/api'
 import { poStatusLabels } from '@/utils/statusMappings'
@@ -54,7 +54,7 @@ const emit = defineEmits<{
 }>()
 
 const supplierLookup = reactive({
-  value: true, // indicates supplier mode vs client mode
+  value: true, // indicates supplier mode vs company mode
 })
 
 // ✅ 2. Add autosave logic
@@ -94,8 +94,8 @@ function onStatusUpdate(value: Status) {
   emit('update:status', value)
 }
 
-function onSupplierSelected(client: { name?: string } | null) {
-  emit('update:supplier', client?.name || '')
+function onSupplierSelected(company: { name?: string } | null) {
+  emit('update:supplier', company?.name || '')
 }
 
 function onSupplierIdUpdate(id: string | null) {
@@ -124,13 +124,13 @@ const statusOptions: { value: Status; label: string }[] =
     <CardContent>
       <div class="flex flex-col gap-1">
         <template v-if="po.status === 'draft'">
-          <ClientLookup
+          <CompanyLookup
             :supplier-lookup="supplierLookup"
             id="supplier"
             :model-value="po.supplier"
             required
             placeholder="Search supplier…"
-            @update:selected-client="onSupplierSelected"
+            @update:selected-company="onSupplierSelected"
             @update:selected-id="onSupplierIdUpdate"
             :label="'Supplier'"
             data-automation-id="PoSummaryCard-supplier-lookup"
diff --git a/frontend/src/components/shared/InlineEditClient.vue b/frontend/src/components/shared/InlineEditCompany.vue
similarity index 56%
rename from frontend/src/components/shared/InlineEditClient.vue
rename to frontend/src/components/shared/InlineEditCompany.vue
index bbf6e17fd..da0bae4fa 100644
--- a/frontend/src/components/shared/InlineEditClient.vue
+++ b/frontend/src/components/shared/InlineEditCompany.vue
@@ -1,5 +1,5 @@
 <template>
-  <div class="inline-edit-client group">
+  <div class="inline-edit-company group">
     <div
       v-if="!isEditing"
       @click="startEdit"
@@ -12,14 +12,14 @@
 
     <div v-else class="flex items-center gap-2">
       <div class="relative flex-1">
-        <ClientLookup
-          id="inline-client-lookup"
+        <CompanyLookup
+          id="inline-company-lookup"
           label=""
           v-model="searchQuery"
           :placeholder="placeholder"
           :search-mode="true"
           :edit-mode="true"
-          @update:selected-client="handleClientSelected"
+          @update:selected-company="handleCompanySelected"
           class="min-w-48"
         />
       </div>
@@ -40,24 +40,24 @@
 <script setup lang="ts">
 import { ref, computed, watch } from 'vue'
 import { PencilIcon, CheckIcon, XIcon } from 'lucide-vue-next'
-import ClientLookup from '../ClientLookup.vue'
-import type { Client } from '../../composables/useClientLookup'
+import CompanyLookup from '../CompanyLookup.vue'
+import type { Company } from '../../composables/useCompanyLookup'
 
 interface Props {
-  clientName?: string | null
-  clientId?: string | null
+  companyName?: string | null
+  companyId?: string | null
   placeholder?: string
   displayClass?: string
 }
 
 interface Emits {
-  'update:client': [client: { id: string; name: string }]
+  'update:company': [company: { id: string; name: string }]
 }
 
 const props = withDefaults(defineProps<Props>(), {
-  clientName: '',
-  clientId: '',
-  placeholder: 'Click to select client',
+  companyName: '',
+  companyId: '',
+  placeholder: 'Click to select company',
   displayClass: '',
 })
 
@@ -65,40 +65,40 @@ const emit = defineEmits<Emits>()
 
 const isEditing = ref(false)
 const searchQuery = ref('')
-const selectedClient = ref<Client | null>(null)
+const selectedCompany = ref<Company | null>(null)
 
 const displayValue = computed(() => {
-  return props.clientName || (isEditing.value ? '' : props.placeholder)
+  return props.companyName || (isEditing.value ? '' : props.placeholder)
 })
 
 const canConfirm = computed(() => {
-  return selectedClient.value !== null
+  return selectedCompany.value !== null
 })
 
 const startEdit = () => {
-  searchQuery.value = props.clientName || ''
-  selectedClient.value = null
+  searchQuery.value = props.companyName || ''
+  selectedCompany.value = null
   isEditing.value = true
 }
 
-const handleClientSelected = (client: Client | null) => {
-  selectedClient.value = client
-  if (client) {
-    searchQuery.value = client.name
+const handleCompanySelected = (company: Company | null) => {
+  selectedCompany.value = company
+  if (company) {
+    searchQuery.value = company.name
   }
 }
 
 const confirm = () => {
-  if (!canConfirm.value || !selectedClient.value) return
+  if (!canConfirm.value || !selectedCompany.value) return
 
-  // Only emit if client actually changed
+  // Only emit if company actually changed
   if (
-    selectedClient.value.id !== props.clientId ||
-    selectedClient.value.name !== props.clientName
+    selectedCompany.value.id !== props.companyId ||
+    selectedCompany.value.name !== props.companyName
   ) {
-    emit('update:client', {
-      id: selectedClient.value.id,
-      name: selectedClient.value.name,
+    emit('update:company', {
+      id: selectedCompany.value.id,
+      name: selectedCompany.value.name,
     })
   }
 
@@ -106,14 +106,14 @@ const confirm = () => {
 }
 
 const cancel = () => {
-  searchQuery.value = props.clientName || ''
-  selectedClient.value = null
+  searchQuery.value = props.companyName || ''
+  selectedCompany.value = null
   isEditing.value = false
 }
 
 // Watch for external value changes
 watch(
-  () => props.clientName,
+  () => props.companyName,
   (newValue) => {
     if (!isEditing.value) {
       searchQuery.value = newValue || ''
@@ -123,21 +123,21 @@ watch(
 </script>
 
 <style scoped>
-.inline-edit-client :deep(.client-lookup) {
+.inline-edit-company :deep(.company-lookup) {
   margin-bottom: 0;
 }
 
-.inline-edit-client :deep(.client-lookup label) {
+.inline-edit-company :deep(.company-lookup label) {
   display: none;
 }
 
-/* Hide the blue confirmation element from ClientLookup */
-.inline-edit-client :deep(.client-lookup .bg-blue-50) {
+/* Hide the blue confirmation element from CompanyLookup */
+.inline-edit-company :deep(.company-lookup .bg-blue-50) {
   display: none;
 }
 
 @media (max-width: 768px) {
-  .inline-edit-client .min-w-48 {
+  .inline-edit-company .min-w-48 {
     min-width: 12rem;
   }
 }
diff --git a/frontend/src/components/timesheet/SmartTimesheetTable.vue b/frontend/src/components/timesheet/SmartTimesheetTable.vue
index 34c3f8072..1270926b4 100644
--- a/frontend/src/components/timesheet/SmartTimesheetTable.vue
+++ b/frontend/src/components/timesheet/SmartTimesheetTable.vue
@@ -133,7 +133,7 @@ function makeEmptyEntry(): TimesheetCostLine {
     job_id: '',
     job_number: 0,
     job_name: '',
-    client_name: '',
+    company_name: '',
     charge_out_rate: 0,
     wage_rate: props.staffWageRate,
     xero_pay_item_name: '',
@@ -429,7 +429,7 @@ function setJob(entry: TimesheetCostLine, job: Job): void {
     job_id: job.id,
     job_number: job.job_number,
     job_name: job.name ?? '',
-    client_name: job.client_name ?? '',
+    company_name: job.company_name ?? '',
     charge_out_rate: rate,
   })
   // Adopt the job's default pay item if the user hasn't picked a non-Ord rate.
@@ -592,17 +592,17 @@ const columns = computed(() => [
     },
   },
   {
-    id: 'client',
-    header: 'Client',
+    id: 'company',
+    header: 'Company',
     cell: ({ row }: RowCtx) => {
       const entry = displayEntries.value[row.index]
       return h(
         'span',
         {
           class: 'text-sm text-slate-500',
-          'data-automation-id': `SmartTimesheetTable-client-${row.index}`,
+          'data-automation-id': `SmartTimesheetTable-company-${row.index}`,
         },
-        entry.client_name || '',
+        entry.company_name || '',
       )
     },
   },
diff --git a/frontend/src/components/timesheet/StaffDetailModal.vue b/frontend/src/components/timesheet/StaffDetailModal.vue
index 33beb6e17..bda00faeb 100644
--- a/frontend/src/components/timesheet/StaffDetailModal.vue
+++ b/frontend/src/components/timesheet/StaffDetailModal.vue
@@ -129,7 +129,7 @@
                     <th
                       class="px-3 md:px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
                     >
-                      Client
+                      Company
                     </th>
                     <th
                       class="px-3 md:px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider"
@@ -174,9 +174,9 @@
                     <td class="px-3 md:px-4 py-3 whitespace-nowrap">
                       <div
                         class="text-sm text-gray-900 truncate max-w-[120px] md:max-w-none"
-                        :title="job.client"
+                        :title="job.company"
                       >
-                        {{ job.client }}
+                        {{ job.company }}
                       </div>
                     </td>
                     <td class="px-3 md:px-4 py-3 whitespace-nowrap">
diff --git a/frontend/src/components/timesheet/SummaryDrawer.vue b/frontend/src/components/timesheet/SummaryDrawer.vue
index 0114506b6..0c6c659e9 100644
--- a/frontend/src/components/timesheet/SummaryDrawer.vue
+++ b/frontend/src/components/timesheet/SummaryDrawer.vue
@@ -103,7 +103,7 @@
                           Job {{ jobData.job.job_number }}
                         </h4>
                         <p class="text-sm text-gray-600 truncate">{{ jobData.job.name }}</p>
-                        <p class="text-xs text-gray-500 truncate">{{ jobData.job.client_name }}</p>
+                        <p class="text-xs text-gray-500 truncate">{{ jobData.job.company_name }}</p>
                       </div>
                       <!-- TODO: Backend inconsistency - Job uses 'job_status', ModernTimesheetJob uses 'status'.
                            jobData.job is FullJob | ModernTimesheetJob union due to enhancedJob || job fallback.
diff --git a/frontend/src/components/timesheet/TimesheetJobPicker.vue b/frontend/src/components/timesheet/TimesheetJobPicker.vue
index 39ba724b8..19a3d70a7 100644
--- a/frontend/src/components/timesheet/TimesheetJobPicker.vue
+++ b/frontend/src/components/timesheet/TimesheetJobPicker.vue
@@ -74,8 +74,8 @@ const filtered = computed<Job[]>(() => {
     .filter((j) => {
       const num = String(j.job_number ?? '').toLowerCase()
       const name = (j.name ?? '').toLowerCase()
-      const client = (j.client_name ?? '').toLowerCase()
-      return num.includes(term) || name.includes(term) || client.includes(term)
+      const company = (j.company_name ?? '').toLowerCase()
+      return num.includes(term) || name.includes(term) || company.includes(term)
     })
     .slice(0, 15)
 })
@@ -228,7 +228,7 @@ function onKeyDown(e: KeyboardEvent) {
         <Input
           ref="searchInput"
           v-model="search"
-          placeholder="Search jobs… (job number, name, or client)"
+          placeholder="Search jobs… (job number, name, or company)"
           class="h-8 text-sm"
           :data-automation-id="`${automationIdPrefix}-search`"
           @keydown="onKeyDown"
@@ -269,7 +269,7 @@ function onKeyDown(e: KeyboardEvent) {
             {{ job.name }}
           </div>
           <div class="text-slate-500 text-xs leading-tight">
-            Client: {{ job.client_name || 'No Client' }}
+            Company: {{ job.company_name || 'No Company' }}
           </div>
           <div class="text-slate-400 text-[11px] leading-tight">
             Rate: ${{ jobDisplayRate(job) }}/hr
diff --git a/frontend/src/components/timesheet/WeeklyMetricsModal.vue b/frontend/src/components/timesheet/WeeklyMetricsModal.vue
index 346eb7fa1..d15de03b2 100644
--- a/frontend/src/components/timesheet/WeeklyMetricsModal.vue
+++ b/frontend/src/components/timesheet/WeeklyMetricsModal.vue
@@ -158,7 +158,7 @@
             <input
               v-model="searchQuery"
               type="text"
-              placeholder="Search jobs by name, client, or job number..."
+              placeholder="Search jobs by name, company, or job number..."
               class="w-full pl-10 pr-4 py-3 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
             />
             <Search class="absolute left-3 top-3.5 h-4 w-4 text-gray-400" />
@@ -190,7 +190,7 @@
                     #{{ job.job_number }}
                   </span>
                 </div>
-                <p class="text-xs text-gray-600 mb-1 truncate">{{ job.client || 'No client' }}</p>
+                <p class="text-xs text-gray-600 mb-1 truncate">{{ job.company || 'No company' }}</p>
 
                 <!-- Issues Warning -->
                 <div v-if="hasJobIssues(job)" class="mt-2">
@@ -296,7 +296,7 @@ const filteredJobs = computed<WeeklyJob[]>(() => {
   return jobs.value.filter(
     (job) =>
       job.name.toLowerCase().includes(query) ||
-      (job.client && job.client.toLowerCase().includes(query)) ||
+      (job.company && job.company.toLowerCase().includes(query)) ||
       job.job_number.toString().toLowerCase().includes(query) ||
       (job.description && job.description.toLowerCase().includes(query)),
   )
diff --git a/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.billReset.test.ts b/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.billReset.test.ts
index 35c9ad015..30e574dc5 100644
--- a/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.billReset.test.ts
+++ b/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.billReset.test.ts
@@ -100,7 +100,7 @@ function makeJob(overrides: Partial<Job>): Job {
     id: overrides.id ?? '11111111-1111-1111-1111-111111111111',
     job_number: overrides.job_number ?? 100,
     name: overrides.name ?? 'Test Job',
-    client_name: overrides.client_name ?? 'Acme',
+    company_name: overrides.company_name ?? 'Acme',
     status: overrides.status ?? 'in_progress',
     labour_rates: overrides.labour_rates ?? [
       {
@@ -146,7 +146,7 @@ function makeEntry(): TimesheetCostLine {
     job_id: '',
     job_number: 0,
     job_name: '',
-    client_name: '',
+    company_name: '',
     charge_out_rate: 0,
     wage_rate: 40,
     xero_pay_item_name: '',
diff --git a/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.urgent.test.ts b/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.urgent.test.ts
index 10730bea1..df6402891 100644
--- a/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.urgent.test.ts
+++ b/frontend/src/components/timesheet/__tests__/SmartTimesheetTable.urgent.test.ts
@@ -6,7 +6,7 @@ import { schemas } from '@/api/generated/api'
 import { getBillMultiplier, getMultiplier, getRateTypeFromMultiplier } from '@/utils/timesheetCalc'
 
 // The real autosave composable reaches into a Pinia store + the generated API
-// client; this test only cares about the in-memory mutation setJob performs on
+// company; this test only cares about the in-memory mutation setJob performs on
 // the row, so stub the autosave layer to a no-op.
 vi.mock('@/composables/useCostLineAutosave', () => ({
   useCostLineAutosave: () => ({
@@ -99,7 +99,7 @@ function makeJob(overrides: Partial<Job>): Job {
     id: overrides.id ?? '11111111-1111-1111-1111-111111111111',
     job_number: overrides.job_number ?? 100,
     name: overrides.name ?? 'Test Job',
-    client_name: overrides.client_name ?? 'Acme',
+    company_name: overrides.company_name ?? 'Acme',
     status: overrides.status ?? 'in_progress',
     labour_rates: overrides.labour_rates ?? [
       {
@@ -151,7 +151,7 @@ function makeEntry(): TimesheetCostLine {
     job_id: '',
     job_number: 0,
     job_name: '',
-    client_name: '',
+    company_name: '',
     charge_out_rate: 0,
     wage_rate: 40,
     xero_pay_item_name: '',
diff --git a/frontend/src/components/timesheet/__tests__/TimesheetJobPicker.urgent.test.ts b/frontend/src/components/timesheet/__tests__/TimesheetJobPicker.urgent.test.ts
index 704424460..a8858340f 100644
--- a/frontend/src/components/timesheet/__tests__/TimesheetJobPicker.urgent.test.ts
+++ b/frontend/src/components/timesheet/__tests__/TimesheetJobPicker.urgent.test.ts
@@ -11,7 +11,7 @@ function makeJob(overrides: Partial<Job>): Job {
     id: overrides.id ?? '11111111-1111-1111-1111-111111111111',
     job_number: overrides.job_number ?? 100,
     name: overrides.name ?? 'Test Job',
-    client_name: overrides.client_name ?? 'Acme',
+    company_name: overrides.company_name ?? 'Acme',
     status: overrides.status ?? 'in_progress',
     labour_rates: overrides.labour_rates ?? [
       {
diff --git a/frontend/src/components/workshop/WorkshopJobHeader.vue b/frontend/src/components/workshop/WorkshopJobHeader.vue
index 029f166b6..2b8db4edf 100644
--- a/frontend/src/components/workshop/WorkshopJobHeader.vue
+++ b/frontend/src/components/workshop/WorkshopJobHeader.vue
@@ -76,8 +76,8 @@ const emit = defineEmits<{
               >
                 <span class="inline-flex items-center gap-1">
                   <Building2 class="h-4 w-4" />
-                  <span class="font-medium text-foreground">Client:</span>
-                  {{ job.client_name || '-' }}
+                  <span class="font-medium text-foreground">Company:</span>
+                  {{ job.company_name || '-' }}
                 </span>
                 <span class="inline-flex items-center gap-1">
                   <UserRound class="h-4 w-4" />
diff --git a/frontend/src/components/workshop/WorkshopJobPickerDrawer.vue b/frontend/src/components/workshop/WorkshopJobPickerDrawer.vue
index 9612ed32d..8523b45f8 100644
--- a/frontend/src/components/workshop/WorkshopJobPickerDrawer.vue
+++ b/frontend/src/components/workshop/WorkshopJobPickerDrawer.vue
@@ -40,7 +40,7 @@ const emit = defineEmits<{
       <div class="mx-auto flex h-full w-full max-w-4xl flex-col min-h-0">
         <DrawerHeader>
           <DrawerTitle class="text-xl font-semibold">Select a job</DrawerTitle>
-          <DrawerDescription>Search by job number, name, or client</DrawerDescription>
+          <DrawerDescription>Search by job number, name, or company</DrawerDescription>
         </DrawerHeader>
         <div class="drawer-scroll flex-1 overflow-y-auto px-4 pb-4 space-y-3">
           <input
@@ -57,7 +57,7 @@ const emit = defineEmits<{
                 <tr>
                   <th class="text-left px-3 py-2 font-semibold">Job #</th>
                   <th class="text-left px-3 py-2 font-semibold">Name</th>
-                  <th class="text-left px-3 py-2 font-semibold">Client</th>
+                  <th class="text-left px-3 py-2 font-semibold">Company</th>
                   <th class="text-left px-3 py-2 font-semibold">Action</th>
                 </tr>
               </thead>
@@ -65,7 +65,7 @@ const emit = defineEmits<{
                 <tr v-for="job in filteredJobs" :key="job.id" class="border-t hover:bg-muted/50">
                   <td class="px-3 py-2 whitespace-nowrap">#{{ job.job_number }}</td>
                   <td class="px-3 py-2">{{ job.name }}</td>
-                  <td class="px-3 py-2">{{ job.client_name || '-' }}</td>
+                  <td class="px-3 py-2">{{ job.company_name || '-' }}</td>
                   <td class="px-3 py-2">
                     <Button
                       size="sm"
diff --git a/frontend/src/components/workshop/WorkshopTimesheetLegacyTable.vue b/frontend/src/components/workshop/WorkshopTimesheetLegacyTable.vue
index 79cecd3f9..1fb968251 100644
--- a/frontend/src/components/workshop/WorkshopTimesheetLegacyTable.vue
+++ b/frontend/src/components/workshop/WorkshopTimesheetLegacyTable.vue
@@ -52,7 +52,7 @@ const emit = defineEmits<{
                   #{{ entry.job_number }} &middot; {{ entry.job_name }}
                 </div>
                 <div class="text-xs text-muted-foreground">
-                  {{ entry.client_name || 'No client' }}
+                  {{ entry.company_name || 'No company' }}
                 </div>
               </div>
             </td>
diff --git a/frontend/src/composables/__tests__/useErrorApi.test.ts b/frontend/src/composables/__tests__/useErrorApi.test.ts
index 1374ce373..3512abf2e 100644
--- a/frontend/src/composables/__tests__/useErrorApi.test.ts
+++ b/frontend/src/composables/__tests__/useErrorApi.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 
-// Mock the generated client so we can assert exactly which query params each
+// Mock the generated company so we can assert exactly which query params each
 // branch forwards to the backend.
 const {
   xeroListMock,
diff --git a/frontend/src/composables/__tests__/useOptimizedKanban.test.ts b/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
index 77826482b..e223fd98d 100644
--- a/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
+++ b/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
@@ -184,7 +184,7 @@ function buildKanbanJob(overrides: Partial<Record<string, unknown>> = {}) {
     name: overrides.name ?? '2 X 1.2MM S/S KICK PLATES 910MM (W) X 300MM (H)',
     description: overrides.description ?? '',
     job_number: overrides.job_number ?? 9001,
-    client_name: overrides.client_name ?? 'Weaver, Decker and Schultz',
+    company_name: overrides.company_name ?? 'Weaver, Decker and Schultz',
     contact_person: overrides.contact_person ?? 'Molly Wainwright',
     people: overrides.people ?? [],
     status: overrides.status ?? 'in_progress',
@@ -316,7 +316,7 @@ describe('useOptimizedKanban search reconciliation', () => {
         buildKanbanJob({
           id: 'job-2',
           name: 'Kick plate revision',
-          client_name: 'Different Client',
+          company_name: 'Different Company',
         }),
       ],
     })
@@ -338,7 +338,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       job_number: '',
       name: '',
       description: '',
-      client_name: '',
+      company_name: '',
       contact_person: '',
       created_by: '',
       created_after: '',
@@ -450,7 +450,7 @@ describe('useOptimizedKanban search reconciliation', () => {
     await flushPromises()
 
     second.resolve({
-      jobs: [buildKanbanJob({ id: 'job-2', client_name: 'Weaver, Decker and Schultz' })],
+      jobs: [buildKanbanJob({ id: 'job-2', company_name: 'Weaver, Decker and Schultz' })],
     })
     await flushPromises()
 
@@ -485,7 +485,7 @@ describe('useOptimizedKanban search reconciliation', () => {
 
   it('uses backend reconciliation for multi-token queries the local substring pass cannot match', async () => {
     performAdvancedSearch.mockResolvedValue({
-      jobs: [buildKanbanJob({ id: 'job-2', client_name: 'Weaver, Decker and Schultz' })],
+      jobs: [buildKanbanJob({ id: 'job-2', company_name: 'Weaver, Decker and Schultz' })],
     })
 
     const kanban = await mountHarness()
@@ -504,7 +504,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       job_number: '',
       name: '',
       description: '',
-      client_name: '',
+      company_name: '',
       contact_person: '',
       created_by: '',
       created_after: '',
@@ -518,7 +518,7 @@ describe('useOptimizedKanban search reconciliation', () => {
 
   it('reconciles typo queries from empty local results to backend matches', async () => {
     performAdvancedSearch.mockResolvedValue({
-      jobs: [buildKanbanJob({ id: 'job-3', client_name: 'Weaver, Decker and Schultz' })],
+      jobs: [buildKanbanJob({ id: 'job-3', company_name: 'Weaver, Decker and Schultz' })],
     })
 
     const kanban = await mountHarness()
@@ -537,7 +537,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       job_number: '',
       name: '',
       description: '',
-      client_name: '',
+      company_name: '',
       contact_person: '',
       created_by: '',
       created_after: '',
diff --git a/frontend/src/composables/useClientLookup.ts b/frontend/src/composables/useCompanyLookup.ts
similarity index 54%
rename from frontend/src/composables/useClientLookup.ts
rename to frontend/src/composables/useCompanyLookup.ts
index 85544ae75..b7b0f10f3 100644
--- a/frontend/src/composables/useClientLookup.ts
+++ b/frontend/src/composables/useCompanyLookup.ts
@@ -7,15 +7,15 @@ import { debugLog } from '@/utils/debug'
 import { logSearchResultClick } from '@/services/searchTelemetry.service'
 
 // Use generated schemas, excluding scalar phone fields now owned by contact methods.
-export type Client = Omit<z.infer<typeof schemas.ClientSearchResult>, 'phone'>
+export type Company = Omit<z.infer<typeof schemas.CompanySearchResult>, 'phone'>
 export type ClientContact = Omit<z.infer<typeof schemas.ClientContact>, 'phone'>
 
-type UseClientLookupOptions = {
+type UseCompanyLookupOptions = {
   supplierLookup?: { value: boolean }
 }
 
-export async function logClientSearchClick(
-  client: Client,
+export async function logCompanySearchClick(
+  company: Company,
   query: string,
   rank: number | null,
   source = 'client_lookup',
@@ -29,36 +29,36 @@ export async function logClientSearchClick(
     await logSearchResultClick({
       domain: 'client',
       query: trimmedQuery,
-      selectedResultId: client.id,
-      selectedLabel: client.name,
+      selectedResultId: company.id,
+      selectedLabel: company.name,
       selectedRank: rank,
       source,
     })
   } catch (error) {
-    debugLog('Failed to log client search click:', error)
+    debugLog('Failed to log company search click:', error)
   }
 }
 
-export function useClientLookup(options: UseClientLookupOptions = {}) {
+export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
   const searchQuery = ref('')
-  const suggestions = ref<Client[]>([])
+  const suggestions = ref<Company[]>([])
   const isLoading = ref(false)
   const showSuggestions = ref(false)
-  const selectedClient = ref<Client | null>(null)
+  const selectedCompany = ref<Company | null>(null)
   const contacts = ref<ClientContact[]>([])
 
   const hasValidXeroId = computed(() => {
-    debugLog('Selected client value: ', selectedClient.value)
+    debugLog('Selected company value: ', selectedCompany.value)
     return (
-      selectedClient.value?.xero_contact_id != null && selectedClient.value.xero_contact_id !== ''
+      selectedCompany.value?.xero_contact_id != null && selectedCompany.value.xero_contact_id !== ''
     )
   })
 
   const displayValue = computed(() => {
-    return selectedClient.value?.name || searchQuery.value
+    return selectedCompany.value?.name || searchQuery.value
   })
 
-  const searchClients = async (query: string) => {
+  const searchCompanies = async (query: string) => {
     if (query.length < 3) {
       suggestions.value = []
       showSuggestions.value = false
@@ -72,36 +72,36 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
         ? await api.purchasing_suppliers_search_retrieve({
             queries: { q: query },
           })
-        : await api.clients_search_retrieve({
+        : await api.companies_search_retrieve({
             queries: { q: query },
           })
 
       suggestions.value = response.results
       showSuggestions.value = true
     } catch (error) {
-      console.error('Error searching clients:', error)
+      console.error('Error searching companies:', error)
       suggestions.value = []
       showSuggestions.value = false
-      toast.error('Failed to search clients')
+      toast.error('Failed to search companies')
     } finally {
       isLoading.value = false
     }
   }
 
   /**
-   * Button-triggered client search: no minimum query length, first page of
+   * Button-triggered company search: no minimum query length, first page of
    * results sorted by name. Results land in `suggestions` (same as the
    * typeahead search) for select-style pickers.
    */
-  const browseClients = async () => {
+  const browseCompanies = async () => {
     if (options.supplierLookup?.value) {
-      throw new Error('browseClients does not support supplier lookup')
+      throw new Error('browseCompanies does not support supplier lookup')
     }
 
     isLoading.value = true
 
     try {
-      const response = await api.clients_search_retrieve({
+      const response = await api.companies_search_retrieve({
         queries: {
           page: 1,
           page_size: 20,
@@ -112,9 +112,9 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
       })
       suggestions.value = response.results || []
     } catch (error) {
-      console.error('Error searching clients:', error)
+      console.error('Error searching companies:', error)
       suggestions.value = []
-      toast.error('Failed to search clients')
+      toast.error('Failed to search companies')
     } finally {
       isLoading.value = false
     }
@@ -124,38 +124,38 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
    * Logs search telemetry for a selection made from `suggestions` by id
    * (select-style pickers where the user picks from a dropdown of results).
    */
-  const logSelectedClientClick = (clientId: string, source: string) => {
-    const index = suggestions.value.findIndex((client) => client.id === clientId)
-    const client = suggestions.value[index]
-    if (!client) return
-    void logClientSearchClick(client, searchQuery.value, index + 1, source)
+  const logSelectedCompanyClick = (companyId: string, source: string) => {
+    const index = suggestions.value.findIndex((company) => company.id === companyId)
+    const company = suggestions.value[index]
+    if (!company) return
+    void logCompanySearchClick(company, searchQuery.value, index + 1, source)
   }
 
-  const selectClient = async (client: Client) => {
-    selectedClient.value = client
-    searchQuery.value = client.name
+  const selectCompany = async (company: Company) => {
+    selectedCompany.value = company
+    searchQuery.value = company.name
     showSuggestions.value = false
 
     contacts.value = []
 
-    await loadClientContacts(client.id)
+    await loadClientContacts(company.id)
   }
 
-  const loadClientContacts = async (clientId: string) => {
-    if (!clientId) {
+  const loadClientContacts = async (companyId: string) => {
+    if (!companyId) {
       contacts.value = []
       return
     }
 
     try {
-      const response = await api.clients_contacts_list({
-        queries: { client_id: clientId },
+      const response = await api.companies_contacts_list({
+        queries: { company_id: companyId },
       })
       contacts.value = response || []
     } catch (error) {
-      console.error('Error loading client contacts:', error)
+      console.error('Error loading company contacts:', error)
       contacts.value = []
-      toast.error('Failed to load client contacts')
+      toast.error('Failed to load company contacts')
     }
   }
 
@@ -170,7 +170,7 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
   }
 
   const clearSelection = () => {
-    selectedClient.value = null
+    selectedCompany.value = null
     searchQuery.value = ''
     suggestions.value = []
     showSuggestions.value = false
@@ -178,8 +178,8 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
   }
 
   const resetToInitialState = () => {
-    // Only clear if no client is actually selected
-    if (!selectedClient.value) {
+    // Only clear if no company is actually selected
+    if (!selectedCompany.value) {
       searchQuery.value = ''
       suggestions.value = []
       showSuggestions.value = false
@@ -187,14 +187,14 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
     }
   }
 
-  const preserveSelectedClient = (modelValue?: string) => {
-    debugLog('Preserving selected client from modelValue:', modelValue)
-    // Preserve the selected client when dialog reopens
-    if (selectedClient.value && !searchQuery.value) {
-      searchQuery.value = selectedClient.value.name
-      handleInputChange(selectedClient.value.name)
+  const preserveSelectedCompany = (modelValue?: string) => {
+    debugLog('Preserving selected company from modelValue:', modelValue)
+    // Preserve the selected company when dialog reopens
+    if (selectedCompany.value && !searchQuery.value) {
+      searchQuery.value = selectedCompany.value.name
+      handleInputChange(selectedCompany.value.name)
     }
-    if (modelValue && !selectedClient.value) {
+    if (modelValue && !selectedCompany.value) {
       searchQuery.value = modelValue
       handleInputChange(modelValue, true)
     }
@@ -203,30 +203,30 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
   const handleInputChange = (value: string, fromReload = false) => {
     searchQuery.value = value
 
-    if (selectedClient.value && selectedClient.value.name !== value) {
-      selectedClient.value = null
+    if (selectedCompany.value && selectedCompany.value.name !== value) {
+      selectedCompany.value = null
       contacts.value = []
     }
 
     if (value.length >= 3) {
-      const searchPromise = searchClients(value)
+      const searchPromise = searchCompanies(value)
       if (fromReload) {
         searchPromise
           .then(() => {
-            if (!selectedClient.value && suggestions.value.length > 0) {
+            if (!selectedCompany.value && suggestions.value.length > 0) {
               const normalizedValue = value.trim().toLowerCase()
-              const matchedClient = suggestions.value.find(
-                (client) => client.name.trim().toLowerCase() === normalizedValue,
+              const matchedCompany = suggestions.value.find(
+                (company) => company.name.trim().toLowerCase() === normalizedValue,
               )
 
-              const clientToSelect = matchedClient ?? suggestions.value[0]
-              if (clientToSelect) {
-                selectClient(clientToSelect)
+              const companyToSelect = matchedCompany ?? suggestions.value[0]
+              if (companyToSelect) {
+                selectCompany(companyToSelect)
               }
             }
           })
           .catch((error) => {
-            console.error('Error restoring client selection:', error)
+            console.error('Error restoring company selection:', error)
           })
       }
     } else {
@@ -235,8 +235,8 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
     }
   }
 
-  const createNewClient = (clientName: string) => {
-    return clientName.trim()
+  const createNewCompany = (companyName: string) => {
+    return companyName.trim()
   }
 
   const hideSuggestions = () => {
@@ -248,23 +248,23 @@ export function useClientLookup(options: UseClientLookupOptions = {}) {
     suggestions,
     isLoading,
     showSuggestions,
-    selectedClient,
+    selectedCompany,
     contacts,
 
     hasValidXeroId,
     displayValue,
 
-    searchClients,
-    browseClients,
-    logSelectedClientClick,
-    selectClient,
+    searchCompanies,
+    browseCompanies,
+    logSelectedCompanyClick,
+    selectCompany,
     loadClientContacts,
     getPrimaryContact,
     clearSelection,
     handleInputChange,
-    createNewClient,
+    createNewCompany,
     hideSuggestions,
     resetToInitialState,
-    preserveSelectedClient,
+    preserveSelectedCompany,
   }
 }
diff --git a/frontend/src/composables/useContactManagement.ts b/frontend/src/composables/useContactManagement.ts
index 6b4547716..691c058b2 100644
--- a/frontend/src/composables/useContactManagement.ts
+++ b/frontend/src/composables/useContactManagement.ts
@@ -18,9 +18,9 @@ type ContactFormFields = {
 export type ContactFormData = ContactFormFields
 
 /**
- * Composable for managing client contacts
+ * Composable for managing company contacts
  *
- * Provides functionality for loading, creating, selecting, and managing client contacts.
+ * Provides functionality for loading, creating, selecting, and managing company contacts.
  * Handles modal state, form validation, and API interactions for contact management.
  *
  * @returns Object containing reactive state and methods for contact management
@@ -30,8 +30,8 @@ export function useContactManagement() {
   const contacts = ref<ClientContact[]>([])
   const selectedContact = ref<ClientContact | null>(null)
   const isLoading = ref(false)
-  const currentClientId = ref<string>('')
-  const currentClientName = ref<string>('')
+  const currentCompanyId = ref<string>('')
+  const currentCompanyName = ref<string>('')
 
   const newContactForm = ref<ContactFormData>({
     name: '',
@@ -80,24 +80,24 @@ export function useContactManagement() {
   }
 
   /**
-   * Opens the contact selection modal for a specific client
+   * Opens the contact selection modal for a specific company
    *
-   * @param clientId - The ID of the client to load contacts for
-   * @param clientName - The name of the client (for display purposes)
+   * @param companyId - The ID of the company to load contacts for
+   * @param companyName - The name of the company (for display purposes)
    */
-  const openModal = async (clientId: string, clientName: string) => {
-    if (!clientId) {
-      debugLog('Cannot open contact modal without client ID')
+  const openModal = async (companyId: string, companyName: string) => {
+    if (!companyId) {
+      debugLog('Cannot open contact modal without company ID')
       return
     }
 
-    currentClientId.value = clientId
-    currentClientName.value = clientName
+    currentCompanyId.value = companyId
+    currentCompanyName.value = companyName
     isModalOpen.value = true
 
     resetNewContactForm()
 
-    await loadContacts(clientId)
+    await loadContacts(companyId)
   }
 
   /**
@@ -110,12 +110,12 @@ export function useContactManagement() {
   }
 
   /**
-   * Loads contacts for a specific client from the API
+   * Loads contacts for a specific company from the API
    *
-   * @param clientId - The ID of the client to load contacts for
+   * @param companyId - The ID of the company to load contacts for
    */
-  const loadContacts = async (clientId: string) => {
-    if (!clientId) {
+  const loadContacts = async (companyId: string) => {
+    if (!companyId) {
       contacts.value = []
       newContactForm.value.is_primary = true
       return
@@ -123,8 +123,8 @@ export function useContactManagement() {
 
     isLoading.value = true
     try {
-      const response = await api.clients_contacts_list({
-        queries: { client_id: clientId },
+      const response = await api.companies_contacts_list({
+        queries: { company_id: companyId },
       })
       contacts.value = response || []
       newContactForm.value.is_primary = contacts.value.length === 0
@@ -138,12 +138,12 @@ export function useContactManagement() {
   }
 
   /**
-   * Loads contacts for a client without opening the modal
+   * Loads contacts for a company without opening the modal
    *
-   * @param clientId - The ID of the client to load contacts for
+   * @param companyId - The ID of the company to load contacts for
    */
-  const loadContactsOnly = async (clientId: string) => {
-    await loadContacts(clientId)
+  const loadContactsOnly = async (companyId: string) => {
+    await loadContacts(companyId)
   }
 
   /**
@@ -168,16 +168,16 @@ export function useContactManagement() {
   }
 
   /**
-   * Creates a new contact for the current client
+   * Creates a new contact for the current company
    *
-   * Automatically sets the contact as primary if it's the first contact for the client.
+   * Automatically sets the contact as primary if it's the first contact for the company.
    * After creation, reloads the contacts list and selects the newly created contact.
    *
    * @returns Promise<boolean> - True if contact was created successfully, false otherwise
    */
   const createNewContact = async (): Promise<boolean> => {
-    if (!currentClientId.value) {
-      debugLog('Cannot create contact without client ID')
+    if (!currentCompanyId.value) {
+      debugLog('Cannot create contact without company ID')
       return false
     }
 
@@ -189,7 +189,7 @@ export function useContactManagement() {
     isLoading.value = true
 
     try {
-      // If this is the first contact for the client, automatically make it primary
+      // If this is the first contact for the company, automatically make it primary
       const shouldBePrimary = newContactForm.value.is_primary || contacts.value.length === 0
 
       const trimmedPosition = newContactForm.value.position?.trim()
@@ -197,7 +197,7 @@ export function useContactManagement() {
       const trimmedNotes = newContactForm.value.notes?.trim()
 
       const contactData: ContactCreateRequest = {
-        client: currentClientId.value,
+        company: currentCompanyId.value,
         name: newContactForm.value.name.trim(),
         is_primary: shouldBePrimary,
         position: trimmedPosition || undefined,
@@ -207,7 +207,7 @@ export function useContactManagement() {
 
       debugLog('Creating new contact:', contactData)
 
-      const response = await api.clients_contacts_create(contactData)
+      const response = await api.companies_contacts_create(contactData)
 
       if (!response || !response.id) {
         throw new Error('Invalid response from server')
@@ -218,7 +218,7 @@ export function useContactManagement() {
       debugLog('Contact created successfully:', newContact)
 
       // Reload contacts first to get the updated list
-      await loadContacts(currentClientId.value)
+      await loadContacts(currentCompanyId.value)
 
       // Then find and select the newly created contact
       const createdContact = contacts.value.find((contact) => contact.id === newContact.id)
@@ -307,14 +307,14 @@ export function useContactManagement() {
 
       debugLog('Updating contact:', editingContact.value.id, contactData)
 
-      await api.clients_contacts_partial_update(contactData, {
+      await api.companies_contacts_partial_update(contactData, {
         params: { id: editingContact.value.id },
       })
 
       debugLog('Contact updated successfully')
 
       // Reload contacts to get updated list
-      await loadContacts(currentClientId.value)
+      await loadContacts(currentCompanyId.value)
 
       // If the updated contact was selected, update the selection
       if (selectedContact.value?.id === editingContact.value.id) {
@@ -352,14 +352,14 @@ export function useContactManagement() {
     try {
       debugLog('Deleting contact:', contactId)
 
-      await api.clients_contacts_destroy(undefined, {
+      await api.companies_contacts_destroy(undefined, {
         params: { id: contactId },
       })
 
       debugLog('Contact deleted successfully')
 
       // Reload contacts to get updated list (inactive contacts filtered out)
-      await loadContacts(currentClientId.value)
+      await loadContacts(currentCompanyId.value)
 
       // Clear selection if deleted contact was selected
       if (selectedContact.value?.id === contactId) {
@@ -439,7 +439,7 @@ export function useContactManagement() {
     contacts,
     selectedContact,
     isLoading,
-    currentClientName,
+    currentCompanyName,
     newContactForm,
 
     // Edit mode state
diff --git a/frontend/src/composables/useJobAutosave.ts b/frontend/src/composables/useJobAutosave.ts
index 829b25bb7..58aecfb1d 100644
--- a/frontend/src/composables/useJobAutosave.ts
+++ b/frontend/src/composables/useJobAutosave.ts
@@ -285,7 +285,7 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
     const rawPatch: Record<string, unknown> = {}
     for (const [k, v] of changeBuffer.entries()) rawPatch[k] = v
 
-    if ('client_id' in rawPatch) {
+    if ('company_id' in rawPatch) {
       rawPatch['contact_id'] = null
       rawPatch['contact_name'] = null
       pendingKeys.value.add('contact_id')
@@ -308,7 +308,7 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
       return
     }
 
-    if ('client_id' in effectivePatch) {
+    if ('company_id' in effectivePatch) {
       if (!('contact_id' in effectivePatch)) effectivePatch['contact_id'] = null
       if (!('contact_name' in effectivePatch)) effectivePatch['contact_name'] = null
     }
@@ -317,9 +317,9 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
     const virtualSnapshot = { ...originalSnapshot, ...effectivePatch }
     if (
       ('contact_id' in effectivePatch || 'contact_name' in effectivePatch) &&
-      !virtualSnapshot['client_id']
+      !virtualSnapshot['company_id']
     ) {
-      log('⛔ canSave=false (contact_* change without client_id)', { reason })
+      log('⛔ canSave=false (contact_* change without company_id)', { reason })
       return
     }
 
diff --git a/frontend/src/composables/useJobHeaderAutosave.ts b/frontend/src/composables/useJobHeaderAutosave.ts
index e3650ab1f..272174ffa 100644
--- a/frontend/src/composables/useJobHeaderAutosave.ts
+++ b/frontend/src/composables/useJobHeaderAutosave.ts
@@ -46,8 +46,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
   const headerToPartialHeaderPatch = (patch: Partial<Job>): Partial<JobHeaderResponse> => {
     const p: Partial<JobHeaderResponse> = {}
     if ('name' in patch) p.name = patch.name as string
-    if ('client_id' in patch) p.client_id = patch.client_id as string | null
-    if ('client_name' in patch) p.client_name = patch.client_name as string | null
+    if ('company_id' in patch) p.company_id = patch.company_id as string | null
+    if ('company_name' in patch) p.company_name = patch.company_name as string | null
     if ('job_status' in patch)
       p.status = (patch.job_status as JobStatusKey | undefined) ?? undefined
     if ('pricing_methodology' in patch)
@@ -64,7 +64,7 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
   /**
    * Applies a patch (based on "local" fields reflected from header) to the header snapshot.
-   * Accepts keys: name, client_id, client_name, job_status, pricing_methodology, quoted, fully_invoiced, paid.
+   * Accepts keys: name, company_id, company_name, job_status, pricing_methodology, quoted, fully_invoiced, paid.
    * Here we do the inverse mapping (local fields -> header).
    */
   const applyPatchToHeader = (base: JobHeaderResponse, patch: Partial<Job>): JobHeaderResponse => {
@@ -76,14 +76,14 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
     return {
       ...base,
       name: patch.name ?? base.name,
-      client_id:
-        patch.client_id !== undefined
-          ? ((patch.client_id as string | null) ?? null)
-          : base.client_id,
-      client_name:
-        patch.client_name !== undefined
-          ? ((patch.client_name as string | null) ?? null)
-          : base.client_name,
+      company_id:
+        patch.company_id !== undefined
+          ? ((patch.company_id as string | null) ?? null)
+          : base.company_id,
+      company_name:
+        patch.company_name !== undefined
+          ? ((patch.company_name as string | null) ?? null)
+          : base.company_name,
       status,
       pricing_methodology:
         (patch.pricing_methodology as PricingMethodology | undefined) ?? base.pricing_methodology,
@@ -133,7 +133,7 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
             const allowedHeaderKeys = [
               'name',
-              'client_id',
+              'company_id',
               'job_status',
               'pricing_methodology',
               'quoted',
@@ -156,7 +156,7 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
             const payloadJob: Record<string, unknown> = { ...filteredPatch }
 
-            if ('client_id' in (filteredPatch as Partial<Job>)) {
+            if ('company_id' in (filteredPatch as Partial<Job>)) {
               payloadJob.contact_id = null
               payloadJob.contact_name = null
             }
@@ -171,8 +171,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
                 case 'name':
                   beforeValues[field] = headerSnapshot.name
                   break
-                case 'client_id':
-                  beforeValues[field] = headerSnapshot.client_id ?? null
+                case 'company_id':
+                  beforeValues[field] = headerSnapshot.company_id ?? null
                   break
                 case 'rejected_flag':
                   beforeValues[field] = headerSnapshot.rejected_flag ?? false
@@ -285,15 +285,15 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
   // Handlers that UI uses (everything in terms of "local" fields that map well to Job)
   const handleNameUpdate = (name: string) => enqueue('name', name)
-  const handleClientUpdate = (client: { id: string; name: string }) => {
+  const handleCompanyUpdate = (company: { id: string; name: string }) => {
     if (!headerRef.value || !autosave) return
     autosave.queueChanges({
-      client_id: client.id,
-      client_name: client.name,
+      company_id: company.id,
+      company_name: company.name,
       contact_id: null,
       contact_name: null,
     })
-    void autosave.flush('client-change')
+    void autosave.flush('company-change')
   }
   const handleStatusUpdate = (newStatus: JobStatusKey) => enqueue('job_status', newStatus)
   const handlePricingMethodologyUpdate = (method: PricingMethodology | null) =>
@@ -348,7 +348,7 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
     localHeader: localHeaderComputed,
     // setters
     handleNameUpdate,
-    handleClientUpdate,
+    handleCompanyUpdate,
     handleStatusUpdate,
     handlePricingMethodologyUpdate,
     handleQuotedUpdate,
diff --git a/frontend/src/composables/useJobNotifications.ts b/frontend/src/composables/useJobNotifications.ts
index c548aa4d9..11608102f 100644
--- a/frontend/src/composables/useJobNotifications.ts
+++ b/frontend/src/composables/useJobNotifications.ts
@@ -38,7 +38,7 @@ export function useJobNotifications() {
 
   const notifyQuoteAccepted = () => {
     toast.success('Quote accepted', {
-      description: 'Quote was accepted by the client',
+      description: 'Quote was accepted by the company',
     })
   }
 
diff --git a/frontend/src/composables/useOptimizedKanban.ts b/frontend/src/composables/useOptimizedKanban.ts
index 2dad7d3da..0bc0a4f26 100644
--- a/frontend/src/composables/useOptimizedKanban.ts
+++ b/frontend/src/composables/useOptimizedKanban.ts
@@ -183,7 +183,7 @@ export function useOptimizedKanban(onJobsLoaded?: () => void) {
       return (
         job.name?.toLowerCase().includes(normalizedQuery) ||
         job.description?.toLowerCase().includes(normalizedQuery) ||
-        job.client_name?.toLowerCase().includes(normalizedQuery) ||
+        job.company_name?.toLowerCase().includes(normalizedQuery) ||
         String(job.job_number).toLowerCase().includes(normalizedQuery) ||
         job.contact_person?.toLowerCase().includes(normalizedQuery)
       )
@@ -1065,7 +1065,7 @@ export function useOptimizedKanban(onJobsLoaded?: () => void) {
         metadata: {
           job_number: job.job_number,
           status: job.status,
-          client_name: job.client_name,
+          company_name: job.company_name,
         },
       })
     }
diff --git a/frontend/src/composables/usePickupAddressManagement.ts b/frontend/src/composables/usePickupAddressManagement.ts
index e07e62a04..92f77dd23 100644
--- a/frontend/src/composables/usePickupAddressManagement.ts
+++ b/frontend/src/composables/usePickupAddressManagement.ts
@@ -131,7 +131,7 @@ export function usePickupAddressManagement() {
 
     isLoading.value = true
     try {
-      const response = await api.clients_pickup_addresses_list({
+      const response = await api.companies_pickup_addresses_list({
         queries: { supplier_id: supplierId },
       })
       addresses.value = response || []
@@ -187,7 +187,7 @@ export function usePickupAddressManagement() {
     }
 
     try {
-      const response = await api.clients_addresses_validate_create({
+      const response = await api.companies_addresses_validate_create({
         address: addressQuery.trim(),
       })
       return response.candidates || []
@@ -253,7 +253,7 @@ export function usePickupAddressManagement() {
       const shouldBePrimary = newAddressForm.value.is_primary || addresses.value.length === 0
 
       const addressData: AddressCreateRequest = {
-        client: currentSupplierId.value,
+        company: currentSupplierId.value,
         name: newAddressForm.value.name.trim(),
         street: newAddressForm.value.street.trim(),
         suburb: newAddressForm.value.suburb?.trim() || undefined,
@@ -270,7 +270,7 @@ export function usePickupAddressManagement() {
 
       debugLog('Creating new address:', addressData)
 
-      const response = await api.clients_pickup_addresses_create(addressData)
+      const response = await api.companies_pickup_addresses_create(addressData)
 
       if (!response || !response.id) {
         throw new Error('Invalid response from server')
@@ -372,7 +372,7 @@ export function usePickupAddressManagement() {
 
     try {
       const addressData: AddressUpdateRequest = {
-        client: currentSupplierId.value,
+        company: currentSupplierId.value,
         name: newAddressForm.value.name.trim(),
         street: newAddressForm.value.street.trim(),
         suburb: newAddressForm.value.suburb?.trim() || null,
@@ -389,7 +389,7 @@ export function usePickupAddressManagement() {
 
       debugLog('Updating address:', editingAddress.value.id, addressData)
 
-      await api.clients_pickup_addresses_partial_update(addressData, {
+      await api.companies_pickup_addresses_partial_update(addressData, {
         params: { id: editingAddress.value.id },
       })
 
@@ -434,7 +434,7 @@ export function usePickupAddressManagement() {
     try {
       debugLog('Deleting address:', addressId)
 
-      await api.clients_pickup_addresses_destroy(undefined, {
+      await api.companies_pickup_addresses_destroy(undefined, {
         params: { id: addressId },
       })
 
diff --git a/frontend/src/composables/useWorkshopTimesheetJobs.ts b/frontend/src/composables/useWorkshopTimesheetJobs.ts
index 5261c127b..38ec2bb7d 100644
--- a/frontend/src/composables/useWorkshopTimesheetJobs.ts
+++ b/frontend/src/composables/useWorkshopTimesheetJobs.ts
@@ -16,8 +16,8 @@ export function useWorkshopTimesheetJobs() {
     return jobs.value.filter((job) => {
       const number = String(job.job_number).toLowerCase()
       const name = (job.name || '').toLowerCase()
-      const client = (job.client_name || '').toLowerCase()
-      return number.includes(term) || name.includes(term) || client.includes(term)
+      const company = (job.company_name || '').toLowerCase()
+      return number.includes(term) || name.includes(term) || company.includes(term)
     })
   })
 
diff --git a/frontend/src/constants/advanced-filters.ts b/frontend/src/constants/advanced-filters.ts
index 11c3b2784..7d3905da2 100644
--- a/frontend/src/constants/advanced-filters.ts
+++ b/frontend/src/constants/advanced-filters.ts
@@ -15,7 +15,7 @@ export const AdvancedFiltersSchema = z.object({
   job_number: z.string().optional().default(''),
   name: z.string().optional().default(''),
   description: z.string().optional().default(''),
-  client_name: z.string().optional().default(''),
+  company_name: z.string().optional().default(''),
   contact_person: z.string().optional().default(''),
   created_by: z.string().optional().default(''),
   status: z.array(z.string()).optional().default([]),
@@ -36,7 +36,7 @@ export const DEFAULT_ADVANCED_FILTERS: AdvancedFilters = {
   job_number: '',
   name: '',
   description: '',
-  client_name: '',
+  company_name: '',
   contact_person: '',
   created_by: '',
   status: [],
diff --git a/frontend/src/constants/client-wrapper.ts b/frontend/src/constants/company-wrapper.ts
similarity index 70%
rename from frontend/src/constants/client-wrapper.ts
rename to frontend/src/constants/company-wrapper.ts
index f116adaba..61d6f1604 100644
--- a/frontend/src/constants/client-wrapper.ts
+++ b/frontend/src/constants/company-wrapper.ts
@@ -7,11 +7,11 @@
 import { z } from 'zod'
 import { schemas } from '@/api/generated/api'
 
-export const CreateClientResponseSchema = z.object({
+export const CreateCompanyResponseSchema = z.object({
   success: z.boolean(),
-  client: schemas.ClientSearchResult.optional(),
+  company: schemas.CompanySearchResult.optional(),
   error: z.string().optional(),
   message: z.string().optional(),
 })
 
-export type CreateClientResponse = z.infer<typeof CreateClientResponseSchema>
+export type CreateCompanyResponse = z.infer<typeof CreateCompanyResponseSchema>
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index 25b293bea..cf7bc0d84 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -35,7 +35,7 @@
                 <Input
                   v-model="searchQuery"
                   class="pl-9"
-                  placeholder="Search number, client, contact, job, or description"
+                  placeholder="Search number, company, contact, job, or description"
                   @keydown.enter.prevent="loadCalls"
                 />
               </div>
@@ -95,11 +95,11 @@
 
           <div class="grid grid-cols-1 gap-3 lg:grid-cols-[1fr_auto]">
             <Input
-              v-model="clientSearch"
-              placeholder="Search clients"
-              @keydown.enter.prevent="searchClients"
+              v-model="companySearch"
+              placeholder="Search companies"
+              @keydown.enter.prevent="searchCompanies"
             />
-            <Button variant="outline" type="button" @click="searchClients">
+            <Button variant="outline" type="button" @click="searchCompanies">
               <Search class="mr-2 h-4 w-4" />
               Search
             </Button>
@@ -107,19 +107,19 @@
 
           <div class="grid grid-cols-1 gap-3 md:grid-cols-2">
             <select
-              v-model="selectedClientId"
+              v-model="selectedCompanyId"
               class="rounded-md border border-gray-300 p-2 text-sm"
-              @change="logAssignClientSearchClick"
+              @change="logAssignCompanySearchClick"
             >
-              <option value="">Select client</option>
-              <option v-for="client in clientOptions" :key="client.id" :value="client.id">
-                {{ client.name }}
+              <option value="">Select company</option>
+              <option v-for="company in companyOptions" :key="company.id" :value="company.id">
+                {{ company.name }}
               </option>
             </select>
             <select
               v-model="selectedContactId"
               class="rounded-md border border-gray-300 p-2 text-sm"
-              :disabled="!selectedClientId"
+              :disabled="!selectedCompanyId"
             >
               <option value="">No specific contact</option>
               <option v-for="contact in contactOptions" :key="contact.id" :value="contact.id">
@@ -138,7 +138,7 @@
             </label>
             <Button
               type="button"
-              :disabled="isAssigningNumber || !selectedClientId"
+              :disabled="isAssigningNumber || !selectedCompanyId"
               @click="assignSelectedCallNumber"
             >
               <Loader2 v-if="isAssigningNumber" class="mr-2 h-4 w-4 animate-spin" />
@@ -169,7 +169,7 @@ import { Input } from '@/components/ui/input'
 import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
 import { api } from '@/api/client'
 import { schemas } from '@/api/generated/api'
-import { useClientLookup } from '@/composables/useClientLookup'
+import { useCompanyLookup } from '@/composables/useCompanyLookup'
 import { dataFreshness } from '@/composables/useDataFreshness'
 import { formatDateTime } from '@/utils/string-formatting'
 import { Loader2, RefreshCw, Search } from 'lucide-vue-next'
@@ -199,7 +199,7 @@ const searchQuery = ref('')
 const directionFilter = ref<DirectionFilter>('all')
 const recordingsOnly = ref(false)
 const selectedCall = ref<PhoneCallRecord | null>(null)
-const selectedClientId = ref('')
+const selectedCompanyId = ref('')
 const selectedContactId = ref('')
 const phoneLabel = ref('')
 const isPrimary = ref(false)
@@ -207,13 +207,13 @@ const isAssigningNumber = ref(false)
 let unsubscribeCrmCallsFreshness: (() => void) | null = null
 
 const {
-  searchQuery: clientSearch,
-  suggestions: clientOptions,
+  searchQuery: companySearch,
+  suggestions: companyOptions,
   contacts: contactOptions,
-  browseClients: searchClients,
+  browseCompanies: searchCompanies,
   loadClientContacts,
-  logSelectedClientClick,
-} = useClientLookup()
+  logSelectedCompanyClick,
+} = useCompanyLookup()
 
 const QUEUE_META: Record<CallsTab, { title: string; description: string }> = {
   recent: {
@@ -223,11 +223,11 @@ const QUEUE_META: Record<CallsTab, { title: string; description: string }> = {
   unmatched: {
     title: 'Unmatched Calls',
     description:
-      'Assign these numbers to clients or contacts so future and historical calls land in the right CRM history.',
+      'Assign these numbers to companies or contacts so future and historical calls land in the right CRM history.',
   },
   unlinked: {
     title: 'Matched Calls Needing Job Link',
-    description: 'These calls already belong to a client but have not been linked to a job.',
+    description: 'These calls already belong to a company but have not been linked to a job.',
   },
   all: {
     title: 'All Calls',
@@ -278,13 +278,13 @@ async function loadCalls(): Promise<void> {
 
 function handleAssignNumber(call: PhoneCallRecord): void {
   selectedCall.value = call
-  selectedClientId.value = ''
+  selectedCompanyId.value = ''
   selectedContactId.value = ''
   phoneLabel.value = ''
   isPrimary.value = false
-  clientOptions.value = []
+  companyOptions.value = []
   contactOptions.value = []
-  toast.info('Select a client for this call number')
+  toast.info('Select a company for this call number')
 }
 
 function handleCallUpdated(updatedCall?: PhoneCallRecord): void {
@@ -296,17 +296,17 @@ function handleCallUpdated(updatedCall?: PhoneCallRecord): void {
   void loadCalls()
 }
 
-function logAssignClientSearchClick(): void {
-  logSelectedClientClick(selectedClientId.value, 'crm_calls_assign_number')
+function logAssignCompanySearchClick(): void {
+  logSelectedCompanyClick(selectedCompanyId.value, 'crm_calls_assign_number')
 }
 
 async function assignSelectedCallNumber(): Promise<void> {
-  if (!selectedCall.value || !selectedClientId.value || isAssigningNumber.value) return
+  if (!selectedCall.value || !selectedCompanyId.value || isAssigningNumber.value) return
   isAssigningNumber.value = true
   try {
     const updatedCall = await api.assignPhoneCallNumber(
       {
-        client: selectedClientId.value,
+        company: selectedCompanyId.value,
         contact: selectedContactId.value || null,
         label: phoneLabel.value,
         is_primary: isPrimary.value,
@@ -327,10 +327,10 @@ async function assignSelectedCallNumber(): Promise<void> {
 
 function resetAssignmentForm(): void {
   selectedCall.value = null
-  clientSearch.value = ''
-  clientOptions.value = []
+  companySearch.value = ''
+  companyOptions.value = []
   contactOptions.value = []
-  selectedClientId.value = ''
+  selectedCompanyId.value = ''
   selectedContactId.value = ''
   phoneLabel.value = ''
   isPrimary.value = false
@@ -344,11 +344,11 @@ watch([activeTab, directionFilter, recordingsOnly], () => {
   void loadCalls()
 })
 
-watch(selectedClientId, (clientId) => {
-  if (!clientId) {
+watch(selectedCompanyId, (companyId) => {
+  if (!companyId) {
     selectedContactId.value = ''
   }
-  void loadClientContacts(clientId)
+  void loadClientContacts(companyId)
 })
 
 onMounted(() => {
diff --git a/frontend/src/pages/crm/clients/(index).vue b/frontend/src/pages/crm/companies/(index).vue
similarity index 58%
rename from frontend/src/pages/crm/clients/(index).vue
rename to frontend/src/pages/crm/companies/(index).vue
index bfac72174..8f296f916 100644
--- a/frontend/src/pages/crm/clients/(index).vue
+++ b/frontend/src/pages/crm/companies/(index).vue
@@ -5,11 +5,11 @@
       <div class="flex flex-col sm:flex-row items-start sm:items-center justify-between gap-4">
         <h1 class="text-xl font-bold flex items-center gap-2">
           <Users class="w-6 h-6 text-indigo-600" />
-          Clients
+          Companies
         </h1>
         <Button @click="openCreateModal">
           <PlusCircle class="w-4 h-4 mr-2" />
-          New Client
+          New Company
         </Button>
       </div>
 
@@ -19,36 +19,36 @@
         <input
           v-model="searchInput"
           type="text"
-          placeholder="Search clients by name or email..."
-          data-automation-id="ClientsTable-search"
+          placeholder="Search companies by name or email..."
+          data-automation-id="CompaniesTable-search"
           class="w-full pl-10 pr-4 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-indigo-500 focus:border-transparent"
           @input="onSearchInput"
         />
       </div>
 
       <!-- Loading State -->
-      <div v-if="clientStore.isLoading" class="flex items-center justify-center py-12">
+      <div v-if="companyStore.isLoading" class="flex items-center justify-center py-12">
         <Loader2 class="w-8 h-8 animate-spin text-indigo-600" />
-        <span class="ml-3 text-gray-600">Loading clients...</span>
+        <span class="ml-3 text-gray-600">Loading companies...</span>
       </div>
 
-      <!-- No Clients -->
+      <!-- No Companies -->
       <div
-        v-else-if="!clientStore.hasClients && !clientStore.searchQuery"
+        v-else-if="!companyStore.hasCompanies && !companyStore.searchQuery"
         class="text-center py-12 text-gray-500"
       >
         <Users class="w-12 h-12 mx-auto mb-4 text-gray-400" />
-        <p class="text-lg font-medium">No clients yet</p>
-        <p class="text-sm">Click "New Client" to add your first client</p>
+        <p class="text-lg font-medium">No companies yet</p>
+        <p class="text-sm">Click "New Company" to add your first company</p>
       </div>
 
       <!-- No Results after search -->
       <div
-        v-else-if="!clientStore.hasClients && clientStore.searchQuery"
+        v-else-if="!companyStore.hasCompanies && companyStore.searchQuery"
         class="text-center py-12 text-gray-500"
       >
         <Search class="w-12 h-12 mx-auto mb-4 text-gray-400" />
-        <p class="text-lg font-medium">No clients found</p>
+        <p class="text-lg font-medium">No companies found</p>
         <p class="text-sm">Try a different search term</p>
       </div>
 
@@ -56,27 +56,27 @@
       <div v-else class="space-y-4">
         <div class="text-sm text-gray-600">
           {{
-            clientStore.searchQuery
-              ? `Found ${clientStore.totalCount}`
-              : `Showing ${clientStore.totalCount}`
+            companyStore.searchQuery
+              ? `Found ${companyStore.totalCount}`
+              : `Showing ${companyStore.totalCount}`
           }}
-          client{{ clientStore.totalCount !== 1 ? 's' : '' }}
+          company{{ companyStore.totalCount !== 1 ? 's' : '' }}
         </div>
 
         <div class="overflow-y-auto max-h-[70vh] rounded-2xl shadow-lg border border-gray-200">
-          <table class="min-w-full text-sm" data-automation-id="ClientsTable-table">
+          <table class="min-w-full text-sm" data-automation-id="CompaniesTable-table">
             <thead class="bg-slate-50 border-b sticky top-0">
               <tr>
                 <th class="p-3 text-left">
                   <button
                     @click="toggleSort('name')"
-                    data-automation-id="ClientsTable-header-name"
+                    data-automation-id="CompaniesTable-header-name"
                     class="flex items-center gap-1 font-semibold text-gray-700 hover:text-indigo-600 transition-colors cursor-pointer"
                   >
-                    Client Name
-                    <ArrowUpDown v-if="clientStore.sortBy !== 'name'" class="w-4 h-4" />
+                    Company Name
+                    <ArrowUpDown v-if="companyStore.sortBy !== 'name'" class="w-4 h-4" />
                     <ArrowUp
-                      v-else-if="clientStore.sortDir === 'asc'"
+                      v-else-if="companyStore.sortDir === 'asc'"
                       class="w-4 h-4 text-indigo-600"
                     />
                     <ArrowDown v-else class="w-4 h-4 text-indigo-600" />
@@ -86,13 +86,13 @@
                 <th class="p-3 text-left">
                   <button
                     @click="toggleSort('total_spend')"
-                    data-automation-id="ClientsTable-header-total-spend"
+                    data-automation-id="CompaniesTable-header-total-spend"
                     class="flex items-center gap-1 font-semibold text-gray-700 hover:text-indigo-600 transition-colors cursor-pointer"
                   >
                     Total Spend
-                    <ArrowUpDown v-if="clientStore.sortBy !== 'total_spend'" class="w-4 h-4" />
+                    <ArrowUpDown v-if="companyStore.sortBy !== 'total_spend'" class="w-4 h-4" />
                     <ArrowUp
-                      v-else-if="clientStore.sortDir === 'asc'"
+                      v-else-if="companyStore.sortDir === 'asc'"
                       class="w-4 h-4 text-indigo-600"
                     />
                     <ArrowDown v-else class="w-4 h-4 text-indigo-600" />
@@ -101,16 +101,16 @@
                 <th class="p-3 text-left">
                   <button
                     @click="toggleSort('last_invoice_date')"
-                    data-automation-id="ClientsTable-header-last-invoice"
+                    data-automation-id="CompaniesTable-header-last-invoice"
                     class="flex items-center gap-1 font-semibold text-gray-700 hover:text-indigo-600 transition-colors cursor-pointer"
                   >
                     Last Invoice
                     <ArrowUpDown
-                      v-if="clientStore.sortBy !== 'last_invoice_date'"
+                      v-if="companyStore.sortBy !== 'last_invoice_date'"
                       class="w-4 h-4"
                     />
                     <ArrowUp
-                      v-else-if="clientStore.sortDir === 'asc'"
+                      v-else-if="companyStore.sortDir === 'asc'"
                       class="w-4 h-4 text-indigo-600"
                     />
                     <ArrowDown v-else class="w-4 h-4 text-indigo-600" />
@@ -121,40 +121,40 @@
             </thead>
             <tbody>
               <tr
-                v-for="(client, index) in clientStore.clients"
-                :key="client.id"
+                v-for="(company, index) in companyStore.companies"
+                :key="company.id"
                 class="border-b hover:bg-slate-50 cursor-pointer transition-colors"
-                :data-automation-id="`ClientsTable-row-${client.id}`"
-                :data-client-id="client.id"
-                @click="navigateToClient(client, index + 1)"
+                :data-automation-id="`CompaniesTable-row-${company.id}`"
+                :data-company-id="company.id"
+                @click="navigateToCompany(company, index + 1)"
               >
                 <td
                   class="p-3 font-medium text-gray-900"
-                  :data-automation-id="`ClientsTable-cell-${client.id}-name`"
+                  :data-automation-id="`CompaniesTable-cell-${company.id}-name`"
                 >
-                  {{ client.name }}
+                  {{ company.name }}
                 </td>
                 <td
                   class="p-3 text-gray-600"
-                  :data-automation-id="`ClientsTable-cell-${client.id}-email`"
+                  :data-automation-id="`CompaniesTable-cell-${company.id}-email`"
                 >
-                  {{ client.email || '-' }}
+                  {{ company.email || '-' }}
                 </td>
                 <td
                   class="p-3 text-gray-900 font-medium"
-                  :data-automation-id="`ClientsTable-cell-${client.id}-total-spend`"
+                  :data-automation-id="`CompaniesTable-cell-${company.id}-total-spend`"
                 >
-                  {{ client.total_spend || '$0.00' }}
+                  {{ company.total_spend || '$0.00' }}
                 </td>
                 <td
                   class="p-3 text-gray-600"
-                  :data-automation-id="`ClientsTable-cell-${client.id}-last-invoice`"
+                  :data-automation-id="`CompaniesTable-cell-${company.id}-last-invoice`"
                 >
-                  {{ formatDate(client.last_invoice_date) }}
+                  {{ formatDate(company.last_invoice_date) }}
                 </td>
-                <td class="p-3" :data-automation-id="`ClientsTable-cell-${client.id}-type`">
-                  <Badge :variant="client.is_account_customer ? 'default' : 'secondary'">
-                    {{ client.is_account_customer ? 'Account' : 'Cash' }}
+                <td class="p-3" :data-automation-id="`CompaniesTable-cell-${company.id}-type`">
+                  <Badge :variant="company.is_account_customer ? 'default' : 'secondary'">
+                    {{ company.is_account_customer ? 'Account' : 'Cash' }}
                   </Badge>
                 </td>
               </tr>
@@ -164,19 +164,19 @@
 
         <!-- Pagination -->
         <Pagination
-          v-if="clientStore.totalPages > 1"
+          v-if="companyStore.totalPages > 1"
           v-model:page="currentPage"
-          :total="clientStore.totalPages"
+          :total="companyStore.totalPages"
           :sibling-count="1"
         />
       </div>
     </div>
 
-    <!-- Create Client Modal -->
-    <CreateClientModal
+    <!-- Create Company Modal -->
+    <CreateCompanyModal
       :is-open="isCreateModalOpen"
       @close="isCreateModalOpen = false"
-      @client-created="handleClientCreated"
+      @company-created="handleCompanyCreated"
     />
   </AppLayout>
 </template>
@@ -184,12 +184,12 @@
 <script setup lang="ts">
 import { ref, watch, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
-import { useClientStore } from '@/stores/clientStore'
-import { logClientSearchClick } from '@/composables/useClientLookup'
-import type { Client } from '@/composables/useClientLookup'
+import { useCompanyStore } from '@/stores/companyStore'
+import { logCompanySearchClick } from '@/composables/useCompanyLookup'
+import type { Company } from '@/composables/useCompanyLookup'
 import { useDebounceFn } from '@vueuse/core'
 import AppLayout from '@/components/AppLayout.vue'
-import CreateClientModal from '@/components/CreateClientModal.vue'
+import CreateCompanyModal from '@/components/CreateCompanyModal.vue'
 import { Button } from '@/components/ui/button'
 import { Badge } from '@/components/ui/badge'
 import Pagination from '@/components/ui/pagination/Pagination.vue'
@@ -206,7 +206,7 @@ import { toast } from 'vue-sonner'
 import { formatDate } from '@/utils/string-formatting'
 
 const router = useRouter()
-const clientStore = useClientStore()
+const companyStore = useCompanyStore()
 
 // Local state
 const searchInput = ref('')
@@ -216,7 +216,7 @@ const currentPage = ref(1)
 // Debounced search
 const debouncedSearch = useDebounceFn(async (query: string) => {
   currentPage.value = 1
-  await clientStore.fetchClients({ query, page: 1 })
+  await companyStore.fetchCompanies({ query, page: 1 })
 }, 300)
 
 function onSearchInput() {
@@ -229,50 +229,50 @@ type SortField = 'name' | 'total_spend' | 'last_invoice_date'
 async function toggleSort(field: SortField) {
   let newDir: 'asc' | 'desc' = 'asc'
 
-  if (clientStore.sortBy === field) {
+  if (companyStore.sortBy === field) {
     // Same field - toggle direction
-    newDir = clientStore.sortDir === 'asc' ? 'desc' : 'asc'
+    newDir = companyStore.sortDir === 'asc' ? 'desc' : 'asc'
   }
 
-  await clientStore.fetchClients({ sortBy: field, sortDir: newDir, page: 1 })
+  await companyStore.fetchCompanies({ sortBy: field, sortDir: newDir, page: 1 })
   currentPage.value = 1
 }
 
 // Page change - server-side
 watch(currentPage, async (newPage) => {
-  await clientStore.fetchClients({ page: newPage })
+  await companyStore.fetchCompanies({ page: newPage })
   window.scrollTo({ top: 0, behavior: 'smooth' })
 })
 
-function navigateToClient(client: Client, rank: number) {
-  logClientSearchClick(client, clientStore.searchQuery, rank, 'crm_clients_table')
-  router.push({ name: '/crm/clients/[id]', params: { id: client.id } })
+function navigateToCompany(company: Company, rank: number) {
+  logCompanySearchClick(company, companyStore.searchQuery, rank, 'crm_clients_table')
+  router.push({ name: '/crm/companies/[id]', params: { id: company.id } })
 }
 
 function openCreateModal() {
   isCreateModalOpen.value = true
 }
 
-async function handleClientCreated(client: { id?: string }) {
+async function handleCompanyCreated(company: { id?: string }) {
   isCreateModalOpen.value = false
-  toast.success('Client created successfully')
+  toast.success('Company created successfully')
 
-  // Reload current page to include the new client
-  await clientStore.fetchClients({})
+  // Reload current page to include the new company
+  await companyStore.fetchCompanies({})
 
-  // Optionally navigate to the new client
-  if (client?.id) {
-    router.push({ name: '/crm/clients/[id]', params: { id: client.id } })
+  // Optionally navigate to the new company
+  if (company?.id) {
+    router.push({ name: '/crm/companies/[id]', params: { id: company.id } })
   }
 }
 
 // Load first page on mount
 onMounted(async () => {
   try {
-    await clientStore.fetchClients({ page: 1, sortBy: 'name', sortDir: 'asc' })
+    await companyStore.fetchCompanies({ page: 1, sortBy: 'name', sortDir: 'asc' })
   } catch (error) {
-    toast.error('Failed to load clients')
-    console.error('Load clients error:', error)
+    toast.error('Failed to load companies')
+    console.error('Load companies error:', error)
   }
 })
 </script>
diff --git a/frontend/src/pages/crm/clients/[id].vue b/frontend/src/pages/crm/companies/[id].vue
similarity index 80%
rename from frontend/src/pages/crm/clients/[id].vue
rename to frontend/src/pages/crm/companies/[id].vue
index 7b4acdcab..ba545e24b 100644
--- a/frontend/src/pages/crm/clients/[id].vue
+++ b/frontend/src/pages/crm/companies/[id].vue
@@ -3,27 +3,27 @@
     <div class="p-4 md:p-8 space-y-6">
       <!-- Header with Back Button -->
       <div class="flex items-center gap-4">
-        <Button variant="outline" size="sm" data-automation-id="ClientDetail-back" @click="goBack">
+        <Button variant="outline" size="sm" data-automation-id="CompanyDetail-back" @click="goBack">
           <ArrowLeft class="w-4 h-4 mr-2" />
           Back
         </Button>
         <div class="flex-1">
           <div v-if="isLoading" class="flex items-center gap-2">
             <Loader2 class="w-5 h-5 animate-spin text-indigo-600" />
-            <span class="text-gray-500">Loading client...</span>
+            <span class="text-gray-500">Loading company...</span>
           </div>
-          <div v-else-if="client" class="flex items-center gap-3">
+          <div v-else-if="company" class="flex items-center gap-3">
             <Users class="w-6 h-6 text-indigo-600" />
             <div>
-              <h1 class="text-2xl font-bold text-gray-900">{{ client.name }}</h1>
+              <h1 class="text-2xl font-bold text-gray-900">{{ company.name }}</h1>
               <div class="flex items-center gap-2 mt-1">
-                <Badge :variant="client.is_account_customer ? 'default' : 'secondary'">
-                  {{ client.is_account_customer ? 'Account Customer' : 'Cash Customer' }}
+                <Badge :variant="company.is_account_customer ? 'default' : 'secondary'">
+                  {{ company.is_account_customer ? 'Account Customer' : 'Cash Customer' }}
                 </Badge>
-                <Badge v-if="client.is_supplier" variant="outline"> Supplier </Badge>
-                <Badge v-if="!client.allow_jobs" variant="destructive"> Jobs Blocked </Badge>
+                <Badge v-if="company.is_supplier" variant="outline"> Supplier </Badge>
+                <Badge v-if="!company.allow_jobs" variant="destructive"> Jobs Blocked </Badge>
                 <Badge
-                  v-if="client.xero_contact_id"
+                  v-if="company.xero_contact_id"
                   variant="outline"
                   class="flex items-center gap-1"
                 >
@@ -39,13 +39,13 @@
       <!-- Error State -->
       <div v-if="error && !isLoading" class="text-center py-12">
         <AlertCircle class="w-12 h-12 mx-auto mb-4 text-red-500" />
-        <p class="text-lg font-medium text-gray-900">Failed to load client</p>
+        <p class="text-lg font-medium text-gray-900">Failed to load company</p>
         <p class="text-sm text-gray-500 mt-2">{{ error }}</p>
-        <Button @click="loadClientData" class="mt-4"> Try Again </Button>
+        <Button @click="loadCompanyData" class="mt-4"> Try Again </Button>
       </div>
 
       <!-- Tabs -->
-      <Tabs v-else-if="client" v-model="activeTab" class="w-full">
+      <Tabs v-else-if="company" v-model="activeTab" class="w-full">
         <TabsList class="grid w-full grid-cols-4">
           <TabsTrigger value="details">
             <FileText class="w-4 h-4 mr-2" />
@@ -75,23 +75,23 @@
             <CardContent class="grid grid-cols-1 md:grid-cols-2 gap-4">
               <div>
                 <label class="text-sm font-medium text-gray-500">Name</label>
-                <p class="text-gray-900">{{ client.name }}</p>
+                <p class="text-gray-900">{{ company.name }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Email</label>
-                <p class="text-gray-900">{{ client.email || '-' }}</p>
+                <p class="text-gray-900">{{ company.email || '-' }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Address</label>
-                <p class="text-gray-900">{{ client.address || '-' }}</p>
+                <p class="text-gray-900">{{ company.address || '-' }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Primary Contact</label>
-                <p class="text-gray-900">{{ client.primary_contact_name || '-' }}</p>
+                <p class="text-gray-900">{{ company.primary_contact_name || '-' }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Primary Contact Email</label>
-                <p class="text-gray-900">{{ client.primary_contact_email || '-' }}</p>
+                <p class="text-gray-900">{{ company.primary_contact_email || '-' }}</p>
               </div>
             </CardContent>
           </Card>
@@ -106,13 +106,13 @@
                 <Input
                   v-model="newAlias"
                   placeholder="Add supplier search alias"
-                  data-automation-id="ClientDetailView-alias-input"
+                  data-automation-id="CompanyDetailView-alias-input"
                   @keydown.enter.prevent="createSupplierAlias"
                 />
                 <Button
                   type="button"
                   :disabled="isSavingAlias || !newAlias.trim()"
-                  data-automation-id="ClientDetailView-alias-add"
+                  data-automation-id="CompanyDetailView-alias-add"
                   @click="createSupplierAlias"
                 >
                   <Plus class="w-4 h-4 mr-2" />
@@ -123,14 +123,14 @@
               <div
                 v-if="isLoadingAliases"
                 class="flex items-center justify-center py-4"
-                data-automation-id="ClientDetailView-alias-loading"
+                data-automation-id="CompanyDetailView-alias-loading"
               >
                 <Loader2 class="w-5 h-5 animate-spin text-indigo-600" />
               </div>
               <div
                 v-else-if="supplierAliases.length === 0"
                 class="text-sm text-gray-500"
-                data-automation-id="ClientDetailView-alias-empty"
+                data-automation-id="CompanyDetailView-alias-empty"
               >
                 No supplier search aliases
               </div>
@@ -139,7 +139,7 @@
                   v-for="alias in supplierAliases"
                   :key="alias.id"
                   class="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-gray-50 px-2 py-1 text-sm"
-                  :data-automation-id="`ClientDetailView-alias-${alias.id}`"
+                  :data-automation-id="`CompanyDetailView-alias-${alias.id}`"
                 >
                   <span>{{ alias.alias }}</span>
                   <Button
@@ -148,7 +148,7 @@
                     size="sm"
                     class="h-6 w-6 p-0"
                     :aria-label="`Remove alias ${alias.alias}`"
-                    :data-automation-id="`ClientDetailView-alias-remove-${alias.id}`"
+                    :data-automation-id="`CompanyDetailView-alias-remove-${alias.id}`"
                     @click="deleteSupplierAlias(alias.id)"
                   >
                     <X class="w-3 h-3" />
@@ -165,7 +165,7 @@
             </CardHeader>
             <CardContent>
               <div
-                v-if="clientStore.isLoadingContacts"
+                v-if="companyStore.isLoadingContacts"
                 class="flex items-center justify-center py-8"
               >
                 <Loader2 class="w-6 h-6 animate-spin text-indigo-600" />
@@ -202,34 +202,34 @@
 
           <PhoneNumberManager
             title="Phone Numbers"
-            :fixed-client-id="props.id"
-            :fixed-client-name="client.name"
+            :fixed-company-id="props.id"
+            :fixed-company-name="company.name"
             search-context="crm_client_detail_phone_numbers"
             @changed="loadPhoneCalls"
           />
 
           <!-- Xero Integration Details -->
-          <Card v-if="client.xero_contact_id">
+          <Card v-if="company.xero_contact_id">
             <CardHeader>
               <CardTitle>Xero Integration</CardTitle>
             </CardHeader>
             <CardContent class="grid grid-cols-1 md:grid-cols-2 gap-4">
               <div>
                 <label class="text-sm font-medium text-gray-500">Xero Contact ID</label>
-                <p class="text-gray-900 font-mono text-xs">{{ client.xero_contact_id }}</p>
+                <p class="text-gray-900 font-mono text-xs">{{ company.xero_contact_id }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Last Modified</label>
-                <p class="text-gray-900">{{ formatDateTime(client.xero_last_modified) }}</p>
+                <p class="text-gray-900">{{ formatDateTime(company.xero_last_modified) }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Last Synced</label>
-                <p class="text-gray-900">{{ formatDateTime(client.xero_last_synced) }}</p>
+                <p class="text-gray-900">{{ formatDateTime(company.xero_last_synced) }}</p>
               </div>
               <div>
                 <label class="text-sm font-medium text-gray-500">Status</label>
-                <Badge :variant="client.xero_archived ? 'destructive' : 'default'">
-                  {{ client.xero_archived ? 'Archived' : 'Active' }}
+                <Badge :variant="company.xero_archived ? 'destructive' : 'default'">
+                  {{ company.xero_archived ? 'Archived' : 'Active' }}
                 </Badge>
               </div>
             </CardContent>
@@ -247,15 +247,15 @@
                 <label class="text-sm font-medium text-indigo-900">Total Spend</label>
                 <p
                   class="text-3xl font-bold text-indigo-600 mt-2"
-                  data-automation-id="ClientDetail-total-spend"
+                  data-automation-id="CompanyDetail-total-spend"
                 >
-                  {{ client.total_spend || '$0.00' }}
+                  {{ company.total_spend || '$0.00' }}
                 </p>
               </div>
               <div class="p-4 bg-green-50 rounded-lg">
                 <label class="text-sm font-medium text-green-900">Last Invoice Date</label>
                 <p class="text-2xl font-bold text-green-600 mt-2">
-                  {{ client.last_invoice_date || 'No invoices' }}
+                  {{ company.last_invoice_date || 'No invoices' }}
                 </p>
               </div>
             </CardContent>
@@ -269,14 +269,14 @@
             <CardContent class="space-y-3">
               <div class="flex justify-between items-center py-2 border-b">
                 <span class="text-gray-600">Account Type</span>
-                <Badge :variant="client.is_account_customer ? 'default' : 'secondary'">
-                  {{ client.is_account_customer ? 'Account Customer' : 'Cash Customer' }}
+                <Badge :variant="company.is_account_customer ? 'default' : 'secondary'">
+                  {{ company.is_account_customer ? 'Account Customer' : 'Cash Customer' }}
                 </Badge>
               </div>
               <div class="flex justify-between items-center py-2 border-b">
                 <span class="text-gray-600">Also a Supplier</span>
-                <Badge :variant="client.is_supplier ? 'default' : 'outline'">
-                  {{ client.is_supplier ? 'Yes' : 'No' }}
+                <Badge :variant="company.is_supplier ? 'default' : 'outline'">
+                  {{ company.is_supplier ? 'Yes' : 'No' }}
                 </Badge>
               </div>
               <div class="py-2 border-b">
@@ -284,13 +284,13 @@
                   <div>
                     <span class="text-gray-600">Allow Jobs</span>
                     <p class="text-xs text-gray-500 mt-0.5">
-                      When disabled, this client cannot be selected when creating jobs.
+                      When disabled, this company cannot be selected when creating jobs.
                     </p>
                   </div>
                   <Switch
-                    :checked="client.allow_jobs"
+                    :checked="company.allow_jobs"
                     :disabled="isSavingAllowJobs"
-                    aria-label="Allow jobs for this client"
+                    aria-label="Allow jobs for this company"
                     @update:checked="onAllowJobsToggle"
                   />
                 </div>
@@ -309,13 +309,13 @@
               <CardTitle>Related Jobs</CardTitle>
             </CardHeader>
             <CardContent>
-              <div v-if="clientStore.isLoadingJobs" class="flex items-center justify-center py-8">
+              <div v-if="companyStore.isLoadingJobs" class="flex items-center justify-center py-8">
                 <Loader2 class="w-6 h-6 animate-spin text-indigo-600" />
               </div>
               <div v-else-if="relatedJobs.length === 0" class="text-center py-12 text-gray-500">
                 <Briefcase class="w-12 h-12 mx-auto mb-4 text-gray-400" />
                 <p class="text-lg font-medium">No jobs found</p>
-                <p class="text-sm">This client doesn't have any jobs yet</p>
+                <p class="text-sm">This company doesn't have any jobs yet</p>
               </div>
               <div v-else class="overflow-x-auto">
                 <table class="min-w-full text-sm">
@@ -381,7 +381,7 @@
               <PhoneCallTable
                 v-else
                 :calls="phoneCalls"
-                empty-text="No phone interactions found for this client"
+                empty-text="No phone interactions found for this company"
                 @call-updated="replacePhoneCall"
               />
             </CardContent>
@@ -401,7 +401,7 @@
 <script setup lang="ts">
 import { ref, onMounted, computed } from 'vue'
 import { useRouter } from 'vue-router'
-import { useClientStore } from '@/stores/clientStore'
+import { useCompanyStore } from '@/stores/companyStore'
 import AppLayout from '@/components/AppLayout.vue'
 import PhoneCallTable from '@/components/crm/PhoneCallTable.vue'
 import PhoneNumberManager from '@/components/crm/PhoneNumberManager.vue'
@@ -437,7 +437,7 @@ interface Props {
 
 const props = defineProps<Props>()
 const router = useRouter()
-const clientStore = useClientStore()
+const companyStore = useCompanyStore()
 type SupplierSearchAlias = z.infer<typeof schemas.SupplierSearchAlias>
 type PhoneCallRecord = z.infer<typeof schemas.PhoneCallRecord>
 
@@ -456,16 +456,16 @@ const isLoadingPhoneCalls = ref(false)
 const phoneCallError = ref<string | null>(null)
 
 // Computed
-const client = computed(() => {
-  return clientStore.detailedClients[props.id]
+const company = computed(() => {
+  return companyStore.detailedCompanies[props.id]
 })
 
 const contacts = computed(() => {
-  return clientStore.clientContacts[props.id] || []
+  return companyStore.companyContacts[props.id] || []
 })
 
 const relatedJobs = computed(() => {
-  return clientStore.clientJobs[props.id] || []
+  return companyStore.companyJobs[props.id] || []
 })
 
 /**
@@ -482,10 +482,10 @@ const isJobQuoted = (job: (typeof relatedJobs.value)[0]): boolean => {
  * Shown as informational text — the admin may still override the toggle manually.
  */
 const allowJobsBlockedReason = computed<string | null>(() => {
-  const current = client.value
+  const current = company.value
   if (!current) return null
   if (current.merged_into) {
-    return 'Blocked because this contact was merged into another client in Xero.'
+    return 'Blocked because this contact was merged into another company in Xero.'
   }
   if (current.xero_archived) {
     return 'Blocked because this contact is archived in Xero.'
@@ -494,25 +494,25 @@ const allowJobsBlockedReason = computed<string | null>(() => {
 })
 
 async function onAllowJobsToggle(nextValue: boolean) {
-  const current = client.value
+  const current = company.value
   if (!current) return
 
   isSavingAllowJobs.value = true
   try {
-    const result = await api.clients_update_update(
+    const result = await api.companies_update_update(
       { allow_jobs: nextValue },
-      { params: { client_id: props.id } },
+      { params: { company_id: props.id } },
     )
-    if (!result.success || !result.client) {
-      throw new Error(result.message || 'Failed to update client')
+    if (!result.success || !result.company) {
+      throw new Error(result.message || 'Failed to update company')
     }
-    clientStore.detailedClients = {
-      ...clientStore.detailedClients,
-      [props.id]: result.client,
+    companyStore.detailedCompanies = {
+      ...companyStore.detailedCompanies,
+      [props.id]: result.company,
     }
-    toast.success(nextValue ? 'Client can now be used for jobs' : 'Client blocked from new jobs')
+    toast.success(nextValue ? 'Company can now be used for jobs' : 'Company blocked from new jobs')
   } catch (err) {
-    const message = err instanceof Error ? err.message : 'Failed to update client'
+    const message = err instanceof Error ? err.message : 'Failed to update company'
     console.error('Error updating allow_jobs:', err)
     toast.error(message)
   } finally {
@@ -523,8 +523,8 @@ async function onAllowJobsToggle(nextValue: boolean) {
 async function loadSupplierAliases() {
   isLoadingAliases.value = true
   try {
-    supplierAliases.value = await api.clients_supplier_aliases_list({
-      params: { client_id: props.id },
+    supplierAliases.value = await api.companies_supplier_aliases_list({
+      params: { company_id: props.id },
     })
   } catch (err) {
     console.error('Failed to load supplier aliases:', err)
@@ -541,9 +541,9 @@ async function createSupplierAlias() {
 
   isSavingAlias.value = true
   try {
-    const created = await api.clients_supplier_aliases_create(
+    const created = await api.companies_supplier_aliases_create(
       { alias },
-      { params: { client_id: props.id } },
+      { params: { company_id: props.id } },
     )
     supplierAliases.value = [
       ...supplierAliases.value.filter((existing) => existing.id !== created.id),
@@ -561,7 +561,7 @@ async function createSupplierAlias() {
 
 async function deleteSupplierAlias(aliasId: string) {
   try {
-    await api.clients_supplier_aliases_destroy(undefined, {
+    await api.companies_supplier_aliases_destroy(undefined, {
       params: { alias_id: aliasId },
     })
     supplierAliases.value = supplierAliases.value.filter((alias) => alias.id !== aliasId)
@@ -577,7 +577,7 @@ async function loadPhoneCalls() {
   phoneCallError.value = null
   try {
     const response = await api.crm_phone_calls_list({
-      queries: { client: props.id, page: 1, page_size: 50 },
+      queries: { company: props.id, page: 1, page_size: 50 },
     })
     phoneCalls.value = response.results
     phoneCallCount.value = response.count
@@ -598,20 +598,20 @@ function replacePhoneCall(updated: PhoneCallRecord) {
 }
 
 // Methods
-async function loadClientData() {
+async function loadCompanyData() {
   isLoading.value = true
   error.value = null
 
   try {
-    // Load client details
-    await clientStore.fetchClientDetail(props.id)
+    // Load company details
+    await companyStore.fetchCompanyDetail(props.id)
 
     // Load supplier aliases
     await loadSupplierAliases()
 
     // Load contacts
     try {
-      await clientStore.fetchClientContacts(props.id)
+      await companyStore.fetchClientContacts(props.id)
     } catch (err) {
       console.error('Failed to load contacts:', err)
       // Don't show error for contacts, just log it
@@ -619,7 +619,7 @@ async function loadClientData() {
 
     // Load related jobs
     try {
-      await clientStore.fetchClientJobs(props.id)
+      await companyStore.fetchCompanyJobs(props.id)
     } catch (err) {
       console.error('Failed to load jobs:', err)
       // Don't show error for jobs, just log it
@@ -629,17 +629,17 @@ async function loadClientData() {
     await loadPhoneCalls()
   } catch (err) {
     const errorMessage =
-      err instanceof Error ? err.message : 'An error occurred while loading client data'
+      err instanceof Error ? err.message : 'An error occurred while loading company data'
     error.value = errorMessage
-    toast.error('Failed to load client details')
-    console.error('Error loading client:', err)
+    toast.error('Failed to load company details')
+    console.error('Error loading company:', err)
   } finally {
     isLoading.value = false
   }
 }
 
 function goBack() {
-  router.push({ name: '/crm/clients/(index)' })
+  router.push({ name: '/crm/companies/(index)' })
 }
 
 function navigateToJob(jobId: string) {
@@ -648,6 +648,6 @@ function navigateToJob(jobId: string) {
 
 // Lifecycle
 onMounted(() => {
-  loadClientData()
+  loadCompanyData()
 })
 </script>
diff --git a/frontend/src/pages/jobs/[id]/(index).vue b/frontend/src/pages/jobs/[id]/(index).vue
index 16a6f6574..1d4580d71 100644
--- a/frontend/src/pages/jobs/[id]/(index).vue
+++ b/frontend/src/pages/jobs/[id]/(index).vue
@@ -40,13 +40,13 @@
             <div class="flex items-center gap-2 text-sm text-gray-500 flex-wrap">
               <span>•</span>
               <div class="group">
-                <InlineEditClient
+                <InlineEditCompany
                   v-if="jobDataWithPaid"
-                  :key="localClientId"
-                  :client-name="localClientName"
-                  :client-id="localClientId"
-                  @update:client="handleClientUpdate"
-                  placeholder="Select client"
+                  :key="localCompanyId"
+                  :company-name="localCompanyName"
+                  :company-id="localCompanyId"
+                  @update:company="handleCompanyUpdate"
+                  placeholder="Select company"
                 />
               </div>
               <span>•</span>
@@ -161,13 +161,13 @@
               </div>
               <div class="flex items-center gap-2 text-xs text-gray-500">
                 <div class="group">
-                  <InlineEditClient
+                  <InlineEditCompany
                     v-if="jobDataWithPaid"
-                    :key="localClientId"
-                    :client-name="localClientName"
-                    :client-id="localClientId"
-                    @update:client="handleClientUpdate"
-                    placeholder="Select client"
+                    :key="localCompanyId"
+                    :company-name="localCompanyName"
+                    :company-id="localCompanyId"
+                    @update:company="handleCompanyUpdate"
+                    placeholder="Select company"
                   />
                 </div>
                 <span>•</span>
@@ -305,7 +305,7 @@ import AppLayout from '@/components/AppLayout.vue'
 import JobViewTabs from '@/components/job/JobViewTabs.vue'
 import JobPdfDialog from '@/components/job/JobPdfDialog.vue'
 import InlineEditText from '@/components/shared/InlineEditText.vue'
-import InlineEditClient from '@/components/shared/InlineEditClient.vue'
+import InlineEditCompany from '@/components/shared/InlineEditCompany.vue'
 import InlineEditSelect from '@/components/shared/InlineEditSelect.vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useJobsStore } from '@/stores/jobs'
@@ -377,8 +377,8 @@ const { activeTab, setTab } = useJobTabs(defaultTab)
 debugLog('[JobView] tabs init', { activeTab: activeTab.value, defaultTab })
 
 const localJobName = ref('')
-const localClientName = ref('')
-const localClientId = ref('')
+const localCompanyName = ref('')
+const localCompanyId = ref('')
 const localJobStatus = ref<JobStatusKey | ''>('')
 type PricingMethodology = 'time_materials' | 'fixed_price'
 const localPricingMethodology = ref<PricingMethodology | ''>('')
@@ -419,10 +419,10 @@ const handleNameUpdate = (newName: string) => {
   headerAutosave.handleNameUpdate(newName)
 }
 
-const handleClientUpdate = (client: { id: string; name: string }) => {
-  localClientName.value = client.name
-  localClientId.value = client.id
-  headerAutosave.handleClientUpdate(client)
+const handleCompanyUpdate = (company: { id: string; name: string }) => {
+  localCompanyName.value = company.name
+  localCompanyId.value = company.id
+  headerAutosave.handleCompanyUpdate(company)
 }
 
 const isValidStatus = (value: string): value is JobStatusKey =>
@@ -528,8 +528,8 @@ const jobDataWithPaid = computed(() => {
     id: h.job_id,
     job_number: h.job_number,
     name: h.name,
-    client_name: h.client_name ?? '',
-    client_id: h.client_id ?? '',
+    company_name: h.company_name ?? '',
+    company_id: h.company_id ?? '',
     job_status: h.status ?? '',
     pricing_methodology: h.pricing_methodology ?? '',
     quoted: h.quoted,
@@ -545,8 +545,8 @@ watch(
   (h) => {
     if (!h) return
     localJobName.value = h.name
-    localClientName.value = h.client_name ?? ''
-    localClientId.value = h.client_id ?? ''
+    localCompanyName.value = h.company_name ?? ''
+    localCompanyId.value = h.company_id ?? ''
     localJobStatus.value = h.status ?? ''
     localPricingMethodology.value = h.pricing_methodology ?? ''
     localQuoted.value = Boolean(h.quoted)
diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index e9860af75..5f2ca8b08 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -13,17 +13,17 @@
             <div class="grid grid-cols-1 md:grid-cols-2 gap-8 items-start">
               <div class="space-y-6">
                 <div>
-                  <ClientLookup
-                    id="client"
-                    v-model="clientDisplayName"
-                    @update:selected-id="formData.client_id = $event"
-                    @update:selected-client="handleClientSelection"
-                    label="Client"
+                  <CompanyLookup
+                    id="company"
+                    v-model="companyDisplayName"
+                    @update:selected-id="formData.company_id = $event"
+                    @update:selected-company="handleCompanySelection"
+                    label="Company"
                     :required="true"
-                    placeholder="Search for a client..."
+                    placeholder="Search for a company..."
                   />
-                  <p v-if="errors.client_id" class="mt-1 text-sm text-red-600">
-                    {{ errors.client_id }}
+                  <p v-if="errors.company_id" class="mt-1 text-sm text-red-600">
+                    {{ errors.company_id }}
                   </p>
                 </div>
 
@@ -61,8 +61,8 @@
                     ref="contactSelectorRef"
                     id="contact"
                     v-model="contactDisplayName"
-                    :client-id="formData.client_id as string"
-                    :client-name="clientDisplayName"
+                    :company-id="formData.company_id as string"
+                    :company-name="companyDisplayName"
                     label="Contact"
                     placeholder="Search or add contact person"
                     :optional="true"
@@ -243,7 +243,7 @@
 import { ref, computed, onMounted, nextTick, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import AppLayout from '@/components/AppLayout.vue'
-import ClientLookup from '@/components/ClientLookup.vue'
+import CompanyLookup from '@/components/CompanyLookup.vue'
 import ContactSelector from '@/components/ContactSelector.vue'
 import RichTextEditor from '@/components/RichTextEditor.vue'
 import { jobService, type JobCreateData } from '@/services/job.service'
@@ -251,7 +251,7 @@ import { schemas } from '@/api/generated/api'
 import { z } from 'zod'
 import { debugLog } from '@/utils/debug'
 
-type ClientSearchResult = z.infer<typeof schemas.ClientSearchResult>
+type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
 type ClientContact = z.infer<typeof schemas.ClientContact>
 import { toast } from 'vue-sonner'
 
@@ -297,7 +297,7 @@ const router = useRouter()
 
 const formData = ref<JobCreateData>({
   name: '',
-  client_id: '',
+  company_id: '',
   description: '',
   order_number: '',
   notes: '',
@@ -308,9 +308,9 @@ const formData = ref<JobCreateData>({
   pricing_methodology: 'time_materials',
 })
 
-const clientDisplayName = ref('')
+const companyDisplayName = ref('')
 
-const selectedClient = ref<ClientSearchResult | null>(null)
+const selectedCompany = ref<CompanySearchResult | null>(null)
 const selectedContact = ref<ClientContact | null>(null)
 const contactDisplayName = ref('')
 
@@ -318,16 +318,16 @@ const errors = ref<Record<string, string>>({})
 const isSubmitting = ref(false)
 const hasCreationError = ref(false)
 
-const handleClientSelection = async (client: ClientSearchResult | null) => {
-  debugLog('JobCreateView - handleClientSelection:', {
-    client,
-    previousClientId: formData.value.client_id,
+const handleCompanySelection = async (company: CompanySearchResult | null) => {
+  debugLog('JobCreateView - handleCompanySelection:', {
+    company,
+    previousCompanyId: formData.value.company_id,
     previousContactId: formData.value.contact_id,
   })
 
-  selectedClient.value = client
+  selectedCompany.value = company
 
-  // Always clear contact person when client changes (even if same client selected)
+  // Always clear contact person when company changes (even if same company selected)
   formData.value.contact_id = null
   selectedContact.value = null
   contactDisplayName.value = ''
@@ -337,17 +337,17 @@ const handleClientSelection = async (client: ClientSearchResult | null) => {
     contactSelectorRef.value.clearSelection()
   }
 
-  if (client) {
-    clientDisplayName.value = client.name
-    formData.value.client_id = client.id
+  if (company) {
+    companyDisplayName.value = company.name
+    formData.value.company_id = company.id
 
-    debugLog('JobCreateView - Client selected, waiting for ContactSelector to update')
+    debugLog('JobCreateView - Company selected, waiting for ContactSelector to update')
 
     // Wait for the next DOM update cycle to ensure the ref is ready
-    // and the new client ID has propagated to the ContactSelector.
+    // and the new company ID has propagated to the ContactSelector.
     await nextTick()
 
-    // Give the ContactSelector's watcher time to process the clientId change
+    // Give the ContactSelector's watcher time to process the companyId change
     await new Promise((resolve) => setTimeout(resolve, 100))
 
     if (contactSelectorRef.value) {
@@ -357,10 +357,10 @@ const handleClientSelection = async (client: ClientSearchResult | null) => {
       await contactSelectorRef.value.selectPrimaryContact()
     }
   } else {
-    // Clear client fields if client is deselected
-    clientDisplayName.value = ''
-    formData.value.client_id = ''
-    debugLog('JobCreateView - Client cleared')
+    // Clear company fields if company is deselected
+    companyDisplayName.value = ''
+    formData.value.company_id = ''
+    debugLog('JobCreateView - Company cleared')
   }
 }
 
@@ -377,11 +377,11 @@ const updateSelectedContact = (contact: ClientContact | null) => {
 }
 
 // Requirements validation computed properties
-const hasValidXeroClient = computed(() => {
+const hasValidXeroCompany = computed(() => {
   return (
-    formData.value.client_id !== '' &&
-    selectedClient.value?.xero_contact_id != null &&
-    selectedClient.value.xero_contact_id !== ''
+    formData.value.company_id !== '' &&
+    selectedCompany.value?.xero_contact_id != null &&
+    selectedCompany.value.xero_contact_id !== ''
   )
 })
 
@@ -395,7 +395,7 @@ const hasValidMaterialsEstimate = computed(() => {
 
 const canSubmit = computed(() => {
   const nameCheck = formData.value.name.trim() !== ''
-  const xeroCheck = hasValidXeroClient.value
+  const xeroCheck = hasValidXeroCompany.value
   const timeCheck = hasValidTimeEstimate.value
   const materialsCheck = hasValidMaterialsEstimate.value
 
@@ -405,9 +405,9 @@ const canSubmit = computed(() => {
     timeCheck,
     materialsCheck,
     name: formData.value.name,
-    clientId: formData.value.client_id,
-    selectedClient: selectedClient.value,
-    xeroContactId: selectedClient.value?.xero_contact_id,
+    companyId: formData.value.company_id,
+    selectedCompany: selectedCompany.value,
+    xeroContactId: selectedCompany.value?.xero_contact_id,
     estimated_time: formData.value.estimated_time,
     estimated_materials: formData.value.estimated_materials,
   })
@@ -427,13 +427,13 @@ const validateForm = (): boolean => {
     return false
   }
 
-  if (!formData.value.client_id) {
-    errors.value.client_id = 'Client selection is required'
+  if (!formData.value.company_id) {
+    errors.value.company_id = 'Company selection is required'
     return false
   }
 
-  if (!selectedClient.value?.xero_contact_id) {
-    errors.value.client_id = 'Client must have a valid Xero ID - maybe add them'
+  if (!selectedCompany.value?.xero_contact_id) {
+    errors.value.company_id = 'Company must have a valid Xero ID - maybe add them'
     return false
   }
 
@@ -483,7 +483,7 @@ const handleSubmit = async () => {
     localStorage.setItem('jobCreationFormData', JSON.stringify(formData.value))
     localStorage.setItem('hasJobCreationError', 'true')
     localStorage.setItem('jobCreationErrorMessage', errorMessage)
-    localStorage.setItem('selectedClient', JSON.stringify(selectedClient.value))
+    localStorage.setItem('selectedCompany', JSON.stringify(selectedCompany.value))
 
     window.location.reload()
     debugLog('Job creation error:', error)
@@ -505,23 +505,23 @@ onMounted(() => {
 
   if (hasError) {
     formData.value = storedFormData ? JSON.parse(storedFormData) : formData.value
-    selectedClient.value = localStorage.getItem('selectedClient')
-      ? JSON.parse(localStorage.getItem('selectedClient') as string)
+    selectedCompany.value = localStorage.getItem('selectedCompany')
+      ? JSON.parse(localStorage.getItem('selectedCompany') as string)
       : null
-    handleClientSelection(selectedClient.value)
+    handleCompanySelection(selectedCompany.value)
     localStorage.removeItem('jobCreationFormData')
     localStorage.removeItem('hasJobCreationError')
-    localStorage.removeItem('selectedClient')
+    localStorage.removeItem('selectedCompany')
     toast.error('Previous job creation failed', {
       description: `Page reloaded and state saved. Original error: ${errorMessage}`,
       dismissible: true,
     })
     debugLog('Restored form data after error:', formData.value)
-    debugLog('Restored selected client after error:', selectedClient.value)
+    debugLog('Restored selected company after error:', selectedCompany.value)
   } else {
     formData.value.name = ''
-    formData.value.client_id = ''
-    clientDisplayName.value = ''
+    formData.value.company_id = ''
+    companyDisplayName.value = ''
     formData.value.description = ''
     formData.value.order_number = ''
     formData.value.notes = ''
diff --git a/frontend/src/pages/kanban.vue b/frontend/src/pages/kanban.vue
index ad41dad96..2562c7e06 100644
--- a/frontend/src/pages/kanban.vue
+++ b/frontend/src/pages/kanban.vue
@@ -136,7 +136,7 @@
           <DrawerHeader>
             <DrawerTitle>Update Job Status</DrawerTitle>
             <DrawerDescription v-if="statusDrawerJob">
-              Job #{{ statusDrawerJob.job_number }} - {{ statusDrawerJob.client_name }}
+              Job #{{ statusDrawerJob.job_number }} - {{ statusDrawerJob.company_name }}
             </DrawerDescription>
             <DrawerDescription v-else>Select a job to update.</DrawerDescription>
           </DrawerHeader>
diff --git a/frontend/src/pages/purchasing/po/(index).vue b/frontend/src/pages/purchasing/po/(index).vue
index f48e40efe..eea3eeac0 100644
--- a/frontend/src/pages/purchasing/po/(index).vue
+++ b/frontend/src/pages/purchasing/po/(index).vue
@@ -188,7 +188,7 @@ const formatStatus = (status: PurchaseOrderStatus) => poStatusLabels[status]
 
 const getStatusClass = (status: PurchaseOrderStatus) => poStatusBadgeClasses[status]
 
-type PurchaseOrderJob = { job_number: string; name: string; client: string }
+type PurchaseOrderJob = { job_number: string; name: string; company: string }
 
 const formatJobs = (jobs: PurchaseOrderJob[]) => {
   if (!jobs || jobs.length === 0) return '—'
diff --git a/frontend/src/pages/purchasing/po/[id].vue b/frontend/src/pages/purchasing/po/[id].vue
index e441e07e2..6ed51d289 100644
--- a/frontend/src/pages/purchasing/po/[id].vue
+++ b/frontend/src/pages/purchasing/po/[id].vue
@@ -811,8 +811,8 @@ async function resolveSupplierEmail(): Promise<string | null> {
   }
 
   try {
-    const contacts = await api.clients_contacts_list({
-      queries: { client_id: supplierId },
+    const contacts = await api.companies_contacts_list({
+      queries: { company_id: supplierId },
     })
 
     const contactsArray: ClientContact[] = Array.isArray(contacts) ? contacts : []
diff --git a/frontend/src/pages/quoting/chat.vue b/frontend/src/pages/quoting/chat.vue
index c057ad9e9..66eb2fe42 100644
--- a/frontend/src/pages/quoting/chat.vue
+++ b/frontend/src/pages/quoting/chat.vue
@@ -14,7 +14,7 @@
               <h1 class="text-xl font-bold text-gray-900">Interactive Quote Chat</h1>
               <p v-if="jobContext" class="text-sm text-gray-500">
                 {{ jobContext.jobName }} • Job #{{ jobContext.jobNumber }} •
-                {{ jobContext.clientName }}
+                {{ jobContext.companyName }}
               </p>
             </div>
           </div>
@@ -182,14 +182,14 @@ const modes: Mode[] = ['AUTO', 'CALC', 'PRICE', 'TABLE']
 const currentMode = ref<Mode>('AUTO')
 
 const jobContext = computed(() => {
-  const { jobId, jobName, jobNumber, clientName } = route.query
+  const { jobId, jobName, jobNumber, companyName } = route.query
   if (!jobId) return null
 
   return {
     jobId: String(jobId),
     jobName: String(jobName || ''),
     jobNumber: String(jobNumber || ''),
-    clientName: String(clientName || ''),
+    companyName: String(companyName || ''),
   }
 })
 
diff --git a/frontend/src/pages/reports/data-quality/archived-jobs.vue b/frontend/src/pages/reports/data-quality/archived-jobs.vue
index 6858ac7a6..f014efba5 100644
--- a/frontend/src/pages/reports/data-quality/archived-jobs.vue
+++ b/frontend/src/pages/reports/data-quality/archived-jobs.vue
@@ -175,11 +175,11 @@
                     </th>
                     <th
                       class="text-left px-4 py-3 text-sm font-semibold text-slate-700 cursor-pointer hover:bg-slate-100 select-none"
-                      @click="handleSort('clientName')"
+                      @click="handleSort('companyName')"
                     >
                       <div class="flex items-center gap-1">
-                        Client
-                        <span v-if="sortColumn === 'clientName'" class="text-slate-500">
+                        Company
+                        <span v-if="sortColumn === 'companyName'" class="text-slate-500">
                           {{ sortDirection === 'asc' ? '↑' : '↓' }}
                         </span>
                       </div>
@@ -228,7 +228,7 @@
                       {{ issue.jobNumber }}
                     </td>
                     <td class="px-4 py-3 text-sm text-slate-700">
-                      {{ issue.clientName }}
+                      {{ issue.companyName }}
                     </td>
                     <td class="px-4 py-3">
                       <span
@@ -285,7 +285,7 @@ interface ValidationIssue {
   id: string
   jobId: string
   jobNumber: string
-  clientName: string
+  companyName: string
   type:
     | 'open_timesheets'
     | 'incomplete_costs'
@@ -392,7 +392,7 @@ const refreshData = async () => {
         (job: {
           job_id: string
           job_number: string
-          client_name: string
+          company_name: string
           issue?: string
           archived_date: string
           job_value: number
@@ -400,7 +400,7 @@ const refreshData = async () => {
           id: job.job_id,
           jobId: job.job_id,
           jobNumber: job.job_number,
-          clientName: job.client_name,
+          companyName: job.company_name,
           type: mapIssueLabelToType(job.issue),
           details: job.issue || 'Issue details unavailable',
           archivedDate: job.archived_date,
@@ -460,10 +460,10 @@ const refreshData = async () => {
 const exportReport = () => {
   if (!issues.value.length) return
 
-  const headers = ['Job Number', 'Client', 'Issue', 'Archived Date', 'Job Value']
+  const headers = ['Job Number', 'Company', 'Issue', 'Archived Date', 'Job Value']
   const rows = issues.value.map((issue) => [
     issue.jobNumber,
-    issue.clientName,
+    issue.companyName,
     issue.details,
     formatDate(issue.archivedDate),
     formatCurrency(issue.jobValue),
diff --git a/frontend/src/pages/reports/data-quality/duplicate-phones.vue b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
index 08ab4f495..ea7382866 100644
--- a/frontend/src/pages/reports/data-quality/duplicate-phones.vue
+++ b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
@@ -206,7 +206,7 @@ const ISSUE_CLASSES: Record<string, string> = {
 }
 
 const OWNER_KIND_LABELS: Record<string, string> = {
-  client: 'Client',
+  company: 'Company',
   contact: 'Contact',
 }
 
diff --git a/frontend/src/pages/reports/job-aging.vue b/frontend/src/pages/reports/job-aging.vue
index e97e0387c..9232f509f 100644
--- a/frontend/src/pages/reports/job-aging.vue
+++ b/frontend/src/pages/reports/job-aging.vue
@@ -154,7 +154,7 @@
                     {{ job.name }}
                   </td>
                   <td class="px-4 py-3">
-                    {{ job.client_name }}
+                    {{ job.company_name }}
                   </td>
                   <td class="px-4 py-3">
                     <span
@@ -226,8 +226,8 @@
 
                 <div class="grid grid-cols-2 gap-4 text-sm">
                   <div>
-                    <div class="font-medium text-gray-700">Client</div>
-                    <div class="text-gray-600">{{ job.client_name }}</div>
+                    <div class="font-medium text-gray-700">Company</div>
+                    <div class="text-gray-600">{{ job.company_name }}</div>
                   </div>
                   <div>
                     <div class="font-medium text-gray-700">Job Age</div>
@@ -327,7 +327,7 @@ const filters = ref<JobAgingFilters>({
 const tableColumns: JobAgingTableColumn[] = [
   { key: 'job_number', label: 'Job #', sortable: true },
   { key: 'name', label: 'Job Name', sortable: true },
-  { key: 'client_name', label: 'Client', sortable: true },
+  { key: 'company_name', label: 'Company', sortable: true },
   { key: 'status_display', label: 'Status', sortable: true },
   {
     key: 'timing_data.days_in_current_status',
diff --git a/frontend/src/pages/reports/job-movement.vue b/frontend/src/pages/reports/job-movement.vue
index 21314b2a7..9095c75d0 100644
--- a/frontend/src/pages/reports/job-movement.vue
+++ b/frontend/src/pages/reports/job-movement.vue
@@ -513,7 +513,7 @@ const JobDetailTable = {
             <tr>
               <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Job #</th>
               <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Name</th>
-              <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Client</th>
+              <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Company</th>
               <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Status</th>
               <th class="px-4 py-2 text-left text-xs font-medium text-gray-500 uppercase">Created</th>
             </tr>
@@ -522,7 +522,7 @@ const JobDetailTable = {
             <tr v-for="job in jobs" :key="job.id" class="hover:bg-gray-50">
               <td class="px-4 py-2 whitespace-nowrap font-medium text-indigo-600">{{ job.job_number }}</td>
               <td class="px-4 py-2 whitespace-nowrap">{{ job.name }}</td>
-              <td class="px-4 py-2 whitespace-nowrap">{{ job.client_name }}</td>
+              <td class="px-4 py-2 whitespace-nowrap">{{ job.company_name }}</td>
               <td class="px-4 py-2 whitespace-nowrap">{{ job.status }}</td>
               <td class="px-4 py-2 whitespace-nowrap text-gray-500">{{ job.created_at }}</td>
             </tr>
diff --git a/frontend/src/pages/reports/job-profitability.vue b/frontend/src/pages/reports/job-profitability.vue
index 1baef7310..79848916c 100644
--- a/frontend/src/pages/reports/job-profitability.vue
+++ b/frontend/src/pages/reports/job-profitability.vue
@@ -230,11 +230,11 @@
                       </th>
                       <th
                         class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer hover:bg-slate-100"
-                        @click="handleSort('client_name')"
+                        @click="handleSort('company_name')"
                       >
                         <div class="flex items-center gap-1">
-                          Client
-                          <span v-if="sortColumn === 'client_name'" class="text-slate-500">
+                          Company
+                          <span v-if="sortColumn === 'company_name'" class="text-slate-500">
                             {{ sortDirection === 'asc' ? '↑' : '↓' }}
                           </span>
                         </div>
@@ -381,9 +381,9 @@
                       </td>
                       <td
                         class="px-4 py-4 whitespace-nowrap text-sm text-gray-900 max-w-[120px] truncate"
-                        :title="job.client_name"
+                        :title="job.company_name"
                       >
-                        {{ job.client_name }}
+                        {{ job.company_name }}
                       </td>
                       <td class="px-4 py-4 whitespace-nowrap text-sm">
                         <span
@@ -505,7 +505,7 @@ interface JobProfitability {
   job_id: string
   job_number: number
   job_name: string
-  client_name: string
+  company_name: string
   pricing_type: string
   pricing_type_display: string
   completion_date: string
@@ -547,7 +547,7 @@ const filters = ref({
 
 type SortableColumn =
   | 'job_number'
-  | 'client_name'
+  | 'company_name'
   | 'pricing_type'
   | 'completion_date'
   | 'revenue'
@@ -698,7 +698,7 @@ const exportReport = () => {
   const headers = [
     'Job Number',
     'Job Name',
-    'Client',
+    'Company',
     'Pricing Type',
     'Completion Date',
     'Revenue',
@@ -724,7 +724,7 @@ const exportReport = () => {
   const rows = jobs.value.map((job) => [
     job.job_number,
     job.job_name,
-    job.client_name,
+    job.company_name,
     job.pricing_type_display,
     job.completion_date,
     job.revenue,
diff --git a/frontend/src/pages/reports/rdti-spend.vue b/frontend/src/pages/reports/rdti-spend.vue
index 32c3d363c..6a4814631 100644
--- a/frontend/src/pages/reports/rdti-spend.vue
+++ b/frontend/src/pages/reports/rdti-spend.vue
@@ -153,11 +153,11 @@
                       </th>
                       <th
                         class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer hover:bg-slate-100"
-                        @click="handleSort('client_name')"
+                        @click="handleSort('company_name')"
                       >
                         <div class="flex items-center gap-1">
-                          Client
-                          <span v-if="sortColumn === 'client_name'" class="text-slate-500">
+                          Company
+                          <span v-if="sortColumn === 'company_name'" class="text-slate-500">
                             {{ sortDirection === 'asc' ? '↑' : '↓' }}
                           </span>
                         </div>
@@ -226,9 +226,9 @@
                       </td>
                       <td
                         class="px-4 py-4 whitespace-nowrap text-sm text-gray-900 max-w-[150px] truncate"
-                        :title="job.client_name"
+                        :title="job.company_name"
                       >
-                        {{ job.client_name }}
+                        {{ job.company_name }}
                       </td>
                       <td class="px-4 py-4 whitespace-nowrap text-sm">
                         <span
@@ -308,7 +308,7 @@ const supportingSummary = computed(() => summary.value.find((s) => s.rdti_type =
 type SortableColumn =
   | 'job_number'
   | 'job_name'
-  | 'client_name'
+  | 'company_name'
   | 'rdti_type'
   | 'hours'
   | 'cost'
@@ -416,12 +416,12 @@ const loadData = async () => {
 const exportReport = () => {
   if (!jobs.value.length) return
 
-  const headers = ['Job Number', 'Job Name', 'Client', 'RDTI Type', 'Hours', 'Cost', 'Revenue']
+  const headers = ['Job Number', 'Job Name', 'Company', 'RDTI Type', 'Hours', 'Cost', 'Revenue']
 
   const rows = jobs.value.map((job) => [
     job.job_number,
     job.job_name,
-    job.client_name,
+    job.company_name,
     job.rdti_type,
     job.hours,
     job.cost,
diff --git a/frontend/src/pages/reports/sales-forecast.vue b/frontend/src/pages/reports/sales-forecast.vue
index 2badaeadc..1932bde2f 100644
--- a/frontend/src/pages/reports/sales-forecast.vue
+++ b/frontend/src/pages/reports/sales-forecast.vue
@@ -331,16 +331,16 @@
                     </th>
                     <th
                       class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase tracking-wider cursor-pointer hover:bg-gray-100 select-none"
-                      @click="toggleSort('client_name')"
+                      @click="toggleSort('company_name')"
                     >
                       <div class="flex items-center gap-1">
-                        Client
+                        Company
                         <ArrowUp
-                          v-if="sortField === 'client_name' && sortDirection === 'asc'"
+                          v-if="sortField === 'company_name' && sortDirection === 'asc'"
                           class="w-3 h-3"
                         />
                         <ArrowDown
-                          v-else-if="sortField === 'client_name' && sortDirection === 'desc'"
+                          v-else-if="sortField === 'company_name' && sortDirection === 'desc'"
                           class="w-3 h-3"
                         />
                         <ArrowUpDown v-else class="w-3 h-3 text-gray-300" />
@@ -483,7 +483,7 @@
                       {{ row.date }}
                     </td>
                     <td class="px-4 py-3 whitespace-nowrap text-sm text-gray-900">
-                      {{ row.client_name }}
+                      {{ row.company_name }}
                     </td>
                     <td class="px-4 py-3 text-sm text-gray-900">
                       <template v-if="row.invoice_numbers">
@@ -616,7 +616,7 @@ const detailData = ref<SalesForecastMonthDetailResponse | null>(null)
 
 type SortField =
   | 'date'
-  | 'client_name'
+  | 'company_name'
   | 'invoice_numbers'
   | 'total_invoiced'
   | 'job_number'
diff --git a/frontend/src/pages/reports/wip.vue b/frontend/src/pages/reports/wip.vue
index 773a41033..3b400dfd3 100644
--- a/frontend/src/pages/reports/wip.vue
+++ b/frontend/src/pages/reports/wip.vue
@@ -133,7 +133,7 @@
                     <td class="px-4 py-3 font-medium text-indigo-600">
                       {{ job.job_number }}
                     </td>
-                    <td class="px-4 py-3">{{ job.client }}</td>
+                    <td class="px-4 py-3">{{ job.company }}</td>
                     <td class="px-4 py-3">
                       <span
                         class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium"
@@ -175,7 +175,7 @@
                     <div>
                       <div class="text-lg font-semibold text-indigo-600">#{{ job.job_number }}</div>
                       <div class="text-sm text-gray-600">{{ job.name }}</div>
-                      <div class="text-sm text-gray-500">{{ job.client }}</div>
+                      <div class="text-sm text-gray-500">{{ job.company }}</div>
                     </div>
                     <span
                       class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium"
@@ -330,7 +330,7 @@ interface TableColumn {
 
 const tableColumns: TableColumn[] = [
   { key: 'job_number', label: 'Job #', sortable: true },
-  { key: 'client', label: 'Client', sortable: true },
+  { key: 'company', label: 'Company', sortable: true },
   { key: 'status', label: 'Status', sortable: true },
   { key: 'time', label: 'Time', sortable: true, align: 'right' },
   { key: 'material', label: 'Material', sortable: true, align: 'right' },
@@ -361,8 +361,8 @@ const getSortValue = (job: WIPJobData, key: string): number | string => {
       return getAdjustValue(job)
     case 'job_number':
       return job.job_number
-    case 'client':
-      return job.client
+    case 'company':
+      return job.company
     case 'status':
       return job.status
     case 'gross_wip':
diff --git a/frontend/src/pages/schedule.vue b/frontend/src/pages/schedule.vue
index 4dc1f8ea0..43d9357af 100644
--- a/frontend/src/pages/schedule.vue
+++ b/frontend/src/pages/schedule.vue
@@ -142,11 +142,11 @@
                           class="absolute top-1 bottom-1 rounded px-2 text-left text-white text-xs font-medium overflow-hidden hover:ring-2 hover:ring-offset-1 hover:ring-indigo-300 transition-all"
                           @click="selectJob(job)"
                           @dblclick.prevent="goToJob(job)"
-                          :title="`#${job.job_number} ${job.name} — ${job.client_name}`"
+                          :title="`#${job.job_number} ${job.name} — ${job.company_name}`"
                         >
                           <div class="truncate">#{{ job.job_number }} · {{ job.name }}</div>
                           <div class="truncate text-[10px] opacity-90">
-                            {{ job.client_name }} · {{ job.remaining_hours.toFixed(1) }}h
+                            {{ job.company_name }} · {{ job.remaining_hours.toFixed(1) }}h
                             <span v-if="job.is_late">· LATE</span>
                           </div>
                         </button>
@@ -195,7 +195,7 @@
                       <div class="font-semibold text-slate-800">
                         #{{ selectedJob.job_number }} · {{ selectedJob.name }}
                       </div>
-                      <div class="text-slate-500">{{ selectedJob.client_name }}</div>
+                      <div class="text-slate-500">{{ selectedJob.company_name }}</div>
                       <div class="mt-1 text-xs text-slate-600">
                         Remaining: {{ selectedJob.remaining_hours.toFixed(1) }}h
                       </div>
@@ -385,7 +385,7 @@
                         >
                           #{{ job.job_number }} {{ job.name }}
                         </button>
-                        <span class="text-slate-500"> · {{ job.client_name }}</span>
+                        <span class="text-slate-500"> · {{ job.company_name }}</span>
                         <div v-if="job.anticipated_staff.length" class="text-[11px] text-slate-600">
                           Workers:
                           {{ job.anticipated_staff.map((s) => s.name).join(', ') }}
@@ -434,7 +434,7 @@
                       #{{ job.job_number }} {{ job.name }}
                     </router-link>
                     <div class="text-xs text-slate-500 truncate">
-                      {{ job.client_name }} · delivery {{ job.delivery_date || '—' }} ·
+                      {{ job.company_name }} · delivery {{ job.delivery_date || '—' }} ·
                       {{ job.remaining_hours.toFixed(1) }}h remaining
                     </div>
                   </div>
diff --git a/frontend/src/pages/timesheets/entry.vue b/frontend/src/pages/timesheets/entry.vue
index 0aaf10380..573293a04 100644
--- a/frontend/src/pages/timesheets/entry.vue
+++ b/frontend/src/pages/timesheets/entry.vue
@@ -378,7 +378,7 @@
                           </h4>
                           <p class="text-xs text-gray-600 truncate">{{ jobData.job.name }}</p>
                           <p class="text-xs text-gray-500 truncate">
-                            {{ jobData.job.client_name }}
+                            {{ jobData.job.company_name }}
                           </p>
                         </div>
                         <div class="flex items-center gap-1.5">
@@ -866,7 +866,7 @@ const activeJobsWithData = computed<ActiveJobWithData[]>(() => {
             job_number: Number(entryWithJobData.job_number) || 0,
             name: entryWithJobData.job_name || 'Unknown Job',
             has_actual_costset: true,
-            client_name: entryWithJobData.client_name || 'Unknown Client',
+            company_name: entryWithJobData.company_name || 'Unknown Company',
             status: 'draft',
             labour_rates: [],
             shop_job: false,
diff --git a/frontend/src/services/admin-company-defaults-service.ts b/frontend/src/services/admin-company-defaults-service.ts
index f872d8495..864bb3af9 100644
--- a/frontend/src/services/admin-company-defaults-service.ts
+++ b/frontend/src/services/admin-company-defaults-service.ts
@@ -18,7 +18,7 @@ export async function updateCompanyDefaults(
   return await api.company_defaults_partial_update(payload)
 }
 
-// Raw fetch used here because the generated Zodios client does not support multipart form uploads.
+// Raw fetch used here because the generated Zodios company does not support multipart form uploads.
 export async function uploadLogo(fieldName: string, file: File): Promise<CompanyDefaults> {
   const formData = new FormData()
   formData.append('field_name', fieldName)
diff --git a/frontend/src/services/clientService.ts b/frontend/src/services/clientService.ts
deleted file mode 100644
index ff55a5550..000000000
--- a/frontend/src/services/clientService.ts
+++ /dev/null
@@ -1,65 +0,0 @@
-import { api } from '../api/client'
-import { debugLog } from '../utils/debug'
-import { z } from 'zod'
-import { schemas } from '../api/generated/api'
-
-type ClientSummary = z.infer<typeof schemas.ClientNameOnly>
-type ClientSearchResult = z.infer<typeof schemas.ClientSearchResult>
-export type Client = ClientSummary | ClientSearchResult
-export type CreateClientData = z.infer<typeof schemas.ClientCreateRequest>
-import type { CreateClientResponse } from '@/constants/client-wrapper'
-
-export class ClientService {
-  private static instance: ClientService
-
-  static getInstance(): ClientService {
-    if (!ClientService.instance) {
-      ClientService.instance = new ClientService()
-    }
-    return ClientService.instance
-  }
-
-  async createClient(data: CreateClientData): Promise<CreateClientResponse> {
-    try {
-      const response = await api.clients_create_create(data)
-      return {
-        success: true,
-        client: response?.client,
-      }
-    } catch (error: unknown) {
-      debugLog('Error creating client:', error)
-      return {
-        success: false,
-        error: 'Failed to create client',
-      }
-    }
-  }
-
-  async getAllClients(): Promise<ClientSummary[]> {
-    try {
-      const response = await api.clients_all_list()
-      return Array.isArray(response) ? response : []
-    } catch (error) {
-      debugLog('Error fetching clients:', error)
-      throw new Error('Failed to load clients')
-    }
-  }
-
-  searchClients(clientList: Client[], searchTerm: string): Client[] {
-    if (!searchTerm.trim()) {
-      return clientList
-    }
-
-    const term = searchTerm.toLowerCase()
-    return clientList.filter((client) => {
-      const nameMatch = client.name.toLowerCase().includes(term)
-      const emailMatch =
-        'email' in client && typeof client.email === 'string'
-          ? client.email.toLowerCase().includes(term)
-          : false
-      return nameMatch || emailMatch
-    })
-  }
-}
-
-export const clientService = ClientService.getInstance()
diff --git a/frontend/src/services/companyService.ts b/frontend/src/services/companyService.ts
new file mode 100644
index 000000000..0e67a2b72
--- /dev/null
+++ b/frontend/src/services/companyService.ts
@@ -0,0 +1,65 @@
+import { api } from '../api/client'
+import { debugLog } from '../utils/debug'
+import { z } from 'zod'
+import { schemas } from '../api/generated/api'
+
+type CompanySummary = z.infer<typeof schemas.CompanyNameOnly>
+type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
+export type Company = CompanySummary | CompanySearchResult
+export type CreateCompanyData = z.infer<typeof schemas.CompanyCreateRequest>
+import type { CreateCompanyResponse } from '@/constants/company-wrapper'
+
+export class CompanyService {
+  private static instance: CompanyService
+
+  static getInstance(): CompanyService {
+    if (!CompanyService.instance) {
+      CompanyService.instance = new CompanyService()
+    }
+    return CompanyService.instance
+  }
+
+  async createCompany(data: CreateCompanyData): Promise<CreateCompanyResponse> {
+    try {
+      const response = await api.companies_create_create(data)
+      return {
+        success: true,
+        company: response?.company,
+      }
+    } catch (error: unknown) {
+      debugLog('Error creating company:', error)
+      return {
+        success: false,
+        error: 'Failed to create company',
+      }
+    }
+  }
+
+  async getAllCompanies(): Promise<CompanySummary[]> {
+    try {
+      const response = await api.companies_all_list()
+      return Array.isArray(response) ? response : []
+    } catch (error) {
+      debugLog('Error fetching companies:', error)
+      throw new Error('Failed to load companies')
+    }
+  }
+
+  searchCompanies(companyList: Company[], searchTerm: string): Company[] {
+    if (!searchTerm.trim()) {
+      return companyList
+    }
+
+    const term = searchTerm.toLowerCase()
+    return companyList.filter((company) => {
+      const nameMatch = company.name.toLowerCase().includes(term)
+      const emailMatch =
+        'email' in company && typeof company.email === 'string'
+          ? company.email.toLowerCase().includes(term)
+          : false
+      return nameMatch || emailMatch
+    })
+  }
+}
+
+export const companyService = CompanyService.getInstance()
diff --git a/frontend/src/services/job-aging-report.service.ts b/frontend/src/services/job-aging-report.service.ts
index 4de7feeef..f78cf4752 100644
--- a/frontend/src/services/job-aging-report.service.ts
+++ b/frontend/src/services/job-aging-report.service.ts
@@ -7,7 +7,7 @@ export interface JobAgingData {
   id: string
   job_number: number
   name: string
-  client_name: string
+  company_name: string
   status: string
   status_display: string
   financial_data: {
@@ -63,7 +63,7 @@ export class JobAgingReportService {
     const headers = [
       'Job Number',
       'Job Name',
-      'Client Name',
+      'Company Name',
       'Status',
       'Days in Status',
       'Job Age (Days)',
@@ -77,7 +77,7 @@ export class JobAgingReportService {
     const rows = jobs.map((job) => [
       job.job_number,
       job.name,
-      job.client_name,
+      job.company_name,
       job.status_display,
       job.timing_data.days_in_current_status,
       job.timing_data.created_days_ago,
diff --git a/frontend/src/services/job.service.ts b/frontend/src/services/job.service.ts
index e61b32e16..2af684f83 100644
--- a/frontend/src/services/job.service.ts
+++ b/frontend/src/services/job.service.ts
@@ -47,7 +47,7 @@ async function updateJobHeaderPartial(
       for (const field of keys) {
         beforeValues[field] = normalizeBefore(field, beforeSnapshot[field])
       }
-      debugLog('[jobService.updateJobHeaderPartial] using client snapshot', { jobId, keys })
+      debugLog('[jobService.updateJobHeaderPartial] using company snapshot', { jobId, keys })
     } else {
       // Fallback: get from server (should not happen in normal delta flow)
       debugLog('[jobService.updateJobHeaderPartial] FALLBACK: fetching from server', {
@@ -61,11 +61,11 @@ async function updateJobHeaderPartial(
           case 'name':
             beforeValues[field] = currentJob.data.job.name
             break
-          case 'client_id':
-            beforeValues[field] = currentJob.data.job.client_id
+          case 'company_id':
+            beforeValues[field] = currentJob.data.job.company_id
             break
-          case 'client_name':
-            beforeValues[field] = currentJob.data.job.client_name
+          case 'company_name':
+            beforeValues[field] = currentJob.data.job.company_name
             break
           case 'job_status':
             beforeValues[field] = currentJob.data.job.job_status
@@ -328,7 +328,7 @@ export const jobService = {
     return jobs.filter(
       (job) =>
         job.name?.toLowerCase().includes(searchTerm) ||
-        job.client_name?.toLowerCase().includes(searchTerm) ||
+        job.company_name?.toLowerCase().includes(searchTerm) ||
         String(job.job_number).toLowerCase().includes(searchTerm) ||
         job.description?.toLowerCase().includes(searchTerm),
     )
diff --git a/frontend/src/services/kpi.service.ts b/frontend/src/services/kpi.service.ts
index ce2eb11bd..07924201e 100644
--- a/frontend/src/services/kpi.service.ts
+++ b/frontend/src/services/kpi.service.ts
@@ -48,7 +48,7 @@ class KPIService {
     try {
       debugLog('Fetching KPI data with params:', params)
 
-      // Use the generated Zodios client with query parameters
+      // Use the generated Zodios company with query parameters
       const response = await api.accounting_reports_calendar_retrieve({
         queries: {
           year: params.year,
diff --git a/frontend/src/services/sales-pipeline-report.service.ts b/frontend/src/services/sales-pipeline-report.service.ts
index 4b1fc3aa9..d8e21e86a 100644
--- a/frontend/src/services/sales-pipeline-report.service.ts
+++ b/frontend/src/services/sales-pipeline-report.service.ts
@@ -22,7 +22,7 @@ export const salesPipelineReportService = {
    * Two GETs hit `/api/accounting/reports/sales-pipeline/` simultaneously; the
    * caller scales the baseline to the headline window's length client-side.
    *
-   * Both calls go through the same generated client, so warnings, etag, and
+   * Both calls go through the same generated company, so warnings, etag, and
    * error handling are identical to the single-window method.
    */
   async getCurrentAndBaseline(args: {
diff --git a/frontend/src/services/wip-report.service.ts b/frontend/src/services/wip-report.service.ts
index 665577856..df91d3cba 100644
--- a/frontend/src/services/wip-report.service.ts
+++ b/frontend/src/services/wip-report.service.ts
@@ -6,7 +6,7 @@ import { toLocalDateString } from '@/utils/dateUtils'
 export interface WIPJobData {
   job_number: number
   name: string
-  client: string
+  company: string
   status: string
   time_cost: number
   time_rev: number
@@ -76,7 +76,7 @@ export class WIPReportService {
     const headers = [
       'Job Number',
       'Job Name',
-      'Client',
+      'Company',
       'Status',
       `Time (${valueLabel})`,
       `Material (${valueLabel})`,
@@ -89,7 +89,7 @@ export class WIPReportService {
     const rows = jobs.map((job) => [
       job.job_number,
       job.name,
-      job.client,
+      job.company,
       job.status,
       method === 'revenue' ? job.time_rev : job.time_cost,
       method === 'revenue' ? job.material_rev : job.material_cost,
diff --git a/frontend/src/stores/__tests__/jobs.test.ts b/frontend/src/stores/__tests__/jobs.test.ts
index 8524a1bca..5cc4bfcb4 100644
--- a/frontend/src/stores/__tests__/jobs.test.ts
+++ b/frontend/src/stores/__tests__/jobs.test.ts
@@ -26,7 +26,7 @@ function buildKanbanJob(overrides: Partial<Record<string, unknown>> = {}) {
     name: overrides.name ?? 'Kanban Job',
     description: overrides.description ?? '',
     job_number: overrides.job_number ?? 9001,
-    client_name: overrides.client_name ?? 'Client',
+    company_name: overrides.company_name ?? 'Company',
     contact_person: overrides.contact_person ?? '',
     people: overrides.people ?? [],
     status: overrides.status ?? 'In Progress',
diff --git a/frontend/src/stores/clientStore.ts b/frontend/src/stores/clientStore.ts
deleted file mode 100644
index 73229851b..000000000
--- a/frontend/src/stores/clientStore.ts
+++ /dev/null
@@ -1,230 +0,0 @@
-import { defineStore } from 'pinia'
-import { ref, computed } from 'vue'
-import { api } from '@/api/client'
-import { schemas } from '@/api/generated/api'
-import type { z } from 'zod'
-
-// Type definitions
-type ClientSearchResult = z.infer<typeof schemas.ClientSearchResult>
-type ClientSearchResponse = z.infer<typeof schemas.ClientSearchResponse>
-type ClientDetail = z.infer<typeof schemas.ClientDetailResponse>
-type ClientContact = z.infer<typeof schemas.ClientContact>
-type ClientJobsResponse = z.infer<typeof schemas.ClientJobsResponse>
-
-// Type for client jobs - inferred from generated schema
-type ClientJob = z.infer<typeof schemas.ClientJobHeader>
-
-export interface FetchClientsParams {
-  page?: number
-  pageSize?: number
-  query?: string
-  sortBy?: string
-  sortDir?: 'asc' | 'desc'
-}
-
-export const useClientStore = defineStore('clients', () => {
-  // State - paginated clients list
-  const clients = ref<ClientSearchResult[]>([])
-  const page = ref(1)
-  const pageSize = ref(50)
-  const totalPages = ref(0)
-  const totalCount = ref(0)
-  const searchQuery = ref('')
-  const sortBy = ref<string>('name')
-  const sortDir = ref<'asc' | 'desc'>('asc')
-
-  // State - client details and related data
-  const detailedClients = ref<Record<string, ClientDetail>>({})
-  const clientContacts = ref<Record<string, ClientContact[]>>({})
-  const clientJobs = ref<Record<string, ClientJob[]>>({})
-  const isLoading = ref(false)
-  const isLoadingDetail = ref(false)
-  const isLoadingContacts = ref(false)
-  const isLoadingJobs = ref(false)
-
-  // Getters
-  const hasClients = computed(() => clients.value.length > 0)
-
-  /**
-   * Fetch clients with server-side pagination, search, and sorting
-   */
-  async function fetchClients(params: FetchClientsParams = {}) {
-    isLoading.value = true
-
-    // Update local state from params
-    if (params.page !== undefined) page.value = params.page
-    if (params.pageSize !== undefined) pageSize.value = params.pageSize
-    if (params.query !== undefined) searchQuery.value = params.query
-    if (params.sortBy !== undefined) sortBy.value = params.sortBy
-    if (params.sortDir !== undefined) sortDir.value = params.sortDir
-
-    try {
-      const response: ClientSearchResponse = await api.clients_search_retrieve({
-        queries: {
-          page: page.value,
-          page_size: pageSize.value,
-          q: searchQuery.value || undefined,
-          sort_by: sortBy.value,
-          sort_dir: sortDir.value,
-        },
-      })
-      clients.value = response.results
-      totalCount.value = response.count
-      totalPages.value = response.total_pages
-      page.value = response.page
-      pageSize.value = response.page_size
-    } catch (error) {
-      console.error('Failed to fetch clients:', error)
-      clients.value = []
-      throw error
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  /**
-   * Fetch detailed information for a specific client
-   * @param clientId UUID of the client
-   */
-  async function fetchClientDetail(clientId: string) {
-    isLoadingDetail.value = true
-
-    try {
-      const response = await api.clients_retrieve({
-        params: { client_id: clientId },
-      })
-      detailedClients.value[clientId] = response
-      return response
-    } catch (error) {
-      console.error('Failed to fetch client details:', error)
-      throw error
-    } finally {
-      isLoadingDetail.value = false
-    }
-  }
-
-  /**
-   * Fetch contacts for a specific client
-   * @param clientId UUID of the client
-   */
-  async function fetchClientContacts(clientId: string) {
-    isLoadingContacts.value = true
-
-    try {
-      const response = await api.clients_contacts_list({
-        queries: { client_id: clientId },
-      })
-      clientContacts.value[clientId] = response
-      return response
-    } catch (error) {
-      console.error('Failed to fetch client contacts:', error)
-      clientContacts.value[clientId] = []
-      throw error
-    } finally {
-      isLoadingContacts.value = false
-    }
-  }
-
-  /**
-   * Get cached client detail or fetch if not available
-   * @param clientId UUID of the client
-   */
-  async function getClientDetail(clientId: string): Promise<ClientDetail> {
-    if (detailedClients.value[clientId]) {
-      return detailedClients.value[clientId]
-    }
-    return await fetchClientDetail(clientId)
-  }
-
-  /**
-   * Get cached client contacts or fetch if not available
-   * @param clientId UUID of the client
-   */
-  async function getClientContacts(clientId: string): Promise<ClientContact[]> {
-    if (clientContacts.value[clientId]) {
-      return clientContacts.value[clientId]
-    }
-    return await fetchClientContacts(clientId)
-  }
-
-  /**
-   * Fetch jobs for a specific client
-   * @param clientId UUID of the client
-   */
-  async function fetchClientJobs(clientId: string) {
-    isLoadingJobs.value = true
-
-    try {
-      const response: ClientJobsResponse = await api.clients_jobs_retrieve({
-        params: { client_id: clientId },
-      })
-      clientJobs.value[clientId] = response.results
-      return response.results
-    } catch (error) {
-      console.error('Failed to fetch client jobs:', error)
-      clientJobs.value[clientId] = []
-      throw error
-    } finally {
-      isLoadingJobs.value = false
-    }
-  }
-
-  /**
-   * Get cached client jobs or fetch if not available
-   * @param clientId UUID of the client
-   */
-  async function getClientJobs(clientId: string): Promise<ClientJob[]> {
-    if (clientJobs.value[clientId]) {
-      return clientJobs.value[clientId]
-    }
-    return await fetchClientJobs(clientId)
-  }
-
-  /**
-   * Clear all cached data
-   */
-  function clearCache() {
-    clients.value = []
-    detailedClients.value = {}
-    clientContacts.value = {}
-    clientJobs.value = {}
-    searchQuery.value = ''
-    page.value = 1
-    totalPages.value = 0
-    totalCount.value = 0
-  }
-
-  return {
-    // State - paginated clients
-    clients,
-    page,
-    pageSize,
-    totalPages,
-    totalCount,
-    searchQuery,
-    sortBy,
-    sortDir,
-
-    // State - other
-    detailedClients,
-    clientContacts,
-    clientJobs,
-    isLoading,
-    isLoadingDetail,
-    isLoadingContacts,
-    isLoadingJobs,
-
-    // Getters
-    hasClients,
-
-    // Actions
-    fetchClients,
-    fetchClientDetail,
-    fetchClientContacts,
-    fetchClientJobs,
-    getClientDetail,
-    getClientContacts,
-    getClientJobs,
-    clearCache,
-  }
-})
diff --git a/frontend/src/stores/companyStore.ts b/frontend/src/stores/companyStore.ts
new file mode 100644
index 000000000..e39f4016b
--- /dev/null
+++ b/frontend/src/stores/companyStore.ts
@@ -0,0 +1,230 @@
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import { api } from '@/api/client'
+import { schemas } from '@/api/generated/api'
+import type { z } from 'zod'
+
+// Type definitions
+type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
+type CompanySearchResponse = z.infer<typeof schemas.CompanySearchResponse>
+type CompanyDetail = z.infer<typeof schemas.CompanyDetailResponse>
+type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyJobsResponse = z.infer<typeof schemas.CompanyJobsResponse>
+
+// Type for company jobs - inferred from generated schema
+type CompanyJob = z.infer<typeof schemas.CompanyJobHeader>
+
+export interface FetchCompaniesParams {
+  page?: number
+  pageSize?: number
+  query?: string
+  sortBy?: string
+  sortDir?: 'asc' | 'desc'
+}
+
+export const useCompanyStore = defineStore('companies', () => {
+  // State - paginated companies list
+  const companies = ref<CompanySearchResult[]>([])
+  const page = ref(1)
+  const pageSize = ref(50)
+  const totalPages = ref(0)
+  const totalCount = ref(0)
+  const searchQuery = ref('')
+  const sortBy = ref<string>('name')
+  const sortDir = ref<'asc' | 'desc'>('asc')
+
+  // State - company details and related data
+  const detailedCompanies = ref<Record<string, CompanyDetail>>({})
+  const companyContacts = ref<Record<string, ClientContact[]>>({})
+  const companyJobs = ref<Record<string, CompanyJob[]>>({})
+  const isLoading = ref(false)
+  const isLoadingDetail = ref(false)
+  const isLoadingContacts = ref(false)
+  const isLoadingJobs = ref(false)
+
+  // Getters
+  const hasCompanies = computed(() => companies.value.length > 0)
+
+  /**
+   * Fetch companies with server-side pagination, search, and sorting
+   */
+  async function fetchCompanies(params: FetchCompaniesParams = {}) {
+    isLoading.value = true
+
+    // Update local state from params
+    if (params.page !== undefined) page.value = params.page
+    if (params.pageSize !== undefined) pageSize.value = params.pageSize
+    if (params.query !== undefined) searchQuery.value = params.query
+    if (params.sortBy !== undefined) sortBy.value = params.sortBy
+    if (params.sortDir !== undefined) sortDir.value = params.sortDir
+
+    try {
+      const response: CompanySearchResponse = await api.companies_search_retrieve({
+        queries: {
+          page: page.value,
+          page_size: pageSize.value,
+          q: searchQuery.value || undefined,
+          sort_by: sortBy.value,
+          sort_dir: sortDir.value,
+        },
+      })
+      companies.value = response.results
+      totalCount.value = response.count
+      totalPages.value = response.total_pages
+      page.value = response.page
+      pageSize.value = response.page_size
+    } catch (error) {
+      console.error('Failed to fetch companies:', error)
+      companies.value = []
+      throw error
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Fetch detailed information for a specific company
+   * @param companyId UUID of the company
+   */
+  async function fetchCompanyDetail(companyId: string) {
+    isLoadingDetail.value = true
+
+    try {
+      const response = await api.companies_retrieve({
+        params: { company_id: companyId },
+      })
+      detailedCompanies.value[companyId] = response
+      return response
+    } catch (error) {
+      console.error('Failed to fetch company details:', error)
+      throw error
+    } finally {
+      isLoadingDetail.value = false
+    }
+  }
+
+  /**
+   * Fetch contacts for a specific company
+   * @param companyId UUID of the company
+   */
+  async function fetchClientContacts(companyId: string) {
+    isLoadingContacts.value = true
+
+    try {
+      const response = await api.companies_contacts_list({
+        queries: { company_id: companyId },
+      })
+      companyContacts.value[companyId] = response
+      return response
+    } catch (error) {
+      console.error('Failed to fetch company contacts:', error)
+      companyContacts.value[companyId] = []
+      throw error
+    } finally {
+      isLoadingContacts.value = false
+    }
+  }
+
+  /**
+   * Get cached company detail or fetch if not available
+   * @param companyId UUID of the company
+   */
+  async function getCompanyDetail(companyId: string): Promise<CompanyDetail> {
+    if (detailedCompanies.value[companyId]) {
+      return detailedCompanies.value[companyId]
+    }
+    return await fetchCompanyDetail(companyId)
+  }
+
+  /**
+   * Get cached company contacts or fetch if not available
+   * @param companyId UUID of the company
+   */
+  async function getClientContacts(companyId: string): Promise<ClientContact[]> {
+    if (companyContacts.value[companyId]) {
+      return companyContacts.value[companyId]
+    }
+    return await fetchClientContacts(companyId)
+  }
+
+  /**
+   * Fetch jobs for a specific company
+   * @param companyId UUID of the company
+   */
+  async function fetchCompanyJobs(companyId: string) {
+    isLoadingJobs.value = true
+
+    try {
+      const response: CompanyJobsResponse = await api.companies_jobs_retrieve({
+        params: { company_id: companyId },
+      })
+      companyJobs.value[companyId] = response.results
+      return response.results
+    } catch (error) {
+      console.error('Failed to fetch company jobs:', error)
+      companyJobs.value[companyId] = []
+      throw error
+    } finally {
+      isLoadingJobs.value = false
+    }
+  }
+
+  /**
+   * Get cached company jobs or fetch if not available
+   * @param companyId UUID of the company
+   */
+  async function getCompanyJobs(companyId: string): Promise<CompanyJob[]> {
+    if (companyJobs.value[companyId]) {
+      return companyJobs.value[companyId]
+    }
+    return await fetchCompanyJobs(companyId)
+  }
+
+  /**
+   * Clear all cached data
+   */
+  function clearCache() {
+    companies.value = []
+    detailedCompanies.value = {}
+    companyContacts.value = {}
+    companyJobs.value = {}
+    searchQuery.value = ''
+    page.value = 1
+    totalPages.value = 0
+    totalCount.value = 0
+  }
+
+  return {
+    // State - paginated companies
+    companies,
+    page,
+    pageSize,
+    totalPages,
+    totalCount,
+    searchQuery,
+    sortBy,
+    sortDir,
+
+    // State - other
+    detailedCompanies,
+    companyContacts,
+    companyJobs,
+    isLoading,
+    isLoadingDetail,
+    isLoadingContacts,
+    isLoadingJobs,
+
+    // Getters
+    hasCompanies,
+
+    // Actions
+    fetchCompanies,
+    fetchCompanyDetail,
+    fetchClientContacts,
+    fetchCompanyJobs,
+    getCompanyDetail,
+    getClientContacts,
+    getCompanyJobs,
+    clearCache,
+  }
+})
diff --git a/frontend/src/stores/jobs.ts b/frontend/src/stores/jobs.ts
index ccf8be590..46ab4e0b2 100644
--- a/frontend/src/stores/jobs.ts
+++ b/frontend/src/stores/jobs.ts
@@ -320,7 +320,7 @@ export const useJobsStore = defineStore('jobs', () => {
           ...kanbanJob,
           name: detailedJob.job.name,
           status: detailedJob.job.job_status,
-          client_name: detailedJob.job.client_name || '',
+          company_name: detailedJob.job.company_name || '',
           contact_person: detailedJob.job.contact_name || kanbanJob.contact_person,
           paid: detailedJob.job.paid || false,
         },
@@ -486,8 +486,8 @@ export const useJobsStore = defineStore('jobs', () => {
       job_id: job.id,
       job_number: job.job_number,
       name: job.name,
-      client_id: job.client_id ?? null,
-      client_name: job.client_name ?? null,
+      company_id: job.company_id ?? null,
+      company_name: job.company_name ?? null,
       contact_id: job.contact_id ?? null,
       contact_name: job.contact_name ?? null,
       status: job.job_status as JobHeaderResponse['status'],
diff --git a/frontend/src/typed-router.d.ts b/frontend/src/typed-router.d.ts
index 211faf942..f83ef2dd6 100644
--- a/frontend/src/typed-router.d.ts
+++ b/frontend/src/typed-router.d.ts
@@ -38,16 +38,16 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
-    '/crm/clients/(index)': RouteRecordInfo<
-      '/crm/clients/(index)',
-      '/crm/clients',
+    '/crm/companies/(index)': RouteRecordInfo<
+      '/crm/companies/(index)',
+      '/crm/companies',
       Record<never, never>,
       Record<never, never>,
       | never
     >,
-    '/crm/clients/[id]': RouteRecordInfo<
-      '/crm/clients/[id]',
-      '/crm/clients/:id',
+    '/crm/companies/[id]': RouteRecordInfo<
+      '/crm/companies/[id]',
+      '/crm/companies/:id',
       { id: ParamValue<true> },
       { id: ParamValue<false> },
       | never
@@ -302,15 +302,15 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
-    'src/pages/crm/clients/(index).vue': {
+    'src/pages/crm/companies/(index).vue': {
       routes:
-        | '/crm/clients/(index)'
+        | '/crm/companies/(index)'
       views:
         | never
     }
-    'src/pages/crm/clients/[id].vue': {
+    'src/pages/crm/companies/[id].vue': {
       routes:
-        | '/crm/clients/[id]'
+        | '/crm/companies/[id]'
       views:
         | never
     }
diff --git a/frontend/src/types/job-aging.types.ts b/frontend/src/types/job-aging.types.ts
index 2c6dc313e..bebf07e23 100644
--- a/frontend/src/types/job-aging.types.ts
+++ b/frontend/src/types/job-aging.types.ts
@@ -2,7 +2,7 @@ export interface JobAgingData {
   id: string
   job_number: number
   name: string
-  client_name: string
+  company_name: string
   status: string
   status_display: string
   financial_data: {
diff --git a/frontend/src/types/job-movement.types.ts b/frontend/src/types/job-movement.types.ts
index 148bf6ad0..baa733def 100644
--- a/frontend/src/types/job-movement.types.ts
+++ b/frontend/src/types/job-movement.types.ts
@@ -91,7 +91,7 @@ export interface JobMovementJobDetail {
   id: string
   job_number: string
   name: string
-  client_name: string
+  company_name: string
   status: string
   created_at: string
 }
diff --git a/frontend/src/types/sales-forecast.types.ts b/frontend/src/types/sales-forecast.types.ts
index 08dd2f99e..ae4c7cc8d 100644
--- a/frontend/src/types/sales-forecast.types.ts
+++ b/frontend/src/types/sales-forecast.types.ts
@@ -13,7 +13,7 @@ export interface SalesForecastReportResponse {
 
 export interface SalesForecastDetailRow {
   date: string
-  client_name: string
+  company_name: string
   job_number: number | null
   job_name: string | null
   job_id: string | null
diff --git a/frontend/src/utils/__tests__/timesheetCalc.test.ts b/frontend/src/utils/__tests__/timesheetCalc.test.ts
index 47ca6b5c0..35742c186 100644
--- a/frontend/src/utils/__tests__/timesheetCalc.test.ts
+++ b/frontend/src/utils/__tests__/timesheetCalc.test.ts
@@ -33,7 +33,7 @@ function makeEntry(over: Partial<TimesheetCostLine> = {}): TimesheetCostLine {
     job_id: '',
     job_number: 0,
     job_name: '',
-    client_name: '',
+    company_name: '',
     charge_out_rate: 0,
     wage_rate: 0,
     xero_pay_item_name: '',
diff --git a/frontend/src/utils/iconRegistry.ts b/frontend/src/utils/iconRegistry.ts
index 02161d5b6..b4601eae8 100644
--- a/frontend/src/utils/iconRegistry.ts
+++ b/frontend/src/utils/iconRegistry.ts
@@ -63,7 +63,7 @@ const sectionIconMap: Record<string, Component> = {
 
 // Field key patterns to icon mapping (used when backend doesn't provide icon)
 const fieldIconPatterns: Array<{ pattern: RegExp; icon: Component }> = [
-  { pattern: /^(company_name|shop_client|test_client_name)$/, icon: User },
+  { pattern: /^(company_name|shop_company|test_company_name)$/, icon: User },
   { pattern: /(rate|target|markup)/, icon: DollarSign },
   { pattern: /percent/, icon: Percent },
   { pattern: /(number|starting_)/, icon: Hash },
diff --git a/frontend/src/views/AdminArchiveJobsView.vue b/frontend/src/views/AdminArchiveJobsView.vue
index 55f5631de..f7c742f38 100644
--- a/frontend/src/views/AdminArchiveJobsView.vue
+++ b/frontend/src/views/AdminArchiveJobsView.vue
@@ -81,7 +81,7 @@ const error = ref('')
 interface ArchiveTableRow {
   id: number
   name: string
-  client_name: string
+  company_name: string
   updated_at?: string | null
   jobId: string
 }
@@ -90,7 +90,7 @@ const toTableRow = (job: Job): ArchiveTableRow => ({
   id: job.job_number,
   jobId: job.id,
   name: job.name,
-  client_name: job.client_name ?? '',
+  company_name: job.company_name ?? '',
   updated_at: job.updated_at ?? null,
 })
 
diff --git a/frontend/src/views/WorkshopKanbanView.vue b/frontend/src/views/WorkshopKanbanView.vue
index 3d6eb4711..ab1e00468 100644
--- a/frontend/src/views/WorkshopKanbanView.vue
+++ b/frontend/src/views/WorkshopKanbanView.vue
@@ -83,7 +83,7 @@ onMounted(async () => {
             <CardContent>
               <div class="text-xl text-black font-semibold">
                 <Briefcase class="inline-block" />
-                Customer: <span class="text-gray font-medium text-lg">{{ job.client_name }}</span>
+                Customer: <span class="text-gray font-medium text-lg">{{ job.company_name }}</span>
               </div>
               <div class="text-xl text-black font-semibold">
                 <NotebookText class="inline-block" />
diff --git a/frontend/src/views/WorkshopView.vue b/frontend/src/views/WorkshopView.vue
index 3eea10478..9db3c04a6 100644
--- a/frontend/src/views/WorkshopView.vue
+++ b/frontend/src/views/WorkshopView.vue
@@ -83,7 +83,7 @@ onMounted(async () => {
             <CardContent>
               <div class="text-xl text-black font-semibold">
                 <Briefcase class="inline-block" />
-                Customer: <span class="text-gray font-medium text-lg">{{ job.client_name }}</span>
+                Customer: <span class="text-gray font-medium text-lg">{{ job.company_name }}</span>
               </div>
               <div class="text-xl text-black font-semibold">
                 <NotebookText class="inline-block" />
@@ -117,7 +117,7 @@ onMounted(async () => {
             <CardContent class="flex flex-col gap-2">
               <!-- <div class="text-xl text-black font-semibold">
                 <Briefcase class="inline-block" />
-                Customer: <span class="text-gray font-medium text-lg">{{ job.client_name }}</span>
+                Customer: <span class="text-gray font-medium text-lg">{{ job.company_name }}</span>
               </div> -->
               <Skeleton class="h-4 max-w-50" />
               <!-- <div class="text-xl text-black font-semibold">
diff --git a/frontend/src/views/__tests__/AdminErrorView.resolved.test.ts b/frontend/src/views/__tests__/AdminErrorView.resolved.test.ts
index ef07a275d..8aa3aa41d 100644
--- a/frontend/src/views/__tests__/AdminErrorView.resolved.test.ts
+++ b/frontend/src/views/__tests__/AdminErrorView.resolved.test.ts
@@ -4,7 +4,7 @@ import { defineComponent, h } from 'vue'
 import type { JobErrorFilterState, SystemErrorFilterState } from '@/types/errorFilters'
 
 // The grouped job-error and grouped xero-error endpoints are the calls these
-// tests exercise. Mock the generated client so we can assert the query params
+// tests exercise. Mock the generated company so we can assert the query params
 // forwarded to them and feed canned grouped responses back through the view's
 // mapping.
 const { groupedRetrieveMock, xeroGroupedRetrieveMock } = vi.hoisted(() => ({
diff --git a/frontend/src/views/__tests__/QuotingChatView.test.ts b/frontend/src/views/__tests__/QuotingChatView.test.ts
index ecf74294e..d89afd3bf 100644
--- a/frontend/src/views/__tests__/QuotingChatView.test.ts
+++ b/frontend/src/views/__tests__/QuotingChatView.test.ts
@@ -53,7 +53,7 @@ const { mockRouter, mockRoute, mockServiceInstance } = vi.hoisted(() => {
         jobId: 'test-job-id',
         jobName: 'Test Job',
         jobNumber: '2024-001',
-        clientName: 'Test Client',
+        companyName: 'Test Company',
       },
     },
     mockServiceInstance: {
@@ -107,7 +107,7 @@ vi.mock('@/api/generated/api', () => ({
   endpoints: [],
 }))
 
-// Mock the API client to avoid initialization issues
+// Mock the API company to avoid initialization issues
 vi.mock('@/api/client', () => ({
   api: {},
   getApi: () => ({}),
diff --git a/frontend/src/views/jobColumns.ts b/frontend/src/views/jobColumns.ts
index e1298da3d..ff3372526 100644
--- a/frontend/src/views/jobColumns.ts
+++ b/frontend/src/views/jobColumns.ts
@@ -5,7 +5,7 @@ import { Checkbox } from '@/components/ui/checkbox'
 interface JobTableRow {
   id: number
   name: string
-  client_name: string
+  company_name: string
   updated_at?: string | null
 }
 
@@ -59,10 +59,10 @@ export const jobColumns: ColumnDef<JobTableRow, unknown>[] = [
     cell: ({ row }: CellContext<JobTableRow, unknown>) => h('span', row.original.name),
   },
   {
-    id: 'client_name',
-    accessorKey: 'client_name',
-    header: 'Client',
-    cell: ({ row }: CellContext<JobTableRow, unknown>) => h('span', row.original.client_name),
+    id: 'company_name',
+    accessorKey: 'company_name',
+    header: 'Company',
+    cell: ({ row }: CellContext<JobTableRow, unknown>) => h('span', row.original.company_name),
   },
   {
     id: 'updated_at',
diff --git a/frontend/tests/company-defaults.spec.ts b/frontend/tests/company-defaults.spec.ts
index 19cea1c03..abfc73f75 100644
--- a/frontend/tests/company-defaults.spec.ts
+++ b/frontend/tests/company-defaults.spec.ts
@@ -19,10 +19,10 @@ test('test can call backend API directly', async ({ authenticatedPage: page }) =
   expect(contentType).toContain('application/json')
 
   const data = await response.json()
-  expect(data.test_client_name).toBeDefined()
-  expect(data.test_client_name).not.toBe('')
+  expect(data.test_company_name).toBeDefined()
+  expect(data.test_company_name).not.toBe('')
 
-  console.log(`Test client name from API: ${data.test_client_name}`)
+  console.log(`Test company name from API: ${data.test_company_name}`)
 })
 
 test('test company defaults edit and save', async ({ authenticatedPage: page }) => {
diff --git a/frontend/tests/crm/phone-call-job-link.spec.ts b/frontend/tests/crm/phone-call-job-link.spec.ts
index 40b308e81..582c4e191 100644
--- a/frontend/tests/crm/phone-call-job-link.spec.ts
+++ b/frontend/tests/crm/phone-call-job-link.spec.ts
@@ -23,7 +23,7 @@ from apps.crm.models import PhoneCallRecord
 from django.utils import timezone
 from uuid import uuid4
 
-job = Job.objects.select_related("client").get(id="${jobId}")
+job = Job.objects.select_related("company").get(id="${jobId}")
 now = timezone.now()
 call = PhoneCallRecord.objects.create(
     provider_call_id=f"e2e:{uuid4()}",
@@ -37,7 +37,7 @@ call = PhoneCallRecord.objects.create(
     origin="+6421555123",
     destination="+6496365131",
     duration_seconds=67,
-    client=job.client,
+    company=job.company,
     raw_json={
         "id": "e2e",
         "calldate": now.date().isoformat(),
diff --git a/frontend/tests/fixtures/auth.ts b/frontend/tests/fixtures/auth.ts
index 6306bc3c6..fae2c7dc0 100644
--- a/frontend/tests/fixtures/auth.ts
+++ b/frontend/tests/fixtures/auth.ts
@@ -6,7 +6,7 @@ import {
   expectStepUnder,
   INFINITE_TIMEOUT,
   submitJobAndWaitForCreatedJob,
-  TEST_CLIENT_NAME,
+  TEST_COMPANY_NAME,
   waitForCurrentUrl,
 } from './helpers'
 
@@ -22,7 +22,7 @@ type WorkerFixtures = {
 
 const SHARED_EDIT_JOB_BUDGET_MS = {
   navigateToCreatePage: 2500,
-  searchAndSelectClient: 1500,
+  searchAndSelectCompany: 1500,
   fillJobDetails: 1000,
   contactSelection: 2500,
   submitAndRedirect: 3500,
@@ -205,14 +205,14 @@ export const test = base.extend<AuthFixtures, WorkerFixtures>({
       )
 
       await expectStepUnder(
-        'sharedEditJobUrl: search and select client',
-        SHARED_EDIT_JOB_BUDGET_MS.searchAndSelectClient,
+        'sharedEditJobUrl: search and select company',
+        SHARED_EDIT_JOB_BUDGET_MS.searchAndSelectCompany,
         async () => {
-          const clientInput = autoId(page, 'ClientLookup-input')
-          await clientInput.waitFor({ timeout: 10000 })
-          await clientInput.fill('ABC')
-          await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-          await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
+          const companyInput = autoId(page, 'CompanyLookup-input')
+          await companyInput.waitFor({ timeout: 10000 })
+          await companyInput.fill('ABC')
+          await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+          await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
         },
       )
 
diff --git a/frontend/tests/fixtures/helpers.ts b/frontend/tests/fixtures/helpers.ts
index 0e296ecd2..74b9de94a 100644
--- a/frontend/tests/fixtures/helpers.ts
+++ b/frontend/tests/fixtures/helpers.ts
@@ -4,7 +4,7 @@ import { appendFileSync, existsSync, mkdirSync } from 'fs'
 import path from 'path'
 
 // Test data constants
-export const TEST_CLIENT_NAME = 'ABC Carpet Cleaning TEST IGNORE'
+export const TEST_COMPANY_NAME = 'ABC Carpet Cleaning TEST IGNORE'
 
 // Network logging state
 let networkRunId: string | null = null
@@ -20,7 +20,7 @@ export const INFINITE_TIMEOUT = 120000
 
 type JsonObject = Record<string, unknown>
 
-type CreatedClientSummary = {
+type CreatedCompanySummary = {
   name: string
   xeroContactId: string
 }
@@ -29,51 +29,51 @@ function isJsonObject(value: unknown): value is JsonObject {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-async function parseClientCreateResponse(response: Response): Promise<CreatedClientSummary> {
+async function parseCompanyCreateResponse(response: Response): Promise<CreatedCompanySummary> {
   const responseText = await response.text()
   let body: unknown
 
   try {
     body = JSON.parse(responseText)
   } catch {
-    throw new Error(`Client create returned non-JSON response: ${responseText}`)
+    throw new Error(`Company create returned non-JSON response: ${responseText}`)
   }
 
   if (!response.ok()) {
-    throw new Error(`Client create failed with HTTP ${response.status()}: ${responseText}`)
+    throw new Error(`Company create failed with HTTP ${response.status()}: ${responseText}`)
   }
 
-  if (!isJsonObject(body) || body.success !== true || !isJsonObject(body.client)) {
-    throw new Error(`Client create returned unsuccessful payload: ${responseText}`)
+  if (!isJsonObject(body) || body.success !== true || !isJsonObject(body.company)) {
+    throw new Error(`Company create returned unsuccessful payload: ${responseText}`)
   }
 
-  const name = body.client.name
-  const xeroContactId = body.client.xero_contact_id
+  const name = body.company.name
+  const xeroContactId = body.company.xero_contact_id
   if (typeof name !== 'string' || name.length === 0) {
-    throw new Error(`Client create returned missing client name: ${responseText}`)
+    throw new Error(`Company create returned missing company name: ${responseText}`)
   }
   if (typeof xeroContactId !== 'string' || xeroContactId.length === 0) {
-    throw new Error(`Client create returned client without Xero ID: ${responseText}`)
+    throw new Error(`Company create returned company without Xero ID: ${responseText}`)
   }
 
   return { name, xeroContactId }
 }
 
-export async function waitForClientCreateResponse(
+export async function waitForCompanyCreateResponse(
   page: Page,
   action: () => Promise<void>,
-): Promise<CreatedClientSummary> {
+): Promise<CreatedCompanySummary> {
   const responsePromise = page.waitForResponse(
     (candidate) => {
       const url = new URL(candidate.url())
-      return url.pathname === '/api/clients/create/' && candidate.request().method() === 'POST'
+      return url.pathname === '/api/companies/create/' && candidate.request().method() === 'POST'
     },
     { timeout: 30000 },
   )
 
   await action()
   const response = await responsePromise
-  return await parseClientCreateResponse(response)
+  return await parseCompanyCreateResponse(response)
 }
 
 /**
@@ -118,7 +118,7 @@ export function enableNetworkLogging(
     }
 
     // Only log API calls, skip static assets
-    if (!url.includes('/api/') && !url.includes('/clients/') && !url.includes('/jobs/')) {
+    if (!url.includes('/api/') && !url.includes('/companies/') && !url.includes('/jobs/')) {
       return
     }
 
@@ -375,18 +375,18 @@ export async function createTestPurchaseOrder(page: Page): Promise<string> {
   await page.waitForLoadState('networkidle')
 
   // Create a new supplier using Ctrl+Enter
-  const supplierInput = autoId(page, 'ClientLookup-input')
+  const supplierInput = autoId(page, 'CompanyLookup-input')
   await supplierInput.click()
   await supplierInput.fill(supplierName)
   await page.waitForTimeout(500)
-  await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-  await autoId(page, 'ClientLookup-create-new').waitFor({ timeout: 5000 })
-  await waitForClientCreateResponse(page, async () => {
+  await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+  await autoId(page, 'CompanyLookup-create-new').waitFor({ timeout: 5000 })
+  await waitForCompanyCreateResponse(page, async () => {
     await supplierInput.press('Control+Enter')
   })
 
   // Verify Xero badge is green
-  const xeroIndicator = autoId(page, 'ClientLookup-xero-valid')
+  const xeroIndicator = autoId(page, 'CompanyLookup-xero-valid')
   await expect(xeroIndicator).toBeVisible({ timeout: 10000 })
 
   // Add reference
@@ -426,15 +426,15 @@ export async function createTestJob(page: Page, jobNameSuffix: string): Promise<
     await page.waitForLoadState('networkidle')
   })
 
-  await expectStepUnder('createTestJob: search and select client', 1500, async () => {
-    const clientInput = autoId(page, 'ClientLookup-input')
-    await clientInput.click()
-    await clientInput.fill('ABC')
+  await expectStepUnder('createTestJob: search and select company', 1500, async () => {
+    const companyInput = autoId(page, 'CompanyLookup-input')
+    await companyInput.click()
+    await companyInput.fill('ABC')
     await page.waitForTimeout(500) // Give search time to trigger
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
 
-    await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
-    await expect(clientInput).toHaveValue(TEST_CLIENT_NAME)
+    await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
+    await expect(companyInput).toHaveValue(TEST_COMPANY_NAME)
   })
 
   await expectStepUnder('createTestJob: fill job details', 1000, async () => {
diff --git a/frontend/tests/job/create-job-with-new-client.spec.ts b/frontend/tests/job/create-job-with-new-company.spec.ts
similarity index 57%
rename from frontend/tests/job/create-job-with-new-client.spec.ts
rename to frontend/tests/job/create-job-with-new-company.spec.ts
index 55298814d..f6ee85b92 100644
--- a/frontend/tests/job/create-job-with-new-client.spec.ts
+++ b/frontend/tests/job/create-job-with-new-company.spec.ts
@@ -3,55 +3,55 @@ import {
   autoId,
   dismissToasts,
   submitJobAndWaitForCreatedJob,
-  waitForClientCreateResponse,
+  waitForCompanyCreateResponse,
 } from '../fixtures/helpers'
 
 /**
- * Tests for creating a job with a new client in Xero.
- * Creates a new client during job creation, verifies Xero sync.
+ * Tests for creating a job with a new company in Xero.
+ * Creates a new company during job creation, verifies Xero sync.
  */
 
 // ============================================================================
-// Test Suite: Create Job with New Xero Client
+// Test Suite: Create Job with New Xero Company
 // ============================================================================
 
-test.describe('create job with new xero client', () => {
-  test('create new client via Ctrl+Enter and complete job creation', async ({
+test.describe('create job with new xero company', () => {
+  test('create new company via Ctrl+Enter and complete job creation', async ({
     authenticatedPage: page,
   }) => {
-    // Generate a unique client name with random number
+    // Generate a unique company name with random number
     const randomSuffix = Math.floor(Math.random() * 100000)
-    const newClientName = `[TEST] Client ${randomSuffix}`
-    const jobName = `[TEST] Job for ${newClientName}`
+    const newCompanyName = `[TEST] Company ${randomSuffix}`
+    const jobName = `[TEST] Job for ${newCompanyName}`
 
-    console.log(`Testing with new client: ${newClientName}`)
+    console.log(`Testing with new company: ${newCompanyName}`)
 
     // Navigate to create job page
     await autoId(page, 'AppNavbar-create-job').click()
     await page.waitForURL('**/jobs/create')
     await expect(autoId(page, 'JobCreateView-title')).toContainText('Create New Job')
 
-    // Type the new client name in the client lookup
-    const clientInput = autoId(page, 'ClientLookup-input')
-    await clientInput.fill(newClientName)
+    // Type the new company name in the company lookup
+    const companyInput = autoId(page, 'CompanyLookup-input')
+    await companyInput.fill(newCompanyName)
 
-    // Wait for the dropdown to appear with "Add new client" option
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-    await autoId(page, 'ClientLookup-create-new').waitFor({ timeout: 5000 })
+    // Wait for the dropdown to appear with "Add new company" option
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-create-new').waitFor({ timeout: 5000 })
 
-    // Press Ctrl+Enter to quick-create the client (bypasses modal)
-    await waitForClientCreateResponse(page, async () => {
-      await clientInput.press('Control+Enter')
+    // Press Ctrl+Enter to quick-create the company (bypasses modal)
+    await waitForCompanyCreateResponse(page, async () => {
+      await companyInput.press('Control+Enter')
     })
 
-    // Verify client was created - input should still have the client name
-    await expect(clientInput).toHaveValue(newClientName)
+    // Verify company was created - input should still have the company name
+    await expect(companyInput).toHaveValue(newCompanyName)
 
-    // Verify the Xero badge shows green (client has Xero ID)
-    const xeroIndicator = autoId(page, 'ClientLookup-xero-valid')
+    // Verify the Xero badge shows green (company has Xero ID)
+    const xeroIndicator = autoId(page, 'CompanyLookup-xero-valid')
     await expect(xeroIndicator).toBeVisible({ timeout: 10000 })
 
-    console.log(`Client "${newClientName}" created with Xero ID`)
+    console.log(`Company "${newCompanyName}" created with Xero ID`)
 
     // Fill in the rest of the job form
     await autoId(page, 'JobCreateView-name-input').fill(jobName)
@@ -62,8 +62,8 @@ test.describe('create job with new xero client', () => {
     await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
     await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
 
-    // For a new client, there won't be existing contacts - fill in the create form
-    // The form fields are always visible for new clients
+    // For a new company, there won't be existing contacts - fill in the create form
+    // The form fields are always visible for new companies
     await autoId(page, 'ContactSelectionModal-name-input').fill(`[TEST] Contact ${randomSuffix}`)
     await page.waitForTimeout(200)
     await autoId(page, 'ContactSelectionModal-email-input').fill(`test${randomSuffix}@example.com`)
@@ -98,52 +98,52 @@ test.describe('create job with new xero client', () => {
     await expect(jobNumberElement).toContainText(/#\d+/, { timeout: 10000 })
     const jobNumberText = await jobNumberElement.innerText()
 
-    console.log(`Created job ${jobNumberText} with new client "${newClientName}"`)
+    console.log(`Created job ${jobNumberText} with new company "${newCompanyName}"`)
   })
 
-  test('create new client via modal and complete job creation', async ({
+  test('create new company via modal and complete job creation', async ({
     authenticatedPage: page,
   }) => {
-    // Generate a unique client name with random number
+    // Generate a unique company name with random number
     const randomSuffix = Math.floor(Math.random() * 100000)
-    const newClientName = `[TEST] Modal Client ${randomSuffix}`
+    const newCompanyName = `[TEST] Modal Company ${randomSuffix}`
     const jobName = `[TEST] Modal Job ${randomSuffix}`
 
-    console.log(`Testing with new client (modal method): ${newClientName}`)
+    console.log(`Testing with new company (modal method): ${newCompanyName}`)
 
     // Navigate to create job page
     await autoId(page, 'AppNavbar-create-job').click()
     await page.waitForURL('**/jobs/create')
 
-    // Type the new client name
-    const clientInput = autoId(page, 'ClientLookup-input')
-    await clientInput.fill(newClientName)
+    // Type the new company name
+    const companyInput = autoId(page, 'CompanyLookup-input')
+    await companyInput.fill(newCompanyName)
 
-    // Wait for dropdown and click "Add new client" - this opens a modal
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-    await autoId(page, 'ClientLookup-create-new').click()
+    // Wait for dropdown and click "Add new company" - this opens a modal
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-create-new').click()
 
-    // Wait for the CreateClientModal to appear
-    const createClientModal = page.locator('div[role="dialog"]:has-text("Add New Client")')
-    await createClientModal.waitFor({ timeout: 5000 })
+    // Wait for the CreateCompanyModal to appear
+    const createCompanyModal = page.locator('div[role="dialog"]:has-text("Add New Company")')
+    await createCompanyModal.waitFor({ timeout: 5000 })
 
-    console.log('CreateClientModal opened')
+    console.log('CreateCompanyModal opened')
 
-    // The client name should already be filled in the modal
-    // Click "Create Client" button to create the client
-    const createClientButton = page.getByRole('button', { name: 'Create Client' })
-    await waitForClientCreateResponse(page, async () => {
-      await createClientButton.click()
+    // The company name should already be filled in the modal
+    // Click "Create Company" button to create the company
+    const createCompanyButton = page.getByRole('button', { name: 'Create Company' })
+    await waitForCompanyCreateResponse(page, async () => {
+      await createCompanyButton.click()
     })
 
-    // Wait for modal to close and client to be created
-    await createClientModal.waitFor({ state: 'hidden', timeout: 10000 })
+    // Wait for modal to close and company to be created
+    await createCompanyModal.waitFor({ state: 'hidden', timeout: 10000 })
 
     // Verify the Xero badge shows green
-    const xeroIndicator = autoId(page, 'ClientLookup-xero-valid')
+    const xeroIndicator = autoId(page, 'CompanyLookup-xero-valid')
     await expect(xeroIndicator).toBeVisible({ timeout: 10000 })
 
-    console.log(`Client "${newClientName}" created with Xero ID via modal`)
+    console.log(`Company "${newCompanyName}" created with Xero ID via modal`)
 
     // Fill in job details
     await autoId(page, 'JobCreateView-name-input').fill(jobName)
diff --git a/frontend/tests/job/create-job.spec.ts b/frontend/tests/job/create-job.spec.ts
index 459f5c319..d50d293a8 100644
--- a/frontend/tests/job/create-job.spec.ts
+++ b/frontend/tests/job/create-job.spec.ts
@@ -4,16 +4,16 @@ import {
   dismissToasts,
   expectStepUnder,
   submitJobAndWaitForCreatedJob,
-  TEST_CLIENT_NAME,
+  TEST_COMPANY_NAME,
   waitForSettingsInitialized,
 } from '../fixtures/helpers'
 
 /**
  * Sequential test cases for job creation.
  * These tests MUST run in order as each builds on the previous state:
- * - Test 1: Client has 0 contacts → creates first contact (becomes primary)
- * - Test 2: Client has 1 contact → creates second contact
- * - Test 3: Client has 2 contacts → selects non-primary contact
+ * - Test 1: Company has 0 contacts → creates first contact (becomes primary)
+ * - Test 2: Company has 1 contact → creates second contact
+ * - Test 3: Company has 2 contacts → selects non-primary contact
  */
 const jobTestCases = [
   {
@@ -47,7 +47,7 @@ const jobTestCases = [
 
 const CREATE_JOB_BUDGET_MS = {
   navigateToCreatePage: 2500,
-  searchAndSelectClient: 1500,
+  searchAndSelectCompany: 1500,
   contactSelection: 2500,
   submitAndRedirect: 3500,
   defaultPayItemCreateJob: 4500,
@@ -57,7 +57,7 @@ const CREATE_JOB_BUDGET_MS = {
 // Use describe.serial to ensure tests run in order (they depend on each other)
 test.describe.serial('create job', () => {
   for (const tc of jobTestCases) {
-    test(`create ${tc.name} job with client and contact`, async ({ authenticatedPage: page }) => {
+    test(`create ${tc.name} job with company and contact`, async ({ authenticatedPage: page }) => {
       // Generate unique job name to avoid conflicts
       const timestamp = Date.now()
       const jobName = `[TEST] Job ${tc.name} ${timestamp}`
@@ -73,22 +73,22 @@ test.describe.serial('create job', () => {
       )
 
       await expectStepUnder(
-        'search and select client',
-        CREATE_JOB_BUDGET_MS.searchAndSelectClient,
+        'search and select company',
+        CREATE_JOB_BUDGET_MS.searchAndSelectCompany,
         async () => {
-          console.log('Searching for client ABC...')
-          const clientInput = autoId(page, 'ClientLookup-input')
-          await clientInput.fill('ABC')
+          console.log('Searching for company ABC...')
+          const companyInput = autoId(page, 'CompanyLookup-input')
+          await companyInput.fill('ABC')
 
           // Wait for results dropdown
-          await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
+          await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
 
-          // Click on the test client using role
-          console.log(`Selecting ${TEST_CLIENT_NAME}...`)
-          await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
+          // Click on the test company using role
+          console.log(`Selecting ${TEST_COMPANY_NAME}...`)
+          await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
 
           // Verify selection
-          await expect(clientInput).toHaveValue(TEST_CLIENT_NAME)
+          await expect(companyInput).toHaveValue(TEST_COMPANY_NAME)
         },
       )
 
@@ -215,11 +215,11 @@ test.describe('new job default pay item', () => {
         await autoId(page, 'AppNavbar-create-job').click()
         await page.waitForURL('**/jobs/create')
 
-        // Select client
-        const clientInput = autoId(page, 'ClientLookup-input')
-        await clientInput.fill('ABC')
-        await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-        await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
+        // Select company
+        const companyInput = autoId(page, 'CompanyLookup-input')
+        await companyInput.fill('ABC')
+        await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+        await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
 
         // Enter job name
         await autoId(page, 'JobCreateView-name-input').fill(jobName)
diff --git a/frontend/tests/job/edit-job-settings.spec.ts b/frontend/tests/job/edit-job-settings.spec.ts
index c59d0939a..67dbddc53 100644
--- a/frontend/tests/job/edit-job-settings.spec.ts
+++ b/frontend/tests/job/edit-job-settings.spec.ts
@@ -6,7 +6,7 @@ import {
   waitForAutosave,
   createTestJob,
   expectStepUnder,
-  TEST_CLIENT_NAME,
+  TEST_COMPANY_NAME,
 } from '../fixtures/helpers'
 
 const EDIT_JOB_BUDGET_MS = {
@@ -14,7 +14,7 @@ const EDIT_JOB_BUDGET_MS = {
   autosave: 1500,
   verifyAfterRefresh: 3000,
   reloadVerify: 3500,
-  changeClientFlow: 2000,
+  changeCompanyFlow: 2000,
   createOrSwitchContact: 2000,
 } as const
 
@@ -63,9 +63,9 @@ test.describe.serial('edit job', () => {
       expect(jobName).toContain('[TEST] Edit Job')
     })
 
-    await test.step('verify client is ABC Carpet Cleaning', async () => {
-      const clientNameInput = autoId(page, 'JobSettingsTab-client-name')
-      await expect(clientNameInput).toHaveValue(TEST_CLIENT_NAME)
+    await test.step('verify company is ABC Carpet Cleaning', async () => {
+      const companyNameInput = autoId(page, 'JobSettingsTab-company-name')
+      await expect(companyNameInput).toHaveValue(TEST_COMPANY_NAME)
     })
 
     await test.step('verify pricing method is Fixed Price', async () => {
@@ -499,64 +499,64 @@ test.describe.serial('edit job', () => {
     })
   })
 
-  test('change client', async ({ authenticatedPage: page }) => {
-    // Create a dedicated job for this test — changing client mutates state
+  test('change company', async ({ authenticatedPage: page }) => {
+    // Create a dedicated job for this test — changing company mutates state
     // that would break other tests sharing sharedEditJobUrl
-    const jobUrl = await createTestJob(page, 'Change Client')
+    const jobUrl = await createTestJob(page, 'Change Company')
     await page.goto(jobUrl)
     await page.waitForLoadState('networkidle')
 
     const companyDefaults = await getCompanyDefaults(page)
-    const shopClientId = companyDefaults.shop_client as string
-    expect(shopClientId).toBeTruthy()
-    const clientsResponse = await page.request.get('/api/clients/all/', {
+    const shopCompanyId = companyDefaults.shop_company as string
+    expect(shopCompanyId).toBeTruthy()
+    const companiesResponse = await page.request.get('/api/companies/all/', {
       headers: { Accept: 'application/json' },
     })
-    const clients = (await clientsResponse.json()) as Array<{ id: string; name: string }>
-    const shopClient = clients.find((client) => client.id === shopClientId)
-    expect(shopClient).toBeTruthy()
-    const shopClientName = shopClient?.name as string
-    console.log(`Using shop client name: ${shopClientName}`)
+    const companies = (await companiesResponse.json()) as Array<{ id: string; name: string }>
+    const shopCompany = companies.find((company) => company.id === shopCompanyId)
+    expect(shopCompany).toBeTruthy()
+    const shopCompanyName = shopCompany?.name as string
+    console.log(`Using shop company name: ${shopCompanyName}`)
 
     // Navigate to Job Settings tab
     await autoId(page, 'JobViewTabs-jobSettings').click()
-    await autoId(page, 'JobSettingsTab-change-client-btn').waitFor({ timeout: 10000 })
+    await autoId(page, 'JobSettingsTab-change-company-btn').waitFor({ timeout: 10000 })
     await waitForSettingsInitialized(page)
 
-    await test.step('click Change Client button', async () => {
-      await autoId(page, 'JobSettingsTab-change-client-btn').click()
-      await autoId(page, 'JobSettingsTab-client-change-panel').waitFor({ timeout: 5000 })
+    await test.step('click Change Company button', async () => {
+      await autoId(page, 'JobSettingsTab-change-company-btn').click()
+      await autoId(page, 'JobSettingsTab-company-change-panel').waitFor({ timeout: 5000 })
     })
 
     await expectStepUnder(
-      'search for and select a different client',
-      EDIT_JOB_BUDGET_MS.changeClientFlow,
+      'search for and select a different company',
+      EDIT_JOB_BUDGET_MS.changeCompanyFlow,
       async () => {
-        const clientChangePanel = autoId(page, 'JobSettingsTab-client-change-panel')
-        const clientInput = clientChangePanel.locator('input[type="text"]')
+        const companyChangePanel = autoId(page, 'JobSettingsTab-company-change-panel')
+        const companyInput = companyChangePanel.locator('input[type="text"]')
 
-        // Search using first word of shop client name
-        await clientInput.fill(shopClientName.split(' ')[0])
+        // Search using first word of shop company name
+        await companyInput.fill(shopCompanyName.split(' ')[0])
         await page.waitForTimeout(1000) // Allow debounce
 
-        const clientOption = page.getByRole('option', { name: shopClientName, exact: true })
-        await clientOption.waitFor({ timeout: 10000 })
-        await clientOption.click()
+        const companyOption = page.getByRole('option', { name: shopCompanyName, exact: true })
+        await companyOption.waitFor({ timeout: 10000 })
+        await companyOption.click()
       },
     )
 
     await expectStepUnder(
-      'confirm the client change',
-      EDIT_JOB_BUDGET_MS.changeClientFlow,
+      'confirm the company change',
+      EDIT_JOB_BUDGET_MS.changeCompanyFlow,
       async () => {
-        await autoId(page, 'JobSettingsTab-confirm-client-btn').click()
+        await autoId(page, 'JobSettingsTab-confirm-company-btn').click()
         await waitForAutosave(page)
       },
     )
 
-    await test.step('verify client was changed', async () => {
-      const clientNameInput = autoId(page, 'JobSettingsTab-client-name')
-      await expect(clientNameInput).toHaveValue(shopClientName)
+    await test.step('verify company was changed', async () => {
+      const companyNameInput = autoId(page, 'JobSettingsTab-company-name')
+      await expect(companyNameInput).toHaveValue(shopCompanyName)
     })
 
     await expectStepUnder(
@@ -565,10 +565,10 @@ test.describe.serial('edit job', () => {
       async () => {
         await page.reload()
         await autoId(page, 'JobViewTabs-jobSettings').click()
-        await autoId(page, 'JobSettingsTab-client-name').waitFor({ timeout: 10000 })
+        await autoId(page, 'JobSettingsTab-company-name').waitFor({ timeout: 10000 })
 
-        const clientNameInput = autoId(page, 'JobSettingsTab-client-name')
-        await expect(clientNameInput).toHaveValue(shopClientName)
+        const companyNameInput = autoId(page, 'JobSettingsTab-company-name')
+        await expect(companyNameInput).toHaveValue(shopCompanyName)
       },
     )
   })
@@ -594,7 +594,7 @@ test.describe.serial('edit job', () => {
         orderNumber: await autoId(page, 'JobSettingsTab-order-number').inputValue(),
         pricingMethod: await autoId(page, 'JobSettingsTab-pricing-method').inputValue(),
         speedQuality: await autoId(page, 'JobSettingsTab-speed-quality').inputValue(),
-        clientName: await autoId(page, 'JobSettingsTab-client-name').inputValue(),
+        companyName: await autoId(page, 'JobSettingsTab-company-name').inputValue(),
       }
     })
 
@@ -625,8 +625,8 @@ test.describe.serial('edit job', () => {
           await expect(autoId(page, 'JobSettingsTab-speed-quality')).toHaveValue(
             valuesBefore.speedQuality,
           )
-          await expect(autoId(page, 'JobSettingsTab-client-name')).toHaveValue(
-            valuesBefore.clientName,
+          await expect(autoId(page, 'JobSettingsTab-company-name')).toHaveValue(
+            valuesBefore.companyName,
           )
         },
       )
@@ -655,7 +655,7 @@ test.describe.serial('edit job', () => {
 
     await expectStepUnder(
       'select a different pay item',
-      EDIT_JOB_BUDGET_MS.changeClientFlow,
+      EDIT_JOB_BUDGET_MS.changeCompanyFlow,
       async () => {
         const payItemSelect = autoId(page, 'JobSettingsTab-default-pay-item')
 
diff --git a/frontend/tests/purchasing/pickup-address.spec.ts b/frontend/tests/purchasing/pickup-address.spec.ts
index 3a9d49a7b..722cc18fd 100644
--- a/frontend/tests/purchasing/pickup-address.spec.ts
+++ b/frontend/tests/purchasing/pickup-address.spec.ts
@@ -1,6 +1,6 @@
 import { test, expect } from '../fixtures/auth'
 import type { Page } from '@playwright/test'
-import { autoId, dismissToasts, TEST_CLIENT_NAME } from '../fixtures/helpers'
+import { autoId, dismissToasts, TEST_COMPANY_NAME } from '../fixtures/helpers'
 
 /**
  * Tests for pickup address functionality on purchase orders.
@@ -16,13 +16,13 @@ async function createPOWithExistingSupplier(page: Page): Promise<string> {
   await page.goto('/purchasing/po/create')
   await page.waitForLoadState('networkidle')
 
-  const supplierInput = autoId(page, 'ClientLookup-input')
+  const supplierInput = autoId(page, 'CompanyLookup-input')
   await supplierInput.click()
   await supplierInput.fill('ABC')
   await page.waitForTimeout(500)
-  await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-  await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
-  await expect(supplierInput).toHaveValue(TEST_CLIENT_NAME)
+  await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+  await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
+  await expect(supplierInput).toHaveValue(TEST_COMPANY_NAME)
 
   await autoId(page, 'PoSummaryCard-reference').fill(`E2E Pickup Test ${randomSuffix}`)
 
@@ -425,12 +425,12 @@ test.describe('pickup address without supplier', () => {
     await page.waitForLoadState('networkidle')
 
     // Select a supplier first
-    const supplierInput = autoId(page, 'ClientLookup-input')
+    const supplierInput = autoId(page, 'CompanyLookup-input')
     await supplierInput.click()
     await supplierInput.fill('ABC')
     await page.waitForTimeout(500)
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-    await page.getByRole('option', { name: new RegExp(TEST_CLIENT_NAME) }).click()
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+    await page.getByRole('option', { name: new RegExp(TEST_COMPANY_NAME) }).click()
 
     // Now pickup address should be visible and button enabled
     const modalButton = autoId(page, 'PickupAddressSelector-modal-button')
diff --git a/frontend/tests/purchasing/supplier-alias-search.spec.ts b/frontend/tests/purchasing/supplier-alias-search.spec.ts
index d7c42d585..60545d174 100644
--- a/frontend/tests/purchasing/supplier-alias-search.spec.ts
+++ b/frontend/tests/purchasing/supplier-alias-search.spec.ts
@@ -1,5 +1,5 @@
 import { test, expect } from '../fixtures/auth'
-import { autoId, waitForClientCreateResponse } from '../fixtures/helpers'
+import { autoId, waitForCompanyCreateResponse } from '../fixtures/helpers'
 
 test.describe('supplier alias search', () => {
   test('adds a supplier alias and finds the supplier from PO lookup', async ({
@@ -12,42 +12,42 @@ test.describe('supplier alias search', () => {
     await page.goto('/purchasing/po/create')
     await page.waitForLoadState('networkidle')
 
-    const supplierInput = autoId(page, 'ClientLookup-input')
+    const supplierInput = autoId(page, 'CompanyLookup-input')
     await supplierInput.click()
     await supplierInput.fill(supplierName)
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
-    await autoId(page, 'ClientLookup-create-new').waitFor({ timeout: 5000 })
-    await waitForClientCreateResponse(page, async () => {
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-create-new').waitFor({ timeout: 5000 })
+    await waitForCompanyCreateResponse(page, async () => {
       await supplierInput.press('Control+Enter')
     })
-    await autoId(page, 'ClientLookup-xero-valid').waitFor({ timeout: 30000 })
+    await autoId(page, 'CompanyLookup-xero-valid').waitFor({ timeout: 30000 })
     await expect(supplierInput).toHaveValue(supplierName)
 
-    await page.goto('/crm/clients')
+    await page.goto('/crm/companies')
     await page.waitForLoadState('networkidle')
-    await expect(page.getByText('Loading clients...')).toBeHidden({ timeout: 30000 })
-
-    const clientSearchInput = page.locator('input[placeholder*="Search clients"]')
-    await clientSearchInput.fill(supplierName)
-    const clientRow = page.locator('tbody tr', { hasText: supplierName }).first()
-    await expect(clientRow).toBeVisible({ timeout: 10000 })
-    await clientRow.click()
-    await page.waitForURL(/\/crm\/clients\/[a-f0-9-]+$/, { timeout: 15000 })
+    await expect(page.getByText('Loading companies...')).toBeHidden({ timeout: 30000 })
+
+    const companySearchInput = page.locator('input[placeholder*="Search companies"]')
+    await companySearchInput.fill(supplierName)
+    const companyRow = page.locator('tbody tr', { hasText: supplierName }).first()
+    await expect(companyRow).toBeVisible({ timeout: 10000 })
+    await companyRow.click()
+    await page.waitForURL(/\/crm\/companies\/[a-f0-9-]+$/, { timeout: 15000 })
     await expect(page.getByRole('heading', { name: supplierName })).toBeVisible({
       timeout: 30000,
     })
 
-    const aliasInput = autoId(page, 'ClientDetailView-alias-input')
+    const aliasInput = autoId(page, 'CompanyDetailView-alias-input')
     await aliasInput.fill(alias)
-    await autoId(page, 'ClientDetailView-alias-add').click()
+    await autoId(page, 'CompanyDetailView-alias-add').click()
     await expect(page.getByText(alias)).toBeVisible({ timeout: 10000 })
 
     await page.goto('/purchasing/po/create')
     await page.waitForLoadState('networkidle')
 
-    const poSupplierInput = autoId(page, 'ClientLookup-input')
+    const poSupplierInput = autoId(page, 'CompanyLookup-input')
     await poSupplierInput.fill(alias)
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
     await expect(page.getByRole('option').first()).toHaveText(supplierName)
     await page.getByRole('option').first().click()
     await expect(poSupplierInput).toHaveValue(supplierName)
@@ -56,8 +56,8 @@ test.describe('supplier alias search', () => {
     await page.waitForLoadState('networkidle')
 
     const punctuationQuery = `S & T Stainless Limited ${suffix}`
-    await autoId(page, 'ClientLookup-input').fill(punctuationQuery)
-    await autoId(page, 'ClientLookup-results').waitFor({ timeout: 10000 })
+    await autoId(page, 'CompanyLookup-input').fill(punctuationQuery)
+    await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
     await expect(page.getByRole('option').first()).toHaveText(supplierName)
   })
 })
diff --git a/frontend/tests/reports/clients.spec.ts b/frontend/tests/reports/companies.spec.ts
similarity index 55%
rename from frontend/tests/reports/clients.spec.ts
rename to frontend/tests/reports/companies.spec.ts
index fb685e304..c52f09ebb 100644
--- a/frontend/tests/reports/clients.spec.ts
+++ b/frontend/tests/reports/companies.spec.ts
@@ -1,26 +1,26 @@
 import { test, expect } from '../fixtures/auth'
-import { autoId, TEST_CLIENT_NAME } from '../fixtures/helpers'
+import { autoId, TEST_COMPANY_NAME } from '../fixtures/helpers'
 
-test.describe('Clients Report', () => {
-  test('sorts by spend, verifies client detail, and searches for testing client', async ({
+test.describe('Companies Report', () => {
+  test('sorts by spend, verifies company detail, and searches for testing company', async ({
     authenticatedPage: page,
   }) => {
-    // Navigate to the Clients page
-    await page.goto('/crm/clients')
+    // Navigate to the Companies page
+    await page.goto('/crm/companies')
     await page.waitForLoadState('networkidle')
 
     // Verify we're on the right page
-    await expect(page.getByRole('heading', { name: 'Clients' })).toBeVisible()
+    await expect(page.getByRole('heading', { name: 'Companies' })).toBeVisible()
 
     // Wait for loading to complete
-    await expect(page.getByText('Loading clients...')).toBeHidden({ timeout: 30000 })
+    await expect(page.getByText('Loading companies...')).toBeHidden({ timeout: 30000 })
 
     // Wait for the table to be visible
-    const table = autoId(page, 'ClientsTable-table')
+    const table = autoId(page, 'CompaniesTable-table')
     await expect(table).toBeVisible()
 
     // Click "Total Spend" column header to sort descending (first click sorts ascending, second sorts descending)
-    const totalSpendHeader = autoId(page, 'ClientsTable-header-total-spend')
+    const totalSpendHeader = autoId(page, 'CompaniesTable-header-total-spend')
     await expect(totalSpendHeader).toBeVisible()
 
     // Click twice to sort descending (biggest spenders first)
@@ -34,12 +34,12 @@ test.describe('Clients Report', () => {
 
     // Get the first row's data
     const firstRow = table.locator('tbody tr').first()
-    const clientId = await firstRow.getAttribute('data-client-id')
-    if (!clientId) {
-      throw new Error('Clients table row is missing data-client-id')
+    const companyId = await firstRow.getAttribute('data-company-id')
+    if (!companyId) {
+      throw new Error('Companies table row is missing data-company-id')
     }
 
-    const firstRowSpend = autoId(page, `ClientsTable-cell-${clientId}-total-spend`)
+    const firstRowSpend = autoId(page, `CompaniesTable-cell-${companyId}-total-spend`)
     await expect(firstRowSpend).toBeVisible()
 
     const spendText = await firstRowSpend.textContent()
@@ -55,19 +55,19 @@ test.describe('Clients Report', () => {
     const amount = parseFloat(spendText!.replace(/[$,]/g, ''))
     expect(amount).toBeGreaterThan(0)
 
-    // Get the client name before clicking
-    const clientName = await autoId(page, `ClientsTable-cell-${clientId}-name`).textContent()
-    console.log(`Clicking on top spender: ${clientName}`)
+    // Get the company name before clicking
+    const companyName = await autoId(page, `CompaniesTable-cell-${companyId}-name`).textContent()
+    console.log(`Clicking on top spender: ${companyName}`)
 
-    // Click on the client row to navigate to details
+    // Click on the company row to navigate to details
     await firstRow.click()
 
-    // Wait for navigation to client detail page
-    await page.waitForURL(/\/crm\/clients\/[a-f0-9-]+$/, { timeout: 15000 })
+    // Wait for navigation to company detail page
+    await page.waitForURL(/\/crm\/companies\/[a-f0-9-]+$/, { timeout: 15000 })
     await page.waitForLoadState('networkidle')
 
-    // Wait for client detail to load
-    await expect(page.getByText('Loading client...')).toBeHidden({ timeout: 30000 })
+    // Wait for company detail to load
+    await expect(page.getByText('Loading company...')).toBeHidden({ timeout: 30000 })
 
     // Click on Financial Summary tab
     const financialTab = page.getByRole('tab', { name: /Financial Summary/i })
@@ -82,29 +82,29 @@ test.describe('Clients Report', () => {
     await expect(totalSpendLabel).toBeVisible()
 
     // Get the total spend value (it's in the sibling p element with large text)
-    const totalSpendValue = autoId(page, 'ClientDetail-total-spend')
+    const totalSpendValue = autoId(page, 'CompanyDetail-total-spend')
     await expect(totalSpendValue).toBeVisible()
 
     const detailSpendText = await totalSpendValue.textContent()
-    console.log(`Client detail Total Spend: ${detailSpendText}`)
+    console.log(`Company detail Total Spend: ${detailSpendText}`)
 
     // Verify the spend amount matches what we saw in the table
     expect(detailSpendText).toBe(spendText)
 
-    // Navigate back to clients list
-    await autoId(page, 'ClientDetail-back').click()
-    await page.waitForURL(/\/crm\/clients$/, { timeout: 10000 })
+    // Navigate back to companies list
+    await autoId(page, 'CompanyDetail-back').click()
+    await page.waitForURL(/\/crm\/companies$/, { timeout: 10000 })
     await page.waitForLoadState('networkidle')
 
     // Wait for loading to complete
-    await expect(page.getByText('Loading clients...')).toBeHidden({ timeout: 30000 })
+    await expect(page.getByText('Loading companies...')).toBeHidden({ timeout: 30000 })
 
     // Re-get table reference after navigation
-    const clientsTable = autoId(page, 'ClientsTable-table')
-    await expect(clientsTable).toBeVisible()
+    const companiesTable = autoId(page, 'CompaniesTable-table')
+    await expect(companiesTable).toBeVisible()
 
-    // Now search for the test client
-    const searchInput = autoId(page, 'ClientsTable-search')
+    // Now search for the test company
+    const searchInput = autoId(page, 'CompaniesTable-search')
     await expect(searchInput).toBeVisible()
     await searchInput.clear()
     await searchInput.fill('ABC Carpet')
@@ -112,26 +112,26 @@ test.describe('Clients Report', () => {
     // Wait for debounced search to trigger and complete
     await page.waitForResponse(
       (response) =>
-        response.url().includes('/clients/search') &&
+        response.url().includes('/companies/search') &&
         response.request().method() === 'GET' &&
         response.status() === 200,
       { timeout: 10000 },
     )
     await page.waitForLoadState('networkidle')
 
-    // Validate that a row with the test client appears in results
-    const testClientRow = clientsTable.locator('tbody tr', {
-      hasText: new RegExp(TEST_CLIENT_NAME, 'i'),
+    // Validate that a row with the test company appears in results
+    const testCompanyRow = companiesTable.locator('tbody tr', {
+      hasText: new RegExp(TEST_COMPANY_NAME, 'i'),
     })
-    await expect(testClientRow.first()).toBeVisible({ timeout: 10000 })
+    await expect(testCompanyRow.first()).toBeVisible({ timeout: 10000 })
 
-    // Verify results are filtered (should be much fewer than all clients)
-    const resultText = page.locator('text=/Found \\d+ client/')
+    // Verify results are filtered (should be much fewer than all companies)
+    const resultText = page.locator('text=/Found \\d+ company/')
     const resultCount = await resultText.textContent()
     console.log(`Search results: ${resultCount}`)
 
     console.log(
-      'Clients report test passed: sorted by spend, validated client detail, found test client',
+      'Companies report test passed: sorted by spend, validated company detail, found test company',
     )
   })
 })
diff --git a/frontend/tests/scripts/db-backup-utils.ts b/frontend/tests/scripts/db-backup-utils.ts
index 5a1bb74d0..630704059 100644
--- a/frontend/tests/scripts/db-backup-utils.ts
+++ b/frontend/tests/scripts/db-backup-utils.ts
@@ -69,7 +69,7 @@ export function getBackendEnv(): Record<string, string> {
   return parseEnvFile(backendEnvPath)
 }
 
-export const TEST_CLIENT_NAME = 'ABC Carpet Cleaning TEST IGNORE'
+export const TEST_COMPANY_NAME = 'ABC Carpet Cleaning TEST IGNORE'
 
 /** Prefix used for all test-created data. Reset script only deletes items matching this. */
 export const TEST_DATA_PREFIX = '[TEST]'
@@ -225,7 +225,7 @@ export function checkSafeToTest(dbConfig: DbConfig): SafetyCheckResult {
   // Check for [TEST]-prefixed contacts
   const testContactCount = runPsql(
     dbConfig,
-    `SELECT COUNT(*) FROM client_clientcontact WHERE name LIKE '${prefix}%'`,
+    `SELECT COUNT(*) FROM company_clientcontact WHERE name LIKE '${prefix}%'`,
   )
   if (parseInt(testContactCount) > 0) {
     issues.push(
@@ -233,13 +233,15 @@ export function checkSafeToTest(dbConfig: DbConfig): SafetyCheckResult {
     )
   }
 
-  // Check for [TEST]-prefixed clients
-  const testClientCount = runPsql(
+  // Check for [TEST]-prefixed companies
+  const testCompanyCount = runPsql(
     dbConfig,
-    `SELECT COUNT(*) FROM client_client WHERE name LIKE '${prefix}%'`,
+    `SELECT COUNT(*) FROM company_company WHERE name LIKE '${prefix}%'`,
   )
-  if (parseInt(testClientCount) > 0) {
-    issues.push(`${testClientCount} test clients found (names starting with '${TEST_DATA_PREFIX}')`)
+  if (parseInt(testCompanyCount) > 0) {
+    issues.push(
+      `${testCompanyCount} test companies found (names starting with '${TEST_DATA_PREFIX}')`,
+    )
   }
 
   return { clean: issues.length === 0, issues }
diff --git a/frontend/tests/scripts/e2e-reset.ts b/frontend/tests/scripts/e2e-reset.ts
index a7d62a6f3..0eb28087f 100644
--- a/frontend/tests/scripts/e2e-reset.ts
+++ b/frontend/tests/scripts/e2e-reset.ts
@@ -9,7 +9,7 @@
  *   npm run test:e2e:reset -- --confirm  # Actually deletes test data
  *
  * Production safety: uses Django ORM for safe FK cascading, only deletes
- * items with [TEST] prefix or on the designated test client.
+ * items with [TEST] prefix or on the designated test company.
  */
 import { spawnSync } from 'child_process'
 import fs from 'fs'
diff --git a/frontend/tests/scripts/global-teardown.ts b/frontend/tests/scripts/global-teardown.ts
index 1c8c5b5b0..a74d0a03b 100644
--- a/frontend/tests/scripts/global-teardown.ts
+++ b/frontend/tests/scripts/global-teardown.ts
@@ -117,7 +117,7 @@ function restoreDatabase(lockContents: string) {
 
   // Let in-flight Celery/Xero work finish against the dirty test DB before
   // restoring the backup. If we restore immediately, a webhook/full-sync task
-  // that was already queued can recreate [TEST] clients in the clean DB a few
+  // that was already queued can recreate [TEST] companies in the clean DB a few
   // seconds later. Waiting here makes those writes part of the state we wipe.
   console.log(
     `[db] Waiting ${PRE_RESTORE_XERO_SETTLE_MS / 1000}s for in-flight Xero/Celery work before restore...`,
diff --git a/frontend/tests/timesheet/urgent-job-defaults.spec.ts b/frontend/tests/timesheet/urgent-job-defaults.spec.ts
index b4b13b56a..b1f0a39d4 100644
--- a/frontend/tests/timesheet/urgent-job-defaults.spec.ts
+++ b/frontend/tests/timesheet/urgent-job-defaults.spec.ts
@@ -1,6 +1,6 @@
 import { test, expect } from '../fixtures/auth'
 import type { Page, Response } from '@playwright/test'
-import { autoId, getPhantomRowIndex, TEST_CLIENT_NAME } from '../fixtures/helpers'
+import { autoId, getPhantomRowIndex, TEST_COMPANY_NAME } from '../fixtures/helpers'
 import { getLatestWeekdayDate } from '../../src/utils/dateUtils'
 
 type JsonObject = Record<string, unknown>
@@ -28,37 +28,37 @@ async function navigateToTimesheetEntry(page: Page): Promise<void> {
   await page.waitForTimeout(1000)
 }
 
-async function getClientId(page: Page): Promise<string> {
-  const response = await page.request.get('/api/clients/all/', {
+async function getCompanyId(page: Page): Promise<string> {
+  const response = await page.request.get('/api/companies/all/', {
     headers: { Accept: 'application/json' },
   })
   const responseText = await response.text()
 
   if (!response.ok()) {
-    throw new Error(`Client list failed with HTTP ${response.status()}: ${responseText}`)
+    throw new Error(`Company list failed with HTTP ${response.status()}: ${responseText}`)
   }
 
-  let clients: Array<{ id: string; name: string }>
+  let companies: Array<{ id: string; name: string }>
   try {
-    clients = JSON.parse(responseText) as Array<{ id: string; name: string }>
+    companies = JSON.parse(responseText) as Array<{ id: string; name: string }>
   } catch {
-    throw new Error(`Client list returned non-JSON response: ${responseText}`)
+    throw new Error(`Company list returned non-JSON response: ${responseText}`)
   }
 
-  if (!Array.isArray(clients)) {
-    throw new Error(`Client list returned unexpected payload: ${responseText}`)
+  if (!Array.isArray(companies)) {
+    throw new Error(`Company list returned unexpected payload: ${responseText}`)
   }
 
-  const match = clients.find((client) => client.name === TEST_CLIENT_NAME)
+  const match = companies.find((company) => company.name === TEST_COMPANY_NAME)
   if (!match) {
-    throw new Error(`Test client not found: ${TEST_CLIENT_NAME}`)
+    throw new Error(`Test company not found: ${TEST_COMPANY_NAME}`)
   }
 
   return match.id
 }
 
 async function createUrgentJob(page: Page): Promise<{ jobId: string; jobNumber: string }> {
-  const clientId = await getClientId(page)
+  const companyId = await getCompanyId(page)
   const timestamp = Date.now()
   const jobName = `[TEST] Urgent Job ${timestamp}`
 
@@ -66,7 +66,7 @@ async function createUrgentJob(page: Page): Promise<{ jobId: string; jobNumber:
     headers: { Accept: 'application/json' },
     data: {
       name: jobName,
-      client_id: clientId,
+      company_id: companyId,
       description: '',
       order_number: '',
       notes: '',

From 89d3b0a6e32c72bf42ef1e991bd7c1a130463562 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 8 Jul 2026 06:09:11 +1200
Subject: [PATCH 04/73] fix: route legacy CRM bookmarks to not-found page

---
 frontend/router-auto-options.ts               | 10 +++-
 frontend/src/pages/[...path].vue              | 40 ++++++++++++++
 .../src/router/__tests__/not-found.test.ts    | 55 +++++++++++++++++++
 frontend/src/typed-router.d.ts                | 13 +++++
 frontend/tests/not-found.spec.ts              | 10 ++++
 frontend/vitest.config.ts                     |  2 +
 6 files changed, 127 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/pages/[...path].vue
 create mode 100644 frontend/src/router/__tests__/not-found.test.ts
 create mode 100644 frontend/tests/not-found.spec.ts

diff --git a/frontend/router-auto-options.ts b/frontend/router-auto-options.ts
index 6b4ba013b..08905528f 100644
--- a/frontend/router-auto-options.ts
+++ b/frontend/router-auto-options.ts
@@ -3,6 +3,7 @@ import type { Options } from 'vue-router/unplugin'
 export const typedRouterDtsPath = 'src/typed-router.d.ts'
 
 const TITLES: Record<string, string> = {
+  '/:path(.*)': 'Page Not Found - DocketWorks',
   '/login': 'Login - DocketWorks',
   '/session-check': 'Connection Check - DocketWorks',
   '/kanban': 'Kanban Board - DocketWorks',
@@ -16,8 +17,8 @@ const TITLES: Record<string, string> = {
   '/timesheets/daily': 'Daily Timesheet Overview - DocketWorks',
   '/timesheets/weekly': 'Weekly Timesheet - DocketWorks',
   '/xero': 'Xero Sync - DocketWorks',
-  '/crm/clients': 'Clients - DocketWorks',
-  '/crm/clients/:id': 'Client Details - DocketWorks',
+  '/crm/companies': 'Companies - DocketWorks',
+  '/crm/companies/:id': 'Company Details - DocketWorks',
   '/crm/calls': 'Calls - DocketWorks',
   '/purchasing/po': 'Purchase Orders - DocketWorks',
   '/purchasing/po/create': 'Create Purchase Order - DocketWorks',
@@ -41,6 +42,7 @@ const TITLES: Record<string, string> = {
 }
 
 const WORKSHOP_ALLOWED = [
+  '/:path(.*)',
   '/login',
   '/session-check',
   '/kanban',
@@ -70,7 +72,9 @@ const ALLOW_SCROLL = [
 export const routerAutoOptions = {
   dts: typedRouterDtsPath,
   extendRoute(route) {
-    const p = route.path
+    // NOTE: route.path is the node-relative segment (e.g. 'entry' for
+    // /timesheets/entry); fullPath is the absolute path the maps below key on.
+    const p = route.fullPath
 
     if (TITLES[p]) {
       route.addToMeta({ title: TITLES[p] })
diff --git a/frontend/src/pages/[...path].vue b/frontend/src/pages/[...path].vue
new file mode 100644
index 000000000..49cc18804
--- /dev/null
+++ b/frontend/src/pages/[...path].vue
@@ -0,0 +1,40 @@
+<template>
+  <main
+    data-automation-id="NotFound-page"
+    class="min-h-screen bg-slate-50 text-slate-900 flex items-center justify-center px-4"
+  >
+    <section class="w-full max-w-md space-y-5 text-center">
+      <div class="space-y-2">
+        <p class="text-5xl font-bold tracking-tight">404</p>
+        <h1 class="text-2xl font-semibold">Page not found</h1>
+        <p class="text-sm leading-6 text-slate-600">
+          No page exists at <code class="rounded bg-slate-200 px-1 py-0.5">{{ attemptedPath }}</code
+          >.
+        </p>
+        <p class="text-sm leading-6 text-slate-600">
+          If you followed a bookmark, it points at a page that no longer exists.
+        </p>
+      </div>
+
+      <RouterLink
+        to="/"
+        class="inline-flex h-10 items-center rounded-md bg-slate-900 px-4 text-sm font-medium text-white hover:bg-slate-800"
+      >
+        Go to home
+      </RouterLink>
+    </section>
+  </main>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useRoute } from 'vue-router'
+
+const route = useRoute()
+
+const attemptedPath = computed(() => {
+  const path = route.params.path
+  const joined = Array.isArray(path) ? `/${path.join('/')}` : `/${path}`
+  return joined
+})
+</script>
diff --git a/frontend/src/router/__tests__/not-found.test.ts b/frontend/src/router/__tests__/not-found.test.ts
new file mode 100644
index 000000000..b86a0e8ea
--- /dev/null
+++ b/frontend/src/router/__tests__/not-found.test.ts
@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import router from '@/router'
+
+vi.mock('@/api/client', () => ({
+  api: {
+    accounts_me_retrieve: vi.fn(),
+    accounts_logout_create: vi.fn(),
+  },
+}))
+
+vi.mock('@/utils/debug', () => ({
+  debugLog: vi.fn(),
+}))
+
+vi.mock('vue-sonner', () => ({
+  toast: {
+    error: vi.fn(),
+  },
+}))
+
+vi.mock('vue-router', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('vue-router')>()
+  return {
+    ...actual,
+    createWebHistory: actual.createMemoryHistory,
+  }
+})
+
+describe('catch-all 404 route', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('resolves an unknown URL (legacy /crm/clients bookmark) to the catch-all, not a silent no-match', () => {
+    const resolved = router.resolve('/crm/clients')
+
+    expect(resolved.name).toBe('/[...path]')
+    expect(resolved.matched.length).toBeGreaterThan(0)
+    expect(resolved.params.path).toBe('crm/clients')
+  })
+
+  it('keeps auth required and allows workshop staff so the 404 renders instead of a wrong toast', () => {
+    const resolved = router.resolve('/crm/clients')
+
+    expect(resolved.meta.requiresAuth).toBe(true)
+    expect(resolved.meta.allowWorkshopStaff).toBe(true)
+    expect(resolved.meta.title).toBe('Page Not Found - DocketWorks')
+  })
+
+  it('still resolves the renamed companies pages to their real routes', () => {
+    expect(router.resolve('/crm/companies').name).toBe('/crm/companies/(index)')
+    expect(router.resolve('/kanban').name).toBe('/kanban')
+  })
+})
diff --git a/frontend/src/typed-router.d.ts b/frontend/src/typed-router.d.ts
index f83ef2dd6..3e9350a41 100644
--- a/frontend/src/typed-router.d.ts
+++ b/frontend/src/typed-router.d.ts
@@ -31,6 +31,13 @@ declare module 'vue-router/auto-routes' {
    * Route name map generated by vue-router
    */
   export interface RouteNamedMap {
+    '/[...path]': RouteRecordInfo<
+      '/[...path]',
+      '/:path(.*)',
+      { path: ParamValue<true> },
+      { path: ParamValue<false> },
+      | never
+    >,
     '/crm/calls': RouteRecordInfo<
       '/crm/calls',
       '/crm/calls',
@@ -296,6 +303,12 @@ declare module 'vue-router/auto-routes' {
    * @internal
    */
   export interface _RouteFileInfoMap {
+    'src/pages/[...path].vue': {
+      routes:
+        | '/[...path]'
+      views:
+        | never
+    }
     'src/pages/crm/calls.vue': {
       routes:
         | '/crm/calls'
diff --git a/frontend/tests/not-found.spec.ts b/frontend/tests/not-found.spec.ts
new file mode 100644
index 000000000..80f4c0b7f
--- /dev/null
+++ b/frontend/tests/not-found.spec.ts
@@ -0,0 +1,10 @@
+import { test, expect } from './fixtures/auth'
+
+test('unknown URL (legacy /crm/clients bookmark) shows the 404 page without redirecting', async ({
+  authenticatedPage: page,
+}) => {
+  await page.goto('/crm/clients')
+
+  await expect(page.locator('[data-automation-id="NotFound-page"]')).toBeVisible()
+  await expect(page).toHaveURL(/\/crm\/clients/)
+})
diff --git a/frontend/vitest.config.ts b/frontend/vitest.config.ts
index 5641a2117..75c1838f1 100644
--- a/frontend/vitest.config.ts
+++ b/frontend/vitest.config.ts
@@ -2,10 +2,12 @@ import path from 'node:path'
 import vue from '@vitejs/plugin-vue'
 import VueRouter from 'vue-router/vite'
 import { defineConfig } from 'vitest/config'
+import { routerAutoOptions } from './router-auto-options'
 
 export default defineConfig({
   plugins: [
     VueRouter({
+      ...routerAutoOptions,
       dts: false,
     }),
     vue(),

From 50bd48c32af03ee93a58f3b9130f8fc0760d32b6 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 8 Jul 2026 06:22:47 +1200
Subject: [PATCH 05/73] fix: address hotfix review feedback

---
 .env.example                                  |   2 +-
 .env.precommit                                |   4 +-
 .../test_payroll_reconciliation_service.py    |  25 +--
 apps/client/serializers.py                    |  18 +-
 apps/client/services/__init__.py              |   4 +-
 apps/client/services/client_rest_service.py   | 169 ++++++++++--------
 apps/client/tests/test_contact_methods.py     |   2 +-
 .../utils/__tests__/authConsoleErrors.test.ts |   2 +-
 .../utils/authConsoleErrors.ts}               |   0
 frontend/tests/fixtures/auth.ts               |   2 +-
 .../kanban/kanban-drag-vanishing.spec.ts      |   8 +-
 11 files changed, 131 insertions(+), 105 deletions(-)
 rename frontend/{tests/fixtures/auth-console-errors.ts => src/utils/authConsoleErrors.ts} (100%)

diff --git a/.env.example b/.env.example
index 427a16e54..eb8105ec1 100644
--- a/.env.example
+++ b/.env.example
@@ -43,9 +43,9 @@ DJANGO_SITE_DOMAIN=your-domain.ngrok-free.app
 
 # Xero Integration
 XERO_DEFAULT_USER_ID=YOUR_XERO_USER_ID_FOR_TIME_ENTRIES
-XERO_SYNC_PROJECTS=False
 # Suppress all Xero writes for this process (E2E/test backends only; reads stay live)
 XERO_READONLY=False
+XERO_SYNC_PROJECTS=False
 
 # JWT Configuration
 ENABLE_JWT_AUTH=True
diff --git a/.env.precommit b/.env.precommit
index 2620d4071..2dd98f941 100644
--- a/.env.precommit
+++ b/.env.precommit
@@ -16,8 +16,8 @@ REDIS_HOST=localhost
 REDIS_PORT=6379
 XERO_CLIENT_ID=dummy
 XERO_CLIENT_SECRET=dummy
-XERO_REDIRECT_URI=http://localhost
 XERO_DEFAULT_USER_ID=dummy
+XERO_REDIRECT_URI=http://localhost
 EMAIL_HOST=localhost
 EMAIL_PORT=587
 EMAIL_USE_TLS=false
@@ -33,8 +33,8 @@ SKIP_VERSION_CHECK=True
 ALLOWED_HOSTS=localhost,127.0.0.1
 DJANGO_SITE_DOMAIN=localhost
 APP_DOMAIN=localhost
-XERO_SYNC_PROJECTS=False
 XERO_READONLY=False
+XERO_SYNC_PROJECTS=False
 XERO_WEBHOOK_KEY=dummy-webhook-key
 CORS_ALLOWED_ORIGINS=http://localhost:3000
 ENABLE_JWT_AUTH=False
diff --git a/apps/accounting/tests/test_payroll_reconciliation_service.py b/apps/accounting/tests/test_payroll_reconciliation_service.py
index d8e653993..ccdccd766 100644
--- a/apps/accounting/tests/test_payroll_reconciliation_service.py
+++ b/apps/accounting/tests/test_payroll_reconciliation_service.py
@@ -18,35 +18,36 @@
 class GetAlignedDateRangeTests(BaseTestCase):
     def _set_payroll_start(self, payroll_start: date | None) -> None:
         defaults = CompanyDefaults.get_solo()
-        defaults.xero_payroll_start_date = payroll_start
-        defaults.save()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_payroll_start_date=payroll_start
+        )
 
     def _aligned(self, start: date, end: date) -> tuple[date, date]:
         result = PayrollReconciliationService.get_aligned_date_range(start, end)
         return result["aligned_start"], result["aligned_end"]
 
-    def test_midweek_dates_snap_to_monday_and_sunday(self):
+    def test_midweek_dates_snap_to_monday_and_sunday(self) -> None:
         self._set_payroll_start(None)
-        # Tuesday 2025-04-01 → Monday 2025-03-31; Tuesday 2026-03-31 → Sunday 2026-04-05
+        # Tuesday 2025-04-01 -> Monday 2025-03-31; Tuesday 2026-03-31 -> Sunday 2026-04-05
         aligned_start, aligned_end = self._aligned(date(2025, 4, 1), date(2026, 3, 31))
         self.assertEqual(aligned_start, date(2025, 3, 31))
         self.assertEqual(aligned_end, date(2026, 4, 5))
 
-    def test_already_aligned_dates_are_unchanged(self):
+    def test_already_aligned_dates_are_unchanged(self) -> None:
         self._set_payroll_start(None)
         # Monday 2025-03-31 and Sunday 2026-04-05 are already week boundaries
         aligned_start, aligned_end = self._aligned(date(2025, 3, 31), date(2026, 4, 5))
         self.assertEqual(aligned_start, date(2025, 3, 31))
         self.assertEqual(aligned_end, date(2026, 4, 5))
 
-    def test_single_day_expands_to_its_full_week(self):
+    def test_single_day_expands_to_its_full_week(self) -> None:
         self._set_payroll_start(None)
-        # Thursday 2025-04-03 → the whole Mon–Sun week containing it
+        # Thursday 2025-04-03 -> the whole Mon-Sun week containing it
         aligned_start, aligned_end = self._aligned(date(2025, 4, 3), date(2025, 4, 3))
         self.assertEqual(aligned_start, date(2025, 3, 31))
         self.assertEqual(aligned_end, date(2025, 4, 6))
 
-    def test_start_clamps_to_payroll_start_before_snapping(self):
+    def test_start_clamps_to_payroll_start_before_snapping(self) -> None:
         # Friday 2025-08-01: requests starting earlier clamp to it, then
         # snap to the Monday of its week.
         self._set_payroll_start(date(2025, 8, 1))
@@ -54,18 +55,18 @@ def test_start_clamps_to_payroll_start_before_snapping(self):
         self.assertEqual(aligned_start, date(2025, 7, 28))
         self.assertEqual(aligned_end, date(2026, 4, 5))
 
-    def test_start_after_payroll_start_is_not_clamped(self):
+    def test_start_after_payroll_start_is_not_clamped(self) -> None:
         self._set_payroll_start(date(2025, 8, 1))
-        # Tuesday 2025-09-02 is after the payroll start → normal Monday snap
+        # Tuesday 2025-09-02 is after the payroll start -> normal Monday snap
         aligned_start, _ = self._aligned(date(2025, 9, 2), date(2026, 3, 31))
         self.assertEqual(aligned_start, date(2025, 9, 1))
 
-    def test_payroll_start_on_a_monday_clamps_exactly_to_it(self):
+    def test_payroll_start_on_a_monday_clamps_exactly_to_it(self) -> None:
         self._set_payroll_start(date(2025, 8, 4))  # a Monday
         aligned_start, _ = self._aligned(date(2025, 4, 1), date(2026, 3, 31))
         self.assertEqual(aligned_start, date(2025, 8, 4))
 
-    def test_end_date_is_never_clamped_by_payroll_start(self):
+    def test_end_date_is_never_clamped_by_payroll_start(self) -> None:
         # The clamp applies to the start only; an end before payroll start
         # still snaps to its own week's Sunday (yielding an empty range,
         # which the report handles, rather than a silently rewritten end).
diff --git a/apps/client/serializers.py b/apps/client/serializers.py
index 6704bd5f6..13e6c5837 100644
--- a/apps/client/serializers.py
+++ b/apps/client/serializers.py
@@ -33,9 +33,11 @@ def set_primary_phone(owner: Client | ClientContact, raw_value: str) -> None:
     )
     old_primary = phone_methods.filter(is_primary=True).first()
     old_number = old_primary.normalized_value if old_primary else ""
-    same_number = phone_methods.filter(
-        normalized_value=ClientContactMethod.normalize_phone(value)
-    ).first()
+    normalized_value = ClientContactMethod.normalize_phone(value)
+    if not normalized_value:
+        raise DjangoValidationError("Phone number must contain at least one digit")
+
+    same_number = phone_methods.filter(normalized_value=normalized_value).first()
 
     if same_number is not None:
         same_number.value = value
@@ -87,13 +89,15 @@ def to_internal_value(self, data: Any) -> Any:
 
     def create(self, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
-        contact = super().create(validated_data)
-        return self._apply_phone(contact, raw_phone)
+        with transaction.atomic():
+            contact = super().create(validated_data)
+            return self._apply_phone(contact, raw_phone)
 
     def update(self, instance, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
-        contact = super().update(instance, validated_data)
-        return self._apply_phone(contact, raw_phone)
+        with transaction.atomic():
+            contact = super().update(instance, validated_data)
+            return self._apply_phone(contact, raw_phone)
 
     def _apply_phone(
         self, contact: ClientContact, raw_phone: str | None
diff --git a/apps/client/services/__init__.py b/apps/client/services/__init__.py
index e9e28a705..770079d98 100644
--- a/apps/client/services/__init__.py
+++ b/apps/client/services/__init__.py
@@ -6,7 +6,7 @@
 
     if apps.ready:
         from .client_merge_service import reassign_client_fk_records
-        from .client_rest_service import ClientRestService, _ClientPhoneAnnotations
+        from .client_rest_service import ClientPhoneAnnotations, ClientRestService
         from .duplicate_phone_report import (
             DuplicatePhoneIssue,
             DuplicatePhoneOwner,
@@ -26,6 +26,7 @@
     pass
 
 __all__ = [
+    "ClientPhoneAnnotations",
     "ClientRestService",
     "DuplicatePhoneIssue",
     "DuplicatePhoneOwner",
@@ -35,7 +36,6 @@
     "GeocodingError",
     "GeocodingNotConfiguredError",
     "GeocodingResult",
-    "_ClientPhoneAnnotations",
     "geocode_address",
     "get_api_key",
     "reassign_client_fk_records",
diff --git a/apps/client/services/client_rest_service.py b/apps/client/services/client_rest_service.py
index 992dee42a..a23763012 100644
--- a/apps/client/services/client_rest_service.py
+++ b/apps/client/services/client_rest_service.py
@@ -47,7 +47,7 @@
 CLIENT_SEARCH_TOKEN_RE = re.compile(r"[a-z0-9]+")
 
 
-class _ClientPhoneAnnotations(TypedDict):
+class ClientPhoneAnnotations(TypedDict):
     """Queryset annotation required by _format_client_summary and
     _format_client_detail; not a Client model field."""
 
@@ -57,7 +57,7 @@ class _ClientPhoneAnnotations(TypedDict):
 if TYPE_CHECKING:
     # Evaluated only by the type checker (annotation is quoted at use site), so
     # the dev-only django_stubs_ext dependency is never imported at runtime.
-    _AnnotatedClientWithPhone = WithAnnotations[Client, _ClientPhoneAnnotations]
+    _AnnotatedClientWithPhone = WithAnnotations[Client, ClientPhoneAnnotations]
 
 logger = logging.getLogger(__name__)
 client_search_logger = logging.getLogger("client_search")
@@ -202,6 +202,8 @@ def list_clients(
 
         except AlreadyLoggedException:
             raise
+        except ValueError:
+            raise
         except Exception as exc:
             persist_and_raise(
                 exc,
@@ -241,6 +243,8 @@ def get_client_by_id(client_id: UUID) -> Dict[str, Any]:
             raise ValueError(f"Client with id {client_id} not found")
         except AlreadyLoggedException:
             raise
+        except ValueError:
+            raise
         except Exception as exc:
             persist_and_raise(
                 exc,
@@ -295,7 +299,9 @@ def create_client(data: Dict[str, Any]) -> Client:
             )
 
     @staticmethod
-    def update_client(client_id: UUID, data: Dict[str, Any]) -> Client:
+    def update_client(
+        client_id: UUID, data: Dict[str, Any]
+    ) -> "_AnnotatedClientWithPhone":
         """
         Updates an existing client.
         If client is synced with Xero, updates Xero first then syncs locally.
@@ -310,95 +316,110 @@ def update_client(client_id: UUID, data: Dict[str, Any]) -> Client:
         Raises:
             ValueError: If client not found or validation fails
         """
-        client = Client.objects.filter(id=client_id).first()
-        if client is None:
-            raise ValueError(f"Client with id {client_id} not found")
-
-        # Store xero_contact_id before validation
-        original_xero_contact_id = client.xero_contact_id
+        try:
+            client = Client.objects.filter(id=client_id).first()
+            if client is None:
+                raise ValueError(f"Client with id {client_id} not found")
 
-        # Validate using DRF serializer
-        serializer = ClientUpdateSerializer(data=data)
-        if not serializer.is_valid():
-            error_messages = []
-            for field, errors in serializer.errors.items():
-                error_messages.extend([f"{field}: {e}" for e in errors])
-            raise ValueError("; ".join(error_messages))
+            # Store xero_contact_id before validation
+            original_xero_contact_id = client.xero_contact_id
 
-        validated_data = serializer.validated_data
-        # Stored as the client's primary ClientContactMethod, not a Client
-        # field, so it never reaches the generic setattr loop below.
-        phone_supplied = "phone" in validated_data
-        phone = validated_data.pop("phone", None)
+            # Validate using DRF serializer
+            serializer = ClientUpdateSerializer(data=data)
+            if not serializer.is_valid():
+                error_messages = []
+                for field, errors in serializer.errors.items():
+                    error_messages.extend([f"{field}: {e}" for e in errors])
+                raise ValueError("; ".join(error_messages))
 
-        # Guard clause - validate required fields
-        if not validated_data.get("name") and not client.name:
-            raise ValueError("Client name is required")
+            validated_data = serializer.validated_data
+            # Stored as the client's primary ClientContactMethod, not a Client
+            # field, so it never reaches the generic setattr loop below.
+            phone_supplied = "phone" in validated_data
+            phone = validated_data.pop("phone", None)
 
-        # DEBUG: Log client state after validation
-        logger.info(
-            f"Client data after validation: xero_contact_id={original_xero_contact_id}",
-            extra={
-                "client_id": str(client.id),
-                "original_xero_contact_id": original_xero_contact_id,
-                "operation": "update_client_debug_after_validation",
-            },
-        )
+            # Guard clause - validate required fields
+            if not validated_data.get("name") and not client.name:
+                raise ValueError("Client name is required")
 
-        # Check if client is synced with Xero
-        if original_xero_contact_id:
-            # Update in Xero first, then sync locally
-            updated_client = ClientRestService._update_client_in_xero(
-                client,
-                validated_data,
-                phone_supplied=phone_supplied,
-                raw_phone=phone,
-            )
+            # DEBUG: Log client state after validation
             logger.info(
-                f"Client {updated_client.id} updated in Xero and synced locally",
+                f"Client data after validation: xero_contact_id={original_xero_contact_id}",
                 extra={
-                    "client_id": str(updated_client.id),
-                    "client_name": updated_client.name,
-                    "xero_contact_id": updated_client.xero_contact_id,
-                    "operation": "update_client_xero_sync",
+                    "client_id": str(client.id),
+                    "original_xero_contact_id": original_xero_contact_id,
+                    "operation": "update_client_debug_after_validation",
                 },
             )
-        else:
-            # Local-only update for clients not synced with Xero
-            with transaction.atomic():
-                for field, value in validated_data.items():
-                    setattr(client, field, value)
-                client.xero_last_modified = timezone.now()
-                client.save()
-
-                ClientRestService._apply_client_phone_change(
+
+            # Check if client is synced with Xero
+            if original_xero_contact_id:
+                # Update in Xero first, then sync locally
+                updated_client = ClientRestService._update_client_in_xero(
                     client,
+                    validated_data,
                     phone_supplied=phone_supplied,
                     raw_phone=phone,
                 )
-
                 logger.info(
-                    f"Client {client.id} updated locally (no Xero sync)",
+                    f"Client {updated_client.id} updated in Xero and synced locally",
                     extra={
-                        "client_id": str(client.id),
-                        "client_name": client.name,
-                        "operation": "update_client_local_only",
+                        "client_id": str(updated_client.id),
+                        "client_name": updated_client.name,
+                        "xero_contact_id": updated_client.xero_contact_id,
+                        "operation": "update_client_xero_sync",
                     },
                 )
-            updated_client = client
+            else:
+                # Local-only update for clients not synced with Xero
+                with transaction.atomic():
+                    for field, value in validated_data.items():
+                        setattr(client, field, value)
+                    client.xero_last_modified = timezone.now()
+                    client.save()
+
+                    ClientRestService._apply_client_phone_change(
+                        client,
+                        phone_supplied=phone_supplied,
+                        raw_phone=phone,
+                    )
 
-        # The response's phone field always reads from a queryset annotation;
-        # refetch through it, restoring the with_invoice_summary() aggregates
-        # _format_client_detail needs.
-        return (
-            Client.objects.with_invoice_summary()
-            .annotate(
-                phone=ClientContactMethod.primary_phone_annotation(
-                    owner="client", outer_ref="pk"
+                    logger.info(
+                        f"Client {client.id} updated locally (no Xero sync)",
+                        extra={
+                            "client_id": str(client.id),
+                            "client_name": client.name,
+                            "operation": "update_client_local_only",
+                        },
+                    )
+                updated_client = client
+
+            # The response's phone field always reads from a queryset annotation;
+            # refetch through it, restoring the with_invoice_summary() aggregates
+            # _format_client_detail needs.
+            updated_with_phone: _AnnotatedClientWithPhone = (
+                Client.objects.with_invoice_summary()
+                .annotate(
+                    phone=ClientContactMethod.primary_phone_annotation(
+                        owner="client", outer_ref="pk"
+                    )
                 )
+                .get(id=updated_client.id)
+            )
+            return updated_with_phone
+        except AlreadyLoggedException:
+            raise
+        except ValueError:
+            raise
+        except Exception as exc:
+            persist_and_raise(
+                exc,
+                additional_context={
+                    "operation": "update_client",
+                    "client_id": str(client_id),
+                    "payload_keys": list(data.keys()),
+                },
             )
-            .get(id=updated_client.id)
-        )
 
     @staticmethod
     def get_client_contacts(client_id: UUID) -> List[Dict[str, Any]]:
@@ -856,7 +877,7 @@ def _format_client_summary(client: "_AnnotatedClientWithPhone") -> Dict[str, Any
         Formats a single client summary for list/search responses.
 
         Callers must annotate their queryset with
-        ClientContactMethod.primary_phone_annotation (see _ClientPhoneAnnotations).
+        ClientContactMethod.primary_phone_annotation (see ClientPhoneAnnotations).
         """
         return {
             "id": str(client.id),
@@ -885,7 +906,7 @@ def _format_client_detail(client: "_AnnotatedClientWithPhone") -> Dict[str, Any]
         Formats complete client details for API response.
 
         Callers must annotate their queryset with
-        ClientContactMethod.primary_phone_annotation (see _ClientPhoneAnnotations).
+        ClientContactMethod.primary_phone_annotation (see ClientPhoneAnnotations).
         """
         return {
             "id": str(client.id),
diff --git a/apps/client/tests/test_contact_methods.py b/apps/client/tests/test_contact_methods.py
index b54d1eda8..34784f1c4 100644
--- a/apps/client/tests/test_contact_methods.py
+++ b/apps/client/tests/test_contact_methods.py
@@ -543,7 +543,7 @@ def setUp(self) -> None:
     def _client(self, name: str = "Acme Ltd") -> Client:
         return Client.objects.create(name=name, xero_last_modified=timezone.now())
 
-    def _update_url(self, client_id) -> str:
+    def _update_url(self, client_id: uuid.UUID) -> str:
         return f"/api/clients/{client_id}/update/"
 
     def test_update_with_new_phone_creates_primary_method(self) -> None:
diff --git a/frontend/src/utils/__tests__/authConsoleErrors.test.ts b/frontend/src/utils/__tests__/authConsoleErrors.test.ts
index 76eeee97e..e3e48e8e0 100644
--- a/frontend/src/utils/__tests__/authConsoleErrors.test.ts
+++ b/frontend/src/utils/__tests__/authConsoleErrors.test.ts
@@ -5,7 +5,7 @@ import {
   LOGIN_ME_PATH,
   UNAUTHENTICATED_SESSION_CHECK_CONSOLE_ERROR,
   type CapturedBrowserError,
-} from '../../../tests/fixtures/auth-console-errors'
+} from '@/utils/authConsoleErrors'
 
 function console401(capturedAt: number): CapturedBrowserError {
   return {
diff --git a/frontend/tests/fixtures/auth-console-errors.ts b/frontend/src/utils/authConsoleErrors.ts
similarity index 100%
rename from frontend/tests/fixtures/auth-console-errors.ts
rename to frontend/src/utils/authConsoleErrors.ts
diff --git a/frontend/tests/fixtures/auth.ts b/frontend/tests/fixtures/auth.ts
index c4e5f033b..420a06996 100644
--- a/frontend/tests/fixtures/auth.ts
+++ b/frontend/tests/fixtures/auth.ts
@@ -13,7 +13,7 @@ import {
   createLoginSessionCheckConsoleAllowance,
   LOGIN_ME_PATH,
   type CapturedBrowserError,
-} from './auth-console-errors'
+} from '@/utils/authConsoleErrors'
 
 // Define fixture types
 type AuthFixtures = {
diff --git a/frontend/tests/kanban/kanban-drag-vanishing.spec.ts b/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
index 4a9ca8103..0594345bc 100644
--- a/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
+++ b/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
@@ -204,9 +204,9 @@ test.describe('kanban drag vanishing', () => {
     const consoleIssues = captureDragConsoleIssues(page)
 
     await page.goto('/kanban')
-    await page.waitForLoadState('networkidle')
 
     const searchInput = page.getByPlaceholder('Search jobs...')
+    await expect(searchInput).toBeVisible()
     await searchInput.fill(jobNumber)
 
     await expect(getVisibleJobCard(page, jobId)).toBeVisible({ timeout: 15000 })
@@ -246,7 +246,7 @@ test.describe('kanban drag vanishing', () => {
     const consoleIssues = captureDragConsoleIssues(page)
 
     await page.goto('/kanban')
-    await page.waitForLoadState('networkidle')
+    await expect(page.getByPlaceholder('Search jobs...')).toBeVisible()
 
     const jobCard = getVisibleJobCard(page, jobId)
     await jobCard.scrollIntoViewIfNeeded()
@@ -286,7 +286,7 @@ test.describe('kanban drag vanishing', () => {
     const consoleIssues = captureDragConsoleIssues(page)
 
     await page.goto('/kanban')
-    await page.waitForLoadState('networkidle')
+    await expect(page.getByPlaceholder('Search jobs...')).toBeVisible()
 
     const jobCard = getVisibleJobCard(page, jobId)
     await jobCard.scrollIntoViewIfNeeded()
@@ -360,7 +360,7 @@ test.describe('kanban drag vanishing', () => {
     const consoleIssues = captureDragConsoleIssues(page)
 
     await page.goto('/kanban')
-    await page.waitForLoadState('networkidle')
+    await expect(page.getByPlaceholder('Search jobs...')).toBeVisible()
 
     const jobCard = getVisibleJobCard(page, jobId)
     await jobCard.scrollIntoViewIfNeeded()

From eab0f8d69b780e95202c037bd9f56d381657585a Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 10:31:16 +1200
Subject: [PATCH 06/73] feat: add first-class people schema checkpoint

---
 apps/company/__init__.py                      |  10 +-
 .../migrations/0004_person_link_structure.py  | 128 +++++++++++
 .../migrations/0005_backfill_person.py        | 101 +++++++++
 apps/company/models.py                        | 207 ++++++++++++------
 apps/company/serializers.py                   |  56 ++++-
 .../tests/test_people_backfill_migration.py   | 133 +++++++++++
 apps/company/views/contact_method_viewset.py  |  11 +-
 apps/company/views/contact_viewset.py         |   4 +-
 ...rd_person_alter_phonecallrecord_contact.py |  37 ++++
 apps/crm/models.py                            |  11 +-
 apps/crm/serializers.py                       |   8 +-
 apps/crm/services/phone_call_service.py       |  60 +++--
 apps/crm/views/phone_call_views.py            |   4 +
 .../0004_job_person_alter_job_contact.py      |  39 ++++
 apps/job/models/job.py                        |  10 +-
 apps/job/serializers/job_serializer.py        |  14 +-
 frontend/schema.yml                           |  88 +++++++-
 17 files changed, 810 insertions(+), 111 deletions(-)
 create mode 100644 apps/company/migrations/0004_person_link_structure.py
 create mode 100644 apps/company/migrations/0005_backfill_person.py
 create mode 100644 apps/company/tests/test_people_backfill_migration.py
 create mode 100644 apps/crm/migrations/0005_phonecallrecord_person_alter_phonecallrecord_contact.py
 create mode 100644 apps/job/migrations/0004_job_person_alter_job_contact.py

diff --git a/apps/company/__init__.py b/apps/company/__init__.py
index f1a828471..0d439a388 100644
--- a/apps/company/__init__.py
+++ b/apps/company/__init__.py
@@ -9,10 +9,11 @@
 
     if apps.ready:
         from .models import (
-            ClientContact,
-            ClientContactMethod,
             Company,
+            CompanyPersonLink,
             CompanyQuerySet,
+            ContactMethod,
+            Person,
             PhoneAssignmentConflictError,
             Supplier,
             SupplierPickupAddress,
@@ -49,8 +50,6 @@
     pass
 
 __all__ = [
-    "ClientContact",
-    "ClientContactMethod",
     "ClientContactMethodSerializer",
     "ClientContactSerializer",
     "Company",
@@ -64,15 +63,18 @@
     "CompanyJobsResponseSerializer",
     "CompanyListResponseSerializer",
     "CompanyNameOnlySerializer",
+    "CompanyPersonLink",
     "CompanyQuerySet",
     "CompanySearchResponseSerializer",
     "CompanySearchResultSerializer",
     "CompanySerializer",
     "CompanyUpdateResponseSerializer",
     "CompanyUpdateSerializer",
+    "ContactMethod",
     "JobContactBaseSerializer",
     "JobContactResponseSerializer",
     "JobContactUpdateSerializer",
+    "Person",
     "PhoneAssignmentConflictError",
     "StandardErrorSerializer",
     "Supplier",
diff --git a/apps/company/migrations/0004_person_link_structure.py b/apps/company/migrations/0004_person_link_structure.py
new file mode 100644
index 000000000..94f4deb9d
--- /dev/null
+++ b/apps/company/migrations/0004_person_link_structure.py
@@ -0,0 +1,128 @@
+# Generated by Codex for KAN-278 Stage B.
+
+import uuid
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0003_alter_clientcontact_company_and_more"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Person",
+            fields=[
+                (
+                    "id",
+                    models.UUIDField(
+                        default=uuid.uuid4,
+                        editable=False,
+                        primary_key=True,
+                        serialize=False,
+                    ),
+                ),
+                ("name", models.CharField(db_index=True, max_length=255)),
+                ("email", models.EmailField(blank=True, max_length=254, null=True)),
+                ("is_active", models.BooleanField(default=True)),
+                ("created_at", models.DateTimeField(auto_now_add=True)),
+                ("updated_at", models.DateTimeField(auto_now=True)),
+            ],
+            options={"ordering": ["name"]},
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontact",
+            name="unique_company_contact_name",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="contact_method_one_owner",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_company_contact_method_value",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_company_primary_contact_method",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_contact_contact_method_value",
+        ),
+        migrations.RemoveConstraint(
+            model_name="clientcontactmethod",
+            name="unique_contact_primary_contact_method",
+        ),
+        migrations.RenameModel(
+            old_name="ClientContact",
+            new_name="CompanyPersonLink",
+        ),
+        migrations.RenameModel(
+            old_name="ClientContactMethod",
+            new_name="ContactMethod",
+        ),
+        migrations.AddField(
+            model_name="companypersonlink",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="company_links",
+                to="company.person",
+            ),
+        ),
+        migrations.AddField(
+            model_name="companypersonlink",
+            name="xero_name",
+            field=models.CharField(blank=True, max_length=255, null=True),
+        ),
+        migrations.AddField(
+            model_name="contactmethod",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="contact_methods",
+                to="company.person",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="contactmethod",
+            name="contact",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="contact_methods",
+                to="company.companypersonlink",
+            ),
+        ),
+        migrations.AlterModelOptions(
+            name="companypersonlink",
+            options={
+                "ordering": ["-is_primary", "name"],
+                "verbose_name": "Company Person Link",
+                "verbose_name_plural": "Company Person Links",
+            },
+        ),
+        migrations.AlterModelOptions(
+            name="contactmethod",
+            options={
+                "ordering": ["method_type", "-is_primary", "label", "value"],
+                "verbose_name": "Contact Method",
+                "verbose_name_plural": "Contact Methods",
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="companypersonlink",
+            constraint=models.UniqueConstraint(
+                fields=("company", "name"), name="unique_company_contact_name"
+            ),
+        ),
+    ]
diff --git a/apps/company/migrations/0005_backfill_person.py b/apps/company/migrations/0005_backfill_person.py
new file mode 100644
index 000000000..32c375fb2
--- /dev/null
+++ b/apps/company/migrations/0005_backfill_person.py
@@ -0,0 +1,101 @@
+# Generated by Codex for KAN-278 Stage B.
+
+from django.db import migrations
+
+
+def forwards(apps, schema_editor):
+    Person = apps.get_model("company", "Person")
+    CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
+    ContactMethod = apps.get_model("company", "ContactMethod")
+    Job = apps.get_model("job", "Job")
+    PhoneCallRecord = apps.get_model("crm", "PhoneCallRecord")
+
+    for link in CompanyPersonLink.objects.filter(person__isnull=True).order_by("id"):
+        person = Person.objects.create(
+            name=link.name,
+            email=link.email,
+            is_active=link.is_active,
+        )
+        link.person = person
+        link.xero_name = link.name
+        link.save(update_fields=["person", "xero_name", "updated_at"])
+
+    person_by_link_id = dict(
+        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
+            "id", "person_id"
+        )
+    )
+
+    for method in ContactMethod.objects.exclude(contact__isnull=True).order_by("id"):
+        person_id = person_by_link_id[method.contact_id]
+        method.person_id = person_id
+        method.contact_id = None
+        method.save(update_fields=["person", "contact", "updated_at"])
+
+    for job in Job.objects.exclude(contact__isnull=True).order_by("id"):
+        job.person_id = person_by_link_id[job.contact_id]
+        job.save(update_fields=["person"])
+
+    for call in PhoneCallRecord.objects.exclude(contact__isnull=True).order_by("id"):
+        call.person_id = person_by_link_id[call.contact_id]
+        call.save(update_fields=["person", "updated_at"])
+
+
+def backwards(apps, schema_editor):
+    CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
+    ContactMethod = apps.get_model("company", "ContactMethod")
+    Job = apps.get_model("job", "Job")
+    PhoneCallRecord = apps.get_model("crm", "PhoneCallRecord")
+
+    link_by_person_id = dict(
+        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
+            "person_id", "id"
+        )
+    )
+
+    for call in PhoneCallRecord.objects.exclude(person__isnull=True).order_by("id"):
+        call.contact_id = link_by_person_id[call.person_id]
+        call.person_id = None
+        call.save(update_fields=["contact", "person", "updated_at"])
+
+    for job in Job.objects.exclude(person__isnull=True).order_by("id"):
+        job.contact_id = link_by_person_id[job.person_id]
+        job.person_id = None
+        job.save(update_fields=["contact", "person"])
+
+    for method in ContactMethod.objects.exclude(person__isnull=True).order_by("id"):
+        method.contact_id = link_by_person_id[method.person_id]
+        method.person_id = None
+        method.save(update_fields=["contact", "person", "updated_at"])
+
+    for link in CompanyPersonLink.objects.exclude(person__isnull=True).select_related(
+        "person"
+    ):
+        link.name = link.person.name
+        link.email = link.person.email
+        link.is_active = link.person.is_active
+        link.person_id = None
+        link.xero_name = None
+        link.save(
+            update_fields=[
+                "name",
+                "email",
+                "is_active",
+                "person",
+                "xero_name",
+                "updated_at",
+            ]
+        )
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0004_person_link_structure"),
+        ("job", "0004_job_person_alter_job_contact"),
+        ("crm", "0005_phonecallrecord_person_alter_phonecallrecord_contact"),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards, backwards),
+    ]
diff --git a/apps/company/models.py b/apps/company/models.py
index 5e3ff8d32..2c66c1e9c 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -280,7 +280,49 @@ def get_final_company(self) -> "Company":
         return current
 
 
-class ClientContact(models.Model):
+class Person(models.Model):
+    """A human independent of any single company relationship."""
+
+    PERSON_API_FIELDS = [
+        "id",
+        "name",
+        "email",
+        "is_active",
+        "created_at",
+        "updated_at",
+    ]
+
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    name = models.CharField(max_length=255, db_index=True)
+    email = models.EmailField(null=True, blank=True)
+    is_active = models.BooleanField(default=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["name"]
+
+    def __str__(self) -> str:
+        return self.name
+
+    def save(
+        self,
+        *,
+        force_insert: bool | tuple[ModelBase, ...] = False,
+        force_update: bool = False,
+        using: str | None = None,
+        update_fields: Iterable[str] | None = None,
+    ) -> None:
+        update_fields = _augment_update_fields(update_fields, "updated_at")
+        super().save(
+            force_insert=force_insert,
+            force_update=force_update,
+            using=using,
+            update_fields=update_fields,
+        )
+
+
+class CompanyPersonLink(models.Model):
     """
     Represents a contact person for a company.
     This model stores contact information that was previously synced with Xero
@@ -300,8 +342,10 @@ class ClientContact(models.Model):
     CLIENTCONTACT_API_FIELDS = [
         "id",
         "company",
+        "person",
         "name",
         "email",
+        "xero_name",
         "position",
         "is_primary",
         "notes",
@@ -323,10 +367,18 @@ class ClientContact(models.Model):
         related_name="contacts",
         help_text="The company this contact belongs to",
     )
+    person = models.ForeignKey(
+        Person,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="company_links",
+    )
     name = models.CharField(max_length=255, help_text="Full name of the contact person")
     email = models.EmailField(
         null=True, blank=True, help_text="Email address of the contact"
     )
+    xero_name = models.CharField(max_length=255, null=True, blank=True)
     position = models.CharField(
         max_length=255,
         null=True,
@@ -349,8 +401,8 @@ class ClientContact(models.Model):
 
     class Meta:
         ordering = ["-is_primary", "name"]
-        verbose_name = "Client Contact"
-        verbose_name_plural = "Client Contacts"
+        verbose_name = "Company Person Link"
+        verbose_name_plural = "Company Person Links"
         constraints = [
             models.UniqueConstraint(
                 fields=["company", "name"],
@@ -370,13 +422,23 @@ def save(
         update_fields: Iterable[str] | None = None,
     ) -> None:
         update_fields = _augment_update_fields(update_fields, "updated_at")
+        if self.person_id is None:
+            self.person = Person.objects.create(
+                name=self.name,
+                email=self.email,
+                is_active=self.is_active,
+            )
+            update_fields = _augment_update_fields(update_fields, "person")
+        if self.xero_name is None:
+            self.xero_name = self.name
+            update_fields = _augment_update_fields(update_fields, "xero_name")
 
         # If this contact is being set as primary, ensure no other contacts
         # for this company are marked as primary
         if self.is_primary:
-            ClientContact.objects.filter(company=self.company, is_primary=True).exclude(
-                id=self.id
-            ).update(is_primary=False)
+            CompanyPersonLink.objects.filter(
+                company=self.company, is_primary=True
+            ).exclude(id=self.id).update(is_primary=False)
         super().save(
             force_insert=force_insert,
             force_update=force_update,
@@ -406,10 +468,10 @@ def __init__(self, conflict: "ClientContactMethod | None") -> None:
 # stable tie-break. Single source — every primary-phone consumer must use it.
 PRIMARY_PHONE_ORDERING: Final[tuple[str, str, str]] = ("-is_primary", "label", "value")
 
-PhoneOwner = Literal["company", "contact"]
+PhoneOwner = Literal["company", "contact", "person"]
 
 
-class ClientContactMethod(models.Model):
+class ContactMethod(models.Model):
     """Phone or email address owned by a company or one of its contacts."""
 
     class MethodType(models.TextChoices):
@@ -429,7 +491,14 @@ class Source(models.TextChoices):
         related_name="contact_methods",
     )
     contact = models.ForeignKey(
-        ClientContact,
+        CompanyPersonLink,
+        on_delete=models.CASCADE,
+        null=True,
+        blank=True,
+        related_name="contact_methods",
+    )
+    person = models.ForeignKey(
+        Person,
         on_delete=models.CASCADE,
         null=True,
         blank=True,
@@ -450,48 +519,12 @@ class Source(models.TextChoices):
 
     class Meta:
         ordering = ["method_type", "-is_primary", "label", "value"]
-        verbose_name = "Client Contact Method"
-        verbose_name_plural = "Client Contact Methods"
-        constraints = [
-            models.CheckConstraint(
-                condition=(
-                    models.Q(company__isnull=False, contact__isnull=True)
-                    | models.Q(company__isnull=True, contact__isnull=False)
-                ),
-                name="contact_method_one_owner",
-            ),
-            models.UniqueConstraint(
-                fields=["company", "method_type", "normalized_value"],
-                condition=models.Q(company__isnull=False, contact__isnull=True),
-                name="unique_company_contact_method_value",
-            ),
-            models.UniqueConstraint(
-                fields=["contact", "method_type", "normalized_value"],
-                condition=models.Q(company__isnull=True, contact__isnull=False),
-                name="unique_contact_contact_method_value",
-            ),
-            models.UniqueConstraint(
-                fields=["company", "method_type"],
-                condition=models.Q(
-                    company__isnull=False,
-                    contact__isnull=True,
-                    is_primary=True,
-                ),
-                name="unique_company_primary_contact_method",
-            ),
-            models.UniqueConstraint(
-                fields=["contact", "method_type"],
-                condition=models.Q(
-                    company__isnull=True,
-                    contact__isnull=False,
-                    is_primary=True,
-                ),
-                name="unique_contact_primary_contact_method",
-            ),
-        ]
+        verbose_name = "Contact Method"
+        verbose_name_plural = "Contact Methods"
+        constraints: list[models.BaseConstraint] = []
 
     def __str__(self) -> str:
-        owner = self.contact or self.company
+        owner = self.person or self.contact or self.company
         return f"{self.method_type}: {self.value} ({owner})"
 
     @classmethod
@@ -514,6 +547,24 @@ def primary_phone_annotation(cls, *, owner: PhoneOwner, outer_ref: str) -> Coale
             output_field=models.CharField(),
         )
 
+    @classmethod
+    def primary_phone_for_link_annotation(cls) -> Coalesce:
+        """Primary phone for a company-person link during contact→person migration."""
+        candidates = (
+            cls.objects.filter(method_type=cls.MethodType.PHONE)
+            .filter(
+                models.Q(person=models.OuterRef("person_id"))
+                | models.Q(contact=models.OuterRef("pk"))
+            )
+            .order_by(*PRIMARY_PHONE_ORDERING)
+            .values("value")[:1]
+        )
+        return Coalesce(
+            models.Subquery(candidates),
+            models.Value(""),
+            output_field=models.CharField(),
+        )
+
     def save(
         self,
         *,
@@ -537,6 +588,7 @@ def save(
                     self.normalized_value,
                     company_id=self.company_id,
                     contact=self.contact,
+                    person=self.person,
                     instance=self,
                     using=db,
                 )
@@ -553,14 +605,16 @@ def save(
 
         if self.is_primary:
             queryset = (
-                ClientContactMethod.objects.using(db)
+                ContactMethod.objects.using(db)
                 .filter(
                     method_type=self.method_type,
                     is_primary=True,
                 )
                 .exclude(id=self.id)
             )
-            if self.contact_id:
+            if self.person_id:
+                queryset = queryset.filter(person_id=self.person_id)
+            elif self.contact_id:
                 queryset = queryset.filter(contact_id=self.contact_id)
             else:
                 queryset = queryset.filter(
@@ -596,20 +650,31 @@ def normalize_phone(value: str | None) -> str:
 
     def owner_company_id(self) -> uuid.UUID | None:
         """The effective company that owns this method (directly or via its contact)."""
+        company_ids = self.owner_company_ids()
+        if len(company_ids) == 1:
+            return next(iter(company_ids))
+        if company_ids:
+            return sorted(company_ids)[0]
+        return None
+
+    def owner_company_ids(self) -> set[uuid.UUID]:
+        """Companies this method can be traced to through its owner."""
         if self.company_id:
-            return self.company_id
+            return {self.company_id}
+        if self.person is not None:
+            return set(self.person.company_links.values_list("company_id", flat=True))
         if self.contact is not None:
-            return self.contact.company_id
-        return None
+            return {self.contact.company_id}
+        return set()
 
     @classmethod
     def conflicting_company(
         cls,
         normalized_value: str,
-        effective_company_id: uuid.UUID | None,
+        effective_company_ids: set[uuid.UUID],
         exclude_id: uuid.UUID | None = None,
         using: str = DEFAULT_DB_ALIAS,
-    ) -> "ClientContactMethod | None":
+    ) -> "ContactMethod | None":
         """A phone method for this number owned by a *different* effective company.
 
         The single source of truth for the "one number, one company" rule, shared by
@@ -630,7 +695,7 @@ def conflicting_company(
             (
                 other
                 for other in queryset
-                if other.owner_company_id() != effective_company_id
+                if not other.owner_company_ids().intersection(effective_company_ids)
             ),
             None,
         )
@@ -641,8 +706,9 @@ def check_phone_assignment(
         normalized_value: str,
         *,
         company_id: uuid.UUID | None,
-        contact: "ClientContact | None",
-        instance: "ClientContactMethod | None" = None,
+        contact: "CompanyPersonLink | None",
+        person: "Person | None" = None,
+        instance: "ContactMethod | None" = None,
         using: str = DEFAULT_DB_ALIAS,
     ) -> None:
         """Enforce the one-number-one-company rule for a proposed phone owner.
@@ -663,11 +729,12 @@ def check_phone_assignment(
                 ``conflict=None`` for an internal-endpoint collision.
         """
         contact_id = contact.pk if contact is not None else None
+        person_id = person.pk if person is not None else None
         if instance is not None and not instance._state.adding:
             stored = (
                 cls.objects.using(using)
                 .filter(pk=instance.pk)
-                .values("normalized_value", "company_id", "contact_id")
+                .values("normalized_value", "company_id", "contact_id", "person_id")
                 .first()
             )
             if (
@@ -675,6 +742,7 @@ def check_phone_assignment(
                 and stored["normalized_value"] == normalized_value
                 and stored["company_id"] == company_id
                 and stored["contact_id"] == contact_id
+                and stored["person_id"] == person_id
             ):
                 return  # unchanged association -> grandfathered
 
@@ -688,14 +756,18 @@ def check_phone_assignment(
             raise PhoneAssignmentConflictError(None)
 
         if company_id is not None:
-            effective_company_id = company_id
+            effective_company_ids = {company_id}
         elif contact is not None:
-            effective_company_id = contact.company_id
+            effective_company_ids = {contact.company_id}
+        elif person is not None:
+            effective_company_ids = set(
+                person.company_links.using(using).values_list("company_id", flat=True)
+            )
         else:
-            effective_company_id = None
+            effective_company_ids = set()
         conflict = cls.conflicting_company(
             normalized_value,
-            effective_company_id,
+            effective_company_ids,
             exclude_id=instance.pk if instance is not None else None,
             using=using,
         )
@@ -705,11 +777,18 @@ def check_phone_assignment(
     def owner_display_name(self) -> str:
         if self.contact:
             return f"contact {self.contact.name} at {self.contact.company.name}"
+        if self.person:
+            return f"person {self.person.name}"
         if self.company:
             return f"company {self.company.name}"
         return "another CRM owner"
 
 
+# Temporary import aliases while consumers are moved to person naming.
+ClientContact = CompanyPersonLink
+ClientContactMethod = ContactMethod
+
+
 class Supplier(Company):
     """
     A Supplier is simply a Company with additional semantics.
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 5ce7442ab..f57c0128e 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -8,13 +8,14 @@
     ClientContact,
     ClientContactMethod,
     Company,
+    Person,
     PhoneAssignmentConflictError,
     SupplierPickupAddress,
     SupplierSearchAlias,
 )
 
 
-def set_primary_phone(owner: Company | ClientContact, raw_value: str) -> None:
+def set_primary_phone(owner: Company | ClientContact | Person, raw_value: str) -> None:
     """Point the owner's primary phone at ``raw_value`` (non-blank).
 
     Reuses an existing method carrying the same normalized number (promoting
@@ -27,7 +28,12 @@ def set_primary_phone(owner: Company | ClientContact, raw_value: str) -> None:
     from apps.crm.tasks import rematch_phone_calls_task
 
     value = raw_value.strip()
-    owner_field = "company" if isinstance(owner, Company) else "contact"
+    if isinstance(owner, Company):
+        owner_field = "company"
+    elif isinstance(owner, Person):
+        owner_field = "person"
+    else:
+        owner_field = "contact"
     phone_methods = ClientContactMethod.objects.filter(
         method_type=ClientContactMethod.MethodType.PHONE, **{owner_field: owner}
     )
@@ -49,11 +55,14 @@ def set_primary_phone(owner: Company | ClientContact, raw_value: str) -> None:
         old_primary.save()
         method = old_primary
     else:
+        create_kwargs = {owner_field: owner}
+        if isinstance(owner, ClientContact) and owner.person_id:
+            create_kwargs["person"] = owner.person
         method = ClientContactMethod.objects.create(
             method_type=ClientContactMethod.MethodType.PHONE,
             value=value,
             is_primary=True,
-            **{owner_field: owner},
+            **create_kwargs,
         )
 
     numbers = sorted(
@@ -90,6 +99,13 @@ def to_internal_value(self, data: Any) -> Any:
     def create(self, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
         with transaction.atomic():
+            person = Person.objects.create(
+                name=validated_data["name"],
+                email=validated_data.get("email"),
+                is_active=validated_data.get("is_active", True),
+            )
+            validated_data["person"] = person
+            validated_data["xero_name"] = validated_data["name"]
             contact = super().create(validated_data)
             return self._apply_phone(contact, raw_phone)
 
@@ -97,6 +113,18 @@ def update(self, instance, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
         with transaction.atomic():
             contact = super().update(instance, validated_data)
+            if contact.person_id:
+                person_update_fields = ["updated_at"]
+                if "name" in validated_data:
+                    contact.person.name = contact.name
+                    person_update_fields.append("name")
+                if "email" in validated_data:
+                    contact.person.email = contact.email
+                    person_update_fields.append("email")
+                if "is_active" in validated_data:
+                    contact.person.is_active = contact.is_active
+                    person_update_fields.append("is_active")
+                contact.person.save(update_fields=person_update_fields)
             return self._apply_phone(contact, raw_phone)
 
     def _apply_phone(
@@ -114,9 +142,7 @@ def _apply_phone(
         # The phone field always reads from a queryset annotation; give the
         # write response the same shape by re-fetching through it.
         return ClientContact.objects.annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
-                owner="contact", outer_ref="pk"
-            )
+            phone=ClientContactMethod.primary_phone_for_link_annotation()
         ).get(pk=contact.pk)
 
 
@@ -136,6 +162,7 @@ class Meta:
             "company_name",
             "contact",
             "contact_name",
+            "person",
             "method_type",
             "value",
             "normalized_value",
@@ -158,11 +185,21 @@ class Meta:
     def get_owner_company(self, obj: ClientContactMethod) -> str:
         if obj.company_id:
             return str(obj.company_id)
+        if obj.person_id:
+            company_id = obj.owner_company_id()
+            return str(company_id) if company_id else ""
         return str(obj.contact.company_id) if obj.contact else ""
 
     def get_company_name(self, obj: ClientContactMethod) -> str:
         if obj.company:
             return obj.company.name
+        if obj.person_id:
+            link = (
+                obj.person.company_links.select_related("company")
+                .order_by("-is_primary", "company__name")
+                .first()
+            )
+            return link.company.name if link else ""
         return obj.contact.company.name if obj.contact else ""
 
     def get_contact_name(self, obj: ClientContactMethod) -> str:
@@ -171,9 +208,11 @@ def get_contact_name(self, obj: ClientContactMethod) -> str:
     def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
         company = attrs.get("company", getattr(self.instance, "company", None))
         contact = attrs.get("contact", getattr(self.instance, "contact", None))
-        if bool(company) == bool(contact):
+        person = attrs.get("person", getattr(self.instance, "person", None))
+        owner_count = sum(1 for owner in (company, contact, person) if owner)
+        if owner_count != 1:
             raise serializers.ValidationError(
-                "Exactly one of company or contact is required"
+                "Exactly one of company, contact, or person is required"
             )
         method_type = attrs.get(
             "method_type", getattr(self.instance, "method_type", None)
@@ -186,6 +225,7 @@ def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
                     normalized,
                     company_id=company.id if company else None,
                     contact=contact,
+                    person=person,
                     instance=self.instance,
                 )
             except PhoneAssignmentConflictError as exc:
diff --git a/apps/company/tests/test_people_backfill_migration.py b/apps/company/tests/test_people_backfill_migration.py
new file mode 100644
index 000000000..3b11c3fcb
--- /dev/null
+++ b/apps/company/tests/test_people_backfill_migration.py
@@ -0,0 +1,133 @@
+import uuid
+
+from django.db import connection, transaction
+from django.db.migrations.executor import MigrationExecutor
+from django.test import TransactionTestCase
+from django.utils import timezone
+
+
+class PeopleBackfillMigrationTests(TransactionTestCase):
+    migrate_from = [
+        ("company", "0004_person_link_structure"),
+        ("job", "0004_job_person_alter_job_contact"),
+        ("crm", "0005_phonecallrecord_person_alter_phonecallrecord_contact"),
+    ]
+    migrate_to = [("company", "0005_backfill_person")]
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.executor = MigrationExecutor(connection)
+        self.executor.migrate(self.migrate_from)
+        self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
+
+    def tearDown(self) -> None:
+        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
+        super().tearDown()
+
+    def test_backfill_and_reverse_restore_legacy_contact_ownership(self) -> None:
+        Company = self.old_apps.get_model("company", "Company")
+        CompanyPersonLink = self.old_apps.get_model("company", "CompanyPersonLink")
+        ContactMethod = self.old_apps.get_model("company", "ContactMethod")
+        Job = self.old_apps.get_model("job", "Job")
+        CostSet = self.old_apps.get_model("job", "CostSet")
+        PhoneCallRecord = self.old_apps.get_model("crm", "PhoneCallRecord")
+        XeroPayItem = self.old_apps.get_model("workflow", "XeroPayItem")
+
+        company = Company.objects.create(
+            name="Acme",
+            xero_last_modified=timezone.now(),
+        )
+        link = CompanyPersonLink.objects.create(
+            company=company,
+            name="Jane Smith",
+            email="jane@example.com",
+            is_primary=True,
+        )
+        method = ContactMethod.objects.create(
+            contact=link,
+            method_type="phone",
+            value="021 123 456",
+            normalized_value="+6421123456",
+            is_primary=True,
+        )
+        pay_item, _created = XeroPayItem.objects.get_or_create(
+            name="Ordinary Time",
+            uses_leave_api=False,
+            defaults={"multiplier": "1.00"},
+        )
+        estimate_id = uuid.uuid4()
+        quote_id = uuid.uuid4()
+        actual_id = uuid.uuid4()
+        with transaction.atomic():
+            with connection.cursor() as cursor:
+                cursor.execute("SET CONSTRAINTS ALL DEFERRED")
+            job = Job.objects.create(
+                company=company,
+                contact=link,
+                name="Test job",
+                job_number=991001,
+                default_xero_pay_item=pay_item,
+                latest_estimate_id=estimate_id,
+                latest_quote_id=quote_id,
+                latest_actual_id=actual_id,
+            )
+            CostSet.objects.create(id=estimate_id, job=job, kind="estimate", rev=1)
+            CostSet.objects.create(id=quote_id, job=job, kind="quote", rev=1)
+            CostSet.objects.create(id=actual_id, job=job, kind="actual", rev=1)
+        now = timezone.now()
+        call = PhoneCallRecord.objects.create(
+            provider_call_id="call-people-backfill",
+            account_code="acct",
+            call_datetime=now,
+            call_date=timezone.localdate(),
+            call_time=now.time(),
+            company=company,
+            contact=link,
+            raw_json={},
+        )
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_to)
+        new_apps = self.executor.loader.project_state(self.migrate_to).apps
+        Person = new_apps.get_model("company", "Person")
+        CompanyPersonLink = new_apps.get_model("company", "CompanyPersonLink")
+        ContactMethod = new_apps.get_model("company", "ContactMethod")
+        Job = new_apps.get_model("job", "Job")
+        PhoneCallRecord = new_apps.get_model("crm", "PhoneCallRecord")
+
+        person = Person.objects.get(name="Jane Smith")
+        link = CompanyPersonLink.objects.get(pk=link.pk)
+        method = ContactMethod.objects.get(pk=method.pk)
+        job = Job.objects.get(pk=job.pk)
+        call = PhoneCallRecord.objects.get(pk=call.pk)
+
+        self.assertEqual(link.person_id, person.pk)
+        self.assertEqual(link.xero_name, "Jane Smith")
+        self.assertEqual(person.email, "jane@example.com")
+        self.assertEqual(method.person_id, person.pk)
+        self.assertIsNone(method.contact_id)
+        self.assertEqual(job.person_id, person.pk)
+        self.assertEqual(call.person_id, person.pk)
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_from)
+        reversed_apps = self.executor.loader.project_state(self.migrate_from).apps
+        CompanyPersonLink = reversed_apps.get_model("company", "CompanyPersonLink")
+        ContactMethod = reversed_apps.get_model("company", "ContactMethod")
+        Job = reversed_apps.get_model("job", "Job")
+        PhoneCallRecord = reversed_apps.get_model("crm", "PhoneCallRecord")
+
+        link = CompanyPersonLink.objects.get(pk=link.pk)
+        method = ContactMethod.objects.get(pk=method.pk)
+        job = Job.objects.get(pk=job.pk)
+        call = PhoneCallRecord.objects.get(pk=call.pk)
+
+        self.assertIsNone(link.person_id)
+        self.assertIsNone(link.xero_name)
+        self.assertEqual(link.name, "Jane Smith")
+        self.assertEqual(method.contact_id, link.pk)
+        self.assertIsNone(method.person_id)
+        self.assertEqual(job.contact_id, link.pk)
+        self.assertIsNone(job.person_id)
+        self.assertEqual(call.contact_id, link.pk)
+        self.assertIsNone(call.person_id)
diff --git a/apps/company/views/contact_method_viewset.py b/apps/company/views/contact_method_viewset.py
index c273fc800..9632547a9 100644
--- a/apps/company/views/contact_method_viewset.py
+++ b/apps/company/views/contact_method_viewset.py
@@ -73,17 +73,24 @@ def get_queryset(self):
             "company",
             "contact",
             "contact__company",
+            "person",
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:
-            queryset = queryset.filter(company_id=company_id) | queryset.filter(
-                contact__company_id=company_id
+            queryset = (
+                queryset.filter(company_id=company_id)
+                | queryset.filter(contact__company_id=company_id)
+                | queryset.filter(person__company_links__company_id=company_id)
             )
 
         contact_id = self.request.query_params.get("contact_id")
         if contact_id:
             queryset = queryset.filter(contact_id=contact_id)
 
+        person_id = self.request.query_params.get("person_id")
+        if person_id:
+            queryset = queryset.filter(person_id=person_id)
+
         method_type = self.request.query_params.get("method_type")
         if method_type:
             queryset = queryset.filter(method_type=method_type)
diff --git a/apps/company/views/contact_viewset.py b/apps/company/views/contact_viewset.py
index c6eb4a633..3ff2351d5 100644
--- a/apps/company/views/contact_viewset.py
+++ b/apps/company/views/contact_viewset.py
@@ -53,9 +53,7 @@ def get_queryset(self):
         Filter to only active contacts, optionally filtered by company_id.
         """
         queryset = ClientContact.objects.filter(is_active=True).annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
-                owner="contact", outer_ref="pk"
-            )
+            phone=ClientContactMethod.primary_phone_for_link_annotation()
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:
diff --git a/apps/crm/migrations/0005_phonecallrecord_person_alter_phonecallrecord_contact.py b/apps/crm/migrations/0005_phonecallrecord_person_alter_phonecallrecord_contact.py
new file mode 100644
index 000000000..fa383148d
--- /dev/null
+++ b/apps/crm/migrations/0005_phonecallrecord_person_alter_phonecallrecord_contact.py
@@ -0,0 +1,37 @@
+# Generated by Django 6.0.4 on 2026-07-08 21:59
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0004_person_link_structure"),
+        ("crm", "0004_rename_client_company"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="phonecallrecord",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="person_phone_calls",
+                to="company.person",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="phonecallrecord",
+            name="contact",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="phone_calls",
+                to="company.companypersonlink",
+            ),
+        ),
+    ]
diff --git a/apps/crm/models.py b/apps/crm/models.py
index 01e42b576..1fd0e3354 100644
--- a/apps/crm/models.py
+++ b/apps/crm/models.py
@@ -71,7 +71,7 @@ def save(
             # both a company contact method and an active internal endpoint, or
             # the company's calls would silently reclassify as INTERNAL.
             conflict = ClientContactMethod.conflicting_company(
-                self.normalized_number, None
+                self.normalized_number, set()
             )
             if conflict:
                 raise ValidationError(
@@ -189,12 +189,19 @@ class Direction(models.TextChoices):
         related_name="phone_calls",
     )
     contact = models.ForeignKey(
-        "company.ClientContact",
+        "company.CompanyPersonLink",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
         related_name="phone_calls",
     )
+    person = models.ForeignKey(
+        "company.Person",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="person_phone_calls",
+    )
     job = models.ForeignKey(
         "job.Job",
         on_delete=models.SET_NULL,
diff --git a/apps/crm/serializers.py b/apps/crm/serializers.py
index d73e80a3d..5f316f914 100644
--- a/apps/crm/serializers.py
+++ b/apps/crm/serializers.py
@@ -150,7 +150,7 @@ def validate(self, attrs: "PhoneEndpointAttrs") -> "PhoneEndpointAttrs":
             return attrs  # association unchanged — grandfathered, like save()
 
         if is_active:
-            conflict = ClientContactMethod.conflicting_company(normalized, None)
+            conflict = ClientContactMethod.conflicting_company(normalized, set())
             if conflict:
                 raise serializers.ValidationError(
                     {
@@ -244,6 +244,7 @@ class PhoneCallRecordSerializer(serializers.ModelSerializer[PhoneCallRecord]):
     recording = serializers.SerializerMethodField()
     company_name = serializers.SerializerMethodField()
     contact_name = serializers.SerializerMethodField()
+    person_name = serializers.SerializerMethodField()
     origin_endpoint_label = serializers.SerializerMethodField()
     destination_endpoint_label = serializers.SerializerMethodField()
     job_number = serializers.SerializerMethodField()
@@ -277,6 +278,8 @@ class Meta:
             "company_name",
             "contact",
             "contact_name",
+            "person",
+            "person_name",
             "job",
             "job_number",
             "job_name",
@@ -295,6 +298,9 @@ def get_company_name(self, obj: PhoneCallRecord) -> str:
     def get_contact_name(self, obj: PhoneCallRecord) -> str:
         return obj.contact.name if obj.contact else ""
 
+    def get_person_name(self, obj: PhoneCallRecord) -> str:
+        return obj.person.name if obj.person else ""
+
     def get_origin_endpoint_label(self, obj: PhoneCallRecord) -> str:
         return obj.origin_endpoint.label if obj.origin_endpoint else ""
 
diff --git a/apps/crm/services/phone_call_service.py b/apps/crm/services/phone_call_service.py
index 9c8ed1ef8..557579f40 100644
--- a/apps/crm/services/phone_call_service.py
+++ b/apps/crm/services/phone_call_service.py
@@ -16,7 +16,7 @@
 from django.db import models, transaction
 from django.utils import timezone
 
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import ClientContact, ClientContactMethod, Company, Person
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -526,6 +526,7 @@ def upsert_call_record(
         "charge": _decimal_or_none(payload.get("charge")),
         "company": classification.company,
         "contact": classification.contact,
+        "person": classification.person,
         "raw_json": payload,
     }
     call = PhoneCallRecord.objects.filter(provider_call_id=provider_call_id).first()
@@ -597,6 +598,7 @@ class CallClassification:
     destination_endpoint: PhoneEndpoint | None
     company: Company | None
     contact: ClientContact | None
+    person: Person | None
 
 
 class PhoneMatcher:
@@ -618,6 +620,12 @@ def __init__(self, numbers: set[str] | None = None):
     def match_customer(
         self, *values: str
     ) -> tuple[Company | None, ClientContact | None]:
+        company, contact, _person = self.match_customer_details(*values)
+        return company, contact
+
+    def match_customer_details(
+        self, *values: str
+    ) -> tuple[Company | None, ClientContact | None, Person | None]:
         matches: set[tuple[str, str, str]] = set()
         for value in values:
             normalized = normalize_phone(value)
@@ -626,22 +634,26 @@ def match_customer(
             matches.update(self.phone_matches.get(normalized, set()))
 
         if not matches:
-            return None, None
+            return None, None, None
 
         company_ids = {company_id for _, _, company_id in matches}
         if len(company_ids) != 1:
-            return None, None
+            return None, None, None
 
         if len(matches) != 1:
             company = Company.objects.get(id=next(iter(company_ids)))
-            return company, None
+            return company, None, None
 
         kind, object_id, _company_id = next(iter(matches))
         if kind == "contact":
             contact = ClientContact.objects.select_related("company").get(id=object_id)
-            return contact.company, contact
+            return contact.company, contact, contact.person
+        if kind == "person":
+            person = Person.objects.get(id=object_id)
+            company = Company.objects.get(id=next(iter(company_ids)))
+            return company, None, person
         company = Company.objects.get(id=object_id)
-        return company, None
+        return company, None, None
 
     def classify(self, origin: str, destination: str) -> CallClassification:
         normalized_origin = normalize_phone(origin)
@@ -658,10 +670,13 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 destination_endpoint=destination_endpoint,
                 company=None,
                 contact=None,
+                person=None,
             )
 
         if origin_endpoint:
-            company, contact = self.match_customer(normalized_destination)
+            company, contact, person = self.match_customer_details(
+                normalized_destination
+            )
             return CallClassification(
                 direction=PhoneCallRecord.Direction.OUTBOUND,
                 our_number=normalized_origin,
@@ -670,10 +685,11 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 destination_endpoint=None,
                 company=company,
                 contact=contact,
+                person=person,
             )
 
         if destination_endpoint:
-            company, contact = self.match_customer(normalized_origin)
+            company, contact, person = self.match_customer_details(normalized_origin)
             return CallClassification(
                 direction=PhoneCallRecord.Direction.INBOUND,
                 our_number=normalized_destination,
@@ -682,9 +698,10 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 destination_endpoint=destination_endpoint,
                 company=company,
                 contact=contact,
+                person=person,
             )
 
-        company, contact = self.match_customer(
+        company, contact, person = self.match_customer_details(
             normalized_origin, normalized_destination
         )
         external_number = ""
@@ -702,6 +719,7 @@ def classify(self, origin: str, destination: str) -> CallClassification:
             destination_endpoint=None,
             company=company,
             contact=contact,
+            person=person,
         )
 
 
@@ -726,7 +744,7 @@ def configured_own_numbers() -> set[str]:
 
 
 _REMATCH_FK_FIELDS = frozenset(
-    {"company", "contact", "origin_endpoint", "destination_endpoint"}
+    {"company", "contact", "person", "origin_endpoint", "destination_endpoint"}
 )
 
 
@@ -768,6 +786,7 @@ def rematch_calls_for_numbers(numbers: list[str]) -> None:
         new_values: dict[str, object] = {
             "company": classification.company,
             "contact": classification.contact,
+            "person": classification.person,
             "direction": classification.direction,
             "our_number": classification.our_number,
             "external_number": classification.external_number,
@@ -822,7 +841,11 @@ def assign_phone_number(
             )
         except ClientContact.DoesNotExist as exc:
             raise ValueError("Contact not found") from exc
-        owner_filter = {"contact": contact, "company": None}
+        owner_filter = {
+            "contact": contact,
+            "person": contact.person,
+            "company": None,
+        }
         existing_primary = ClientContactMethod.objects.filter(
             contact=contact,
             method_type=ClientContactMethod.MethodType.PHONE,
@@ -833,7 +856,7 @@ def assign_phone_number(
             company = Company.objects.get(id=company_uuid)
         except Company.DoesNotExist as exc:
             raise ValueError("Company not found") from exc
-        owner_filter = {"company": company, "contact": None}
+        owner_filter = {"company": company, "contact": None, "person": None}
         existing_primary = ClientContactMethod.objects.filter(
             company=company,
             contact__isnull=True,
@@ -842,7 +865,7 @@ def assign_phone_number(
         ).exists()
 
     should_be_primary = is_primary or not existing_primary
-    conflict = ClientContactMethod.conflicting_company(normalized, company_uuid)
+    conflict = ClientContactMethod.conflicting_company(normalized, {company_uuid})
     if conflict:
         raise ValueError(
             f"phone number already belongs to {conflict.owner_display_name()}"
@@ -886,6 +909,7 @@ def _build_contact_method_phone_index(
         "company",
         "contact",
         "contact__company",
+        "person",
     ).filter(method_type=ClientContactMethod.MethodType.PHONE)
     if numbers is not None:
         methods = methods.filter(normalized_value__in=numbers)
@@ -893,7 +917,15 @@ def _build_contact_method_phone_index(
         normalized = method.normalized_value or normalize_phone(method.value)
         if not normalized or normalized in internal_numbers:
             continue
-        if method.contact_id:
+        if method.person_id:
+            if not method.person.is_active:
+                continue
+            company_ids = method.owner_company_ids()
+            for company_id in company_ids:
+                index.setdefault(normalized, set()).add(
+                    ("person", str(method.person_id), str(company_id))
+                )
+        elif method.contact_id:
             if not method.contact.is_active:
                 continue
             index.setdefault(normalized, set()).add(
diff --git a/apps/crm/views/phone_call_views.py b/apps/crm/views/phone_call_views.py
index 0185efe34..8ac596dfd 100644
--- a/apps/crm/views/phone_call_views.py
+++ b/apps/crm/views/phone_call_views.py
@@ -67,6 +67,7 @@ def _phone_call_filter_kwargs(request: Request) -> dict[str, UUID]:
     query_filters = (
         ("company_id", _query_uuid(request.query_params.get("company"), "company")),
         ("contact_id", _query_uuid(request.query_params.get("contact"), "contact")),
+        ("person_id", _query_uuid(request.query_params.get("person"), "person")),
         ("job_id", _query_uuid(request.query_params.get("job"), "job")),
         (
             "origin_endpoint_id",
@@ -186,6 +187,7 @@ def _apply_search_filter(
     filters = (
         Q(company__name__icontains=search)
         | Q(contact__name__icontains=search)
+        | Q(person__name__icontains=search)
         | Q(origin_endpoint__label__icontains=search)
         | Q(destination_endpoint__label__icontains=search)
         | Q(job__name__icontains=search)
@@ -242,6 +244,7 @@ class PhoneCallRecordViewSet(viewsets.ReadOnlyModelViewSet[PhoneCallRecord]):
         parameters=[
             OpenApiParameter("company", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("contact", OpenApiTypes.UUID, OpenApiParameter.QUERY),
+            OpenApiParameter("person", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("job", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter(
                 "origin_endpoint", OpenApiTypes.UUID, OpenApiParameter.QUERY
@@ -284,6 +287,7 @@ def get_queryset(self) -> QuerySet[PhoneCallRecord]:
             PhoneCallRecord.objects.select_related(
                 "company",
                 "contact",
+                "person",
                 "job",
                 "job_linked_by",
                 "origin_endpoint",
diff --git a/apps/job/migrations/0004_job_person_alter_job_contact.py b/apps/job/migrations/0004_job_person_alter_job_contact.py
new file mode 100644
index 000000000..4fdc6f570
--- /dev/null
+++ b/apps/job/migrations/0004_job_person_alter_job_contact.py
@@ -0,0 +1,39 @@
+# Generated by Django 6.0.4 on 2026-07-08 21:59
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0004_person_link_structure"),
+        ("job", "0003_rename_client_company"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="job",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="The person for this job",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="person_jobs",
+                to="company.person",
+            ),
+        ),
+        migrations.AlterField(
+            model_name="job",
+            name="contact",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="The contact person for this job",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="jobs",
+                to="company.companypersonlink",
+            ),
+        ),
+    ]
diff --git a/apps/job/models/job.py b/apps/job/models/job.py
index fe98357cf..198d291b0 100644
--- a/apps/job/models/job.py
+++ b/apps/job/models/job.py
@@ -217,13 +217,21 @@ class Job(models.Model):
 
     # New relationship to ClientContact
     contact = models.ForeignKey(
-        "company.ClientContact",
+        "company.CompanyPersonLink",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
         related_name="jobs",
         help_text="The contact person for this job",
     )
+    person = models.ForeignKey(
+        "company.Person",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="person_jobs",
+        help_text="The person for this job",
+    )
     job_number = models.IntegerField(unique=True)  # Job 1234
     description = models.TextField(
         blank=True,
diff --git a/apps/job/serializers/job_serializer.py b/apps/job/serializers/job_serializer.py
index 0ef14b2a5..10ae219e3 100644
--- a/apps/job/serializers/job_serializer.py
+++ b/apps/job/serializers/job_serializer.py
@@ -8,7 +8,7 @@
 
 from apps.accounting.models.invoice import Invoice
 from apps.accounting.models.quote import Quote
-from apps.company.models import ClientContact, Company
+from apps.company.models import ClientContact, Company, Person
 from apps.job.models import Job, JobEvent, JobFile
 from apps.workflow.models import XeroPayItem
 
@@ -134,6 +134,16 @@ class JobSerializer(serializers.ModelSerializer):
     contact_name = serializers.CharField(
         source="contact.name", read_only=True, required=False, allow_null=True
     )
+    person_id = serializers.PrimaryKeyRelatedField(
+        queryset=Person.objects.all(),
+        source="person",
+        write_only=False,
+        required=False,
+        allow_null=True,
+    )
+    person_name = serializers.CharField(
+        source="person.name", read_only=True, required=False, allow_null=True
+    )
     default_xero_pay_item_id = serializers.PrimaryKeyRelatedField(
         queryset=XeroPayItem.objects.all(),
         source="default_xero_pay_item",
@@ -210,6 +220,8 @@ class Meta:
             "company_name",
             "contact_id",
             "contact_name",
+            "person_id",
+            "person_name",
             "job_number",
             "notes",
             "order_number",
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 4080f97df..175f04b7a 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -1533,7 +1533,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact Method.
+          description: A UUID string identifying this Contact Method.
           required: true
       tags:
         - companies
@@ -1555,7 +1555,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact Method.
+          description: A UUID string identifying this Contact Method.
           required: true
       tags:
         - companies
@@ -1589,7 +1589,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact Method.
+          description: A UUID string identifying this Contact Method.
           required: true
       tags:
         - companies
@@ -1622,7 +1622,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact Method.
+          description: A UUID string identifying this Contact Method.
           required: true
       tags:
         - companies
@@ -1715,7 +1715,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact.
+          description: A UUID string identifying this Company Person Link.
           required: true
       tags:
         - companies
@@ -1749,7 +1749,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact.
+          description: A UUID string identifying this Company Person Link.
           required: true
       tags:
         - companies
@@ -1795,7 +1795,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact.
+          description: A UUID string identifying this Company Person Link.
           required: true
       tags:
         - companies
@@ -1840,7 +1840,7 @@ paths:
           schema:
             type: string
             format: uuid
-          description: A UUID string identifying this Client Contact.
+          description: A UUID string identifying this Company Person Link.
           required: true
       tags:
         - companies
@@ -2627,6 +2627,11 @@ paths:
           name: page_size
           schema:
             type: integer
+        - in: query
+          name: person
+          schema:
+            type: string
+            format: uuid
         - in: query
           name: q
           schema:
@@ -10191,6 +10196,10 @@ components:
           type: string
           format: uuid
           description: The company this contact belongs to
+        person:
+          type: string
+          format: uuid
+          nullable: true
         name:
           type: string
           description: Full name of the contact person
@@ -10201,6 +10210,10 @@ components:
           nullable: true
           description: Email address of the contact
           maxLength: 254
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
         position:
           type: string
           nullable: true
@@ -10262,6 +10275,10 @@ components:
         contact_name:
           type: string
           readOnly: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
         method_type:
           $ref: '#/components/schemas/MethodTypeEnum'
         value:
@@ -10275,7 +10292,6 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          default: false
         source:
           $ref: '#/components/schemas/ClientContactMethodSourceEnum'
         created_at:
@@ -10308,6 +10324,10 @@ components:
           type: string
           format: uuid
           nullable: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
         method_type:
           $ref: '#/components/schemas/MethodTypeEnum'
         value:
@@ -10319,7 +10339,6 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          default: false
         source:
           $ref: '#/components/schemas/ClientContactMethodSourceEnum'
       required:
@@ -10341,6 +10360,10 @@ components:
           type: string
           format: uuid
           description: The company this contact belongs to
+        person:
+          type: string
+          format: uuid
+          nullable: true
         name:
           type: string
           minLength: 1
@@ -10352,6 +10375,10 @@ components:
           nullable: true
           description: Email address of the contact
           maxLength: 254
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
         position:
           type: string
           nullable: true
@@ -12989,6 +13016,14 @@ components:
           type: string
           readOnly: true
           nullable: true
+        person_id:
+          type: string
+          format: uuid
+          nullable: true
+        person_name:
+          type: string
+          readOnly: true
+          nullable: true
         job_number:
           type: integer
           maximum: 2147483647
@@ -13158,6 +13193,7 @@ components:
         - latest_estimate
         - latest_quote
         - name
+        - person_name
         - quote
         - quote_sheet
         - quoted
@@ -14540,6 +14576,14 @@ components:
           type: string
           readOnly: true
           nullable: true
+        person_id:
+          type: string
+          format: uuid
+          nullable: true
+        person_name:
+          type: string
+          readOnly: true
+          nullable: true
         job_number:
           type: integer
           maximum: 2147483647
@@ -14709,6 +14753,7 @@ components:
         - latest_estimate
         - latest_quote
         - name
+        - person_name
         - quote
         - quote_sheet
         - quoted
@@ -16160,6 +16205,10 @@ components:
           type: string
           format: uuid
           nullable: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
         method_type:
           $ref: '#/components/schemas/MethodTypeEnum'
         value:
@@ -16171,7 +16220,6 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          default: false
         source:
           $ref: '#/components/schemas/ClientContactMethodSourceEnum'
     PatchedClientContactRequest:
@@ -16182,6 +16230,10 @@ components:
           type: string
           format: uuid
           description: The company this contact belongs to
+        person:
+          type: string
+          format: uuid
+          nullable: true
         name:
           type: string
           minLength: 1
@@ -16193,6 +16245,10 @@ components:
           nullable: true
           description: Email address of the contact
           maxLength: 254
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
         position:
           type: string
           nullable: true
@@ -17651,6 +17707,14 @@ components:
         contact_name:
           type: string
           readOnly: true
+        person:
+          type: string
+          format: uuid
+          readOnly: true
+          nullable: true
+        person_name:
+          type: string
+          readOnly: true
         job:
           type: string
           format: uuid
@@ -17719,6 +17783,8 @@ components:
         - origin_endpoint
         - origin_endpoint_label
         - our_number
+        - person
+        - person_name
         - provider_call_id
         - recording
         - status

From 5e1bfa8bfc5f415070518a2e67eb4286d7df6953 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 12:43:11 +1200
Subject: [PATCH 07/73] feat: complete people company cutover

---
 CLAUDE.md                                     |    4 +
 .../tests/test_sales_pipeline_service.py      |    2 +-
 apps/company/__init__.py                      |   20 +-
 .../migrations/0005_backfill_person.py        |    6 +-
 ...lter_companypersonlink_options_and_more.py |  200 +++
 apps/company/models.py                        |  162 +-
 apps/company/serializers.py                   |  179 +-
 .../company/services/company_merge_service.py |   95 +-
 apps/company/services/company_rest_service.py |  126 +-
 .../services/duplicate_phone_report.py        |   50 +-
 apps/company/tests/test_company_fts_search.py |    2 +-
 .../tests/test_company_invoice_summary.py     |    4 +-
 .../tests/test_company_merge_service.py       |  108 +-
 apps/company/tests/test_contact_methods.py    |  317 ++--
 .../tests/test_duplicate_phone_report.py      |   30 +-
 .../tests/test_get_company_for_xero.py        |    6 +-
 apps/company/tests/test_job_contact_view.py   |   68 +-
 .../tests/test_people_backfill_migration.py   |    4 -
 apps/company/urls_rest.py                     |   22 +-
 apps/company/views/__init__.py                |   12 +-
 apps/company/views/company_rest_views.py      |   72 +-
 apps/company/views/contact_method_viewset.py  |   42 +-
 apps/company/views/contact_viewset.py         |   44 +-
 ...remove_phonecallrecord_contact_and_more.py |   62 +
 apps/crm/models.py                            |   33 +-
 apps/crm/serializers.py                       |   12 +-
 apps/crm/services/phone_call_service.py       |  120 +-
 apps/crm/tests/test_phone_call_service.py     |   78 +-
 apps/crm/tests/test_phone_endpoint_guard.py   |   47 +-
 apps/crm/views/phone_call_views.py            |    9 +-
 ...005_remove_job_contact_alter_job_person.py |   51 +
 apps/job/models/job.py                        |   39 +-
 apps/job/models/job_event.py                  |    6 +-
 apps/job/serializers/job_serializer.py        |  101 +-
 apps/job/serializers/kanban_serializer.py     |   12 +-
 apps/job/services/data_integrity_service.py   |   29 +-
 apps/job/services/job_rest_service.py         |   67 +-
 apps/job/services/kanban_service.py           |   40 +-
 apps/job/services/workshop_pdf_service.py     |   53 +-
 apps/job/tests/_pdf_golden_fixtures.py        |    9 +-
 apps/job/tests/test_duplicate_phones_view.py  |   10 +-
 apps/job/tests/test_job_header_view.py        |    4 +-
 apps/job/tests/test_job_rest_service.py       |    6 +-
 apps/job/tests/test_kanban_search.py          |   25 +-
 apps/job/tests/test_kanban_service.py         |   27 +-
 apps/job/tests/test_workshop_pdf_service.py   |   33 +-
 apps/job/views/job_rest_views.py              |    8 +-
 apps/job/views/kanban_view_api.py             |    6 +-
 apps/job/views/workshop_view.py               |    6 +-
 .../services/supplier_search_service.py       |    4 +-
 .../management/commands/create_special_job.py |    1 -
 apps/workflow/api/xero/push.py                |   10 +-
 apps/workflow/api/xero/reprocess_xero.py      |  125 +-
 apps/workflow/api/xero/seed.py                |   24 +-
 apps/workflow/fixtures/company_defaults.json  |    3 -
 .../fixtures/company_defaults_prospect.json   |    3 -
 .../management/commands/e2e_cleanup.py        |  135 +-
 .../management/commands/relabel_client_app.py |    7 +-
 .../commands/seed_xero_from_database.py       |   42 +-
 ...7_rename_search_telemetry_client_domain.py |   35 +
 .../workflow/models/search_telemetry_event.py |    2 +-
 apps/workflow/services/db_scrubber.py         |   40 +-
 .../workflow/tests/test_data_versions_view.py |   17 +-
 apps/workflow/tests/test_db_scrubber.py       |    6 +-
 apps/workflow/tests/test_dev_demo_export.py   |   10 +-
 apps/workflow/tests/test_push_contacts.py     |    8 +-
 .../workflow/tests/test_relabel_client_app.py |    2 -
 apps/workflow/tests/test_search_telemetry.py  |    4 +-
 apps/workflow/tests/test_sync_clients.py      |   36 +-
 apps/workflow/views/data_versions_view.py     |    8 +-
 ...30-first-class-people-and-company-links.md |   40 +
 docs/adr/README.md                            |    1 +
 .../client_contact_management_test_plan.md    |  123 +-
 docs/urls/client.md                           |   22 +-
 docs/urls/company.md                          |    2 +-
 frontend/schema.yml                           | 1544 ++++++++---------
 frontend/src/api/generated/api.ts             |  521 +++---
 .../src/components/AdvancedSearchDialog.vue   |    6 +-
 frontend/src/components/JobCard.vue           |    6 +-
 frontend/src/components/KanbanColumn.vue      |    2 +-
 ...tionModal.vue => PersonSelectionModal.vue} |  218 +--
 ...ContactSelector.vue => PersonSelector.vue} |  224 +--
 .../__tests__/CompanyLookup.test.ts           |    2 +-
 .../src/components/board/ActiveJobCard.vue    |   10 +-
 .../src/components/crm/PhoneCallTable.vue     |    2 +-
 .../src/components/crm/PhoneNumberManager.vue |   44 +-
 .../PhoneCallTable.recording.test.ts          |    2 +-
 .../src/components/job/JobSettingsTab.vue     |  176 +-
 .../JobSettingsTab.labourRate.test.ts         |    4 +-
 .../__tests__/JobSettingsTab.urgent.test.ts   |    4 +-
 .../components/workshop/WorkshopJobHeader.vue |    4 +-
 .../__tests__/useContactManagement.test.ts    |  107 --
 .../__tests__/useOptimizedKanban.test.ts      |    8 +-
 .../__tests__/usePersonManagement.test.ts     |  109 ++
 frontend/src/composables/useCompanyLookup.ts  |   16 +-
 .../src/composables/useContactManagement.ts   |  486 ------
 frontend/src/composables/useJobAutosave.ts    |   14 +-
 .../src/composables/useJobHeaderAutosave.ts   |   16 +-
 .../src/composables/useOptimizedKanban.ts     |    2 +-
 .../src/composables/usePersonManagement.ts    |  486 ++++++
 frontend/src/constants/advanced-filters.ts    |    4 +-
 frontend/src/pages/crm/calls.vue              |   26 +-
 frontend/src/pages/crm/companies/[id].vue     |   18 +-
 frontend/src/pages/jobs/create.vue            |   68 +-
 frontend/src/pages/purchasing/po/[id].vue     |   14 +-
 .../reports/data-quality/duplicate-phones.vue |    2 +-
 frontend/src/services/job.service.ts          |    4 +-
 .../src/services/searchTelemetry.service.ts   |    2 +-
 frontend/src/stores/__tests__/jobs.test.ts    |    2 +-
 frontend/src/stores/companyStore.ts           |   16 +-
 frontend/src/stores/jobs.ts                   |    6 +-
 frontend/src/views/WorkshopKanbanView.vue     |    8 +-
 frontend/src/views/WorkshopView.vue           |   14 +-
 frontend/tests/fixtures/auth.ts               |   16 +-
 frontend/tests/fixtures/helpers.ts            |   26 +-
 .../job/create-job-with-new-company.spec.ts   |   26 +-
 frontend/tests/job/create-job.spec.ts         |   66 +-
 frontend/tests/job/edit-job-settings.spec.ts  |   24 +-
 .../timesheet/urgent-job-defaults.spec.ts     |    2 +-
 mypy-baseline.txt                             |   13 -
 120 files changed, 3816 insertions(+), 3732 deletions(-)
 create mode 100644 apps/company/migrations/0006_alter_companypersonlink_options_and_more.py
 create mode 100644 apps/crm/migrations/0006_remove_phonecallrecord_contact_and_more.py
 create mode 100644 apps/job/migrations/0005_remove_job_contact_alter_job_person.py
 create mode 100644 apps/workflow/migrations/0007_rename_search_telemetry_client_domain.py
 create mode 100644 docs/adr/0030-first-class-people-and-company-links.md
 rename frontend/src/components/{ContactSelectionModal.vue => PersonSelectionModal.vue} (77%)
 rename frontend/src/components/{ContactSelector.vue => PersonSelector.vue} (50%)
 delete mode 100644 frontend/src/composables/__tests__/useContactManagement.test.ts
 create mode 100644 frontend/src/composables/__tests__/usePersonManagement.test.ts
 delete mode 100644 frontend/src/composables/useContactManagement.ts
 create mode 100644 frontend/src/composables/usePersonManagement.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 11ab4c680..e8acea722 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -66,6 +66,10 @@ Job → CostSet (1:many) → CostLine (1:many)
 PurchaseOrder → PurchaseOrderLine → Stock → CostLine
 Staff → CostLine (time entries)
 Company → Job (1:many)
+Person → Job (1:many)
+Person → PhoneCallRecord (1:many)
+Company → CompanyPersonLink → Person
+Company/Person → ContactMethod (1:many, exactly one owner)
 ```
 
 **Key Design Patterns:**
diff --git a/apps/accounting/tests/test_sales_pipeline_service.py b/apps/accounting/tests/test_sales_pipeline_service.py
index f45f8e587..96b62b3b9 100644
--- a/apps/accounting/tests/test_sales_pipeline_service.py
+++ b/apps/accounting/tests/test_sales_pipeline_service.py
@@ -62,7 +62,7 @@ def _make_job(self, *, name: str, company: Company, created_dt: datetime) -> Job
             detail={
                 "job_name": job.name,
                 "company_name": company.name if company else "Shop Job",
-                "contact_name": None,
+                "person_name": None,
                 "initial_status": job.get_status_display(),
                 "pricing_methodology": job.get_pricing_methodology_display(),
             },
diff --git a/apps/company/__init__.py b/apps/company/__init__.py
index 0d439a388..ff7a64bd0 100644
--- a/apps/company/__init__.py
+++ b/apps/company/__init__.py
@@ -20,8 +20,6 @@
             SupplierSearchAlias,
         )
         from .serializers import (
-            ClientContactMethodSerializer,
-            ClientContactSerializer,
             CompanyCreateResponseSerializer,
             CompanyCreateSerializer,
             CompanyDetailResponseSerializer,
@@ -31,14 +29,16 @@
             CompanyJobsResponseSerializer,
             CompanyListResponseSerializer,
             CompanyNameOnlySerializer,
+            CompanyPersonLinkSerializer,
             CompanySearchResponseSerializer,
             CompanySearchResultSerializer,
             CompanySerializer,
             CompanyUpdateResponseSerializer,
             CompanyUpdateSerializer,
-            JobContactBaseSerializer,
-            JobContactResponseSerializer,
-            JobContactUpdateSerializer,
+            ContactMethodSerializer,
+            JobPersonBaseSerializer,
+            JobPersonResponseSerializer,
+            JobPersonUpdateSerializer,
             StandardErrorSerializer,
             SupplierPickupAddressSerializer,
             SupplierSearchAliasCreateSerializer,
@@ -50,8 +50,6 @@
     pass
 
 __all__ = [
-    "ClientContactMethodSerializer",
-    "ClientContactSerializer",
     "Company",
     "CompanyConfig",
     "CompanyCreateResponseSerializer",
@@ -64,6 +62,7 @@
     "CompanyListResponseSerializer",
     "CompanyNameOnlySerializer",
     "CompanyPersonLink",
+    "CompanyPersonLinkSerializer",
     "CompanyQuerySet",
     "CompanySearchResponseSerializer",
     "CompanySearchResultSerializer",
@@ -71,9 +70,10 @@
     "CompanyUpdateResponseSerializer",
     "CompanyUpdateSerializer",
     "ContactMethod",
-    "JobContactBaseSerializer",
-    "JobContactResponseSerializer",
-    "JobContactUpdateSerializer",
+    "ContactMethodSerializer",
+    "JobPersonBaseSerializer",
+    "JobPersonResponseSerializer",
+    "JobPersonUpdateSerializer",
     "Person",
     "PhoneAssignmentConflictError",
     "StandardErrorSerializer",
diff --git a/apps/company/migrations/0005_backfill_person.py b/apps/company/migrations/0005_backfill_person.py
index 32c375fb2..c52680b8a 100644
--- a/apps/company/migrations/0005_backfill_person.py
+++ b/apps/company/migrations/0005_backfill_person.py
@@ -1,9 +1,11 @@
 # Generated by Codex for KAN-278 Stage B.
 
+from typing import Any
+
 from django.db import migrations
 
 
-def forwards(apps, schema_editor):
+def forwards(apps: Any, schema_editor: Any) -> None:
     Person = apps.get_model("company", "Person")
     CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
     ContactMethod = apps.get_model("company", "ContactMethod")
@@ -41,7 +43,7 @@ def forwards(apps, schema_editor):
         call.save(update_fields=["person", "updated_at"])
 
 
-def backwards(apps, schema_editor):
+def backwards(apps: Any, schema_editor: Any) -> None:
     CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
     ContactMethod = apps.get_model("company", "ContactMethod")
     Job = apps.get_model("job", "Job")
diff --git a/apps/company/migrations/0006_alter_companypersonlink_options_and_more.py b/apps/company/migrations/0006_alter_companypersonlink_options_and_more.py
new file mode 100644
index 000000000..16146a4b9
--- /dev/null
+++ b/apps/company/migrations/0006_alter_companypersonlink_options_and_more.py
@@ -0,0 +1,200 @@
+# Generated by Django 6.0.4 on 2026-07-08 22:47
+
+from typing import Any
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+def repair_people_final_shape(apps: Any, schema_editor: Any) -> None:
+    Person = apps.get_model("company", "Person")
+    CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
+    ContactMethod = apps.get_model("company", "ContactMethod")
+
+    for link in CompanyPersonLink.objects.filter(person__isnull=True).iterator():
+        person = Person.objects.create(
+            name=link.name,
+            email=link.email,
+            is_active=link.is_active,
+        )
+        link.person = person
+        if link.xero_name is None:
+            link.xero_name = link.name
+        link.save(update_fields=["person", "xero_name"])
+
+    for method in ContactMethod.objects.filter(
+        person__isnull=True, contact__isnull=False
+    ).select_related("contact"):
+        method.person_id = method.contact.person_id
+        method.contact_id = None
+        method.save(update_fields=["person", "contact", "updated_at"])
+
+    # Collapse exact duplicates before final partial unique constraints land.
+    owner_fields = [
+        ("company_id", ContactMethod.objects.filter(company__isnull=False)),
+        ("person_id", ContactMethod.objects.filter(person__isnull=False)),
+    ]
+    for owner_field, queryset in owner_fields:
+        duplicates = (
+            queryset.values(owner_field, "method_type", "normalized_value")
+            .annotate(count=models.Count("id"))
+            .filter(count__gt=1)
+        )
+        for duplicate in duplicates:
+            matches = queryset.filter(
+                **{
+                    owner_field: duplicate[owner_field],
+                    "method_type": duplicate["method_type"],
+                    "normalized_value": duplicate["normalized_value"],
+                }
+            ).order_by("-is_primary", "created_at", "id")
+            keep = matches.first()
+            matches.exclude(pk=keep.pk).delete()
+
+        primary_duplicates = (
+            queryset.filter(is_primary=True)
+            .values(owner_field, "method_type")
+            .annotate(count=models.Count("id"))
+            .filter(count__gt=1)
+        )
+        for duplicate in primary_duplicates:
+            matches = queryset.filter(
+                **{
+                    owner_field: duplicate[owner_field],
+                    "method_type": duplicate["method_type"],
+                    "is_primary": True,
+                }
+            ).order_by("created_at", "id")
+            keep = matches.first()
+            matches.exclude(pk=keep.pk).update(is_primary=False)
+
+    missing_links = CompanyPersonLink.objects.filter(person__isnull=True).count()
+    missing_methods = ContactMethod.objects.filter(
+        person__isnull=True, contact__isnull=False
+    ).count()
+    ownerless_methods = ContactMethod.objects.filter(
+        company__isnull=True, person__isnull=True
+    ).count()
+    overowned_methods = ContactMethod.objects.filter(
+        company__isnull=False, person__isnull=False
+    ).count()
+    if missing_links or missing_methods or ownerless_methods or overowned_methods:
+        raise RuntimeError(
+            "Final people schema repair failed: "
+            f"missing_links={missing_links}, missing_methods={missing_methods}, "
+            f"ownerless_methods={ownerless_methods}, "
+            f"overowned_methods={overowned_methods}"
+        )
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0005_backfill_person"),
+    ]
+
+    operations = [
+        migrations.AlterModelOptions(
+            name="companypersonlink",
+            options={
+                "ordering": ["-is_primary", "person__name"],
+                "verbose_name": "Company Person Link",
+                "verbose_name_plural": "Company Person Links",
+            },
+        ),
+        migrations.RemoveConstraint(
+            model_name="companypersonlink",
+            name="unique_company_contact_name",
+        ),
+        migrations.RemoveField(
+            model_name="company",
+            name="additional_contact_persons",
+        ),
+        migrations.RemoveField(
+            model_name="company",
+            name="primary_contact_email",
+        ),
+        migrations.RemoveField(
+            model_name="company",
+            name="primary_contact_name",
+        ),
+        migrations.RunPython(repair_people_final_shape, migrations.RunPython.noop),
+        migrations.RemoveField(
+            model_name="contactmethod",
+            name="contact",
+        ),
+        migrations.AlterField(
+            model_name="companypersonlink",
+            name="person",
+            field=models.ForeignKey(
+                on_delete=django.db.models.deletion.CASCADE,
+                related_name="company_links",
+                to="company.person",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="companypersonlink",
+            constraint=models.UniqueConstraint(
+                fields=("company", "person"), name="unique_company_person_link"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="companypersonlink",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("xero_name__isnull", False)),
+                fields=("company", "xero_name"),
+                name="unique_company_person_link_xero_name",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="contactmethod",
+            constraint=models.CheckConstraint(
+                condition=models.Q(
+                    models.Q(("company__isnull", False), ("person__isnull", True)),
+                    models.Q(("company__isnull", True), ("person__isnull", False)),
+                    _connector="OR",
+                ),
+                name="contact_method_one_owner",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="contactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("company__isnull", False)),
+                fields=("company", "method_type", "normalized_value"),
+                name="unique_company_contact_method_value",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="contactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("person__isnull", False)),
+                fields=("person", "method_type", "normalized_value"),
+                name="unique_person_contact_method_value",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="contactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("company__isnull", False), ("is_primary", True)),
+                fields=("company", "method_type"),
+                name="unique_company_primary_contact_method",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="contactmethod",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("is_primary", True), ("person__isnull", False)),
+                fields=("person", "method_type"),
+                name="unique_person_primary_contact_method",
+            ),
+        ),
+        migrations.RemoveField(
+            model_name="companypersonlink",
+            name="email",
+        ),
+        migrations.RemoveField(
+            model_name="companypersonlink",
+            name="name",
+        ),
+    ]
diff --git a/apps/company/models.py b/apps/company/models.py
index 2c66c1e9c..a1a79d5c3 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -67,9 +67,6 @@ class Company(models.Model):
         "allow_jobs",
         "xero_contact_id",
         "xero_tenant_id",
-        "primary_contact_name",
-        "primary_contact_email",
-        "additional_contact_persons",
         "xero_last_modified",
         "xero_last_synced",
         "xero_archived",
@@ -110,13 +107,6 @@ class Company(models.Model):
         null=True, blank=True
     )  # For debugging, stores the raw JSON from Xero
 
-    # Fields for the primary contact person
-    primary_contact_name = models.CharField(max_length=255, null=True, blank=True)
-    primary_contact_email = models.EmailField(null=True, blank=True)
-
-    # Store all contact persons from the Xero ContactPersons list
-    additional_contact_persons = models.JSONField(null=True, blank=True, default=list)
-
     django_created_at = models.DateTimeField(auto_now_add=True)
     django_updated_at = models.DateTimeField(auto_now=True)
 
@@ -249,12 +239,10 @@ def primary_phone_value(self) -> str:
         """The company's own primary phone number, or "" when it has none.
 
         Single-object flows only (Xero sync, PO PDFs). Queryset consumers must
-        use ClientContactMethod.primary_phone_annotation instead.
+        use ContactMethod.primary_phone_annotation instead.
         """
         method = (
-            self.contact_methods.filter(
-                method_type=ClientContactMethod.MethodType.PHONE
-            )
+            self.contact_methods.filter(method_type=ContactMethod.MethodType.PHONE)
             .order_by(*PRIMARY_PHONE_ORDERING)
             .first()
         )
@@ -323,28 +311,12 @@ def save(
 
 
 class CompanyPersonLink(models.Model):
-    """
-    Represents a contact person for a company.
-    This model stores contact information that was previously synced with Xero
-    but is now managed entirely within our application.
-    """
+    """A person's role/relationship at a company."""
 
-    # CHECKLIST - when adding a new field or property to ClientContact, check these locations:
-    #   1. CLIENTCONTACT_API_FIELDS or CLIENTCONTACT_INTERNAL_FIELDS below (if it's a model field)
-    #   2. ClientContactSerializer in apps/company/serializers.py (uses CLIENTCONTACT_API_FIELDS)
-    #   3. ClientContactSerializer.to_internal_value() nullable_fields list (converts "" → None)
-    #   4. JobContactResponseSerializer in apps/company/serializers.py (subset for job context)
-    #   5. ClientContactViewSet in apps/company/views/contact_viewset.py (CRUD operations)
-    #   6. Job.contact FK in apps/job/models/job.py (relationship to ClientContact)
-    #   7. reprocess_xero.py in apps/workflow/api/xero/ (Xero sync creates contacts)
-    #
-    # Database fields exposed via API serializers
-    CLIENTCONTACT_API_FIELDS = [
+    COMPANYPERSONLINK_API_FIELDS = [
         "id",
         "company",
         "person",
-        "name",
-        "email",
         "xero_name",
         "position",
         "is_primary",
@@ -354,11 +326,10 @@ class CompanyPersonLink(models.Model):
         "updated_at",
     ]
 
-    # No internal fields for ClientContact - all fields are exposed
-    CLIENTCONTACT_INTERNAL_FIELDS = []
-
-    # All ClientContact model fields (derived)
-    CLIENTCONTACT_ALL_FIELDS = CLIENTCONTACT_API_FIELDS + CLIENTCONTACT_INTERNAL_FIELDS
+    COMPANYPERSONLINK_INTERNAL_FIELDS: list[str] = []
+    COMPANYPERSONLINK_ALL_FIELDS = (
+        COMPANYPERSONLINK_API_FIELDS + COMPANYPERSONLINK_INTERNAL_FIELDS
+    )
 
     id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
     company = models.ForeignKey(
@@ -370,14 +341,8 @@ class CompanyPersonLink(models.Model):
     person = models.ForeignKey(
         Person,
         on_delete=models.CASCADE,
-        null=True,
-        blank=True,
         related_name="company_links",
     )
-    name = models.CharField(max_length=255, help_text="Full name of the contact person")
-    email = models.EmailField(
-        null=True, blank=True, help_text="Email address of the contact"
-    )
     xero_name = models.CharField(max_length=255, null=True, blank=True)
     position = models.CharField(
         max_length=255,
@@ -400,18 +365,23 @@ class CompanyPersonLink(models.Model):
     updated_at = models.DateTimeField(auto_now=True)
 
     class Meta:
-        ordering = ["-is_primary", "name"]
+        ordering = ["-is_primary", "person__name"]
         verbose_name = "Company Person Link"
         verbose_name_plural = "Company Person Links"
         constraints = [
             models.UniqueConstraint(
-                fields=["company", "name"],
-                name="unique_company_contact_name",
+                fields=["company", "person"],
+                name="unique_company_person_link",
+            ),
+            models.UniqueConstraint(
+                fields=["company", "xero_name"],
+                condition=models.Q(xero_name__isnull=False),
+                name="unique_company_person_link_xero_name",
             ),
         ]
 
     def __str__(self):
-        return f"{self.name} ({self.company.name})"
+        return f"{self.person.name} ({self.company.name})"
 
     def save(
         self,
@@ -422,18 +392,7 @@ def save(
         update_fields: Iterable[str] | None = None,
     ) -> None:
         update_fields = _augment_update_fields(update_fields, "updated_at")
-        if self.person_id is None:
-            self.person = Person.objects.create(
-                name=self.name,
-                email=self.email,
-                is_active=self.is_active,
-            )
-            update_fields = _augment_update_fields(update_fields, "person")
-        if self.xero_name is None:
-            self.xero_name = self.name
-            update_fields = _augment_update_fields(update_fields, "xero_name")
-
-        # If this contact is being set as primary, ensure no other contacts
+        # If this link is being set as primary, ensure no other links
         # for this company are marked as primary
         if self.is_primary:
             CompanyPersonLink.objects.filter(
@@ -448,14 +407,14 @@ def save(
 
 
 class PhoneAssignmentConflictError(Exception):
-    """A phone number cannot be assigned to the proposed company/contact owner.
+    """A phone number cannot be assigned to the proposed company/person owner.
 
-    ``conflict`` is the existing :class:`ClientContactMethod` owned by a
+    ``conflict`` is the existing :class:`ContactMethod` owned by a
     different effective company, or ``None`` when the number is an active
     internal :class:`~apps.crm.models.PhoneEndpoint`.
     """
 
-    def __init__(self, conflict: "ClientContactMethod | None") -> None:
+    def __init__(self, conflict: "ContactMethod | None") -> None:
         self.conflict = conflict
         if conflict is None:
             message = "phone number is an active internal phone endpoint"
@@ -468,11 +427,11 @@ def __init__(self, conflict: "ClientContactMethod | None") -> None:
 # stable tie-break. Single source — every primary-phone consumer must use it.
 PRIMARY_PHONE_ORDERING: Final[tuple[str, str, str]] = ("-is_primary", "label", "value")
 
-PhoneOwner = Literal["company", "contact", "person"]
+PhoneOwner = Literal["company", "person"]
 
 
 class ContactMethod(models.Model):
-    """Phone or email address owned by a company or one of its contacts."""
+    """Phone or email address owned by a company or person."""
 
     class MethodType(models.TextChoices):
         PHONE = "phone", "Phone"
@@ -490,13 +449,6 @@ class Source(models.TextChoices):
         blank=True,
         related_name="contact_methods",
     )
-    contact = models.ForeignKey(
-        CompanyPersonLink,
-        on_delete=models.CASCADE,
-        null=True,
-        blank=True,
-        related_name="contact_methods",
-    )
     person = models.ForeignKey(
         Person,
         on_delete=models.CASCADE,
@@ -521,10 +473,38 @@ class Meta:
         ordering = ["method_type", "-is_primary", "label", "value"]
         verbose_name = "Contact Method"
         verbose_name_plural = "Contact Methods"
-        constraints: list[models.BaseConstraint] = []
+        constraints = [
+            models.CheckConstraint(
+                condition=(
+                    models.Q(company__isnull=False, person__isnull=True)
+                    | models.Q(company__isnull=True, person__isnull=False)
+                ),
+                name="contact_method_one_owner",
+            ),
+            models.UniqueConstraint(
+                fields=["company", "method_type", "normalized_value"],
+                condition=models.Q(company__isnull=False),
+                name="unique_company_contact_method_value",
+            ),
+            models.UniqueConstraint(
+                fields=["person", "method_type", "normalized_value"],
+                condition=models.Q(person__isnull=False),
+                name="unique_person_contact_method_value",
+            ),
+            models.UniqueConstraint(
+                fields=["company", "method_type"],
+                condition=models.Q(company__isnull=False, is_primary=True),
+                name="unique_company_primary_contact_method",
+            ),
+            models.UniqueConstraint(
+                fields=["person", "method_type"],
+                condition=models.Q(person__isnull=False, is_primary=True),
+                name="unique_person_primary_contact_method",
+            ),
+        ]
 
     def __str__(self) -> str:
-        owner = self.person or self.contact or self.company
+        owner = self.person or self.company
         return f"{self.method_type}: {self.value} ({owner})"
 
     @classmethod
@@ -549,13 +529,10 @@ def primary_phone_annotation(cls, *, owner: PhoneOwner, outer_ref: str) -> Coale
 
     @classmethod
     def primary_phone_for_link_annotation(cls) -> Coalesce:
-        """Primary phone for a company-person link during contact→person migration."""
+        """Primary phone for a company-person link."""
         candidates = (
             cls.objects.filter(method_type=cls.MethodType.PHONE)
-            .filter(
-                models.Q(person=models.OuterRef("person_id"))
-                | models.Q(contact=models.OuterRef("pk"))
-            )
+            .filter(person=models.OuterRef("person_id"))
             .order_by(*PRIMARY_PHONE_ORDERING)
             .values("value")[:1]
         )
@@ -587,7 +564,6 @@ def save(
                 type(self).check_phone_assignment(
                     self.normalized_value,
                     company_id=self.company_id,
-                    contact=self.contact,
                     person=self.person,
                     instance=self,
                     using=db,
@@ -614,12 +590,8 @@ def save(
             )
             if self.person_id:
                 queryset = queryset.filter(person_id=self.person_id)
-            elif self.contact_id:
-                queryset = queryset.filter(contact_id=self.contact_id)
             else:
-                queryset = queryset.filter(
-                    company_id=self.company_id, contact__isnull=True
-                )
+                queryset = queryset.filter(company_id=self.company_id)
             queryset.update(is_primary=False)
 
         super().save(
@@ -663,8 +635,6 @@ def owner_company_ids(self) -> set[uuid.UUID]:
             return {self.company_id}
         if self.person is not None:
             return set(self.person.company_links.values_list("company_id", flat=True))
-        if self.contact is not None:
-            return {self.contact.company_id}
         return set()
 
     @classmethod
@@ -683,7 +653,7 @@ def conflicting_company(
         """
         queryset = (
             cls.objects.using(using)
-            .select_related("company", "contact")
+            .select_related("company", "person")
             .filter(
                 method_type=cls.MethodType.PHONE,
                 normalized_value=normalized_value,
@@ -706,7 +676,6 @@ def check_phone_assignment(
         normalized_value: str,
         *,
         company_id: uuid.UUID | None,
-        contact: "CompanyPersonLink | None",
         person: "Person | None" = None,
         instance: "ContactMethod | None" = None,
         using: str = DEFAULT_DB_ALIAS,
@@ -728,20 +697,18 @@ def check_phone_assignment(
             PhoneAssignmentConflictError: carrying the conflicting method, or
                 ``conflict=None`` for an internal-endpoint collision.
         """
-        contact_id = contact.pk if contact is not None else None
         person_id = person.pk if person is not None else None
         if instance is not None and not instance._state.adding:
             stored = (
                 cls.objects.using(using)
                 .filter(pk=instance.pk)
-                .values("normalized_value", "company_id", "contact_id", "person_id")
+                .values("normalized_value", "company_id", "person_id")
                 .first()
             )
             if (
                 stored is not None
                 and stored["normalized_value"] == normalized_value
                 and stored["company_id"] == company_id
-                and stored["contact_id"] == contact_id
                 and stored["person_id"] == person_id
             ):
                 return  # unchanged association -> grandfathered
@@ -757,11 +724,11 @@ def check_phone_assignment(
 
         if company_id is not None:
             effective_company_ids = {company_id}
-        elif contact is not None:
-            effective_company_ids = {contact.company_id}
         elif person is not None:
             effective_company_ids = set(
-                person.company_links.using(using).values_list("company_id", flat=True)
+                CompanyPersonLink.objects.using(using)
+                .filter(person_id=person.pk)
+                .values_list("company_id", flat=True)
             )
         else:
             effective_company_ids = set()
@@ -775,8 +742,6 @@ def check_phone_assignment(
             raise PhoneAssignmentConflictError(conflict)
 
     def owner_display_name(self) -> str:
-        if self.contact:
-            return f"contact {self.contact.name} at {self.contact.company.name}"
         if self.person:
             return f"person {self.person.name}"
         if self.company:
@@ -784,11 +749,6 @@ def owner_display_name(self) -> str:
         return "another CRM owner"
 
 
-# Temporary import aliases while consumers are moved to person naming.
-ClientContact = CompanyPersonLink
-ClientContactMethod = ContactMethod
-
-
 class Supplier(Company):
     """
     A Supplier is simply a Company with additional semantics.
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index f57c0128e..9211d01d9 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -5,9 +5,9 @@
 from rest_framework import serializers
 
 from apps.company.models import (
-    ClientContact,
-    ClientContactMethod,
     Company,
+    CompanyPersonLink,
+    ContactMethod,
     Person,
     PhoneAssignmentConflictError,
     SupplierPickupAddress,
@@ -15,7 +15,7 @@
 )
 
 
-def set_primary_phone(owner: Company | ClientContact | Person, raw_value: str) -> None:
+def set_primary_phone(owner: Company | Person, raw_value: str) -> None:
     """Point the owner's primary phone at ``raw_value`` (non-blank).
 
     Reuses an existing method carrying the same normalized number (promoting
@@ -30,16 +30,14 @@ def set_primary_phone(owner: Company | ClientContact | Person, raw_value: str) -
     value = raw_value.strip()
     if isinstance(owner, Company):
         owner_field = "company"
-    elif isinstance(owner, Person):
-        owner_field = "person"
     else:
-        owner_field = "contact"
-    phone_methods = ClientContactMethod.objects.filter(
-        method_type=ClientContactMethod.MethodType.PHONE, **{owner_field: owner}
+        owner_field = "person"
+    phone_methods = ContactMethod.objects.filter(
+        method_type=ContactMethod.MethodType.PHONE, **{owner_field: owner}
     )
     old_primary = phone_methods.filter(is_primary=True).first()
     old_number = old_primary.normalized_value if old_primary else ""
-    normalized_value = ClientContactMethod.normalize_phone(value)
+    normalized_value = ContactMethod.normalize_phone(value)
     if not normalized_value:
         raise DjangoValidationError("Phone number must contain at least one digit")
 
@@ -55,14 +53,11 @@ def set_primary_phone(owner: Company | ClientContact | Person, raw_value: str) -
         old_primary.save()
         method = old_primary
     else:
-        create_kwargs = {owner_field: owner}
-        if isinstance(owner, ClientContact) and owner.person_id:
-            create_kwargs["person"] = owner.person
-        method = ClientContactMethod.objects.create(
-            method_type=ClientContactMethod.MethodType.PHONE,
+        method = ContactMethod.objects.create(
+            method_type=ContactMethod.MethodType.PHONE,
             value=value,
             is_primary=True,
-            **create_kwargs,
+            **{owner_field: owner},
         )
 
     numbers = sorted(
@@ -71,24 +66,43 @@ def set_primary_phone(owner: Company | ClientContact | Person, raw_value: str) -
     transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
 
 
-class ClientContactSerializer(serializers.ModelSerializer):
-    """Serializer for ClientContact model."""
+class CompanyPersonLinkSerializer(serializers.ModelSerializer):
+    """Serializer for a person's relationship to a company."""
 
-    # Backed by ClientContactMethod: reads come from the viewset's
+    person = serializers.UUIDField(source="person_id", read_only=True)
+    person_name = serializers.CharField(source="person.name")
+    person_email = serializers.EmailField(
+        source="person.email", required=False, allow_blank=True, allow_null=True
+    )
+    # Backed by ContactMethod: reads come from the viewset's
     # primary_phone_annotation; writes upsert the contact's primary method.
     phone = serializers.CharField(
         required=False, allow_blank=True, allow_null=True, default=""
     )
 
     class Meta:
-        model = ClientContact
-        fields = ClientContact.CLIENTCONTACT_API_FIELDS + ["phone"]
+        model = CompanyPersonLink
+        fields = [
+            "id",
+            "company",
+            "person",
+            "person_name",
+            "person_email",
+            "xero_name",
+            "position",
+            "is_primary",
+            "notes",
+            "is_active",
+            "created_at",
+            "updated_at",
+            "phone",
+        ]
         read_only_fields = ["id", "is_active", "created_at", "updated_at"]
 
     def to_internal_value(self, data: Any) -> Any:
         """Convert empty strings to None for nullable fields before validation."""
         # Fields that should be NULL instead of empty string
-        nullable_fields = ["email", "position", "notes"]
+        nullable_fields = ["person_email", "position", "notes"]
 
         for field in nullable_fields:
             if field in data and data[field] == "":
@@ -98,71 +112,75 @@ def to_internal_value(self, data: Any) -> Any:
 
     def create(self, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
+        person_value = validated_data.pop("person", None)
         with transaction.atomic():
-            person = Person.objects.create(
-                name=validated_data["name"],
-                email=validated_data.get("email"),
-                is_active=validated_data.get("is_active", True),
-            )
-            validated_data["person"] = person
-            validated_data["xero_name"] = validated_data["name"]
-            contact = super().create(validated_data)
-            return self._apply_phone(contact, raw_phone)
+            if isinstance(person_value, dict):
+                person = Person.objects.create(
+                    name=person_value["name"],
+                    email=person_value.get("email"),
+                    is_active=validated_data.get("is_active", True),
+                )
+                validated_data["person"] = person
+            else:
+                raise serializers.ValidationError(
+                    {"person_name": "This field is required."}
+                )
+            if validated_data.get("xero_name") is None:
+                validated_data["xero_name"] = person.name
+            link = super().create(validated_data)
+            return self._apply_phone(link, raw_phone)
 
     def update(self, instance, validated_data):
         raw_phone = validated_data.pop("phone", None)  # not a model field
+        person_data = validated_data.pop("person", None)
         with transaction.atomic():
-            contact = super().update(instance, validated_data)
-            if contact.person_id:
+            link = super().update(instance, validated_data)
+            if isinstance(person_data, dict):
                 person_update_fields = ["updated_at"]
-                if "name" in validated_data:
-                    contact.person.name = contact.name
+                if "name" in person_data:
+                    link.person.name = person_data["name"]
                     person_update_fields.append("name")
-                if "email" in validated_data:
-                    contact.person.email = contact.email
+                if "email" in person_data:
+                    link.person.email = person_data["email"]
                     person_update_fields.append("email")
-                if "is_active" in validated_data:
-                    contact.person.is_active = contact.is_active
-                    person_update_fields.append("is_active")
-                contact.person.save(update_fields=person_update_fields)
-            return self._apply_phone(contact, raw_phone)
+                link.person.save(update_fields=person_update_fields)
+            return self._apply_phone(link, raw_phone)
 
     def _apply_phone(
-        self, contact: ClientContact, raw_phone: str | None
-    ) -> ClientContact:
+        self, link: CompanyPersonLink, raw_phone: str | None
+    ) -> CompanyPersonLink:
         """Upsert the primary phone; blank/omitted input is a no-op (deleting
         numbers is PhoneNumberManager's job, not this form's)."""
         if raw_phone and raw_phone.strip():
             try:
-                set_primary_phone(contact, raw_phone)
+                set_primary_phone(link.person, raw_phone)
             except DjangoValidationError as exc:
                 raise serializers.ValidationError({"phone": exc.messages}) from exc
         else:
             pass  # blank phone: leave existing contact methods untouched
         # The phone field always reads from a queryset annotation; give the
         # write response the same shape by re-fetching through it.
-        return ClientContact.objects.annotate(
-            phone=ClientContactMethod.primary_phone_for_link_annotation()
-        ).get(pk=contact.pk)
+        return CompanyPersonLink.objects.annotate(
+            phone=ContactMethod.primary_phone_for_link_annotation()
+        ).get(pk=link.pk)
 
 
-class ClientContactMethodSerializer(serializers.ModelSerializer):
-    """Serializer for canonical company/contact phone and email methods."""
+class ContactMethodSerializer(serializers.ModelSerializer):
+    """Serializer for canonical company/person phone and email methods."""
 
     owner_company = serializers.SerializerMethodField()
     company_name = serializers.SerializerMethodField()
-    contact_name = serializers.SerializerMethodField()
+    person_name = serializers.SerializerMethodField()
 
     class Meta:
-        model = ClientContactMethod
+        model = ContactMethod
         fields = [
             "id",
             "company",
             "owner_company",
             "company_name",
-            "contact",
-            "contact_name",
             "person",
+            "person_name",
             "method_type",
             "value",
             "normalized_value",
@@ -176,55 +194,56 @@ class Meta:
             "id",
             "owner_company",
             "company_name",
-            "contact_name",
+            "person_name",
             "normalized_value",
             "created_at",
             "updated_at",
         ]
 
-    def get_owner_company(self, obj: ClientContactMethod) -> str:
+    def get_owner_company(self, obj: ContactMethod) -> str:
         if obj.company_id:
             return str(obj.company_id)
         if obj.person_id:
             company_id = obj.owner_company_id()
             return str(company_id) if company_id else ""
-        return str(obj.contact.company_id) if obj.contact else ""
+        return ""
 
-    def get_company_name(self, obj: ClientContactMethod) -> str:
+    def get_company_name(self, obj: ContactMethod) -> str:
         if obj.company:
             return obj.company.name
         if obj.person_id:
+            person = obj.person
+            if person is None:
+                raise RuntimeError(f"Contact method {obj.id} has no person")
             link = (
-                obj.person.company_links.select_related("company")
+                person.company_links.select_related("company")
                 .order_by("-is_primary", "company__name")
                 .first()
             )
             return link.company.name if link else ""
-        return obj.contact.company.name if obj.contact else ""
+        return ""
 
-    def get_contact_name(self, obj: ClientContactMethod) -> str:
-        return obj.contact.name if obj.contact else ""
+    def get_person_name(self, obj: ContactMethod) -> str:
+        return obj.person.name if obj.person else ""
 
     def validate(self, attrs: dict[str, Any]) -> dict[str, Any]:
         company = attrs.get("company", getattr(self.instance, "company", None))
-        contact = attrs.get("contact", getattr(self.instance, "contact", None))
         person = attrs.get("person", getattr(self.instance, "person", None))
-        owner_count = sum(1 for owner in (company, contact, person) if owner)
+        owner_count = sum(1 for owner in (company, person) if owner)
         if owner_count != 1:
             raise serializers.ValidationError(
-                "Exactly one of company, contact, or person is required"
+                "Exactly one of company or person is required"
             )
         method_type = attrs.get(
             "method_type", getattr(self.instance, "method_type", None)
         )
         value = attrs.get("value", getattr(self.instance, "value", None))
-        if method_type == ClientContactMethod.MethodType.PHONE:
-            normalized = ClientContactMethod.normalize_phone(value)
+        if method_type == ContactMethod.MethodType.PHONE:
+            normalized = ContactMethod.normalize_phone(value)
             try:
-                ClientContactMethod.check_phone_assignment(
+                ContactMethod.check_phone_assignment(
                     normalized,
                     company_id=company.id if company else None,
-                    contact=contact,
                     person=person,
                     instance=self.instance,
                 )
@@ -285,7 +304,7 @@ def to_internal_value(self, data: Any) -> Any:
 
 
 class CompanySerializer(serializers.ModelSerializer):
-    contacts = ClientContactSerializer(many=True, read_only=True)
+    contacts = CompanyPersonLinkSerializer(many=True, read_only=True)
 
     class Meta:
         model = Company
@@ -376,7 +395,7 @@ class CompanyCreateSerializer(serializers.Serializer):
 
     name = serializers.CharField(max_length=255)
     email = serializers.EmailField(required=False, allow_blank=True, allow_null=True)
-    # Stored as the client's primary ClientContactMethod, not a Client column
+    # Stored as the client's primary ContactMethod, not a Client column
     phone = serializers.CharField(required=False, allow_blank=True, allow_null=True)
     address = serializers.CharField(required=False, allow_blank=True, allow_null=True)
     is_account_customer = serializers.BooleanField(default=True)
@@ -420,9 +439,6 @@ class CompanyDetailResponseSerializer(serializers.Serializer):
     allow_jobs = serializers.BooleanField()
     xero_contact_id = serializers.CharField(allow_blank=True)
     xero_tenant_id = serializers.CharField(allow_blank=True)
-    primary_contact_name = serializers.CharField(allow_blank=True)
-    primary_contact_email = serializers.CharField(allow_blank=True)
-    additional_contact_persons = serializers.ListField(required=False)
     xero_last_modified = serializers.DateTimeField(allow_null=True)
     xero_last_synced = serializers.DateTimeField(allow_null=True)
     xero_archived = serializers.BooleanField()
@@ -440,7 +456,7 @@ class CompanyUpdateSerializer(serializers.Serializer):
 
     name = serializers.CharField(max_length=255, required=False)
     email = serializers.EmailField(required=False, allow_blank=True)
-    # Stored as the client's primary ClientContactMethod, not a Client column
+    # Stored as the client's primary ContactMethod, not a Client column
     phone = serializers.CharField(required=False, allow_blank=True, allow_null=True)
     address = serializers.CharField(required=False, allow_blank=True)
     is_account_customer = serializers.BooleanField(required=False)
@@ -455,23 +471,20 @@ class CompanyUpdateResponseSerializer(serializers.Serializer):
     message = serializers.CharField()
 
 
-class JobContactBaseSerializer(serializers.Serializer):
-    """Fields shared by the job contact response and update serializers."""
+class JobPersonBaseSerializer(serializers.Serializer):
+    """Fields shared by the job person response and update serializers."""
 
     id = serializers.UUIDField()
     name = serializers.CharField()
     email = serializers.CharField(allow_blank=True, allow_null=True)
-    position = serializers.CharField(allow_blank=True, allow_null=True)
-    is_primary = serializers.BooleanField()
-    notes = serializers.CharField(allow_blank=True, allow_null=True)
 
 
-class JobContactResponseSerializer(JobContactBaseSerializer):
-    """Serializer for job contact information response"""
+class JobPersonResponseSerializer(JobPersonBaseSerializer):
+    """Serializer for job person information response"""
 
 
-class JobContactUpdateSerializer(JobContactBaseSerializer):
-    """Serializer for job contact update request"""
+class JobPersonUpdateSerializer(JobPersonBaseSerializer):
+    """Serializer for job person update request"""
 
 
 class CompanyJobHeaderSerializer(serializers.Serializer):
diff --git a/apps/company/services/company_merge_service.py b/apps/company/services/company_merge_service.py
index bff80d6ca..04c535421 100644
--- a/apps/company/services/company_merge_service.py
+++ b/apps/company/services/company_merge_service.py
@@ -17,33 +17,17 @@
 from django.db import transaction
 from django.utils import timezone
 
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod
 from apps.workflow.services.error_persistence import persist_app_error
 
 logger = logging.getLogger("xero")
 
 
-def _move_contact_methods(
-    *,
-    source_contact: ClientContact | None,
-    source_company: Company | None,
-    destination_contact: ClientContact | None,
-    destination_company: Company | None,
-) -> int:
-    if source_contact is None:
-        source_queryset = ClientContactMethod.objects.filter(
-            company=source_company,
-            contact__isnull=True,
-        )
-        destination_queryset = ClientContactMethod.objects.filter(
-            company=destination_company,
-            contact__isnull=True,
-        )
-    else:
-        source_queryset = ClientContactMethod.objects.filter(contact=source_contact)
-        destination_queryset = ClientContactMethod.objects.filter(
-            contact=destination_contact
-        )
+def _move_company_contact_methods(source: Company, destination: Company) -> int:
+    """Move only company-owned methods during a company merge."""
+
+    source_queryset = ContactMethod.objects.filter(company=source)
+    destination_queryset = ContactMethod.objects.filter(company=destination)
 
     affected = 0
 
@@ -60,11 +44,11 @@ def _move_contact_methods(
         if (method_type, normalized_value) in destination_pairs
     ]
     if duplicate_ids:
-        ClientContactMethod.objects.filter(id__in=duplicate_ids).delete()
+        ContactMethod.objects.filter(id__in=duplicate_ids).delete()
         affected += len(duplicate_ids)
 
     # A moving primary method wins over the destination's existing primary of
-    # the same method_type (mirrors ClientContactMethod.save()'s demotion),
+    # the same method_type (mirrors ContactMethod.save()'s demotion),
     # keeping the partial unique constraints on (owner, method_type, is_primary)
     # satisfied.
     moving_primary_types = list(
@@ -76,24 +60,16 @@ def _move_contact_methods(
             is_primary=True,
         ).update(is_primary=False)
 
-    # queryset.update() bypasses ClientContactMethod.save()'s
+    # queryset.update() bypasses ContactMethod.save()'s
     # one-number-one-company guard DELIBERATELY: a merge moves ALL of the
     # source's methods to the destination, so any cross-company sharing the
     # guard would flag (e.g. the company-level/contact-level twins migration
     # 0023 created) already existed before the merge — the move creates no
     # new conflicting ownership.
-    if destination_contact is None:
-        affected += source_queryset.update(
-            company=destination_company,
-            contact=None,
-            updated_at=timezone.now(),
-        )
-    else:
-        affected += source_queryset.update(
-            company=None,
-            contact=destination_contact,
-            updated_at=timezone.now(),
-        )
+    affected += source_queryset.update(
+        company=destination,
+        updated_at=timezone.now(),
+    )
     return affected
 
 
@@ -110,37 +86,34 @@ def _move_company_contacts_and_methods(
         "phone_calls": 0,
     }
 
-    counts["contact_methods"] += _move_contact_methods(
-        source_contact=None,
-        source_company=source,
-        destination_contact=None,
-        destination_company=destination,
-    )
+    counts["contact_methods"] += _move_company_contact_methods(source, destination)
 
-    destination_contacts_by_name = {
-        existing.name: existing
-        for existing in ClientContact.objects.filter(company=destination)
+    destination_links_by_person = {
+        existing.person_id: existing
+        for existing in CompanyPersonLink.objects.filter(company=destination)
     }
-    for contact in ClientContact.objects.filter(company=source).iterator():
-        destination_contact = destination_contacts_by_name.get(contact.name)
-        if destination_contact is None:
-            contact.company = destination
-            contact.save(update_fields=["company", "updated_at"])
-            destination_contact = contact
+    for link in CompanyPersonLink.objects.filter(company=source).iterator():
+        destination_link = destination_links_by_person.get(link.person_id)
+        if destination_link is None:
+            if (
+                link.xero_name is not None
+                and CompanyPersonLink.objects.filter(
+                    company=destination,
+                    xero_name=link.xero_name,
+                ).exists()
+            ):
+                link.xero_name = None
+            link.company = destination
+            link.save(update_fields=["company", "xero_name", "updated_at"])
+            destination_links_by_person[link.person_id] = link
         else:
-            counts["contact_methods"] += _move_contact_methods(
-                source_contact=contact,
-                source_company=None,
-                destination_contact=destination_contact,
-                destination_company=None,
-            )
             counts["phone_calls"] += PhoneCallRecord.objects.filter(
-                contact=contact
+                person=link.person,
+                company=source,
             ).update(
                 company=destination,
-                contact=destination_contact,
             )
-            contact.delete()
+            link.delete()
 
         counts["contacts"] += 1
 
diff --git a/apps/company/services/company_rest_service.py b/apps/company/services/company_rest_service.py
index 3e7316cd8..d20348aa4 100644
--- a/apps/company/services/company_rest_service.py
+++ b/apps/company/services/company_rest_service.py
@@ -25,9 +25,8 @@
 
 from apps.company.models import (
     PRIMARY_PHONE_ORDERING,
-    ClientContact,
-    ClientContactMethod,
     Company,
+    ContactMethod,
 )
 from apps.company.serializers import (
     CompanyCreateSerializer,
@@ -164,7 +163,7 @@ def list_companies(
                 Company.objects.with_invoice_summary()
                 .defer("raw_json")
                 .annotate(
-                    phone=ClientContactMethod.primary_phone_annotation(
+                    phone=ContactMethod.primary_phone_annotation(
                         owner="company", outer_ref="pk"
                     )
                 )
@@ -231,7 +230,7 @@ def get_company_by_id(company_id: UUID) -> Dict[str, Any]:
             company = (
                 Company.objects.with_invoice_summary()
                 .annotate(
-                    phone=ClientContactMethod.primary_phone_annotation(
+                    phone=ContactMethod.primary_phone_annotation(
                         owner="company", outer_ref="pk"
                     )
                 )
@@ -334,7 +333,7 @@ def update_company(
                 raise ValueError("; ".join(error_messages))
 
             validated_data = serializer.validated_data
-            # Stored as the company's primary ClientContactMethod, not a Company
+            # Stored as the company's primary ContactMethod, not a Company
             # field, so it never reaches the generic setattr loop below.
             phone_supplied = "phone" in validated_data
             phone = validated_data.pop("phone", None)
@@ -401,7 +400,7 @@ def update_company(
             updated_with_phone: _AnnotatedCompanyWithPhone = (
                 Company.objects.with_invoice_summary()
                 .annotate(
-                    phone=ClientContactMethod.primary_phone_annotation(
+                    phone=ContactMethod.primary_phone_annotation(
                         owner="company", outer_ref="pk"
                     )
                 )
@@ -438,17 +437,20 @@ def get_company_contacts(company_id: UUID) -> List[Dict[str, Any]]:
         """
         try:
             company = get_object_or_404(Company, id=company_id)
-            contacts = company.contacts.all().order_by("name")
+            links = (
+                company.contacts.select_related("person").all().order_by("person__name")
+            )
 
             return [
                 {
-                    "id": str(contact.id),
-                    "name": contact.name,
-                    "email": contact.email,
-                    "position": contact.position,
-                    "is_primary": contact.is_primary,
+                    "id": str(link.id),
+                    "person": str(link.person_id),
+                    "person_name": link.person.name,
+                    "person_email": link.person.email,
+                    "position": link.position,
+                    "is_primary": link.is_primary,
                 }
-                for contact in contacts
+                for link in links
             ]
 
         except AlreadyLoggedException:
@@ -463,24 +465,24 @@ def get_company_contacts(company_id: UUID) -> List[Dict[str, Any]]:
             )
 
     @staticmethod
-    def get_job_contact(job_id: UUID) -> Dict[str, Any]:
+    def get_job_person(job_id: UUID) -> Dict[str, Any]:
         """
-        Retrieves contact information for a specific job.
+        Retrieves person information for a specific job.
 
         Args:
             job_id: Job UUID
 
         Returns:
-            Dict with contact information
+            Dict with person information
 
         Raises:
-            ValueError: If job not found or no contact associated
+            ValueError: If job not found or no person associated
         """
         # Import here to avoid circular imports
         from apps.job.models import Job
 
         try:
-            job = Job.objects.select_related("contact").get(id=job_id)
+            job = Job.objects.select_related("person").get(id=job_id)
         except Job.DoesNotExist:
             raise ValueError(f"Job with id {job_id} not found")
         except AlreadyLoggedException:
@@ -489,24 +491,21 @@ def get_job_contact(job_id: UUID) -> Dict[str, Any]:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "get_job_contact",
+                    "operation": "get_job_person",
                     "job_id": str(job_id),
                 },
             )
 
-        if not job.contact:
+        if not job.person:
             # Documented business validation failure should not be persisted
-            raise ValueError(f"No contact associated with job {job_id}")
+            raise ValueError(f"No person associated with job {job_id}")
 
-        contact = job.contact
+        person = job.person
         try:
             return {
-                "id": str(contact.id),
-                "name": contact.name,
-                "email": contact.email,
-                "position": contact.position,
-                "is_primary": contact.is_primary,
-                "notes": contact.notes,
+                "id": str(person.id),
+                "name": person.name,
+                "email": person.email,
             }
         except AlreadyLoggedException:
             raise
@@ -514,73 +513,65 @@ def get_job_contact(job_id: UUID) -> Dict[str, Any]:
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "serialize_job_contact",
+                    "operation": "serialize_job_person",
                     "job_id": str(job_id),
                 },
             )
 
     @staticmethod
-    def update_job_contact(
-        job_id: UUID, contact_data: Dict[str, Any], user: "Staff"
+    def update_job_person(
+        job_id: UUID, person_data: Dict[str, Any], user: "Staff"
     ) -> Dict[str, Any]:
         """
-        Updates the contact person for a specific job.
+        Updates the person for a specific job.
 
         Args:
             job_id: Job UUID
-            contact_data: Contact data to update
+            person_data: Person data to update
             user: Staff performing the update
 
         Returns:
             Dict with updated contact information
 
         Raises:
-            ValueError: If job not found, contact not found, or validation fails
+            ValueError: If job not found, person not found, or validation fails
         """
         try:
             # Import here to avoid circular imports
+            from apps.company.models import Person
             from apps.job.models import Job
 
             try:
-                job = Job.objects.select_related("company", "contact").get(id=job_id)
+                job = Job.objects.select_related("company", "person").get(id=job_id)
             except Job.DoesNotExist:
                 raise ValueError(f"Job with id {job_id} not found")
 
-            # Validate contact exists and belongs to the same company
-            contact_id = contact_data.get("id")
-            if not contact_id:
-                raise ValueError("Contact ID is required")
+            person_id = person_data.get("id")
+            if not person_id:
+                raise ValueError("Person ID is required")
 
             try:
-                contact = ClientContact.objects.get(id=contact_id)
-            except ClientContact.DoesNotExist:
-                raise ValueError(f"Contact with id {contact_id} not found")
-
-            # Validate contact belongs to the job's company
-            if contact.company_id != job.company_id:
-                raise ValueError("Contact does not belong to the job's company")
+                person = Person.objects.get(id=person_id)
+            except Person.DoesNotExist:
+                raise ValueError(f"Person with id {person_id} not found")
 
-            # Update job's contact
-            job.contact = contact
+            job.person = person
             job.save(staff=user)
 
             logger.info(
-                f"Contact {contact_id} assigned to job {job_id}",
+                f"Person {person_id} assigned to job {job_id}",
                 extra={
                     "job_id": str(job_id),
-                    "contact_id": str(contact_id),
+                    "person_id": str(person_id),
                     "company_id": str(job.company_id),
-                    "operation": "update_job_contact",
+                    "operation": "update_job_person",
                 },
             )
 
             return {
-                "id": str(contact.id),
-                "name": contact.name,
-                "email": contact.email,
-                "position": contact.position,
-                "is_primary": contact.is_primary,
-                "notes": contact.notes,
+                "id": str(person.id),
+                "name": person.name,
+                "email": person.email,
             }
 
         except AlreadyLoggedException:
@@ -589,9 +580,9 @@ def update_job_contact(
             persist_and_raise(
                 exc,
                 additional_context={
-                    "operation": "update_job_contact",
+                    "operation": "update_job_person",
                     "job_id": str(job_id),
-                    "contact_id": contact_data.get("id"),
+                    "person_id": person_data.get("id"),
                 },
             )
 
@@ -621,7 +612,7 @@ def _hydrate_company_search_results(company_ids):
             Company.objects.with_invoice_summary()
             .defer("raw_json")  # Not needed for search results
             .annotate(
-                phone=ClientContactMethod.primary_phone_annotation(
+                phone=ContactMethod.primary_phone_annotation(
                     owner="company", outer_ref="pk"
                 )
             )
@@ -780,7 +771,7 @@ def log_company_search_results(
         company_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
         SearchTelemetryService.log_search(
             request=request,
-            domain="client",
+            domain="company",
             source=source,
             query=query,
             result_count=total_count,
@@ -820,7 +811,7 @@ def log_company_search_click(
         company_search_logger.info(json.dumps(payload, sort_keys=True, default=str))
         SearchTelemetryService.log_click(
             request=request,
-            domain="client",
+            domain="company",
             source=source,
             query=query,
             selected_result_id=str(company.id),
@@ -882,7 +873,7 @@ def _format_company_summary(
         Formats a single company summary for list/search responses.
 
         Callers must annotate their queryset with
-        ClientContactMethod.primary_phone_annotation (see CompanyPhoneAnnotations).
+        ContactMethod.primary_phone_annotation (see CompanyPhoneAnnotations).
         """
         return {
             "id": str(company.id),
@@ -915,7 +906,7 @@ def _format_company_detail(
         Formats complete company details for API response.
 
         Callers must annotate their queryset with
-        ClientContactMethod.primary_phone_annotation (see CompanyPhoneAnnotations).
+        ContactMethod.primary_phone_annotation (see CompanyPhoneAnnotations).
         """
         return {
             "id": str(company.id),
@@ -928,9 +919,6 @@ def _format_company_detail(
             "allow_jobs": company.allow_jobs,
             "xero_contact_id": company.xero_contact_id or "",
             "xero_tenant_id": company.xero_tenant_id or "",
-            "primary_contact_name": company.primary_contact_name or "",
-            "primary_contact_email": company.primary_contact_email or "",
-            "additional_contact_persons": company.additional_contact_persons or [],
             "xero_last_modified": company.xero_last_modified,
             "xero_last_synced": company.xero_last_synced,
             "xero_archived": company.xero_archived,
@@ -1114,9 +1102,9 @@ def _apply_company_phone_change(
     @staticmethod
     def _clear_company_primary_phone(company: Company) -> None:
         primary = (
-            ClientContactMethod.objects.filter(
+            ContactMethod.objects.filter(
                 company=company,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 is_primary=True,
             )
             .order_by(*PRIMARY_PHONE_ORDERING)
diff --git a/apps/company/services/duplicate_phone_report.py b/apps/company/services/duplicate_phone_report.py
index 71af7d791..a806083b4 100644
--- a/apps/company/services/duplicate_phone_report.py
+++ b/apps/company/services/duplicate_phone_report.py
@@ -1,21 +1,11 @@
-"""Data Quality report: phone numbers that break the one-number-one-company rule.
-
-Surfaces the two ways a phone number can be mis-owned, for manual clean-up:
-- ``cross_client`` — a number whose effective companies (``COALESCE(company_id,
-  contact.company_id)``) number more than one (the grandfathered pre-existing links).
-- ``internal_line`` — a company/contact phone method whose number is one of the
-  company's own internal ``PhoneEndpoint`` lines (e.g. a staff line mis-filed as a
-  customer contact).
-"""
+"""Data Quality report: phone numbers that break the one-number-one-company rule."""
 
 from datetime import datetime
 from typing import TypedDict
 
-from django.db.models import Count
-from django.db.models.functions import Coalesce
 from django.utils import timezone
 
-from apps.company.models import ClientContactMethod
+from apps.company.models import ContactMethod
 from apps.crm.models import PhoneEndpoint
 
 
@@ -60,25 +50,28 @@ def get_report(self) -> DuplicatePhonesReport:
         }
 
     def _cross_company_conflicts(self) -> list[DuplicatePhoneIssue]:
-        phones = ClientContactMethod.objects.filter(
-            method_type=ClientContactMethod.MethodType.PHONE
+        phones = ContactMethod.objects.filter(
+            method_type=ContactMethod.MethodType.PHONE
         )
-        conflict_numbers = [
-            row["normalized_value"]
-            for row in phones.values("normalized_value")
-            .annotate(
-                companies=Count(
-                    Coalesce("company_id", "contact__company_id"), distinct=True
-                )
+        companies_by_number: dict[str, set[str]] = {}
+        for method in phones.select_related("company", "person").prefetch_related(
+            "person__company_links"
+        ):
+            companies_by_number.setdefault(method.normalized_value, set()).update(
+                str(company_id) for company_id in method.owner_company_ids()
             )
-            .filter(companies__gt=1)
+        conflict_numbers = [
+            number
+            for number, company_ids in companies_by_number.items()
+            if len(company_ids) > 1
         ]
         if not conflict_numbers:
             return []
         grouped: dict[str, list[DuplicatePhoneOwner]] = {}
         for method in (
             phones.filter(normalized_value__in=conflict_numbers)
-            .select_related("company", "contact", "contact__company")
+            .select_related("company", "person")
+            .prefetch_related("person__company_links")
             .order_by("normalized_value", "id")
         ):
             grouped.setdefault(method.normalized_value, []).append(self._owner(method))
@@ -108,21 +101,22 @@ def _internal_line_collisions(self) -> list[DuplicatePhoneIssue]:
                 "owners": [self._owner(method)],
             }
             for method in (
-                ClientContactMethod.objects.filter(
-                    method_type=ClientContactMethod.MethodType.PHONE,
+                ContactMethod.objects.filter(
+                    method_type=ContactMethod.MethodType.PHONE,
                     normalized_value__in=list(endpoint_labels),
                 )
-                .select_related("company", "contact", "contact__company")
+                .select_related("company", "person")
+                .prefetch_related("person__company_links")
                 .order_by("normalized_value", "id")
             )
         ]
 
     @staticmethod
-    def _owner(method: ClientContactMethod) -> DuplicatePhoneOwner:
+    def _owner(method: ContactMethod) -> DuplicatePhoneOwner:
         effective_company_id = method.owner_company_id()
         return {
             "method_id": str(method.id),
-            "owner_kind": "company" if method.company_id else "contact",
+            "owner_kind": "company" if method.company_id else "person",
             "owner_name": method.owner_display_name(),
             "effective_client_id": (
                 str(effective_company_id) if effective_company_id else None
diff --git a/apps/company/tests/test_company_fts_search.py b/apps/company/tests/test_company_fts_search.py
index 2a0d08fdd..f7d5271d5 100644
--- a/apps/company/tests/test_company_fts_search.py
+++ b/apps/company/tests/test_company_fts_search.py
@@ -289,7 +289,7 @@ def test_company_search_logging_emits_structured_json(db, caplog):
 
     event = SearchTelemetryEvent.objects.get(
         event_type=SearchTelemetryEvent.EventType.SEARCH,
-        domain=SearchTelemetryEvent.Domain.CLIENT,
+        domain=SearchTelemetryEvent.Domain.COMPANY,
     )
     assert event.query == "FUME"
     assert event.normalized_query == "fume"
diff --git a/apps/company/tests/test_company_invoice_summary.py b/apps/company/tests/test_company_invoice_summary.py
index 96cee25bd..e684610ea 100644
--- a/apps/company/tests/test_company_invoice_summary.py
+++ b/apps/company/tests/test_company_invoice_summary.py
@@ -10,7 +10,7 @@
 from rest_framework.test import APIRequestFactory, force_authenticate
 
 from apps.accounting.models import Invoice
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 from apps.company.services.company_rest_service import CompanyRestService
 from apps.company.utils import date_to_datetime
 from apps.company.views.company_rest_views import CompanyCreateRestView
@@ -97,7 +97,7 @@ def test_formatting_annotated_companies_does_not_query_invoice_metrics(db):
     companies = list(
         Company.objects.with_invoice_summary()
         .annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
+            phone=ContactMethod.primary_phone_annotation(
                 owner="company", outer_ref="pk"
             )
         )
diff --git a/apps/company/tests/test_company_merge_service.py b/apps/company/tests/test_company_merge_service.py
index 413af31b5..a21be838f 100644
--- a/apps/company/tests/test_company_merge_service.py
+++ b/apps/company/tests/test_company_merge_service.py
@@ -15,7 +15,7 @@
 from django.utils import timezone
 
 from apps.accounting.models import Bill, CreditNote, Invoice, Quote
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.company.services.company_merge_service import reassign_company_fk_records
 from apps.crm.models import PhoneCallRecord
 from apps.job.models import Job, JobEvent
@@ -35,6 +35,15 @@ def make_company(name: str) -> Company:
     )
 
 
+def make_link(company: Company, name: str) -> CompanyPersonLink:
+    person = Person.objects.create(name=name)
+    return CompanyPersonLink.objects.create(
+        company=company,
+        person=person,
+        xero_name=name,
+    )
+
+
 _next_job_number = {"n": 90000}
 
 
@@ -118,7 +127,7 @@ def make_scrape_job(supplier: Company) -> ScrapeJob:
 
 
 def make_phone_call(
-    company: Company, *, contact: ClientContact | None = None
+    company: Company, *, person: Person | None = None
 ) -> PhoneCallRecord:
     call_datetime = timezone.now()
     return PhoneCallRecord.objects.create(
@@ -130,7 +139,7 @@ def make_phone_call(
         origin="+6421555123",
         destination="+6496365131",
         company=company,
-        contact=contact,
+        person=person,
         raw_json={},
     )
 
@@ -328,18 +337,18 @@ def test_all_fk_types_move_in_one_call(self) -> None:
 
 class ReassignCrmHistoryTests(ReassignFKBaseCase):
     def test_contact_methods_and_phone_calls_move_to_destination(self) -> None:
-        contact = ClientContact.objects.create(company=self.source, name="Jane Smith")
-        method = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact = make_link(self.source, "Jane Smith")
+        method = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        company_method = ClientContactMethod.objects.create(
+        company_method = ContactMethod.objects.create(
             company=self.source,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 124",
         )
-        contact_call = make_phone_call(self.source, contact=contact)
+        contact_call = make_phone_call(self.source, person=contact.person)
         company_call = make_phone_call(self.source)
 
         counts = reassign_company_fk_records(
@@ -355,30 +364,24 @@ def test_contact_methods_and_phone_calls_move_to_destination(self) -> None:
         company_call.refresh_from_db()
 
         self.assertEqual(contact.company_id, self.destination.id)
-        self.assertEqual(method.contact_id, contact.id)
+        self.assertEqual(method.person_id, contact.person_id)
         self.assertEqual(company_method.company_id, self.destination.id)
         self.assertEqual(contact_call.company_id, self.destination.id)
-        self.assertEqual(contact_call.contact_id, contact.id)
+        self.assertEqual(contact_call.person_id, contact.person_id)
         self.assertEqual(company_call.company_id, self.destination.id)
         self.assertEqual(counts["contacts"], 1)
         self.assertEqual(counts["contact_methods"], 1)
         self.assertEqual(counts["phone_calls"], 2)
 
     def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
-        source_contact = ClientContact.objects.create(
-            company=self.source,
-            name="Jane Smith",
-        )
-        destination_contact = ClientContact.objects.create(
-            company=self.destination,
-            name="Jane Smith",
-        )
-        method = ClientContactMethod.objects.create(
-            contact=source_contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        source_contact = make_link(self.source, "Jane Smith")
+        make_link(self.destination, "Jane Smith")
+        method = ContactMethod.objects.create(
+            person=source_contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        call = make_phone_call(self.source, contact=source_contact)
+        call = make_phone_call(self.source, person=source_contact.person)
 
         counts = reassign_company_fk_records(
             self.source,
@@ -389,12 +392,13 @@ def test_exact_name_contact_conflict_merges_methods_and_calls(self) -> None:
         method.refresh_from_db()
         call.refresh_from_db()
 
-        self.assertFalse(ClientContact.objects.filter(id=source_contact.id).exists())
-        self.assertEqual(method.contact_id, destination_contact.id)
+        source_contact.refresh_from_db()
+        self.assertEqual(source_contact.company_id, self.destination.id)
+        self.assertEqual(method.person_id, source_contact.person_id)
         self.assertEqual(call.company_id, self.destination.id)
-        self.assertEqual(call.contact_id, destination_contact.id)
+        self.assertEqual(call.person_id, source_contact.person_id)
         self.assertEqual(counts["contacts"], 1)
-        self.assertEqual(counts["contact_methods"], 1)
+        self.assertEqual(counts["contact_methods"], 0)
         self.assertEqual(counts["phone_calls"], 1)
 
 
@@ -407,30 +411,30 @@ class ContactMethodMergeGuardTests(ReassignFKBaseCase):
 
     NUMBER = "021 555 123"
 
-    def _grandfathered_method(self, company: Company) -> ClientContactMethod:
+    def _grandfathered_method(self, company: Company) -> ContactMethod:
         """Insert a cross-company duplicate bypassing the save() guard,
         exactly as pre-guard legacy rows (and migration 0023 twins) exist."""
-        legacy = ClientContactMethod(
+        legacy = ContactMethod(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
-        legacy.normalized_value = ClientContactMethod.normalize_phone(self.NUMBER)
-        ClientContactMethod.objects.bulk_create([legacy])
+        legacy.normalized_value = ContactMethod.normalize_phone(self.NUMBER)
+        ContactMethod.objects.bulk_create([legacy])
         return legacy
 
     def test_same_number_on_company_and_own_contact_both_move(self) -> None:
         """Migration 0023 creates company-level + contact-level twins; a merge
         must move both without the guard rejecting the not-yet-moved sibling."""
-        contact = ClientContact.objects.create(company=self.source, name="Jane Smith")
-        company_method = ClientContactMethod.objects.create(
+        contact = make_link(self.source, "Jane Smith")
+        company_method = ContactMethod.objects.create(
             company=self.source,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
-        contact_method = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact_method = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
 
@@ -443,16 +447,16 @@ def test_same_number_on_company_and_own_contact_both_move(self) -> None:
         contact.refresh_from_db()
         self.assertEqual(company_method.company_id, self.destination.id)
         self.assertEqual(contact.company_id, self.destination.id)
-        self.assertEqual(contact_method.contact_id, contact.id)
+        self.assertEqual(contact_method.person_id, contact.person_id)
         self.assertEqual(counts["contact_methods"], 1)
         self.assertEqual(counts["contacts"], 1)
 
     def test_merge_succeeds_when_third_company_owns_same_number(self) -> None:
         """A grandfathered duplicate on an unrelated company must not block
         merging A into B."""
-        source_method = ClientContactMethod.objects.create(
+        source_method = ContactMethod.objects.create(
             company=self.source,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
         third = make_company("Third Company")
@@ -467,9 +471,9 @@ def test_merge_succeeds_when_third_company_owns_same_number(self) -> None:
         self.assertEqual(counts["contact_methods"], 1)
 
     def test_duplicate_of_destination_number_is_dropped_not_duplicated(self) -> None:
-        destination_method = ClientContactMethod.objects.create(
+        destination_method = ContactMethod.objects.create(
             company=self.destination,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
         )
         source_method = self._grandfathered_method(self.source)
@@ -478,11 +482,9 @@ def test_duplicate_of_destination_number_is_dropped_not_duplicated(self) -> None
             self.source, self.destination, self.test_staff
         )
 
-        self.assertFalse(
-            ClientContactMethod.objects.filter(id=source_method.id).exists()
-        )
-        remaining = ClientContactMethod.objects.filter(
-            normalized_value=ClientContactMethod.normalize_phone(self.NUMBER)
+        self.assertFalse(ContactMethod.objects.filter(id=source_method.id).exists())
+        remaining = ContactMethod.objects.filter(
+            normalized_value=ContactMethod.normalize_phone(self.NUMBER)
         )
         self.assertEqual(remaining.count(), 1)
         self.assertEqual(remaining.get().id, destination_method.id)
@@ -491,15 +493,15 @@ def test_duplicate_of_destination_number_is_dropped_not_duplicated(self) -> None
     def test_moving_primary_method_demotes_destination_primary(self) -> None:
         """The bulk move must not violate the single-primary-per-owner
         constraint when both sides have a primary phone."""
-        destination_primary = ClientContactMethod.objects.create(
+        destination_primary = ContactMethod.objects.create(
             company=self.destination,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 999",
             is_primary=True,
         )
-        source_primary = ClientContactMethod.objects.create(
+        source_primary = ContactMethod.objects.create(
             company=self.source,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=self.NUMBER,
             is_primary=True,
         )
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index afb79e457..06b05ec5c 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -11,7 +11,7 @@
 if TYPE_CHECKING:
     from apps.job.models import Job
 
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.company.services.company_rest_service import CompanyRestService
 from apps.crm.models import PhoneCallRecord
 from apps.crm.services.phone_call_service import rematch_calls_for_numbers
@@ -21,33 +21,42 @@
 from apps.workflow.models import AppError
 
 
-class ClientContactMethodTests(TestCase):
+def _link(company: Company, name: str, email: str | None = None) -> CompanyPersonLink:
+    person = Person.objects.create(name=name, email=email)
+    return CompanyPersonLink.objects.create(
+        company=company,
+        person=person,
+        xero_name=name,
+    )
+
+
+class ContactMethodTests(TestCase):
     def _company(self, name: str = "Acme Ltd") -> Company:
         return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
     def test_phone_normalization_matches_nz_variants(self) -> None:
         """Catches call matching failures when NZ local and E.164 numbers diverge."""
         self.assertEqual(
-            ClientContactMethod.normalize_phone("+64 9 636 5131"),
+            ContactMethod.normalize_phone("+64 9 636 5131"),
             "+6496365131",
         )
         self.assertEqual(
-            ClientContactMethod.normalize_phone("09 636 5131"),
+            ContactMethod.normalize_phone("09 636 5131"),
             "+6496365131",
         )
 
     def test_primary_phone_is_single_per_company_owner(self) -> None:
         """Catches multiple primary phone numbers being left on a company record."""
         company = self._company()
-        first = ClientContactMethod.objects.create(
+        first = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
-        second = ClientContactMethod.objects.create(
+        second = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 222 2222",
             is_primary=True,
         )
@@ -61,15 +70,15 @@ def test_primary_phone_is_single_per_company_owner(self) -> None:
     def test_same_number_allowed_on_company_and_its_own_contact(self) -> None:
         """A company and its own contact sharing one line must not be rejected."""
         company = self._company()
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
-        on_company = ClientContactMethod.objects.create(
+        contact = _link(company, "Jane Smith")
+        on_company = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
-        on_contact = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        on_contact = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
 
@@ -79,16 +88,16 @@ def test_same_number_allowed_on_company_and_its_own_contact(self) -> None:
     def test_same_number_allowed_on_two_contacts_of_same_company(self) -> None:
         """Two contacts of one company can share a number (one effective company)."""
         company = self._company()
-        first_contact = ClientContact.objects.create(company=company, name="A")
-        second_contact = ClientContact.objects.create(company=company, name="B")
-        ClientContactMethod.objects.create(
-            contact=first_contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        first_contact = _link(company, "A")
+        second_contact = _link(company, "B")
+        ContactMethod.objects.create(
+            person=first_contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
-        on_second = ClientContactMethod.objects.create(
-            contact=second_contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        on_second = ContactMethod.objects.create(
+            person=second_contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
 
@@ -98,15 +107,15 @@ def test_same_number_rejected_across_different_companies(self) -> None:
         """Two different companies cannot own one number; the matcher would be ambiguous."""
         company_a = self._company("Acme Ltd")
         company_b = self._company("Beta Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company_a,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         with self.assertRaises(ValidationError):
-            ClientContactMethod.objects.create(
+            ContactMethod.objects.create(
                 company=company_b,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 value="021 111 111",
             )
 
@@ -114,17 +123,17 @@ def test_same_number_rejected_across_contacts_of_different_companies(self) -> No
         """Contacts of two different companies cannot share a number."""
         company_a = self._company("Acme Ltd")
         company_b = self._company("Beta Ltd")
-        contact_a = ClientContact.objects.create(company=company_a, name="A")
-        contact_b = ClientContact.objects.create(company=company_b, name="B")
-        ClientContactMethod.objects.create(
-            contact=contact_a,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact_a = _link(company_a, "A")
+        contact_b = _link(company_b, "B")
+        ContactMethod.objects.create(
+            person=contact_a.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         with self.assertRaises(ValidationError):
-            ClientContactMethod.objects.create(
-                contact=contact_b,
-                method_type=ClientContactMethod.MethodType.PHONE,
+            ContactMethod.objects.create(
+                person=contact_b.person,
+                method_type=ContactMethod.MethodType.PHONE,
                 value="021 111 111",
             )
 
@@ -132,20 +141,20 @@ def test_grandfathered_cross_company_number_can_be_resaved(self) -> None:
         """A pre-existing cross-company number (legacy data) re-saves unchanged."""
         company_a = self._company("Acme Ltd")
         company_b = self._company("Beta Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company_a,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
         # Simulate legacy prod data: B already owns the same number, inserted
         # bypassing the guard (as pre-guard rows were).
-        legacy = ClientContactMethod(
+        legacy = ContactMethod(
             company=company_b,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
-        legacy.normalized_value = ClientContactMethod.normalize_phone("021 111 111")
-        ClientContactMethod.objects.bulk_create([legacy])
+        legacy.normalized_value = ContactMethod.normalize_phone("021 111 111")
+        ContactMethod.objects.bulk_create([legacy])
 
         legacy.refresh_from_db()
         legacy.label = "Mobile"
@@ -158,14 +167,14 @@ def test_changing_number_into_another_companies_ownership_raises(self) -> None:
         """Editing a method's number onto another company's number is blocked."""
         company_a = self._company("Acme Ltd")
         company_b = self._company("Beta Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company_a,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
-        moving = ClientContactMethod.objects.create(
+        moving = ContactMethod.objects.create(
             company=company_b,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 222 222",
         )
 
@@ -176,16 +185,16 @@ def test_changing_number_into_another_companies_ownership_raises(self) -> None:
     def test_primary_phone_is_single_per_contact_owner(self) -> None:
         """Catches multiple primary phone numbers being left on a contact record."""
         company = self._company()
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
-        first = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact = _link(company, "Jane Smith")
+        first = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
             is_primary=True,
         )
-        second = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        second = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 222 222",
             is_primary=True,
         )
@@ -200,9 +209,9 @@ def test_partial_update_fields_still_persists_normalized_value(self) -> None:
         """save(update_fields=["value"]) must also persist the recomputed
         normalized_value, or the matching/uniqueness index goes stale."""
         company = self._company("Acme Ltd")
-        method = ClientContactMethod.objects.create(
+        method = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
 
@@ -212,7 +221,7 @@ def test_partial_update_fields_still_persists_normalized_value(self) -> None:
         method.refresh_from_db()
         self.assertEqual(
             method.normalized_value,
-            ClientContactMethod.normalize_phone("021 222 222"),
+            ContactMethod.normalize_phone("021 222 222"),
         )
 
 
@@ -223,14 +232,14 @@ def test_returns_primary_phone_first(self) -> None:
         company = Company.objects.create(
             name="Acme Ltd", xero_last_modified=timezone.now()
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 222 2222",
             is_primary=True,
         )
@@ -241,9 +250,9 @@ def test_returns_empty_string_when_no_phone_methods(self) -> None:
         company = Company.objects.create(
             name="Phoneless Ltd", xero_last_modified=timezone.now()
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.EMAIL,
+            method_type=ContactMethod.MethodType.EMAIL,
             value="office@example.com",
         )
 
@@ -258,22 +267,22 @@ def _company(self, name: str = "Acme Ltd") -> Company:
 
     def test_company_annotation_prefers_primary_over_label_order(self) -> None:
         company = self._company()
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             label="AAA sorts first",
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 222 2222",
             label="ZZZ sorts last",
             is_primary=True,
         )
 
         annotated = Company.objects.annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
+            phone=ContactMethod.primary_phone_annotation(
                 owner="company", outer_ref="pk"
             )
         ).get(pk=company.pk)
@@ -282,14 +291,14 @@ def test_company_annotation_prefers_primary_over_label_order(self) -> None:
 
     def test_company_annotation_is_empty_string_without_phones(self) -> None:
         company = self._company("Phoneless Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.EMAIL,
+            method_type=ContactMethod.MethodType.EMAIL,
             value="office@example.com",
         )
 
         annotated = Company.objects.annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
+            phone=ContactMethod.primary_phone_annotation(
                 owner="company", outer_ref="pk"
             )
         ).get(pk=company.pk)
@@ -298,23 +307,21 @@ def test_company_annotation_is_empty_string_without_phones(self) -> None:
 
     def test_contact_annotation_returns_contact_primary_phone(self) -> None:
         company = self._company()
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
-        ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact = _link(company, "Jane Smith")
+        ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 111 111",
         )
-        ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 222 222",
             is_primary=True,
         )
 
-        annotated = ClientContact.objects.annotate(
-            phone=ClientContactMethod.primary_phone_annotation(
-                owner="contact", outer_ref="pk"
-            )
+        annotated = CompanyPersonLink.objects.annotate(
+            phone=ContactMethod.primary_phone_for_link_annotation()
         ).get(pk=contact.pk)
 
         self.assertEqual(annotated.phone, "021 222 222")
@@ -323,45 +330,45 @@ def test_contact_annotation_returns_contact_primary_phone(self) -> None:
 class UpdateJobContactTests(BaseTestCase):
     """Guards that reassigning a job's contact persists to the job record."""
 
-    def _job_with_contact(self) -> "tuple[Job, Company, ClientContact]":
+    def _job_with_contact(self) -> "tuple[Job, Company, CompanyPersonLink]":
         from apps.job.models import Job
         from apps.workflow.models import XeroPayItem
 
         company = Company.objects.create(
             name="Acme Ltd", xero_last_modified=timezone.now()
         )
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
+        contact = _link(company, "Jane Smith")
         job: Job = Job.objects.create(
             name="Contact Assignment Job",
             company=company,
-            contact=contact,
+            person=contact.person,
             created_by=self.test_staff,
             default_xero_pay_item=XeroPayItem.get_ordinary_time(),
             staff=self.test_staff,
         )
         return job, company, contact
 
-    def test_update_job_contact_persists_new_contact(self) -> None:
+    def test_update_job_person_persists_new_person(self) -> None:
         job, company, _ = self._job_with_contact()
-        new_contact = ClientContact.objects.create(company=company, name="Bob Brown")
+        new_contact = _link(company, "Bob Brown")
 
-        CompanyRestService.update_job_contact(
-            job.id, {"id": str(new_contact.id)}, self.test_staff
+        CompanyRestService.update_job_person(
+            job.id, {"id": str(new_contact.person_id)}, self.test_staff
         )
 
         job.refresh_from_db()
-        self.assertEqual(job.contact_id, new_contact.id)
+        self.assertEqual(job.person_id, new_contact.person_id)
 
 
 class CompanyListPhoneTests(TestCase):
     """Guards the Phone column of the companies list (restored after the
-    ClientContactMethod migration dropped it)."""
+    ContactMethod migration dropped it)."""
 
     def _company_with_phone(self, name: str, phone: str) -> Company:
         company = Company.objects.create(name=name, xero_last_modified=timezone.now())
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=phone,
             is_primary=True,
         )
@@ -394,11 +401,11 @@ def test_searched_clients_include_phone(self) -> None:
         self.assertEqual(result["results"][0]["phone"], "09 111 1111")
 
 
-class ClientContactApiPhoneTests(BaseAPITestCase):
+class CompanyPersonLinkApiPhoneTests(BaseAPITestCase):
     """Guards the contact phone read/write restored on the contacts endpoint
-    (company detail Contacts card, ContactSelectionModal, contact picker)."""
+    (company detail People card, PersonSelectionModal, person picker)."""
 
-    URL = "/api/companies/contacts/"
+    URL = "/api/companies/person-links/"
 
     def setUp(self) -> None:
         super().setUp()
@@ -409,12 +416,12 @@ def setUp(self) -> None:
 
     def _contact(
         self, name: str = "Jane Smith", phone: str | None = None
-    ) -> ClientContact:
-        contact = ClientContact.objects.create(company=self.job_client, name=name)
+    ) -> CompanyPersonLink:
+        contact = _link(self.job_client, name)
         if phone is not None:
-            ClientContactMethod.objects.create(
-                contact=contact,
-                method_type=ClientContactMethod.MethodType.PHONE,
+            ContactMethod.objects.create(
+                person=contact.person,
+                method_type=ContactMethod.MethodType.PHONE,
                 value=phone,
                 is_primary=True,
             )
@@ -430,7 +437,7 @@ def test_list_includes_contact_phone_without_lazy_queries(self) -> None:
             )
 
         self.assertEqual(response.status_code, 200)
-        phones = {row["name"]: row["phone"] for row in response.json()}
+        phones = {row["person_name"]: row["phone"] for row in response.json()}
         self.assertEqual(phones["Jane Smith"], "021 111 111")
         self.assertEqual(phones["No Phone"], "")
         lazy = [
@@ -447,7 +454,7 @@ def test_create_contact_with_phone_creates_primary_method(self) -> None:
                     self.URL,
                     {
                         "company": str(self.job_client.id),
-                        "name": "Bob Brown",
+                        "person_name": "Bob Brown",
                         "phone": "021 222 222",
                     },
                     format="json",
@@ -455,14 +462,14 @@ def test_create_contact_with_phone_creates_primary_method(self) -> None:
 
         self.assertEqual(response.status_code, 201)
         self.assertEqual(response.json()["phone"], "021 222 222")
-        method = ClientContactMethod.objects.get(contact__name="Bob Brown")
-        self.assertEqual(method.method_type, ClientContactMethod.MethodType.PHONE)
+        method = ContactMethod.objects.get(person__name="Bob Brown")
+        self.assertEqual(method.method_type, ContactMethod.MethodType.PHONE)
         self.assertTrue(method.is_primary)
         rematch.assert_called_once_with(["+6421222222"])
 
     def test_update_phone_updates_existing_primary_method(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
-        method = contact.contact_methods.get()
+        method = contact.person.contact_methods.get()
 
         with patch("apps.crm.tasks.rematch_phone_calls_task.delay") as rematch:
             with self.captureOnCommitCallbacks(execute=True):
@@ -476,14 +483,14 @@ def test_update_phone_updates_existing_primary_method(self) -> None:
         self.assertEqual(response.json()["phone"], "021 333 333")
         method.refresh_from_db()
         self.assertEqual(method.value, "021 333 333")
-        self.assertEqual(contact.contact_methods.count(), 1)
+        self.assertEqual(contact.person.contact_methods.count(), 1)
         rematch.assert_called_once_with(["+6421111111", "+6421333333"])
 
     def test_update_phone_matching_secondary_promotes_it(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
-        secondary = ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        secondary = ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 444 444",
         )
 
@@ -496,7 +503,9 @@ def test_update_phone_matching_secondary_promotes_it(self) -> None:
         self.assertEqual(response.status_code, 200)
         secondary.refresh_from_db()
         self.assertTrue(secondary.is_primary)
-        self.assertEqual(contact.contact_methods.filter(is_primary=True).count(), 1)
+        self.assertEqual(
+            contact.person.contact_methods.filter(is_primary=True).count(), 1
+        )
 
     def test_blank_phone_leaves_methods_untouched(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
@@ -509,15 +518,15 @@ def test_blank_phone_leaves_methods_untouched(self) -> None:
 
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.json()["phone"], "021 111 111")
-        self.assertEqual(contact.contact_methods.count(), 1)
+        self.assertEqual(contact.person.contact_methods.count(), 1)
 
     def test_conflicting_phone_returns_400_and_creates_nothing(self) -> None:
         other_client = Company.objects.create(
             name="Beta Ltd", xero_last_modified=timezone.now()
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=other_client,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 555",
         )
         contact = self._contact("Jane Smith")
@@ -530,12 +539,12 @@ def test_conflicting_phone_returns_400_and_creates_nothing(self) -> None:
 
         self.assertEqual(response.status_code, 400)
         self.assertIn("phone", response.json())
-        self.assertEqual(contact.contact_methods.count(), 0)
+        self.assertEqual(contact.person.contact_methods.count(), 0)
 
 
 class CompanyUpdatePhoneTests(BaseAPITestCase):
     """Guards the phone edit restored on the Edit Company modal's update flow
-    (company detail's "phone" read via ClientContactMethod, written through
+    (company detail's "phone" read via ContactMethod, written through
     set_primary_phone)."""
 
     def setUp(self) -> None:
@@ -561,25 +570,23 @@ def test_update_with_new_phone_creates_primary_method(self) -> None:
 
         self.assertEqual(response.status_code, 200)
         self.assertEqual(response.json()["company"]["phone"], "09 111 1111")
-        method = ClientContactMethod.objects.get(company=company)
-        self.assertEqual(method.method_type, ClientContactMethod.MethodType.PHONE)
+        method = ContactMethod.objects.get(company=company)
+        self.assertEqual(method.method_type, ContactMethod.MethodType.PHONE)
         self.assertEqual(method.value, "09 111 1111")
         self.assertTrue(method.is_primary)
-        rematch.assert_called_once_with(
-            [ClientContactMethod.normalize_phone("09 111 1111")]
-        )
+        rematch.assert_called_once_with([ContactMethod.normalize_phone("09 111 1111")])
 
     def test_update_with_existing_secondary_number_promotes_it(self) -> None:
         company = self._company()
-        primary = ClientContactMethod.objects.create(
+        primary = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
-        secondary = ClientContactMethod.objects.create(
+        secondary = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 222 2222",
         )
 
@@ -599,9 +606,9 @@ def test_update_renumbers_current_primary_when_number_is_new(self) -> None:
         (renumbers) the existing primary row instead of creating a second
         one."""
         company = self._company()
-        primary = ClientContactMethod.objects.create(
+        primary = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
@@ -618,9 +625,9 @@ def test_update_renumbers_current_primary_when_number_is_new(self) -> None:
 
     def test_blank_phone_clears_primary_method(self) -> None:
         company = self._company()
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
@@ -640,15 +647,13 @@ def test_blank_phone_clears_primary_method(self) -> None:
         self.assertEqual(company.contact_methods.count(), 0)
         company.refresh_from_db()
         self.assertEqual(company.name, "Acme Renamed")
-        rematch.assert_called_once_with(
-            [ClientContactMethod.normalize_phone("09 111 1111")]
-        )
+        rematch.assert_called_once_with([ContactMethod.normalize_phone("09 111 1111")])
 
     def test_omitted_phone_leaves_methods_untouched(self) -> None:
         company = self._company()
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
@@ -674,9 +679,9 @@ def test_conflicting_phone_returns_400_and_rolls_back_update(self) -> None:
         """A conflict must not leave the update half-applied: neither the new
         name nor a stray contact method should be persisted."""
         other = self._company("Beta Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=other,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 555 5555",
         )
         company = self._company("Acme Ltd")
@@ -695,9 +700,9 @@ def test_conflicting_phone_returns_400_and_rolls_back_update(self) -> None:
 
     def test_get_company_detail_returns_primary_phone(self) -> None:
         company = self._company()
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
@@ -743,17 +748,15 @@ def test_xero_synced_update_applies_phone_before_provider_push(self) -> None:
         pushed_company = provider.update_contact.call_args.args[0]
         pushed_contact = pushed_company.get_company_for_xero()
         self.assertEqual(pushed_contact.phones[0].phone_number, "09 444 4444")
-        rematch.assert_called_once_with(
-            [ClientContactMethod.normalize_phone("09 444 4444")]
-        )
+        rematch.assert_called_once_with([ContactMethod.normalize_phone("09 444 4444")])
 
     def test_xero_synced_blank_phone_clears_before_provider_push(self) -> None:
         company = self._company()
         company.xero_contact_id = "xero-contact-id"
         company.save()
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 111 1111",
             is_primary=True,
         )
@@ -784,9 +787,7 @@ def test_xero_synced_blank_phone_clears_before_provider_push(self) -> None:
         pushed_company = provider.update_contact.call_args.args[0]
         pushed_contact = pushed_company.get_company_for_xero()
         self.assertIsNone(pushed_contact.phones[0].phone_number)
-        rematch.assert_called_once_with(
-            [ClientContactMethod.normalize_phone("09 111 1111")]
-        )
+        rematch.assert_called_once_with([ContactMethod.normalize_phone("09 111 1111")])
 
     def test_phone_rematch_waits_until_transaction_commit(self) -> None:
         company = self._company()
@@ -805,7 +806,7 @@ def test_phone_rematch_waits_until_transaction_commit(self) -> None:
             rematch.assert_not_called()
             callbacks[0]()
             rematch.assert_called_once_with(
-                [ClientContactMethod.normalize_phone("09 111 1111")]
+                [ContactMethod.normalize_phone("09 111 1111")]
             )
 
     def test_unknown_company_update_returns_404_without_app_error(self) -> None:
@@ -976,23 +977,23 @@ def test_create_with_phone_creates_primary_company_method(self) -> None:
             with self.captureOnCommitCallbacks(execute=True):
                 company = self._create(self._provider(), phone="09 777 7777")
 
-        method = ClientContactMethod.objects.get(company=company)
-        self.assertEqual(method.method_type, ClientContactMethod.MethodType.PHONE)
+        method = ContactMethod.objects.get(company=company)
+        self.assertEqual(method.method_type, ContactMethod.MethodType.PHONE)
         self.assertEqual(method.value, "09 777 7777")
         self.assertTrue(method.is_primary)
 
     def test_create_without_phone_creates_no_methods(self) -> None:
         company = self._create(self._provider())
 
-        self.assertEqual(ClientContactMethod.objects.filter(company=company).count(), 0)
+        self.assertEqual(ContactMethod.objects.filter(company=company).count(), 0)
 
     def test_create_with_conflicting_phone_rolls_back_company(self) -> None:
         owner = Company.objects.create(
             name="Owner Ltd", xero_last_modified=timezone.now()
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=owner,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 777 7777",
         )
         provider = self._provider()
@@ -1005,7 +1006,7 @@ def test_create_with_conflicting_phone_rolls_back_company(self) -> None:
         provider.create_contact.assert_not_called()
 
 
-class ClientContactMethodApiTests(BaseAPITestCase):
+class ContactMethodApiTests(BaseAPITestCase):
     def _company(self, name: str = "Acme Ltd") -> Company:
         return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
@@ -1014,9 +1015,9 @@ def test_list_paginates_phone_contact_methods(self) -> None:
         self.client.force_authenticate(user=self.test_staff)
         company = self._company("Acme Ltd")
         for index in range(3):
-            ClientContactMethod.objects.create(
+            ContactMethod.objects.create(
                 company=company,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 value=f"021 555 10{index}",
             )
 
@@ -1038,9 +1039,9 @@ def test_list_page_size_is_capped(self) -> None:
         self.client.force_authenticate(user=self.test_staff)
         company = self._company("Acme Ltd")
         for index in range(101):
-            ClientContactMethod.objects.create(
+            ContactMethod.objects.create(
                 company=company,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 value=f"021 555 {index:03d}",
             )
 
@@ -1059,9 +1060,9 @@ def test_updating_phone_contact_method_rematches_affected_calls(self) -> None:
         """Catches stale call ownership after a customer phone number changes."""
         self.client.force_authenticate(user=self.test_staff)
         company = self._company("Acme Ltd")
-        method = ClientContactMethod.objects.create(
+        method = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
         old_call = self._call("old-number", origin="021 555 100", company=company)
@@ -1089,9 +1090,9 @@ def test_deleting_phone_contact_method_unmatches_affected_calls(self) -> None:
         """Catches deleted phone numbers continuing to own CRM calls."""
         self.client.force_authenticate(user=self.test_staff)
         company = self._company("Acme Ltd")
-        method = ClientContactMethod.objects.create(
+        method = ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
         call = self._call("deleted-number", origin="021 555 100", company=company)
diff --git a/apps/company/tests/test_duplicate_phone_report.py b/apps/company/tests/test_duplicate_phone_report.py
index d52eac761..1945afcf9 100644
--- a/apps/company/tests/test_duplicate_phone_report.py
+++ b/apps/company/tests/test_duplicate_phone_report.py
@@ -1,7 +1,7 @@
 from django.test import TestCase
 from django.utils import timezone
 
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.company.services.duplicate_phone_report import DuplicatePhoneReportService
 from apps.crm.models import PhoneEndpoint
 
@@ -14,19 +14,27 @@ def _phone(
         self,
         value: str,
         company: Company | None = None,
-        contact: ClientContact | None = None,
-    ) -> ClientContactMethod:
+        contact: CompanyPersonLink | None = None,
+    ) -> ContactMethod:
         """Insert a phone method bypassing the save() guard (legacy-style data)."""
-        method = ClientContactMethod(
+        method = ContactMethod(
             company=company,
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            person=contact.person if contact else None,
+            method_type=ContactMethod.MethodType.PHONE,
             value=value,
         )
-        method.normalized_value = ClientContactMethod.normalize_phone(value)
-        ClientContactMethod.objects.bulk_create([method])
+        method.normalized_value = ContactMethod.normalize_phone(value)
+        ContactMethod.objects.bulk_create([method])
         return method
 
+    def _link(self, company: Company, name: str) -> CompanyPersonLink:
+        person = Person.objects.create(name=name)
+        return CompanyPersonLink.objects.create(
+            company=company,
+            person=person,
+            xero_name=name,
+        )
+
     def test_detects_cross_company_number(self) -> None:
         acme = self._company("Acme Ltd")
         beta = self._company("Beta Ltd")
@@ -39,14 +47,14 @@ def test_detects_cross_company_number(self) -> None:
         self.assertEqual(len(cross), 1)
         self.assertEqual(
             cross[0]["normalized_value"],
-            ClientContactMethod.normalize_phone("021 111 111"),
+            ContactMethod.normalize_phone("021 111 111"),
         )
         self.assertEqual(len(cross[0]["owners"]), 2)
         self.assertEqual(report["summary"]["cross_client"], 1)
 
     def test_detects_internal_line_collision(self) -> None:
         company = self._company("Acme Ltd")
-        contact = ClientContact.objects.create(company=company, name="Paul Jones")
+        contact = self._link(company, "Paul Jones")
         self._phone("09 636 5131", contact=contact)
         # Bypass PhoneEndpoint.save()'s collision guard (legacy-style data):
         # the report exists precisely to surface rows that predate the guard.
@@ -55,7 +63,7 @@ def test_detects_internal_line_collision(self) -> None:
             label="Main line",
             endpoint_type=PhoneEndpoint.EndpointType.MAIN_LINE,
         )
-        endpoint.normalized_number = ClientContactMethod.normalize_phone("09 636 5131")
+        endpoint.normalized_number = ContactMethod.normalize_phone("09 636 5131")
         PhoneEndpoint.objects.bulk_create([endpoint])
 
         report = DuplicatePhoneReportService().get_report()
diff --git a/apps/company/tests/test_get_company_for_xero.py b/apps/company/tests/test_get_company_for_xero.py
index ffa94301e..214e36876 100644
--- a/apps/company/tests/test_get_company_for_xero.py
+++ b/apps/company/tests/test_get_company_for_xero.py
@@ -12,7 +12,7 @@
 from xero_python.accounting.models import Address, Contact, Phone
 from xero_python.api_client.serializer import serialize
 
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 
 
 class GetCompanyForXeroTests(TestCase):
@@ -27,9 +27,9 @@ def _make_company(self, **overrides):
         defaults.update(overrides)
         company = Company.objects.create(**defaults)
         if phone is not None:
-            ClientContactMethod.objects.create(
+            ContactMethod.objects.create(
                 company=company,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 value=phone,
                 is_primary=True,
             )
diff --git a/apps/company/tests/test_job_contact_view.py b/apps/company/tests/test_job_contact_view.py
index ea1f2244e..876405fdf 100644
--- a/apps/company/tests/test_job_contact_view.py
+++ b/apps/company/tests/test_job_contact_view.py
@@ -1,8 +1,8 @@
-"""Job contact endpoint tests.
+"""Job person endpoint tests.
 
-Guards the GET/PUT contract of the job-contact endpoint end-to-end (URL
+Guards the GET/PUT contract of the job-person endpoint end-to-end (URL
 routing, permissions, and response-serializer validation), which the
-job-settings tab uses to load and reassign a job's contact person.
+job-settings tab uses to load and reassign a job's person.
 """
 
 from typing import TYPE_CHECKING, Any
@@ -13,13 +13,13 @@
 if TYPE_CHECKING:
     from rest_framework.response import _MonkeyPatchedResponse
 
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.job.models import Job
 from apps.testing import BaseAPITestCase
 from apps.workflow.models import XeroPayItem
 
 
-class JobContactViewTests(BaseAPITestCase):
+class JobPersonViewTests(BaseAPITestCase):
     def setUp(self) -> None:
         super().setUp()
         self.client.force_authenticate(user=self.test_staff)
@@ -27,14 +27,19 @@ def setUp(self) -> None:
             name="Acme Ltd", xero_last_modified=timezone.now()
         )
 
-    def _contact(self, name: str) -> ClientContact:
-        return ClientContact.objects.create(company=self.job_company, name=name)
+    def _link(self, name: str) -> CompanyPersonLink:
+        person = Person.objects.create(name=name)
+        return CompanyPersonLink.objects.create(
+            company=self.job_company,
+            person=person,
+            xero_name=name,
+        )
 
-    def _job(self, contact: ClientContact) -> Job:
+    def _job(self, link: CompanyPersonLink) -> Job:
         job: Job = Job.objects.create(
-            name="Contact Job",
+            name="Person Job",
             company=self.job_company,
-            contact=contact,
+            person=link.person,
             created_by=self.test_staff,
             default_xero_pay_item=XeroPayItem.get_ordinary_time(),
             staff=self.test_staff,
@@ -42,7 +47,7 @@ def _job(self, contact: ClientContact) -> Job:
         return job
 
     def _url(self, job: Job) -> str:
-        return reverse("companies:job_contact_rest", kwargs={"job_id": job.id})
+        return reverse("companies:job_person_rest", kwargs={"job_id": job.id})
 
     def _get(self, job: Job) -> "_MonkeyPatchedResponse":
         return self.client.get(self._url(job))
@@ -50,51 +55,48 @@ def _get(self, job: Job) -> "_MonkeyPatchedResponse":
     def _put(self, job: Job, payload: dict[str, Any]) -> "_MonkeyPatchedResponse":
         return self.client.put(self._url(job), payload, format="json")
 
-    def _put_payload(self, contact: ClientContact) -> dict[str, Any]:
+    def _put_payload(self, link: CompanyPersonLink) -> dict[str, Any]:
         return {
-            "id": str(contact.id),
-            "name": contact.name,
-            "email": contact.email,
-            "position": contact.position,
-            "is_primary": contact.is_primary,
-            "notes": contact.notes,
+            "id": str(link.person_id),
+            "name": link.person.name,
+            "email": link.person.email,
         }
 
-    def test_get_returns_job_contact(self) -> None:
-        contact = self._contact("Jane Smith")
-        job = self._job(contact)
+    def test_get_returns_job_person(self) -> None:
+        link = self._link("Jane Smith")
+        job = self._job(link)
 
         response = self._get(job)
 
         self.assertEqual(response.status_code, 200)
         body = response.json()
-        self.assertEqual(body["id"], str(contact.id))
+        self.assertEqual(body["id"], str(link.person_id))
         self.assertEqual(body["name"], "Jane Smith")
 
-    def test_put_response_reflects_new_contact(self) -> None:
-        job = self._job(self._contact("Jane Smith"))
-        replacement = self._contact("Bob Jones")
+    def test_put_response_reflects_new_person(self) -> None:
+        job = self._job(self._link("Jane Smith"))
+        replacement = self._link("Bob Jones")
 
         response = self._put(job, self._put_payload(replacement))
 
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.json()["id"], str(replacement.id))
+        self.assertEqual(response.json()["id"], str(replacement.person_id))
         job.refresh_from_db()
-        self.assertEqual(job.contact_id, replacement.id)
+        self.assertEqual(job.person_id, replacement.person_id)
 
     def test_put_ignores_unrecognized_field(self) -> None:
-        """Phones live in ClientContactMethod; the job contact update path
-        only reassigns the contact FK. An unexpected key (here the removed
+        """Phones live in ContactMethod; the job person update path
+        only reassigns the person FK. An unexpected key (here the removed
         phone field) must be ignored, not written or echoed back."""
-        job = self._job(self._contact("Jane Smith"))
-        replacement = self._contact("Bob Jones")
+        job = self._job(self._link("Jane Smith"))
+        replacement = self._link("Bob Jones")
         payload = self._put_payload(replacement) | {"phone": "09 999 9999"}
 
         response = self._put(job, payload)
 
         self.assertEqual(response.status_code, 200)
         body = response.json()
-        self.assertEqual(body["id"], str(replacement.id))
+        self.assertEqual(body["id"], str(replacement.person_id))
         self.assertNotIn("phone", body)
         job.refresh_from_db()
-        self.assertEqual(job.contact_id, replacement.id)
+        self.assertEqual(job.person_id, replacement.person_id)
diff --git a/apps/company/tests/test_people_backfill_migration.py b/apps/company/tests/test_people_backfill_migration.py
index 3b11c3fcb..1903d7302 100644
--- a/apps/company/tests/test_people_backfill_migration.py
+++ b/apps/company/tests/test_people_backfill_migration.py
@@ -20,10 +20,6 @@ def setUp(self) -> None:
         self.executor.migrate(self.migrate_from)
         self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
 
-    def tearDown(self) -> None:
-        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
-        super().tearDown()
-
     def test_backfill_and_reverse_restore_legacy_contact_ownership(self) -> None:
         Company = self.old_apps.get_model("company", "Company")
         CompanyPersonLink = self.old_apps.get_model("company", "CompanyPersonLink")
diff --git a/apps/company/urls_rest.py b/apps/company/urls_rest.py
index 92ef7a5f2..07645d1c1 100644
--- a/apps/company/urls_rest.py
+++ b/apps/company/urls_rest.py
@@ -18,10 +18,10 @@
     CompanyRetrieveRestView,
     CompanySearchRestView,
     CompanyUpdateRestView,
-    JobContactRestView,
+    JobPersonRestView,
 )
-from apps.company.views.contact_method_viewset import ClientContactMethodViewSet
-from apps.company.views.contact_viewset import ClientContactViewSet
+from apps.company.views.contact_method_viewset import ContactMethodViewSet
+from apps.company.views.contact_viewset import CompanyPersonLinkViewSet
 from apps.company.views.supplier_pickup_address_viewset import (
     SupplierPickupAddressViewSet,
 )
@@ -36,10 +36,12 @@
 router = DefaultRouter()
 router.register(
     "contact-methods",
-    ClientContactMethodViewSet,
+    ContactMethodViewSet,
     basename="contact-method",
 )
-router.register("contacts", ClientContactViewSet, basename="company-contact")
+router.register(
+    "person-links", CompanyPersonLinkViewSet, basename="company-person-link"
+)
 router.register(
     "pickup-addresses", SupplierPickupAddressViewSet, basename="supplier-pickup-address"
 )
@@ -91,11 +93,11 @@
         SupplierAliasDetailView.as_view(),
         name="supplier_alias_detail_rest",
     ),
-    # Job contact REST endpoint
+    # Job person REST endpoint
     path(
-        "jobs/<uuid:job_id>/contact/",
-        JobContactRestView.as_view(),
-        name="job_contact_rest",
+        "jobs/<uuid:job_id>/person/",
+        JobPersonRestView.as_view(),
+        name="job_person_rest",
     ),
     # Address validation endpoint
     path(
@@ -103,6 +105,6 @@
         AddressValidateView.as_view(),
         name="address_validate",
     ),
-    # ViewSet routes (contacts CRUD)
+    # ViewSet routes (people/contact method CRUD)
     path("", include(router.urls)),
 ]
diff --git a/apps/company/views/__init__.py b/apps/company/views/__init__.py
index 57fd58ebe..ab6214ffd 100644
--- a/apps/company/views/__init__.py
+++ b/apps/company/views/__init__.py
@@ -8,7 +8,7 @@
     CompanyRetrieveRestView,
     CompanySearchRestView,
     CompanyUpdateRestView,
-    JobContactRestView,
+    JobPersonRestView,
 )
 from .supplier_search_alias_views import (
     CompanySupplierAliasListCreateView,
@@ -20,8 +20,8 @@
     from django.apps import apps
 
     if apps.ready:
-        from .contact_method_viewset import ClientContactMethodViewSet
-        from .contact_viewset import ClientContactViewSet
+        from .contact_method_viewset import ContactMethodViewSet
+        from .contact_viewset import CompanyPersonLinkViewSet
         from .supplier_pickup_address_viewset import SupplierPickupAddressViewSet
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
@@ -29,16 +29,16 @@
 
 __all__ = [
     "AddressValidateView",
-    "ClientContactMethodViewSet",
-    "ClientContactViewSet",
     "CompanyCreateRestView",
     "CompanyJobsRestView",
     "CompanyListAllRestView",
+    "CompanyPersonLinkViewSet",
     "CompanyRetrieveRestView",
     "CompanySearchRestView",
     "CompanySupplierAliasListCreateView",
     "CompanyUpdateRestView",
-    "JobContactRestView",
+    "ContactMethodViewSet",
+    "JobPersonRestView",
     "SupplierAliasDetailView",
     "SupplierPickupAddressViewSet",
 ]
diff --git a/apps/company/views/company_rest_views.py b/apps/company/views/company_rest_views.py
index 58bc37552..37d16f688 100644
--- a/apps/company/views/company_rest_views.py
+++ b/apps/company/views/company_rest_views.py
@@ -10,6 +10,7 @@
 
 import logging
 from typing import Any, Dict
+from uuid import UUID
 
 from drf_spectacular.utils import (
     OpenApiParameter,
@@ -23,7 +24,8 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.company.models import ClientContactMethod, Company
+from apps.accounts.models import Staff
+from apps.company.models import Company, ContactMethod
 from apps.company.serializers import (
     CompanyCreateResponseSerializer,
     CompanyCreateSerializer,
@@ -36,8 +38,8 @@
     CompanySearchResponseSerializer,
     CompanyUpdateResponseSerializer,
     CompanyUpdateSerializer,
-    JobContactResponseSerializer,
-    JobContactUpdateSerializer,
+    JobPersonResponseSerializer,
+    JobPersonUpdateSerializer,
 )
 from apps.company.services.company_rest_service import CompanyRestService
 from apps.workflow.exceptions import AlreadyLoggedException
@@ -437,7 +439,7 @@ def post(self, request: Request) -> Response:
             created_company = (
                 Company.objects.with_invoice_summary()
                 .annotate(
-                    phone=ClientContactMethod.primary_phone_annotation(
+                    phone=ContactMethod.primary_phone_annotation(
                         owner="company", outer_ref="pk"
                     )
                 )
@@ -505,8 +507,8 @@ def post(self, request: Request) -> Response:
 
 @extend_schema_view(
     get=extend_schema(
-        summary="Get job contact",
-        description="Retrieve contact information for a specific job.",
+        summary="Get job person",
+        description="Retrieve person information for a specific job.",
         parameters=[
             OpenApiParameter(
                 name="job_id",
@@ -517,15 +519,15 @@ def post(self, request: Request) -> Response:
             )
         ],
         responses={
-            200: JobContactResponseSerializer,
+            200: JobPersonResponseSerializer,
             404: CompanyErrorResponseSerializer,
             500: CompanyErrorResponseSerializer,
         },
         tags=["Companies"],
     ),
     put=extend_schema(
-        summary="Update job contact",
-        description="Update the contact person associated with a specific job.",
+        summary="Update job person",
+        description="Update the person associated with a specific job.",
         parameters=[
             OpenApiParameter(
                 name="job_id",
@@ -535,35 +537,35 @@ def post(self, request: Request) -> Response:
                 type=OpenApiTypes.UUID,
             )
         ],
-        request=JobContactUpdateSerializer,
+        request=JobPersonUpdateSerializer,
         responses={
-            200: JobContactResponseSerializer,
+            200: JobPersonResponseSerializer,
             400: CompanyErrorResponseSerializer,
             404: CompanyErrorResponseSerializer,
             500: CompanyErrorResponseSerializer,
         },
         tags=["Companies"],
-        operation_id="companies_jobs_contact_update",
+        operation_id="companies_jobs_person_update",
     ),
 )
-class JobContactRestView(APIView):
+class JobPersonRestView(APIView):
     """
-    REST view for contact information operations for a job.
-    Handles both retrieving and updating the contact associated with a specific job.
+    REST view for person information operations for a job.
+    Handles both retrieving and updating the person associated with a specific job.
     """
 
     permission_classes = [IsAuthenticated]
-    serializer_class = JobContactResponseSerializer
+    serializer_class = JobPersonResponseSerializer
 
     def get_serializer_class(self):
         """Return the appropriate serializer class based on the request method"""
         if self.request.method == "PUT":
-            return JobContactUpdateSerializer
-        return JobContactResponseSerializer
+            return JobPersonUpdateSerializer
+        return JobPersonResponseSerializer
 
-    def get(self, request: Request, job_id: str) -> Response:
+    def get(self, request: Request, job_id: UUID) -> Response:
         """
-        Retrieves contact information for a specific job.
+        Retrieves person information for a specific job.
         """
         try:
             # Guard clause: validate job_id
@@ -576,8 +578,8 @@ def get(self, request: Request, job_id: str) -> Response:
                     error_serializer.data, status=status.HTTP_400_BAD_REQUEST
                 )
 
-            contact_data = CompanyRestService.get_job_contact(job_id)
-            serializer = JobContactResponseSerializer(data=contact_data)
+            person_data = CompanyRestService.get_job_person(job_id)
+            serializer = JobPersonResponseSerializer(data=person_data)
             serializer.is_valid(raise_exception=True)
             return Response(serializer.data)
 
@@ -587,12 +589,12 @@ def get(self, request: Request, job_id: str) -> Response:
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as exc:
             return _build_server_error_response(
-                message="Error retrieving job contact", exc=exc
+                message="Error retrieving job person", exc=exc
             )
 
-    def put(self, request: Request, job_id: str) -> Response:
+    def put(self, request: Request, job_id: UUID) -> Response:
         """
-        Updates the contact person for a specific job.
+        Updates the person for a specific job.
         """
         try:
             # Guard clause: validate job_id
@@ -606,7 +608,7 @@ def put(self, request: Request, job_id: str) -> Response:
                 )
 
             # Validate input data
-            input_serializer = JobContactUpdateSerializer(data=request.data)
+            input_serializer = JobPersonUpdateSerializer(data=request.data)
             if not input_serializer.is_valid():
                 error_serializer = CompanyErrorResponseSerializer(
                     data={"error": f"Invalid input data: {input_serializer.errors}"}
@@ -616,11 +618,19 @@ def put(self, request: Request, job_id: str) -> Response:
                     error_serializer.data, status=status.HTTP_400_BAD_REQUEST
                 )
 
-            contact_data = input_serializer.validated_data
-            updated_contact = CompanyRestService.update_job_contact(
-                job_id, contact_data, request.user
+            person_data = input_serializer.validated_data
+            if not isinstance(request.user, Staff):
+                error_serializer = CompanyErrorResponseSerializer(
+                    data={"error": "Authentication required"}
+                )
+                error_serializer.is_valid(raise_exception=True)
+                return Response(
+                    error_serializer.data, status=status.HTTP_401_UNAUTHORIZED
+                )
+            updated_person = CompanyRestService.update_job_person(
+                job_id, person_data, request.user
             )
-            serializer = JobContactResponseSerializer(data=updated_contact)
+            serializer = JobPersonResponseSerializer(data=updated_person)
             serializer.is_valid(raise_exception=True)
             return Response(serializer.data)
 
@@ -630,7 +640,7 @@ def put(self, request: Request, job_id: str) -> Response:
             return Response(error_serializer.data, status=status.HTTP_404_NOT_FOUND)
         except Exception as exc:
             return _build_server_error_response(
-                message="Error updating job contact", exc=exc
+                message="Error updating job person", exc=exc
             )
 
 
diff --git a/apps/company/views/contact_method_viewset.py b/apps/company/views/contact_method_viewset.py
index 9632547a9..920d12bd7 100644
--- a/apps/company/views/contact_method_viewset.py
+++ b/apps/company/views/contact_method_viewset.py
@@ -1,4 +1,4 @@
-"""Company/contact contact method ViewSet."""
+"""Company/person contact method ViewSet."""
 
 from typing import cast
 
@@ -7,27 +7,27 @@
 from rest_framework import permissions, viewsets
 from rest_framework.serializers import BaseSerializer
 
-from apps.company.models import ClientContactMethod
-from apps.company.serializers import ClientContactMethodSerializer
+from apps.company.models import ContactMethod
+from apps.company.serializers import ContactMethodSerializer
 from apps.crm.tasks import rematch_phone_calls_task
 from apps.workflow.api.pagination import PageSizePagination
 
 
-def _phone_number_for_rematch(method: ClientContactMethod | None) -> str | None:
+def _phone_number_for_rematch(method: ContactMethod | None) -> str | None:
     if method is None:
         return None
-    if method.method_type != ClientContactMethod.MethodType.PHONE:
+    if method.method_type != ContactMethod.MethodType.PHONE:
         return None
     normalized = method.normalized_value
     if normalized:
         return normalized
-    return ClientContactMethod.normalize_phone(method.value)
+    return ContactMethod.normalize_phone(method.value)
 
 
-class ClientContactMethodViewSet(viewsets.ModelViewSet):
-    """CRUD API for canonical company/contact phone and email methods."""
+class ContactMethodViewSet(viewsets.ModelViewSet):
+    """CRUD API for canonical company/person phone and email methods."""
 
-    serializer_class = ClientContactMethodSerializer
+    serializer_class = ContactMethodSerializer
     permission_classes = [permissions.IsAuthenticated]
     pagination_class = PageSizePagination
 
@@ -40,7 +40,7 @@ class ClientContactMethodViewSet(viewsets.ModelViewSet):
                 required=False,
             ),
             OpenApiParameter(
-                name="contact_id",
+                name="person_id",
                 type=OpenApiTypes.UUID,
                 location=OpenApiParameter.QUERY,
                 required=False,
@@ -69,24 +69,16 @@ def list(self, request, *args, **kwargs):
         return super().list(request, *args, **kwargs)
 
     def get_queryset(self):
-        queryset = ClientContactMethod.objects.select_related(
+        queryset = ContactMethod.objects.select_related(
             "company",
-            "contact",
-            "contact__company",
             "person",
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:
-            queryset = (
-                queryset.filter(company_id=company_id)
-                | queryset.filter(contact__company_id=company_id)
-                | queryset.filter(person__company_links__company_id=company_id)
+            queryset = queryset.filter(company_id=company_id) | queryset.filter(
+                person__company_links__company_id=company_id
             )
 
-        contact_id = self.request.query_params.get("contact_id")
-        if contact_id:
-            queryset = queryset.filter(contact_id=contact_id)
-
         person_id = self.request.query_params.get("person_id")
         if person_id:
             queryset = queryset.filter(person_id=person_id)
@@ -97,14 +89,14 @@ def get_queryset(self):
 
         return queryset.distinct().order_by("method_type", "-is_primary", "value")
 
-    def perform_create(self, serializer: BaseSerializer[ClientContactMethod]) -> None:
+    def perform_create(self, serializer: BaseSerializer[ContactMethod]) -> None:
         method = serializer.save()
         phone_number = _phone_number_for_rematch(method)
         if phone_number:
             rematch_phone_calls_task.delay([phone_number])
 
-    def perform_update(self, serializer: BaseSerializer[ClientContactMethod]) -> None:
-        old_method = cast(ClientContactMethod, self.get_object())
+    def perform_update(self, serializer: BaseSerializer[ContactMethod]) -> None:
+        old_method = cast(ContactMethod, self.get_object())
         old_phone_number = _phone_number_for_rematch(old_method)
         method = serializer.save()
         new_phone_number = _phone_number_for_rematch(method)
@@ -114,7 +106,7 @@ def perform_update(self, serializer: BaseSerializer[ClientContactMethod]) -> Non
         if phone_numbers:
             rematch_phone_calls_task.delay(phone_numbers)
 
-    def perform_destroy(self, instance: ClientContactMethod) -> None:
+    def perform_destroy(self, instance: ContactMethod) -> None:
         phone_number = _phone_number_for_rematch(instance)
         instance.delete()
         if phone_number:
diff --git a/apps/company/views/contact_viewset.py b/apps/company/views/contact_viewset.py
index 3ff2351d5..164bee66a 100644
--- a/apps/company/views/contact_viewset.py
+++ b/apps/company/views/contact_viewset.py
@@ -1,7 +1,7 @@
 """
-ClientContact ViewSet
+CompanyPersonLink ViewSet
 
-ViewSet for ClientContact CRUD operations using DRF's ModelViewSet.
+ViewSet for CompanyPersonLink CRUD operations using DRF's ModelViewSet.
 Provides list, create, retrieve, update, partial_update, and destroy actions.
 """
 
@@ -9,28 +9,28 @@
 from drf_spectacular.utils import OpenApiParameter, extend_schema
 from rest_framework import permissions, viewsets
 
-from apps.company.models import ClientContact, ClientContactMethod
-from apps.company.serializers import ClientContactSerializer
+from apps.company.models import CompanyPersonLink, ContactMethod
+from apps.company.serializers import CompanyPersonLinkSerializer
 
 
-class ClientContactViewSet(viewsets.ModelViewSet):
+class CompanyPersonLinkViewSet(viewsets.ModelViewSet):
     """
-    ViewSet for ClientContact CRUD operations.
+    ViewSet for CompanyPersonLink CRUD operations.
 
     Endpoints:
-    - GET    /api/companies/contacts/           - list all contacts
-    - POST   /api/companies/contacts/           - create contact
-    - GET    /api/companies/contacts/<id>/      - retrieve contact
-    - PUT    /api/companies/contacts/<id>/      - full update
-    - PATCH  /api/companies/contacts/<id>/      - partial update
-    - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+    - GET    /api/companies/person-links/       - list all company-person links
+    - POST   /api/companies/person-links/       - create link
+    - GET    /api/companies/person-links/<id>/  - retrieve link
+    - PUT    /api/companies/person-links/<id>/  - full update
+    - PATCH  /api/companies/person-links/<id>/  - partial update
+    - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
     Query Parameters:
-    - company_id: Filter contacts by company UUID
+    - company_id: Filter links by company UUID
     """
 
-    queryset = ClientContact.objects.filter(is_active=True)
-    serializer_class = ClientContactSerializer
+    queryset = CompanyPersonLink.objects.filter(is_active=True)
+    serializer_class = CompanyPersonLinkSerializer
     permission_classes = [permissions.IsAuthenticated]
 
     @extend_schema(
@@ -39,26 +39,28 @@ class ClientContactViewSet(viewsets.ModelViewSet):
                 name="company_id",
                 type=OpenApiTypes.UUID,
                 location=OpenApiParameter.QUERY,
-                description="Filter contacts by company UUID",
+                description="Filter links by company UUID",
                 required=False,
             ),
         ]
     )
     def list(self, request, *args, **kwargs):
-        """List all contacts, optionally filtered by company_id."""
+        """List all company-person links, optionally filtered by company_id."""
         return super().list(request, *args, **kwargs)
 
     def get_queryset(self):
         """
-        Filter to only active contacts, optionally filtered by company_id.
+        Filter to only active links, optionally filtered by company_id.
         """
-        queryset = ClientContact.objects.filter(is_active=True).annotate(
-            phone=ClientContactMethod.primary_phone_for_link_annotation()
+        queryset = (
+            CompanyPersonLink.objects.filter(is_active=True)
+            .select_related("person")
+            .annotate(phone=ContactMethod.primary_phone_for_link_annotation())
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:
             queryset = queryset.filter(company_id=company_id)
-        return queryset.order_by("-is_primary", "name")
+        return queryset.order_by("-is_primary", "person__name")
 
     def perform_destroy(self, instance):
         """
diff --git a/apps/crm/migrations/0006_remove_phonecallrecord_contact_and_more.py b/apps/crm/migrations/0006_remove_phonecallrecord_contact_and_more.py
new file mode 100644
index 000000000..12a1d148d
--- /dev/null
+++ b/apps/crm/migrations/0006_remove_phonecallrecord_contact_and_more.py
@@ -0,0 +1,62 @@
+# Generated by Django 6.0.4 on 2026-07-08 22:47
+
+from typing import Any
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+def repair_call_people(apps: Any, schema_editor: Any) -> None:
+    PhoneCallRecord = apps.get_model("crm", "PhoneCallRecord")
+    CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
+
+    link_person_by_id = dict(
+        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
+            "id", "person_id"
+        )
+    )
+    calls = PhoneCallRecord.objects.filter(person__isnull=True).exclude(
+        contact__isnull=True
+    )
+    for call in calls.iterator():
+        person_id = link_person_by_id.get(call.contact_id)
+        if person_id is not None:
+            call.person_id = person_id
+            call.save(update_fields=["person"])
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0006_alter_companypersonlink_options_and_more"),
+        ("crm", "0005_phonecallrecord_person_alter_phonecallrecord_contact"),
+    ]
+
+    operations = [
+        migrations.RunPython(repair_call_people, migrations.RunPython.noop),
+        migrations.RemoveIndex(
+            model_name="phonecallrecord",
+            name="crm_phone_contact_call_idx",
+        ),
+        migrations.RemoveField(
+            model_name="phonecallrecord",
+            name="contact",
+        ),
+        migrations.AlterField(
+            model_name="phonecallrecord",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="phone_calls",
+                to="company.person",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="phonecallrecord",
+            index=models.Index(
+                fields=["person", "-call_datetime"], name="crm_phone_person_call_idx"
+            ),
+        ),
+    ]
diff --git a/apps/crm/models.py b/apps/crm/models.py
index 1fd0e3354..b507fafb0 100644
--- a/apps/crm/models.py
+++ b/apps/crm/models.py
@@ -61,18 +61,16 @@ def save(
         using: str | None = None,
         update_fields: Iterable[str] | None = None,
     ) -> None:
-        from apps.company.models import ClientContactMethod
+        from apps.company.models import ContactMethod
 
-        self.normalized_number = ClientContactMethod.normalize_phone(self.number)
+        self.normalized_number = ContactMethod.normalize_phone(self.number)
         if not self.normalized_number:
             raise ValueError("phone endpoint requires a phone number")
         if self.is_active and self._active_number_changed():
-            # Mirror of the ClientContactMethod.save() guard: a number cannot be
+            # Mirror of the ContactMethod.save() guard: a number cannot be
             # both a company contact method and an active internal endpoint, or
             # the company's calls would silently reclassify as INTERNAL.
-            conflict = ClientContactMethod.conflicting_company(
-                self.normalized_number, set()
-            )
+            conflict = ContactMethod.conflicting_company(self.normalized_number, set())
             if conflict:
                 raise ValidationError(
                     f"phone number {self.normalized_number} already belongs to "
@@ -90,7 +88,7 @@ def _active_number_changed(self) -> bool:
         """True when the endpoint is new or its number/is_active changed.
 
         Grandfathers pre-existing rows (symmetry with the grandfathering in
-        ClientContactMethod.check_phone_assignment): re-saving an existing
+        ContactMethod.check_phone_assignment): re-saving an existing
         endpoint without touching number or is_active must not start failing.
         """
         if self._state.adding:
@@ -188,19 +186,12 @@ class Direction(models.TextChoices):
         blank=True,
         related_name="phone_calls",
     )
-    contact = models.ForeignKey(
-        "company.CompanyPersonLink",
-        on_delete=models.SET_NULL,
-        null=True,
-        blank=True,
-        related_name="phone_calls",
-    )
     person = models.ForeignKey(
         "company.Person",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
-        related_name="person_phone_calls",
+        related_name="phone_calls",
     )
     job = models.ForeignKey(
         "job.Job",
@@ -233,8 +224,8 @@ class Meta:
                 name="crm_phone_company_call_idx",
             ),
             models.Index(
-                fields=["contact", "-call_datetime"],
-                name="crm_phone_contact_call_idx",
+                fields=["person", "-call_datetime"],
+                name="crm_phone_person_call_idx",
             ),
             models.Index(
                 fields=["job", "-call_datetime"],
@@ -270,12 +261,10 @@ def save(
         using: str | None = None,
         update_fields: Iterable[str] | None = None,
     ) -> None:
-        from apps.company.models import ClientContactMethod
+        from apps.company.models import ContactMethod
 
-        self.normalized_origin = ClientContactMethod.normalize_phone(self.origin)
-        self.normalized_destination = ClientContactMethod.normalize_phone(
-            self.destination
-        )
+        self.normalized_origin = ContactMethod.normalize_phone(self.origin)
+        self.normalized_destination = ContactMethod.normalize_phone(self.destination)
         if update_fields is not None:
             fields = set(update_fields)
             if "origin" in fields:
diff --git a/apps/crm/serializers.py b/apps/crm/serializers.py
index 5f316f914..5e9b3056f 100644
--- a/apps/crm/serializers.py
+++ b/apps/crm/serializers.py
@@ -3,7 +3,7 @@
 from drf_spectacular.utils import extend_schema_field
 from rest_framework import serializers
 
-from apps.company.models import ClientContactMethod
+from apps.company.models import ContactMethod
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -28,7 +28,7 @@ class PhoneNumberAssignmentSerializer(serializers.Serializer[None]):
     """Request body for assigning a call's external number to a company."""
 
     company = serializers.UUIDField()
-    contact = serializers.UUIDField(required=False, allow_null=True, default=None)
+    person = serializers.UUIDField(required=False, allow_null=True, default=None)
     is_primary = serializers.BooleanField(required=False, default=False)
 
     def get_fields(self) -> dict[str, "serializers.Field[Any, Any, Any, Any]"]:
@@ -150,7 +150,7 @@ def validate(self, attrs: "PhoneEndpointAttrs") -> "PhoneEndpointAttrs":
             return attrs  # association unchanged — grandfathered, like save()
 
         if is_active:
-            conflict = ClientContactMethod.conflicting_company(normalized, set())
+            conflict = ContactMethod.conflicting_company(normalized, set())
             if conflict:
                 raise serializers.ValidationError(
                     {
@@ -243,7 +243,6 @@ class PhoneCallRecordSerializer(serializers.ModelSerializer[PhoneCallRecord]):
 
     recording = serializers.SerializerMethodField()
     company_name = serializers.SerializerMethodField()
-    contact_name = serializers.SerializerMethodField()
     person_name = serializers.SerializerMethodField()
     origin_endpoint_label = serializers.SerializerMethodField()
     destination_endpoint_label = serializers.SerializerMethodField()
@@ -276,8 +275,6 @@ class Meta:
             "charge",
             "company",
             "company_name",
-            "contact",
-            "contact_name",
             "person",
             "person_name",
             "job",
@@ -295,9 +292,6 @@ class Meta:
     def get_company_name(self, obj: PhoneCallRecord) -> str:
         return obj.company.name if obj.company else ""
 
-    def get_contact_name(self, obj: PhoneCallRecord) -> str:
-        return obj.contact.name if obj.contact else ""
-
     def get_person_name(self, obj: PhoneCallRecord) -> str:
         return obj.person.name if obj.person else ""
 
diff --git a/apps/crm/services/phone_call_service.py b/apps/crm/services/phone_call_service.py
index 557579f40..6f95257dd 100644
--- a/apps/crm/services/phone_call_service.py
+++ b/apps/crm/services/phone_call_service.py
@@ -16,7 +16,7 @@
 from django.db import models, transaction
 from django.utils import timezone
 
-from apps.company.models import ClientContact, ClientContactMethod, Company, Person
+from apps.company.models import Company, ContactMethod, Person
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -310,7 +310,7 @@ def assign_phone_number_from_call(
     *,
     call_id: str,
     company_id: str,
-    contact_id: str | None = None,
+    person_id: str | None = None,
     label: str = "",
     is_primary: bool = False,
 ) -> PhoneCallRecord:
@@ -326,7 +326,7 @@ def assign_phone_number_from_call(
     assign_phone_number(
         phone_number=call.external_number,
         company_id=company_id,
-        contact_id=contact_id,
+        person_id=person_id,
         label=label,
         is_primary=is_primary,
     )
@@ -525,7 +525,6 @@ def upsert_call_record(
         "duration_seconds": _positive_int(payload.get("seconds")),
         "charge": _decimal_or_none(payload.get("charge")),
         "company": classification.company,
-        "contact": classification.contact,
         "person": classification.person,
         "raw_json": payload,
     }
@@ -597,7 +596,6 @@ class CallClassification:
     origin_endpoint: PhoneEndpoint | None
     destination_endpoint: PhoneEndpoint | None
     company: Company | None
-    contact: ClientContact | None
     person: Person | None
 
 
@@ -617,15 +615,7 @@ def __init__(self, numbers: set[str] | None = None):
             for endpoint in PhoneEndpoint.objects.filter(is_active=True)
         }
 
-    def match_customer(
-        self, *values: str
-    ) -> tuple[Company | None, ClientContact | None]:
-        company, contact, _person = self.match_customer_details(*values)
-        return company, contact
-
-    def match_customer_details(
-        self, *values: str
-    ) -> tuple[Company | None, ClientContact | None, Person | None]:
+    def match_customer(self, *values: str) -> tuple[Company | None, Person | None]:
         matches: set[tuple[str, str, str]] = set()
         for value in values:
             normalized = normalize_phone(value)
@@ -634,26 +624,23 @@ def match_customer_details(
             matches.update(self.phone_matches.get(normalized, set()))
 
         if not matches:
-            return None, None, None
+            return None, None
 
         company_ids = {company_id for _, _, company_id in matches}
         if len(company_ids) != 1:
-            return None, None, None
+            return None, None
 
         if len(matches) != 1:
             company = Company.objects.get(id=next(iter(company_ids)))
-            return company, None, None
+            return company, None
 
         kind, object_id, _company_id = next(iter(matches))
-        if kind == "contact":
-            contact = ClientContact.objects.select_related("company").get(id=object_id)
-            return contact.company, contact, contact.person
         if kind == "person":
             person = Person.objects.get(id=object_id)
             company = Company.objects.get(id=next(iter(company_ids)))
-            return company, None, person
+            return company, person
         company = Company.objects.get(id=object_id)
-        return company, None, None
+        return company, None
 
     def classify(self, origin: str, destination: str) -> CallClassification:
         normalized_origin = normalize_phone(origin)
@@ -669,14 +656,11 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 origin_endpoint=origin_endpoint,
                 destination_endpoint=destination_endpoint,
                 company=None,
-                contact=None,
                 person=None,
             )
 
         if origin_endpoint:
-            company, contact, person = self.match_customer_details(
-                normalized_destination
-            )
+            company, person = self.match_customer(normalized_destination)
             return CallClassification(
                 direction=PhoneCallRecord.Direction.OUTBOUND,
                 our_number=normalized_origin,
@@ -684,12 +668,11 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 origin_endpoint=origin_endpoint,
                 destination_endpoint=None,
                 company=company,
-                contact=contact,
                 person=person,
             )
 
         if destination_endpoint:
-            company, contact, person = self.match_customer_details(normalized_origin)
+            company, person = self.match_customer(normalized_origin)
             return CallClassification(
                 direction=PhoneCallRecord.Direction.INBOUND,
                 our_number=normalized_destination,
@@ -697,13 +680,10 @@ def classify(self, origin: str, destination: str) -> CallClassification:
                 origin_endpoint=None,
                 destination_endpoint=destination_endpoint,
                 company=company,
-                contact=contact,
                 person=person,
             )
 
-        company, contact, person = self.match_customer_details(
-            normalized_origin, normalized_destination
-        )
+        company, person = self.match_customer(normalized_origin, normalized_destination)
         external_number = ""
         if normalized_origin and not normalized_destination:
             external_number = normalized_origin
@@ -718,7 +698,6 @@ def classify(self, origin: str, destination: str) -> CallClassification:
             origin_endpoint=None,
             destination_endpoint=None,
             company=company,
-            contact=contact,
             person=person,
         )
 
@@ -732,7 +711,7 @@ def is_call_payload(payload: dict[str, Any]) -> bool:
 
 
 def normalize_phone(value: Any) -> str:
-    return ClientContactMethod.normalize_phone(value)
+    return ContactMethod.normalize_phone(value)
 
 
 def configured_own_numbers() -> set[str]:
@@ -744,7 +723,7 @@ def configured_own_numbers() -> set[str]:
 
 
 _REMATCH_FK_FIELDS = frozenset(
-    {"company", "contact", "person", "origin_endpoint", "destination_endpoint"}
+    {"company", "person", "origin_endpoint", "destination_endpoint"}
 )
 
 
@@ -785,7 +764,6 @@ def rematch_calls_for_numbers(numbers: list[str]) -> None:
         )
         new_values: dict[str, object] = {
             "company": classification.company,
-            "contact": classification.contact,
             "person": classification.person,
             "direction": classification.direction,
             "our_number": classification.our_number,
@@ -820,10 +798,10 @@ def assign_phone_number(
     *,
     phone_number: str,
     company_id: str,
-    contact_id: str | None = None,
+    person_id: str | None = None,
     label: str = "",
     is_primary: bool = False,
-) -> ClientContactMethod:
+) -> ContactMethod:
     normalized = normalize_phone(phone_number)
     if not normalized:
         raise ValueError("phone number is required")
@@ -831,24 +809,22 @@ def assign_phone_number(
         raise ValueError("internal phone endpoint cannot be assigned to a company")
 
     company_uuid = _uuid_or_client_error(company_id, "Company not found")
-    if contact_id:
-        contact_uuid = _uuid_or_client_error(contact_id, "Contact not found")
+    owner_filter: dict[str, Company | Person | None]
+    if person_id:
+        person_uuid = _uuid_or_client_error(person_id, "Person not found")
         try:
-            contact = ClientContact.objects.select_related("company").get(
-                id=contact_uuid,
-                company_id=company_uuid,
-                is_active=True,
-            )
-        except ClientContact.DoesNotExist as exc:
-            raise ValueError("Contact not found") from exc
+            person = Person.objects.get(id=person_uuid, is_active=True)
+        except Person.DoesNotExist as exc:
+            raise ValueError("Person not found") from exc
+        if not person.company_links.filter(company_id=company_uuid).exists():
+            raise ValueError("Person is not linked to the selected company")
         owner_filter = {
-            "contact": contact,
-            "person": contact.person,
+            "person": person,
             "company": None,
         }
-        existing_primary = ClientContactMethod.objects.filter(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        existing_primary = ContactMethod.objects.filter(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
             is_primary=True,
         ).exists()
     else:
@@ -856,36 +832,36 @@ def assign_phone_number(
             company = Company.objects.get(id=company_uuid)
         except Company.DoesNotExist as exc:
             raise ValueError("Company not found") from exc
-        owner_filter = {"company": company, "contact": None, "person": None}
-        existing_primary = ClientContactMethod.objects.filter(
+        owner_filter = {"company": company, "person": None}
+        existing_primary = ContactMethod.objects.filter(
             company=company,
-            contact__isnull=True,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            person__isnull=True,
+            method_type=ContactMethod.MethodType.PHONE,
             is_primary=True,
         ).exists()
 
     should_be_primary = is_primary or not existing_primary
-    conflict = ClientContactMethod.conflicting_company(normalized, {company_uuid})
+    conflict = ContactMethod.conflicting_company(normalized, {company_uuid})
     if conflict:
         raise ValueError(
             f"phone number already belongs to {conflict.owner_display_name()}"
         )
 
-    method, created = ClientContactMethod.objects.get_or_create(
+    method, created = ContactMethod.objects.get_or_create(
         **owner_filter,
-        method_type=ClientContactMethod.MethodType.PHONE,
+        method_type=ContactMethod.MethodType.PHONE,
         normalized_value=normalized,
         defaults={
             "value": phone_number.strip(),
             "label": label.strip(),
             "is_primary": should_be_primary,
-            "source": ClientContactMethod.Source.LOCAL,
+            "source": ContactMethod.Source.LOCAL,
         },
     )
     if not created:
         method.value = phone_number.strip()
         method.label = label.strip()
-        method.source = ClientContactMethod.Source.LOCAL
+        method.source = ContactMethod.Source.LOCAL
         method.is_primary = should_be_primary or method.is_primary
         method.save(
             update_fields=["value", "label", "source", "is_primary", "updated_at"]
@@ -905,12 +881,10 @@ def _build_contact_method_phone_index(
     """
     index: dict[str, set[tuple[str, str, str]]] = {}
     internal_numbers = configured_own_numbers()
-    methods = ClientContactMethod.objects.select_related(
+    methods = ContactMethod.objects.select_related(
         "company",
-        "contact",
-        "contact__company",
         "person",
-    ).filter(method_type=ClientContactMethod.MethodType.PHONE)
+    ).filter(method_type=ContactMethod.MethodType.PHONE)
     if numbers is not None:
         methods = methods.filter(normalized_value__in=numbers)
     for method in methods:
@@ -918,21 +892,21 @@ def _build_contact_method_phone_index(
         if not normalized or normalized in internal_numbers:
             continue
         if method.person_id:
-            if not method.person.is_active:
+            person = method.person
+            if person is None:
+                raise RuntimeError(f"Contact method {method.id} has no person")
+            if not person.is_active:
                 continue
             company_ids = method.owner_company_ids()
             for company_id in company_ids:
                 index.setdefault(normalized, set()).add(
                     ("person", str(method.person_id), str(company_id))
                 )
-        elif method.contact_id:
-            if not method.contact.is_active:
-                continue
-            index.setdefault(normalized, set()).add(
-                ("contact", str(method.contact_id), str(method.contact.company_id))
-            )
         else:
-            if not method.company.allow_jobs:
+            company = method.company
+            if company is None:
+                raise RuntimeError(f"Contact method {method.id} has no company")
+            if not company.allow_jobs:
                 continue
             index.setdefault(normalized, set()).add(
                 ("company", str(method.company_id), str(method.company_id))
diff --git a/apps/crm/tests/test_phone_call_service.py b/apps/crm/tests/test_phone_call_service.py
index 23b7d2eb5..8741f73dc 100644
--- a/apps/crm/tests/test_phone_call_service.py
+++ b/apps/crm/tests/test_phone_call_service.py
@@ -10,7 +10,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -83,12 +83,20 @@ def test_normalize_phone_matches_nz_variants_by_local_tail(self) -> None:
 class PhoneMatcherDatabaseTests(TestCase):
     """Business case: call records drive customer history. The matcher should
     attach calls when ownership is unambiguous, and refuse ambiguous matches so
-    one company's calls are not shown under another company or contact.
+    one company's calls are not shown under another company or person.
     """
 
     def _client(self, name: str) -> Company:
         return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
+    def _link(self, company: Company, name: str) -> CompanyPersonLink:
+        person = Person.objects.create(name=name)
+        return CompanyPersonLink.objects.create(
+            company=company,
+            person=person,
+            xero_name=name,
+        )
+
     def test_assign_phone_number_creates_primary_contact_method_and_matches_client(
         self,
     ) -> None:
@@ -112,16 +120,16 @@ def test_assign_phone_number_creates_primary_contact_method_and_matches_client(
     def test_assign_number_allowed_on_contact_of_owning_client(self) -> None:
         """Assigning a company's number to one of its own contacts is not a conflict."""
         company = self._client("Acme Ltd")
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
+        person = self._link(company, "Jane Smith")
         assign_phone_number(phone_number="021 555 900", company_id=str(company.id))
 
         method = assign_phone_number(
             phone_number="021 555 900",
             company_id=str(company.id),
-            contact_id=str(contact.id),
+            person_id=str(person.person_id),
         )
 
-        self.assertEqual(method.contact_id, contact.id)
+        self.assertEqual(method.person_id, person.person_id)
 
     def test_assign_number_rejected_for_different_client(self) -> None:
         """A number owned by one company cannot be assigned to a different company."""
@@ -134,10 +142,10 @@ def test_assign_number_rejected_for_different_client(self) -> None:
 
     def test_single_contact_method_matches_contact(self) -> None:
         company = self._client("Acme Ltd")
-        contact = ClientContact.objects.create(company=company, name="Jane Smith")
-        ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        person = self._link(company, "Jane Smith")
+        ContactMethod.objects.create(
+            person=person.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
             is_primary=True,
         )
@@ -148,23 +156,23 @@ def test_single_contact_method_matches_contact(self) -> None:
         )
 
         self.assertEqual(matched_company, company)
-        self.assertEqual(matched_contact, contact)
+        self.assertEqual(matched_contact, person.person)
 
     def test_same_number_across_contacts_on_one_client_is_allowed(
         self,
     ) -> None:
         """Two contacts of one company resolve to a single effective company owner."""
         company = self._client("Acme Ltd")
-        jane = ClientContact.objects.create(company=company, name="Jane Smith")
-        john = ClientContact.objects.create(company=company, name="John Smith")
-        ClientContactMethod.objects.create(
-            contact=jane,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        jane = self._link(company, "Jane Smith")
+        john = self._link(company, "John Smith")
+        ContactMethod.objects.create(
+            person=jane.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        on_john = ClientContactMethod.objects.create(
-            contact=john,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        on_john = ContactMethod.objects.create(
+            person=john.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
 
@@ -177,16 +185,16 @@ def test_same_number_across_contacts_on_one_client_is_allowed(
     def test_same_number_across_clients_is_rejected(self) -> None:
         first = self._client("Acme Ltd")
         second = self._client("Beta Ltd")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=first,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
 
         with self.assertRaises(ValidationError):
-            ClientContactMethod.objects.create(
+            ContactMethod.objects.create(
                 company=second,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 value="021 555 123",
             )
 
@@ -221,9 +229,9 @@ def test_rematch_clears_job_link_when_number_moves_to_other_client(
             is_office_staff=True,
         )
         job = Job.objects.create(company=first, name="Linked Job", staff=staff)
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=second,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="+6421555123",
             normalized_value="+6421555123",
         )
@@ -251,7 +259,7 @@ def test_rematch_clears_job_link_when_number_moves_to_other_client(
 
         call.refresh_from_db()
         self.assertEqual(call.company, second)
-        self.assertIsNone(call.contact)
+        self.assertIsNone(call.person)
         self.assertIsNone(call.job)
         self.assertIsNone(call.job_linked_by)
         self.assertIsNone(call.job_linked_at)
@@ -384,9 +392,9 @@ def test_sync_archives_recording_and_is_idempotent(self) -> None:
             name="Sync Company",
             xero_last_modified=timezone.now(),
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
         payload = self._payload()
@@ -754,7 +762,7 @@ def test_malformed_call_id_on_unlink_does_not_persist_app_error(self) -> None:
         self.assertIn("Phone call not found", response.data["message"])
         self.assertEqual(AppError.objects.count(), before)
 
-    def test_assign_number_bad_client_id_does_not_persist_app_error(self) -> None:
+    def test_assign_number_bad_company_id_does_not_persist_app_error(self) -> None:
         self.call.external_number = "+6421555000"
         self.call.save(update_fields=["external_number", "updated_at"])
         before = AppError.objects.count()
@@ -771,14 +779,16 @@ def test_assign_number_bad_client_id_does_not_persist_app_error(self) -> None:
         self.assertIn("Company not found", response.data["message"])
         self.assertEqual(AppError.objects.count(), before)
 
-    def test_assign_number_cross_client_contact_does_not_persist_app_error(
+    def test_assign_number_cross_company_person_does_not_persist_app_error(
         self,
     ) -> None:
         self.call.external_number = "+6421555001"
         self.call.save(update_fields=["external_number", "updated_at"])
-        contact = ClientContact.objects.create(
+        person = Person.objects.create(name="Other Contact")
+        CompanyPersonLink.objects.create(
             company=self.other_company,
-            name="Other Contact",
+            person=person,
+            xero_name=person.name,
         )
         before = AppError.objects.count()
 
@@ -786,13 +796,15 @@ def test_assign_number_cross_client_contact_does_not_persist_app_error(
             f"/api/crm/phone-calls/{self.call.id}/assign-number/",
             {
                 "company": str(self.company_obj.id),
-                "contact": str(contact.id),
+                "person": str(person.id),
             },
             format="json",
         )
 
         self.assertEqual(response.status_code, 400)
-        self.assertIn("Contact not found", response.data["message"])
+        self.assertIn(
+            "Person is not linked to the selected company", response.data["message"]
+        )
         self.assertEqual(AppError.objects.count(), before)
 
     def test_link_rejects_unmatched_call(self) -> None:
diff --git a/apps/crm/tests/test_phone_endpoint_guard.py b/apps/crm/tests/test_phone_endpoint_guard.py
index 2a544321a..eeac79478 100644
--- a/apps/crm/tests/test_phone_endpoint_guard.py
+++ b/apps/crm/tests/test_phone_endpoint_guard.py
@@ -1,6 +1,6 @@
 """One-number-one-owner symmetry: PhoneEndpoint side of the guard.
 
-ClientContactMethod.save() refuses numbers held by an active PhoneEndpoint;
+ContactMethod.save() refuses numbers held by an active PhoneEndpoint;
 these tests cover the mirror — an active endpoint cannot claim a number a
 company already owns, or that company's calls silently become INTERNAL.
 """
@@ -11,7 +11,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.crm.models import PhoneEndpoint
 from apps.testing import BaseAPITestCase
 
@@ -20,14 +20,23 @@ def _client(name: str = "Acme Ltd") -> Company:
     return Company.objects.create(name=name, xero_last_modified=timezone.now())
 
 
-def _client_phone(company: Company, value: str = "021 555 123") -> ClientContactMethod:
-    return ClientContactMethod.objects.create(
+def _client_phone(company: Company, value: str = "021 555 123") -> ContactMethod:
+    return ContactMethod.objects.create(
         company=company,
-        method_type=ClientContactMethod.MethodType.PHONE,
+        method_type=ContactMethod.MethodType.PHONE,
         value=value,
     )
 
 
+def _link(company: Company, name: str) -> CompanyPersonLink:
+    person = Person.objects.create(name=name)
+    return CompanyPersonLink.objects.create(
+        company=company,
+        person=person,
+        xero_name=name,
+    )
+
+
 def _endpoint(number: str, **overrides: object) -> PhoneEndpoint:
     fields: dict[str, object] = {
         "number": number,
@@ -48,16 +57,14 @@ def test_create_active_endpoint_over_client_number_raises(self) -> None:
             _endpoint("021 555 123")
 
     def test_error_names_owning_contact(self) -> None:
-        contact = ClientContact.objects.create(
-            company=_client("Acme Ltd"), name="Jane Smith"
-        )
-        ClientContactMethod.objects.create(
-            contact=contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        contact = _link(_client("Acme Ltd"), "Jane Smith")
+        ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
 
-        with self.assertRaisesRegex(ValidationError, "contact Jane Smith at Acme Ltd"):
+        with self.assertRaisesRegex(ValidationError, "person Jane Smith"):
             _endpoint("021 555 123")
 
     def test_inactive_endpoint_over_client_number_is_allowed(self) -> None:
@@ -88,13 +95,13 @@ def test_existing_endpoint_resave_is_grandfathered(self) -> None:
         endpoint = _endpoint("021 555 123")
         # Legacy cross-owned row inserted bypassing the method-side guard,
         # as pre-guard data was.
-        legacy = ClientContactMethod(
+        legacy = ContactMethod(
             company=_client(),
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        legacy.normalized_value = ClientContactMethod.normalize_phone("021 555 123")
-        ClientContactMethod.objects.bulk_create([legacy])
+        legacy.normalized_value = ContactMethod.normalize_phone("021 555 123")
+        ContactMethod.objects.bulk_create([legacy])
 
         endpoint.label = "Renamed line"
         endpoint.save()  # number/is_active unchanged -> grandfathered
@@ -136,13 +143,13 @@ def test_create_endpoint_over_client_number_returns_400(self) -> None:
 
     def test_update_unrelated_field_on_grandfathered_endpoint_succeeds(self) -> None:
         endpoint = _endpoint("021 555 123")
-        legacy = ClientContactMethod(
+        legacy = ContactMethod(
             company=_client(),
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        legacy.normalized_value = ClientContactMethod.normalize_phone("021 555 123")
-        ClientContactMethod.objects.bulk_create([legacy])
+        legacy.normalized_value = ContactMethod.normalize_phone("021 555 123")
+        ContactMethod.objects.bulk_create([legacy])
 
         response = self.api.patch(
             f"/api/crm/phone-endpoints/{endpoint.id}/",
diff --git a/apps/crm/views/phone_call_views.py b/apps/crm/views/phone_call_views.py
index 8ac596dfd..a088f5abf 100644
--- a/apps/crm/views/phone_call_views.py
+++ b/apps/crm/views/phone_call_views.py
@@ -66,7 +66,6 @@ def _query_uuid(value: str | None, field_name: str) -> UUID | None:
 def _phone_call_filter_kwargs(request: Request) -> dict[str, UUID]:
     query_filters = (
         ("company_id", _query_uuid(request.query_params.get("company"), "company")),
-        ("contact_id", _query_uuid(request.query_params.get("contact"), "contact")),
         ("person_id", _query_uuid(request.query_params.get("person"), "person")),
         ("job_id", _query_uuid(request.query_params.get("job"), "job")),
         (
@@ -186,7 +185,7 @@ def _apply_search_filter(
     normalized_phone = normalize_phone(search)
     filters = (
         Q(company__name__icontains=search)
-        | Q(contact__name__icontains=search)
+        | Q(person__name__icontains=search)
         | Q(person__name__icontains=search)
         | Q(origin_endpoint__label__icontains=search)
         | Q(destination_endpoint__label__icontains=search)
@@ -243,7 +242,6 @@ class PhoneCallRecordViewSet(viewsets.ReadOnlyModelViewSet[PhoneCallRecord]):
     @extend_schema(
         parameters=[
             OpenApiParameter("company", OpenApiTypes.UUID, OpenApiParameter.QUERY),
-            OpenApiParameter("contact", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("person", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter("job", OpenApiTypes.UUID, OpenApiParameter.QUERY),
             OpenApiParameter(
@@ -286,7 +284,6 @@ def get_queryset(self) -> QuerySet[PhoneCallRecord]:
         queryset = (
             PhoneCallRecord.objects.select_related(
                 "company",
-                "contact",
                 "person",
                 "job",
                 "job_linked_by",
@@ -377,12 +374,12 @@ def assign_number(
     ) -> Response:
         payload = PhoneNumberAssignmentSerializer(data=request.data)
         payload.is_valid(raise_exception=True)
-        contact = payload.validated_data["contact"]
+        person = payload.validated_data["person"]
         return self._call_operation_response(
             lambda: assign_phone_number_from_call(
                 call_id=str(pk),
                 company_id=str(payload.validated_data["company"]),
-                contact_id=str(contact) if contact else None,
+                person_id=str(person) if person else None,
                 label=payload.validated_data["label"],
                 is_primary=payload.validated_data["is_primary"],
             )
diff --git a/apps/job/migrations/0005_remove_job_contact_alter_job_person.py b/apps/job/migrations/0005_remove_job_contact_alter_job_person.py
new file mode 100644
index 000000000..24c0134f5
--- /dev/null
+++ b/apps/job/migrations/0005_remove_job_contact_alter_job_person.py
@@ -0,0 +1,51 @@
+# Generated by Django 6.0.4 on 2026-07-08 22:47
+
+from typing import Any
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+def repair_job_people(apps: Any, schema_editor: Any) -> None:
+    Job = apps.get_model("job", "Job")
+    CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
+
+    link_person_by_id = dict(
+        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
+            "id", "person_id"
+        )
+    )
+    jobs = Job.objects.filter(person__isnull=True).exclude(contact__isnull=True)
+    for job in jobs.iterator():
+        person_id = link_person_by_id.get(job.contact_id)
+        if person_id is not None:
+            job.person_id = person_id
+            job.save(update_fields=["person"])
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0006_alter_companypersonlink_options_and_more"),
+        ("job", "0004_job_person_alter_job_contact"),
+    ]
+
+    operations = [
+        migrations.RunPython(repair_job_people, migrations.RunPython.noop),
+        migrations.RemoveField(
+            model_name="job",
+            name="contact",
+        ),
+        migrations.AlterField(
+            model_name="job",
+            name="person",
+            field=models.ForeignKey(
+                blank=True,
+                help_text="The person for this job",
+                null=True,
+                on_delete=django.db.models.deletion.SET_NULL,
+                related_name="jobs",
+                to="company.person",
+            ),
+        ),
+    ]
diff --git a/apps/job/models/job.py b/apps/job/models/job.py
index 198d291b0..4c22b6612 100644
--- a/apps/job/models/job.py
+++ b/apps/job/models/job.py
@@ -215,21 +215,12 @@ class Job(models.Model):
     )
     order_number = models.CharField(max_length=100, null=True, blank=True)
 
-    # New relationship to ClientContact
-    contact = models.ForeignKey(
-        "company.CompanyPersonLink",
-        on_delete=models.SET_NULL,
-        null=True,
-        blank=True,
-        related_name="jobs",
-        help_text="The contact person for this job",
-    )
     person = models.ForeignKey(
         "company.Person",
         on_delete=models.SET_NULL,
         null=True,
         blank=True,
-        related_name="person_jobs",
+        related_name="jobs",
         help_text="The person for this job",
     )
     job_number = models.IntegerField(unique=True)  # Job 1234
@@ -960,26 +951,24 @@ def _handle_company_change(self_job, old_company_id, new_company_id):
         )
 
     @staticmethod
-    def _handle_contact_change(self_job, old_contact_id, new_contact_id):
-        old_contact = "None"
-        new_contact = "None"
-        if old_contact_id:
+    def _handle_person_change(self_job, old_person_id, new_person_id):
+        old_person = "None"
+        new_person = "None"
+        if old_person_id:
             try:
-                from apps.company.models import ClientContact
+                from apps.company.models import Person
 
-                old_contact = ClientContact.objects.get(id=old_contact_id).name
+                old_person = Person.objects.get(id=old_person_id).name
             except Exception:
-                old_contact = "Unknown Contact"
-        if new_contact_id:
-            new_contact = (
-                self_job.contact.name if self_job.contact else "Unknown Contact"
-            )
+                old_person = "Unknown Person"
+        if new_person_id:
+            new_person = self_job.person.name if self_job.person else "Unknown Person"
         return (
             "contact_changed",
             {
-                "field_name": "Primary contact",
-                "old_value": old_contact,
-                "new_value": new_contact,
+                "field_name": "Person",
+                "old_value": old_person,
+                "new_value": new_person,
             },
         )
 
@@ -1113,7 +1102,7 @@ def _handle_rdti_type_change(_self_job, old_type, new_type):
             {"field_name": "Job name", "old_value": str(old), "new_value": str(new)},
         ),
         "company_id": _handle_company_change.__func__,
-        "contact_id": _handle_contact_change.__func__,
+        "person_id": _handle_person_change.__func__,
         "order_number": lambda _self, old, new: (
             "job_updated",
             {
diff --git a/apps/job/models/job_event.py b/apps/job/models/job_event.py
index a9b6c88a3..becca74e8 100644
--- a/apps/job/models/job_event.py
+++ b/apps/job/models/job_event.py
@@ -273,12 +273,12 @@ def _build_status_changed_description(detail: dict) -> str:
     def _build_job_created_description(detail: dict) -> str:
         job_name = detail.get("job_name", "Unknown")
         company_name = detail.get("company_name", "Unknown")
-        contact_name = detail.get("contact_name")
+        person_name = detail.get("person_name")
         initial_status = detail.get("initial_status", "Unknown")
         pricing = detail.get("pricing_methodology", "Unknown")
-        contact_info = f" (Contact: {contact_name})" if contact_name else ""
+        person_info = f" (Person: {person_name})" if person_name else ""
         return (
-            f"New job '{job_name}' created for company {company_name}{contact_info}. "
+            f"New job '{job_name}' created for company {company_name}{person_info}. "
             f"Initial status: {initial_status}. "
             f"Pricing methodology: {pricing}."
         )
diff --git a/apps/job/serializers/job_serializer.py b/apps/job/serializers/job_serializer.py
index 10ae219e3..43ff30354 100644
--- a/apps/job/serializers/job_serializer.py
+++ b/apps/job/serializers/job_serializer.py
@@ -8,7 +8,7 @@
 
 from apps.accounting.models.invoice import Invoice
 from apps.accounting.models.quote import Quote
-from apps.company.models import ClientContact, Company, Person
+from apps.company.models import Company, Person
 from apps.job.models import Job, JobEvent, JobFile
 from apps.workflow.models import XeroPayItem
 
@@ -124,16 +124,6 @@ class JobSerializer(serializers.ModelSerializer):
     company_name = serializers.CharField(
         source="company.name", read_only=True, allow_null=True, required=False
     )
-    contact_id = serializers.PrimaryKeyRelatedField(
-        queryset=ClientContact.objects.all(),
-        source="contact",
-        write_only=False,  # Allow read access
-        required=False,
-        allow_null=True,
-    )
-    contact_name = serializers.CharField(
-        source="contact.name", read_only=True, required=False, allow_null=True
-    )
     person_id = serializers.PrimaryKeyRelatedField(
         queryset=Person.objects.all(),
         source="person",
@@ -218,8 +208,6 @@ class Meta:
             "name",
             "company_id",
             "company_name",
-            "contact_id",
-            "contact_name",
             "person_id",
             "person_name",
             "job_number",
@@ -262,33 +250,6 @@ def validate(self, attrs):
         if DEBUG_SERIALIZER:
             logger.debug(f"JobSerializer validate called with attrs: {attrs}")
 
-        # Validate contact belongs to company
-        contact = attrs.get("contact")
-        company = attrs.get("company")
-
-        # If we're updating and no company is provided, use the existing company
-        if not company and self.instance:
-            company = self.instance.company
-
-        if contact and company:
-            logger.debug(
-                f"JobSerializer validate - Checking if contact {contact.id} belongs to company {company.id}"
-            )
-            if contact.company != company:
-                logger.error(
-                    f"JobSerializer validate - Contact {contact.id} does not belong to company {company.id}"
-                )
-                raise serializers.ValidationError(
-                    {
-                        "contact_id": f"Contact does not belong to the selected company. Contact belongs to {contact.company.name}, but job is for {company.name}."
-                    }
-                )
-            if DEBUG_SERIALIZER:
-                logger.debug(
-                    f"JobSerializer validate - Contact {contact.id} belongs to company {company.id}"
-                )
-                logger.debug("JobSerializer validate - Contact validation passed")
-
         # No longer validating pricing data - use CostSet/CostLine instead
 
         validated = super().validate(attrs)
@@ -298,7 +259,7 @@ def validate(self, attrs):
 
     def update(self, instance, validated_data):
         # Store original values for change detection
-        original_contact = instance.contact if "contact" in validated_data else None
+        original_person = instance.person if "person" in validated_data else None
 
         # Remove read-only/computed fields to avoid AttributeError
         validated_data.pop("quoted", None)
@@ -365,13 +326,10 @@ def update(self, instance, validated_data):
         # Save the instance (enrichment kwargs flow through to _create_change_events)
         instance.save(staff=staff, **save_enrichment)
 
-        # Log contact change after save if it actually changed
-        if (
-            "contact" in validated_data
-            and original_contact != validated_data["contact"]
-        ):
+        # Log person change after save if it actually changed
+        if "person" in validated_data and original_person != validated_data["person"]:
             logger.debug(
-                f"JobSerializer update - contact changed from {original_contact} to {instance.contact}"
+                f"JobSerializer update - person changed from {original_person} to {instance.person}"
             )
 
         return instance
@@ -450,7 +408,7 @@ def get_undo_description(self, obj) -> str | None:
                 "order_number": "order number",
                 "notes": "notes",
                 "company_id": "company",
-                "contact_id": "contact",
+                "person_id": "person",
                 "delivery_date": "delivery date",
                 "job_status": "status",
                 "paid": "payment status",
@@ -536,7 +494,7 @@ class JobCreateSerializer(serializers.Serializer):
     description = serializers.CharField(required=False, allow_blank=True)
     order_number = serializers.CharField(required=False, allow_blank=True)
     notes = serializers.CharField(required=False, allow_blank=True)
-    contact_id = serializers.UUIDField(required=False, allow_null=True)
+    person_id = serializers.UUIDField(required=False, allow_null=True)
     pricing_methodology = serializers.CharField(
         required=False, allow_null=True, allow_blank=True
     )
@@ -831,11 +789,11 @@ class JobHeaderResponseSerializer(serializers.ModelSerializer):
     company_name = serializers.CharField(
         source="company.name", read_only=True, allow_null=True
     )
-    contact_id = serializers.UUIDField(
-        source="contact.id", read_only=True, allow_null=True
+    person_id = serializers.UUIDField(
+        source="person.id", read_only=True, allow_null=True
     )
-    contact_name = serializers.CharField(
-        source="contact.name", read_only=True, allow_null=True
+    person_name = serializers.CharField(
+        source="person.name", read_only=True, allow_null=True
     )
     quoted = serializers.BooleanField()
     default_xero_pay_item_id = serializers.UUIDField(
@@ -852,8 +810,8 @@ class Meta:
             "job_id",
             "company_id",
             "company_name",
-            "contact_id",
-            "contact_name",
+            "person_id",
+            "person_name",
             "quoted",
             "default_xero_pay_item_id",
             "default_xero_pay_item_name",
@@ -1042,7 +1000,7 @@ def get_undo_description(self, obj) -> str | None:
                 "order_number": "order number",
                 "notes": "notes",
                 "company_id": "company",
-                "contact_id": "contact",
+                "person_id": "person",
                 "delivery_date": "delivery date",
                 "job_status": "status",
                 "paid": "payment status",
@@ -1155,8 +1113,8 @@ class JobPatchSerializer(serializers.Serializer):
     company_id = serializers.UUIDField(
         required=False, allow_null=True, help_text="Company ID"
     )
-    contact_id = serializers.UUIDField(
-        required=False, allow_null=True, help_text="Contact person ID"
+    person_id = serializers.UUIDField(
+        required=False, allow_null=True, help_text="Person ID"
     )
 
     # Files
@@ -1173,34 +1131,17 @@ def validate_company_id(self, value):
                 raise serializers.ValidationError("Company not found")
         return value
 
-    def validate_contact_id(self, value):
-        """Validate that contact exists if provided"""
+    def validate_person_id(self, value):
+        """Validate that person exists if provided"""
         if value:
             try:
-                ClientContact.objects.get(id=value)
-            except ClientContact.DoesNotExist:
-                raise serializers.ValidationError("Contact not found")
+                Person.objects.get(id=value)
+            except Person.DoesNotExist:
+                raise serializers.ValidationError("Person not found")
         return value
 
     def validate(self, attrs):
         """Cross-field validation"""
-        # Validate contact belongs to company if both are provided
-        contact_id = attrs.get("contact_id")
-        company_id = attrs.get("company_id")
-
-        if contact_id and company_id:
-            try:
-                contact = ClientContact.objects.get(id=contact_id)
-                company = Company.objects.get(id=company_id)
-                if contact.company != company:
-                    raise serializers.ValidationError(
-                        {
-                            "contact_id": "Contact does not belong to the selected company"
-                        }
-                    )
-            except (ClientContact.DoesNotExist, Company.DoesNotExist):
-                pass  # Individual field validation will catch these
-
         return attrs
 
 
diff --git a/apps/job/serializers/kanban_serializer.py b/apps/job/serializers/kanban_serializer.py
index 41fa8776a..5df3dc9e0 100644
--- a/apps/job/serializers/kanban_serializer.py
+++ b/apps/job/serializers/kanban_serializer.py
@@ -70,7 +70,7 @@ class JobSearchFiltersSerializer(serializers.Serializer):
     name = serializers.CharField(required=False, allow_blank=True)
     description = serializers.CharField(required=False, allow_blank=True)
     company_name = serializers.CharField(required=False, allow_blank=True)
-    contact_person = serializers.CharField(required=False, allow_blank=True)
+    person_name = serializers.CharField(required=False, allow_blank=True)
     created_by = serializers.CharField(required=False, allow_blank=True)
     created_after = serializers.DateField(required=False, allow_null=True)
     created_before = serializers.DateField(required=False, allow_null=True)
@@ -100,9 +100,9 @@ class KanbanJobSerializer(serializers.Serializer):
     description = serializers.CharField(allow_blank=True, allow_null=True)
     job_number = serializers.IntegerField()
 
-    # Company and contact info
+    # Company and person info
     company_name = serializers.CharField(allow_blank=True)
-    contact_person = serializers.CharField(allow_blank=True)
+    person_name = serializers.CharField(allow_blank=True)
 
     # People assigned to the job
     people = KanbanJobPersonSerializer(many=True)
@@ -198,9 +198,9 @@ class KanbanColumnJobSerializer(serializers.Serializer):
     name = serializers.CharField()
     description = serializers.CharField(allow_blank=True, allow_null=True)
 
-    # Company and contact info
+    # Company and person info
     company_name = serializers.CharField(allow_blank=True)
-    contact_person = serializers.CharField(allow_blank=True)
+    person_name = serializers.CharField(allow_blank=True)
 
     # People assigned to the job (empty list for now)
     people = KanbanJobPersonSerializer(many=True)
@@ -265,5 +265,5 @@ class WorkshopJobSerializer(serializers.Serializer):
     description = serializers.CharField(allow_blank=True, allow_null=True)
     job_number = serializers.IntegerField()
     company_name = serializers.CharField()
-    contact_person = serializers.CharField(allow_blank=True, allow_null=True)
+    person_name = serializers.CharField(allow_blank=True, allow_null=True)
     people = KanbanJobPersonSerializer(many=True)
diff --git a/apps/job/services/data_integrity_service.py b/apps/job/services/data_integrity_service.py
index 4fc247647..e09bd378d 100644
--- a/apps/job/services/data_integrity_service.py
+++ b/apps/job/services/data_integrity_service.py
@@ -17,7 +17,7 @@
     Quote,
 )
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.job.models import (
     CostLine,
     CostSet,
@@ -116,7 +116,7 @@ def _check_job_fks() -> list[dict[str, Any]]:
         """Check Job FK references."""
         issues = []
         valid_company_ids = set(Company.objects.values_list("id", flat=True))
-        valid_contact_ids = set(ClientContact.objects.values_list("id", flat=True))
+        valid_person_ids = set(Person.objects.values_list("id", flat=True))
         valid_staff_ids = set(Staff.objects.values_list("id", flat=True))
         valid_costset_ids = set(CostSet.objects.values_list("id", flat=True))
 
@@ -131,14 +131,14 @@ def _check_job_fks() -> list[dict[str, Any]]:
                         "target_id": str(job.company_id),
                     }
                 )
-            if job.contact_id and job.contact_id not in valid_contact_ids:
+            if job.person_id and job.person_id not in valid_person_ids:
                 issues.append(
                     {
                         "model": "Job",
                         "record_id": str(job.id),
-                        "field": "contact",
-                        "target_model": "ClientContact",
-                        "target_id": str(job.contact_id),
+                        "field": "person",
+                        "target_model": "Person",
+                        "target_id": str(job.person_id),
                     }
                 )
             if job.created_by_id and job.created_by_id not in valid_staff_ids:
@@ -593,21 +593,32 @@ def _check_company_fks() -> list[dict[str, Any]]:
 
     @staticmethod
     def _check_clientcontact_fks() -> list[dict[str, Any]]:
-        """Check ClientContact FK references."""
+        """Check CompanyPersonLink FK references."""
         issues = []
         valid_company_ids = set(Company.objects.values_list("id", flat=True))
+        valid_person_ids = set(Person.objects.values_list("id", flat=True))
 
-        for contact in ClientContact.objects.all():
+        for contact in CompanyPersonLink.objects.all():
             if contact.company_id not in valid_company_ids:
                 issues.append(
                     {
-                        "model": "ClientContact",
+                        "model": "CompanyPersonLink",
                         "record_id": str(contact.id),
                         "field": "company",
                         "target_model": "Company",
                         "target_id": str(contact.company_id),
                     }
                 )
+            if contact.person_id not in valid_person_ids:
+                issues.append(
+                    {
+                        "model": "CompanyPersonLink",
+                        "record_id": str(contact.id),
+                        "field": "person",
+                        "target_model": "Person",
+                        "target_id": str(contact.person_id),
+                    }
+                )
 
         return issues
 
diff --git a/apps/job/services/job_rest_service.py b/apps/job/services/job_rest_service.py
index bbd98bd28..ea1cbc55f 100644
--- a/apps/job/services/job_rest_service.py
+++ b/apps/job/services/job_rest_service.py
@@ -21,7 +21,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, Person
 from apps.job.models import Job, JobDeltaRejection, JobEvent, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.job.serializers import JobSerializer
@@ -33,7 +33,6 @@
     QuoteSerializer,
 )
 from apps.job.services.delta_checksum import compute_job_delta_checksum, normalise_value
-from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.models import CompanyDefaults, XeroPayItem
 from apps.workflow.services.error_persistence import persist_and_raise
 
@@ -283,13 +282,13 @@ def create_job(data: Dict[str, Any], user: Staff) -> Job:
             if data.get(field):
                 job_data[field] = data[field]
 
-        # Contact (optional relationship)
-        if contact_id := data.get("contact_id"):
+        # Person (optional relationship)
+        if person_id := data.get("person_id"):
             try:
-                contact = ClientContact.objects.get(id=contact_id)
-                job_data["contact"] = contact
-            except ClientContact.DoesNotExist:
-                raise ValueError(f"Contact with id {contact_id} not found")
+                person = Person.objects.get(id=person_id)
+                job_data["person"] = person
+            except Person.DoesNotExist:
+                raise ValueError(f"Person with id {person_id} not found")
 
         if "is_urgent" in data:
             job_data["is_urgent"] = data["is_urgent"]
@@ -311,14 +310,14 @@ def create_job(data: Dict[str, Any], user: Staff) -> Job:
 
             # Create job creation event (moved from Job.save() to prevent duplicates)
             company_name = job.company.name if job.company else "Shop Job"
-            contact_name = job.contact.name if job.contact else None
+            person_name = job.person.name if job.person else None
             JobEvent.objects.create(
                 job=job,
                 event_type="job_created",
                 detail={
                     "job_name": job.name,
                     "company_name": company_name,
-                    "contact_name": contact_name,
+                    "person_name": person_name,
                     "initial_status": job.get_status_display(),
                     "pricing_methodology": job.get_pricing_methodology_display(),
                 },
@@ -1076,15 +1075,14 @@ def update_job(
                 # DEBUG: Log incoming data
                 logger.debug(f"JobRestService.update_job - Incoming data: {data}")
                 logger.debug(
-                    f"JobRestService.update_job - Current job contact: {job.contact}"
+                    f"JobRestService.update_job - Current job person: {job.person}"
                 )
                 logger.debug(
-                    f"JobRestService.update_job - Current job contact_id: {job.contact.id if job.contact else None}"
+                    f"JobRestService.update_job - Current job person_id: {job.person.id if job.person else None}"
                 )
 
-                # Snapshot values needed for post-save logic (priority bump, company change)
+                # Snapshot values needed for post-save logic (priority bump)
                 original_status = job.status
-                original_company_id = job.company_id
 
                 if delta_payload.job_id and str(job.id) != delta_payload.job_id:
                     detail = {
@@ -1146,45 +1144,6 @@ def update_job(
                     job.priority = Job._calculate_next_priority_for_status(job.status)
                     job.save(staff=user, update_fields=["priority", "updated_at"])
 
-                # When company changes, auto-set contact to new company's primary contact.
-                # Only do this if contact_id was NOT explicitly provided in the update.
-                contact_explicitly_updated = "contact_id" in delta_payload.fields
-                try:
-                    if (
-                        job.company
-                        and original_company_id != job.company_id
-                        and not contact_explicitly_updated
-                    ):
-                        primary_contact = ClientContact.objects.filter(
-                            company_id=job.company_id,
-                            is_primary=True,
-                            is_active=True,
-                        ).first()
-                        job.contact = primary_contact  # May be None if no primary
-                        job.save(staff=user)
-                        logger.info(
-                            f"Auto-set contact to primary contact after company change: "
-                            f"job.company_id={job.company_id}, "
-                            f"contact={'None' if not primary_contact else primary_contact.id}"
-                        )
-                    elif (
-                        job.contact
-                        and job.company
-                        and job.contact.company_id != job.company_id
-                    ):
-                        logger.warning(
-                            "Clearing mismatched contact after company change: "
-                            f"contact.company_id={job.contact.company_id} != job.company_id={job.company_id}"
-                        )
-                        job.contact = None
-                        job.save(staff=user)
-                except Exception as _e:
-                    # Persist the error but do not mask the main operation
-                    try:
-                        persist_and_raise(_e)
-                    except AlreadyLoggedException:
-                        pass
-
                 result_job = job
         except PreconditionFailed:
             if soft_fail_context:
@@ -1578,7 +1537,7 @@ def get_job_timeline(job_id: UUID) -> list[Dict[str, Any]]:
                             "order_number": "order number",
                             "notes": "notes",
                             "company_id": "company",
-                            "contact_id": "contact",
+                            "person_id": "person",
                             "delivery_date": "delivery date",
                             "job_status": "status",
                             "paid": "payment status",
diff --git a/apps/job/services/kanban_service.py b/apps/job/services/kanban_service.py
index 62e2f56c5..d11932455 100644
--- a/apps/job/services/kanban_service.py
+++ b/apps/job/services/kanban_service.py
@@ -34,7 +34,7 @@
 
 from apps.accounting.models import Invoice
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, Person
 from apps.job.models import CostSet, Job
 from apps.job.services.kanban_categorization_service import KanbanCategorizationService
 from apps.workflow.models import CompanyDefaults
@@ -58,7 +58,7 @@ class KanbanSerializationContext:
     shop_company_id: Optional[UUID]
     summaries: Dict[UUID, Dict[str, Any]]
     company_names: Dict[UUID, str]
-    contact_names: Dict[UUID, str]
+    person_names: Dict[UUID, str]
     people_by_job: Dict[UUID, List[Staff]]
 
 
@@ -72,7 +72,7 @@ class KanbanService:
     SEARCH_SCORE_QUOTE_CONTAINS = 75.0
     SEARCH_SCORE_NAME_CONTAINS = 65.0
     SEARCH_SCORE_COMPANY_CONTAINS = 55.0
-    SEARCH_SCORE_CONTACT_CONTAINS = 55.0
+    SEARCH_SCORE_PERSON_CONTAINS = 55.0
     SEARCH_SCORE_DESCRIPTION_CONTAINS = 35.0
     SEARCH_SCORE_TRIGRAM_MULTIPLIER = 30.0
     SEARCH_SCORE_FALLBACK_RATIO = 0.5
@@ -95,12 +95,10 @@ class KanbanService:
             "reason": "client_contains",
         },
         {
-            "db_path": "contact__name",
-            "expression": Coalesce(
-                "contact__name", Value(""), output_field=TextField()
-            ),
-            "score": SEARCH_SCORE_CONTACT_CONTAINS,
-            "reason": "contact_contains",
+            "db_path": "person__name",
+            "expression": Coalesce("person__name", Value(""), output_field=TextField()),
+            "score": SEARCH_SCORE_PERSON_CONTAINS,
+            "reason": "person_contains",
         },
         {
             "db_path": "description",
@@ -246,7 +244,7 @@ def _apply_kanban_search(jobs_query: QuerySet[Job], query: str) -> List[Job]:
 
         candidates = list(
             jobs_query.filter(token_filter)
-            .select_related("company", "contact", "quote")
+            .select_related("company", "person", "quote")
             .prefetch_related("invoices")
             .order_by("-trigram_score", "-created_at")
         )
@@ -371,10 +369,8 @@ def _get_search_field_value(job: Job, db_path: str) -> str:
                 return (
                     job.company.name if job.company_id and job.company else ""
                 ).lower()
-            case "contact__name":
-                return (
-                    job.contact.name if job.contact_id and job.contact else ""
-                ).lower()
+            case "person__name":
+                return (job.person.name if job.person_id and job.person else "").lower()
             case "description":
                 return (job.description or "").lower()
             case "job_number":
@@ -529,9 +525,9 @@ def build_serialization_context(jobs: List[Job]) -> KanbanSerializationContext:
             Company.objects.filter(id__in=company_ids).values_list("id", "name")
         )
 
-        contact_ids = {job.contact_id for job in jobs} - {None}
-        contact_names = dict(
-            ClientContact.objects.filter(id__in=contact_ids).values_list("id", "name")
+        person_ids = {job.person_id for job in jobs} - {None}
+        person_names = dict(
+            Person.objects.filter(id__in=person_ids).values_list("id", "name")
         )
 
         people_links = list(
@@ -556,7 +552,7 @@ def build_serialization_context(jobs: List[Job]) -> KanbanSerializationContext:
             shop_company_id=defaults.shop_company_id,
             summaries=summaries,
             company_names=company_names,
-            contact_names=contact_names,
+            person_names=person_names,
             people_by_job=dict(people_by_job),
         )
 
@@ -630,8 +626,8 @@ def serialize_job_for_api(
             "company_name": (
                 context.company_names.get(job.company_id, "") if job.company_id else ""
             ),
-            "contact_person": (
-                context.contact_names.get(job.contact_id, "") if job.contact_id else ""
+            "person_name": (
+                context.person_names.get(job.person_id, "") if job.person_id else ""
             ),
             "people": [
                 {
@@ -958,8 +954,8 @@ def perform_advanced_search(
         if company_name := filters.get("company_name", "").strip():
             jobs_query = jobs_query.filter(company__name__icontains=company_name)
 
-        if contact_person := filters.get("contact_person", "").strip():
-            jobs_query = jobs_query.filter(contact__name__icontains=contact_person)
+        if person_name := filters.get("person_name", "").strip():
+            jobs_query = jobs_query.filter(person__name__icontains=person_name)
 
         if order_number := filters.get("order_number", "").strip():
             jobs_query = jobs_query.filter(order_number__icontains=order_number)
diff --git a/apps/job/services/workshop_pdf_service.py b/apps/job/services/workshop_pdf_service.py
index 507e3de21..a9e2a0af2 100644
--- a/apps/job/services/workshop_pdf_service.py
+++ b/apps/job/services/workshop_pdf_service.py
@@ -22,7 +22,7 @@
 from reportlab.pdfgen import canvas
 from reportlab.platypus import Flowable, Paragraph, Table, TableStyle
 
-from apps.company.models import ClientContactMethod
+from apps.company.models import ContactMethod
 from apps.crm.models import PhoneEndpoint
 from apps.job.enums import SpeedQualityTradeoff
 from apps.job.models import CostLine, CostSet, Job, JobFile
@@ -35,25 +35,24 @@
 JOB_SUMMARY_PDF_FILENAME = "JobSummary.pdf"
 WORKSHOP_PDF_COST_LINES_ATTR = "_workshop_pdf_cost_lines"
 WORKSHOP_PDF_FILES_ATTR = "_workshop_pdf_files_to_print"
-WORKSHOP_PDF_CONTACT_PHONE_ATTR = "_workshop_pdf_contact_phone"
+WORKSHOP_PDF_PERSON_PHONE_ATTR = "_workshop_pdf_person_phone"
 WORKSHOP_PDF_COMPANY_PHONE_ATTR = "_workshop_pdf_company_phone"
 
 
 def _primary_phone_for_job(job: Job) -> str:
     """Phone to print on workshop docs and delivery dockets.
 
-    Display preference order: the job contact's own number first, falling back
-    to the company's number when the contact has no phone method (the business
-    rule carried over from the pre-ClientContactMethod scalar fields).
+    Display preference order: the job person's own number first, falling back
+    to the company's number when the person has no phone method.
     """
-    if not hasattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR) or not hasattr(
+    if not hasattr(job, WORKSHOP_PDF_PERSON_PHONE_ATTR) or not hasattr(
         job, WORKSHOP_PDF_COMPANY_PHONE_ATTR
     ):
         raise ValueError("PDF phone fields must be loaded before rendering")
 
-    contact_phone = getattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR)
-    if contact_phone:
-        return str(contact_phone)
+    person_phone = getattr(job, WORKSHOP_PDF_PERSON_PHONE_ATTR)
+    if person_phone:
+        return str(person_phone)
     return str(getattr(job, WORKSHOP_PDF_COMPANY_PHONE_ATTR) or "")
 
 
@@ -71,10 +70,10 @@ def _primary_company_endpoint_number() -> str:
 
 def _primary_phone_annotations() -> dict[str, Coalesce]:
     return {
-        WORKSHOP_PDF_CONTACT_PHONE_ATTR: ClientContactMethod.primary_phone_annotation(
-            owner="contact", outer_ref="contact_id"
+        WORKSHOP_PDF_PERSON_PHONE_ATTR: ContactMethod.primary_phone_annotation(
+            owner="person", outer_ref="person_id"
         ),
-        WORKSHOP_PDF_COMPANY_PHONE_ATTR: ClientContactMethod.primary_phone_annotation(
+        WORKSHOP_PDF_COMPANY_PHONE_ATTR: ContactMethod.primary_phone_annotation(
             owner="company", outer_ref="company_id"
         ),
     }
@@ -84,7 +83,7 @@ def get_job_for_delivery_docket_pdf(job_id: UUID) -> Job:
     """Load a job with the relations required to render a delivery docket."""
     return cast(
         Job,
-        Job.objects.select_related("company", "contact")
+        Job.objects.select_related("company", "person")
         .annotate(**_primary_phone_annotations())
         .get(id=job_id),
     )
@@ -104,7 +103,7 @@ def get_job_for_workshop_pdf(job_id: UUID) -> Job:
         Job,
         Job.objects.select_related(
             "company",
-            "contact",
+            "person",
             "latest_estimate",
             "latest_quote",
             "latest_actual",
@@ -150,7 +149,7 @@ def _ensure_workshop_pdf_job_loaded(job: Job) -> Job:
 
 
 def _ensure_delivery_docket_pdf_job_loaded(job: Job) -> Job:
-    if hasattr(job, WORKSHOP_PDF_CONTACT_PHONE_ATTR) and hasattr(
+    if hasattr(job, WORKSHOP_PDF_PERSON_PHONE_ATTR) and hasattr(
         job, WORKSHOP_PDF_COMPANY_PHONE_ATTR
     ):
         return job
@@ -1163,19 +1162,19 @@ def add_workshop_details_table(
 ) -> float:
     """Render a full-page workshop brief: identity, constraints, labour budget, and specs."""
     company_name = job.company.name if job.company else "N/A"
-    contact_name = job.contact.name if job.contact else ""
-    contact_phone = _primary_phone_for_job(job)
-    contact_info = (
-        f"{escape(contact_name)}<br/>{escape(contact_phone)}"
-        if contact_phone
-        else escape(contact_name or "N/A")
+    person_name = job.person.name if job.person else ""
+    person_phone = _primary_phone_for_job(job)
+    person_info = (
+        f"{escape(person_name)}<br/>{escape(person_phone)}"
+        if person_phone
+        else escape(person_name or "N/A")
     )
 
     contact_table = Table(
         [
             [
                 _plain_paragraph(company_name, header_company_style),
-                Paragraph(contact_info, header_contact_style),
+                Paragraph(person_info, header_contact_style),
             ]
         ],
         colWidths=[CONTENT_WIDTH * 0.42, CONTENT_WIDTH * 0.58],
@@ -1312,18 +1311,16 @@ def add_delivery_docket_details_table(
 ):
     """Render the delivery docket details with page-aware wrapping."""
     company_name = job.company.name if job.company else "N/A"
-    contact_name = job.contact.name if job.contact else ""
+    person_name = job.person.name if job.person else ""
 
-    contact_phone = _primary_phone_for_job(job)
-    contact_info = (
-        f"{contact_name}<br/>{contact_phone}" if contact_phone else contact_name
-    )
+    person_phone = _primary_phone_for_job(job)
+    person_info = f"{person_name}<br/>{person_phone}" if person_phone else person_name
 
     # Delivery docket details - no workshop time or internal notes
     job_details = [
         [
             Paragraph(company_name, header_company_style),
-            Paragraph(contact_info, header_contact_style),
+            Paragraph(person_info, header_contact_style),
         ],
         [
             Paragraph("DESCRIPTION", label_style),
diff --git a/apps/job/tests/_pdf_golden_fixtures.py b/apps/job/tests/_pdf_golden_fixtures.py
index 326b67a9a..9a2e8b5f7 100644
--- a/apps/job/tests/_pdf_golden_fixtures.py
+++ b/apps/job/tests/_pdf_golden_fixtures.py
@@ -24,7 +24,7 @@
 from django.conf import settings
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, Person
 from apps.job.models import CostLine, Job, JobEvent, JobFile, LabourSubtype
 from apps.workflow.models import CompanyDefaults, XeroPayItem
 
@@ -78,14 +78,11 @@ def build_golden_job(test_staff: Staff) -> Job:
         xero_last_modified=FROZEN_NOW,
     )
 
-    contact = ClientContact.objects.create(
-        company=company,
-        name="Jane Doe",
-    )
+    person = Person.objects.create(name="Jane Doe")
 
     job = Job.objects.create(
         company=company,
-        contact=contact,
+        person=person,
         name="Custom Bracket Fabrication",
         description=("Stainless steel mounting bracket, 200x100x5mm, 4 holes per spec"),
         notes=(
diff --git a/apps/job/tests/test_duplicate_phones_view.py b/apps/job/tests/test_duplicate_phones_view.py
index 347bf987d..87a385e1f 100644
--- a/apps/job/tests/test_duplicate_phones_view.py
+++ b/apps/job/tests/test_duplicate_phones_view.py
@@ -1,7 +1,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 from apps.testing import BaseAPITestCase
 
 URL = "/api/job/data-quality/duplicate-phones/"
@@ -18,13 +18,13 @@ def _office_staff(self) -> Staff:
         )
 
     def _phone(self, value: str, company: Company) -> None:
-        method = ClientContactMethod(
+        method = ContactMethod(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=value,
         )
-        method.normalized_value = ClientContactMethod.normalize_phone(value)
-        ClientContactMethod.objects.bulk_create([method])
+        method.normalized_value = ContactMethod.normalize_phone(value)
+        ContactMethod.objects.bulk_create([method])
 
     def test_returns_cross_company_conflict_to_office_staff(self) -> None:
         acme = Company.objects.create(name="Acme", xero_last_modified=timezone.now())
diff --git a/apps/job/tests/test_job_header_view.py b/apps/job/tests/test_job_header_view.py
index 8000815d8..a51c1c6a3 100644
--- a/apps/job/tests/test_job_header_view.py
+++ b/apps/job/tests/test_job_header_view.py
@@ -51,8 +51,8 @@ def test_header_for_job_without_company(self) -> None:
         payload = response.json()
         self.assertIsNone(payload["company_id"])
         self.assertIsNone(payload["company_name"])
-        self.assertIsNone(payload["contact_id"])
-        self.assertIsNone(payload["contact_name"])
+        self.assertIsNone(payload["person_id"])
+        self.assertIsNone(payload["person_name"])
 
     def test_etag_round_trip_returns_304(self) -> None:
         job_company = Company.objects.create(
diff --git a/apps/job/tests/test_job_rest_service.py b/apps/job/tests/test_job_rest_service.py
index 6525f07f5..17fec110d 100644
--- a/apps/job/tests/test_job_rest_service.py
+++ b/apps/job/tests/test_job_rest_service.py
@@ -2,7 +2,7 @@
 
 from django.utils import timezone
 
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, Person
 from apps.job.models import Job, JobEvent
 from apps.job.models.costing import CostLine
 from apps.job.services.job_rest_service import JobRestService
@@ -49,11 +49,11 @@ def test_get_job_for_edit_serializes_event_staff(self):
             name="Edit Job Company",
             xero_last_modified=timezone.now(),
         )
-        contact = ClientContact.objects.create(company=company, name="Site Contact")
+        person = Person.objects.create(name="Site Contact")
         job = Job.objects.create(
             name="Editable Job",
             company=company,
-            contact=contact,
+            person=person,
             created_by=self.test_staff,
             default_xero_pay_item=XeroPayItem.get_ordinary_time(),
             staff=self.test_staff,
diff --git a/apps/job/tests/test_kanban_search.py b/apps/job/tests/test_kanban_search.py
index fcdedffc2..f9cba47b2 100644
--- a/apps/job/tests/test_kanban_search.py
+++ b/apps/job/tests/test_kanban_search.py
@@ -12,7 +12,7 @@
 from nplusone.ext.django.patch import apply_patches
 
 from apps.accounting.models import Invoice, Quote
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.job.models import Job
 from apps.job.services.kanban_service import KanbanService
 from apps.testing import BaseTestCase
@@ -38,20 +38,25 @@ def _make_job(
         name: str,
         company_name: str,
         status: str = "in_progress",
-        contact_name: str | None = None,
+        person_name: str | None = None,
         order_number: str | None = None,
     ):
         company = self._make_client(company_name)
-        contact = None
-        if contact_name:
-            contact = ClientContact.objects.create(company=company, name=contact_name)
+        person = None
+        if person_name:
+            person = Person.objects.create(name=person_name)
+            CompanyPersonLink.objects.create(
+                company=company,
+                person=person,
+                xero_name=person_name,
+            )
 
         self.job_number += 1
         return Job.objects.create(
             staff=self.test_staff,
             name=name,
             company=company,
-            contact=contact,
+            person=person,
             status=status,
             job_number=self.job_number,
             created_by=self.test_staff,
@@ -287,7 +292,7 @@ def test_perform_advanced_search_keeps_plausible_short_job_number_match(
         self._make_job(
             name="Auckland airport - bag drop",
             company_name="Another Company",
-            contact_name="Alice Brown",
+            person_name="Alice Brown",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "977"}))
@@ -362,17 +367,17 @@ def test_perform_advanced_search_matches_client_tokens_in_any_order(self):
 
         self.assertEqual([job.id for job in jobs], [target.id])
 
-    def test_perform_advanced_search_matches_contact_name_substring(self):
+    def test_perform_advanced_search_matches_person_name_substring(self):
         """Catches contact-name search no longer matching partial names."""
         target = self._make_job(
             name="Kick plates",
             company_name="Weaver, Decker and Schultz",
-            contact_name="Molly Wainwright",
+            person_name="Molly Wainwright",
         )
         self._make_job(
             name="Other work",
             company_name="Other Company",
-            contact_name="Alice Brown",
+            person_name="Alice Brown",
         )
 
         jobs = list(KanbanService.perform_advanced_search({"universal_search": "wain"}))
diff --git a/apps/job/tests/test_kanban_service.py b/apps/job/tests/test_kanban_service.py
index f4dbe3221..0afcb4f46 100644
--- a/apps/job/tests/test_kanban_service.py
+++ b/apps/job/tests/test_kanban_service.py
@@ -8,7 +8,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.job.models import Job
 from apps.job.services.kanban_service import KanbanService
 from apps.testing import BaseTestCase
@@ -43,6 +43,14 @@ def _set_summary_revenue(self, cost_set, revenue):
     def _serialize_one(self, job: Job) -> dict[str, Any]:
         return KanbanService.serialize_jobs_for_api([job])[0]
 
+    def _link(self, name: str) -> CompanyPersonLink:
+        person = Person.objects.create(name=name)
+        return CompanyPersonLink.objects.create(
+            company=self.client_obj,
+            person=person,
+            xero_name=name,
+        )
+
     def test_over_budget_when_tm_actual_exceeds_price_cap(self):
         """T&M jobs show over-budget when actual revenue exceeds the price cap."""
         job = self._create_job("time_materials")
@@ -80,10 +88,9 @@ def test_serialize_jobs_for_api_query_count_is_constant(self):
         jobs = []
         for index in range(3):
             job = self._create_job(name=f"Batch Job {index}")
-            job.contact = ClientContact.objects.create(
-                company=self.client_obj, name=f"Contact {index}"
-            )
-            job.save(staff=self.test_staff, update_fields=["contact"])
+            link = self._link(f"Contact {index}")
+            job.person = link.person
+            job.save(staff=self.test_staff, update_fields=["person"])
             job.people.add(self.test_staff)
             self._set_summary_revenue(job.latest_actual, Decimal("100.00"))
             self._set_summary_revenue(job.latest_quote, Decimal("200.00"))
@@ -107,10 +114,10 @@ def test_serialized_shape_for_fully_populated_job(self):
         """The rewritten serializer must keep the exact response contract the
         frontend Zod schema requires."""
         job = self._create_job(name="Shape Job")
-        contact = ClientContact.objects.create(company=self.client_obj, name="Jane Doe")
-        job.contact = contact
+        contact = self._link("Jane Doe")
+        job.person = contact.person
         job.delivery_date = timezone.localdate()
-        job.save(staff=self.test_staff, update_fields=["contact", "delivery_date"])
+        job.save(staff=self.test_staff, update_fields=["person", "delivery_date"])
         staff_b = Staff.objects.create_user(
             email="kanban-shape-b@example.com",
             password="testpass",
@@ -137,7 +144,7 @@ def test_serialized_shape_for_fully_populated_job(self):
                 "description",
                 "job_number",
                 "company_name",
-                "contact_person",
+                "person_name",
                 "people",
                 "status",
                 "status_key",
@@ -162,7 +169,7 @@ def test_serialized_shape_for_fully_populated_job(self):
             },
         )
         self.assertEqual(serialized["company_name"], "Test Company")
-        self.assertEqual(serialized["contact_person"], "Jane Doe")
+        self.assertEqual(serialized["person_name"], "Jane Doe")
         self.assertEqual(serialized["quote_revenue"], 200.0)
         self.assertEqual(serialized["time_and_materials_revenue"], 100.0)
         self.assertEqual(serialized["created_by_id"], str(self.test_staff.id))
diff --git a/apps/job/tests/test_workshop_pdf_service.py b/apps/job/tests/test_workshop_pdf_service.py
index 612208bde..779aa9dd6 100644
--- a/apps/job/tests/test_workshop_pdf_service.py
+++ b/apps/job/tests/test_workshop_pdf_service.py
@@ -14,7 +14,7 @@
 from django.utils import timezone
 from pypdf import PdfReader
 
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod, Person
 from apps.job.models import CostSet, Job, LabourSubtype
 from apps.job.models.costing import CostLine
 from apps.job.services.workshop_pdf_service import (
@@ -40,26 +40,23 @@ def setUp(self) -> None:
             name="Phone Pref Company",
             xero_last_modified=timezone.now(),
         )
-        self.contact = ClientContact.objects.create(
-            company=self.client_obj,
-            name="Jane Doe",
-        )
+        self.person = Person.objects.create(name="Jane Doe")
         self.job = Job.objects.create(
             company=self.client_obj,
-            contact=self.contact,
+            person=self.person,
             name="Phone Pref Job",
             staff=self.test_staff,
         )
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=self.client_obj,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 555 0001",
         )
 
     def test_contact_phone_wins_when_contact_has_one(self) -> None:
-        ClientContactMethod.objects.create(
-            contact=self.contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        ContactMethod.objects.create(
+            person=self.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
         loaded_job = get_job_for_delivery_docket_pdf(self.job.id)
@@ -72,8 +69,8 @@ def test_falls_back_to_client_phone_when_contact_has_none(self) -> None:
         self.assertEqual(_primary_phone_for_job(loaded_job), "09 555 0001")
 
     def test_no_contact_uses_client_phone(self) -> None:
-        self.job.contact = None
-        self.job.save(staff=self.test_staff, update_fields=["contact"])
+        self.job.person = None
+        self.job.save(staff=self.test_staff, update_fields=["person"])
         loaded_job = get_job_for_delivery_docket_pdf(self.job.id)
 
         self.assertEqual(_primary_phone_for_job(loaded_job), "09 555 0001")
@@ -85,9 +82,9 @@ def test_plain_job_phone_lookup_is_rejected(self) -> None:
             _primary_phone_for_job(self.job)
 
     def test_annotated_contact_phone_wins_when_contact_has_one(self) -> None:
-        ClientContactMethod.objects.create(
-            contact=self.contact,
-            method_type=ClientContactMethod.MethodType.PHONE,
+        ContactMethod.objects.create(
+            person=self.person,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 100",
         )
 
@@ -553,9 +550,9 @@ def test_preloaded_workshop_pdf_render_does_not_query_cost_lines(self) -> None:
         estimate = self.job.latest_estimate
         assert estimate is not None
         self._add_time(estimate, "Workshop", "4.000", "Workshop")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=self.job.company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 555 0001",
         )
 
diff --git a/apps/job/views/job_rest_views.py b/apps/job/views/job_rest_views.py
index dd0b39096..e83e06f32 100644
--- a/apps/job/views/job_rest_views.py
+++ b/apps/job/views/job_rest_views.py
@@ -263,7 +263,7 @@ def post(self, request):
             "description": "Optional description",
             "order_number": "Optional order number",
             "notes": "Optional notes",
-            "contact_id": "optional-contact-uuid"
+            "person_id": "optional-person-uuid"
             "pricing_methodology": "Optional methodology (defaults to T&M)"
         }
         """
@@ -889,15 +889,15 @@ def get(self, request, job_id):
         Fetch essential job header data for fast initial loading.
         """
         try:
-            # Query fields derived from JOB_DIRECT_FIELDS, plus id and company/contact for joins
+            # Query fields derived from JOB_DIRECT_FIELDS, plus id and company/person for joins
             query_fields = [
                 "id",
                 "updated_at",
                 "company_id",
-                "contact_id",
+                "person_id",
             ] + Job.JOB_DIRECT_FIELDS
             job = (
-                Job.objects.select_related("company", "contact")
+                Job.objects.select_related("company", "person")
                 .only(*query_fields)
                 .get(id=job_id)
             )
diff --git a/apps/job/views/kanban_view_api.py b/apps/job/views/kanban_view_api.py
index 9261b01ef..bc237261c 100644
--- a/apps/job/views/kanban_view_api.py
+++ b/apps/job/views/kanban_view_api.py
@@ -366,11 +366,11 @@ class AdvancedSearchAPIView(APIView):
                 description="Filter by company name",
             ),
             OpenApiParameter(
-                name="contact_person",
+                name="person_name",
                 type=str,
                 location=OpenApiParameter.QUERY,
                 required=False,
-                description="Filter by contact person",
+                description="Filter by person name",
             ),
             OpenApiParameter(
                 name="order_number",
@@ -440,7 +440,7 @@ def get(self, request: Request) -> Response:
                 "name": request.GET.get("name", ""),
                 "description": request.GET.get("description", ""),
                 "company_name": request.GET.get("company_name", ""),
-                "contact_person": request.GET.get("contact_person", ""),
+                "person_name": request.GET.get("person_name", ""),
                 "order_number": request.GET.get("order_number", ""),
                 "created_by": request.GET.get("created_by", ""),
                 "created_after": request.GET.get("created_after", ""),
diff --git a/apps/job/views/workshop_view.py b/apps/job/views/workshop_view.py
index fdb8b5e03..6e42c59ea 100644
--- a/apps/job/views/workshop_view.py
+++ b/apps/job/views/workshop_view.py
@@ -30,7 +30,9 @@ def get_queryset(self):
         """Retrieve jobs for the workshop kanban view."""
         staff = self.request.user
         logger.info(f"Fetching in-progress jobs for staff ID: {staff.id}")
-        jobs = Job.objects.filter(people__id=staff.id, status__in=["in_progress"])
+        jobs = Job.objects.filter(
+            people__id=staff.id, status__in=["in_progress"]
+        ).select_related("company", "person")
         logger.info(f"Retrieved {jobs.count()} jobs for staff ID: {staff.id}")
 
         return [
@@ -40,7 +42,7 @@ def get_queryset(self):
                 "description": job.description,
                 "job_number": job.job_number,
                 "company_name": job.company.name,
-                "contact_person": job.contact.name if job.contact else None,
+                "person_name": job.person.name if job.person else None,
                 "people": [
                     {
                         "id": staff.id,
diff --git a/apps/purchasing/services/supplier_search_service.py b/apps/purchasing/services/supplier_search_service.py
index 625bbcfad..ecddbacc2 100644
--- a/apps/purchasing/services/supplier_search_service.py
+++ b/apps/purchasing/services/supplier_search_service.py
@@ -12,7 +12,7 @@
 from django.db.models import Count, Q
 from django.utils import timezone
 
-from apps.company.models import ClientContactMethod, Company, SupplierSearchAlias
+from apps.company.models import Company, ContactMethod, SupplierSearchAlias
 
 if TYPE_CHECKING:
     from django_stubs_ext import WithAnnotations
@@ -181,7 +181,7 @@ def list_suppliers(
                 & ~Q(purchase_orders__status="deleted"),
                 distinct=True,
             ),
-            primary_phone=ClientContactMethod.primary_phone_annotation(
+            primary_phone=ContactMethod.primary_phone_annotation(
                 owner="company", outer_ref="pk"
             ),
         )
diff --git a/apps/timesheet/management/commands/create_special_job.py b/apps/timesheet/management/commands/create_special_job.py
index 9d9c8c1d9..84db298b7 100644
--- a/apps/timesheet/management/commands/create_special_job.py
+++ b/apps/timesheet/management/commands/create_special_job.py
@@ -70,7 +70,6 @@ def handle(self, *args, **options):
                 name=name,
                 status="special",
                 company=company,
-                contact=None,
                 pricing_methodology="time_materials",
                 speed_quality_tradeoff="normal",
                 job_is_valid=True,
diff --git a/apps/workflow/api/xero/push.py b/apps/workflow/api/xero/push.py
index 0df6d6700..6f28a1a3f 100644
--- a/apps/workflow/api/xero/push.py
+++ b/apps/workflow/api/xero/push.py
@@ -478,17 +478,17 @@ def create_company_contact_in_xero(company):
     return company.xero_contact_id
 
 
-def bulk_create_contacts_in_xero(clients_to_create, batch_size=50):
+def bulk_create_contacts_in_xero(companies_to_create, batch_size=50):
     """Create multiple company contacts in Xero in batches of 50"""
-    if not clients_to_create:
+    if not companies_to_create:
         return 0
 
     accounting_api = AccountingApi(api_client)
 
     total_created = 0
 
-    for i in range(0, len(clients_to_create), batch_size):
-        batch = clients_to_create[i : i + batch_size]
+    for i in range(0, len(companies_to_create), batch_size):
+        batch = companies_to_create[i : i + batch_size]
 
         contact_batch = []
         for company in batch:
@@ -527,7 +527,7 @@ def bulk_create_contacts_in_xero(clients_to_create, batch_size=50):
 
             time.sleep(SLEEP_TIME)
 
-            # Map response back to clients by submission order. Verified
+            # Map response back to companies by submission order. Verified
             # against dev Xero by scripts/integration/verify_xero_batch_order.py.
             for idx, (company, created_contact) in enumerate(
                 zip(batch, response.contacts, strict=True)
diff --git a/apps/workflow/api/xero/reprocess_xero.py b/apps/workflow/api/xero/reprocess_xero.py
index 506e45c5c..8674d9158 100644
--- a/apps/workflow/api/xero/reprocess_xero.py
+++ b/apps/workflow/api/xero/reprocess_xero.py
@@ -17,9 +17,10 @@
     InvoiceLineItem,
 )
 from apps.company.models import (
-    ClientContact,
-    ClientContactMethod,
     Company,
+    CompanyPersonLink,
+    ContactMethod,
+    Person,
     SupplierPickupAddress,
 )
 from apps.crm.tasks import rematch_phone_calls_task
@@ -59,26 +60,25 @@ def sync_xero_phone_methods(company: Company) -> list[str]:
         if not isinstance(phone_entry, dict):
             continue
         value = _xero_phone_value(phone_entry)
-        normalized = ClientContactMethod.normalize_phone(value)
+        normalized = ContactMethod.normalize_phone(value)
         if not normalized:
             continue
         # The "one number, one company" rule is enforced by the grandfathered
-        # ClientContactMethod.save() guard reached via get_or_create below:
+        # ContactMethod.save() guard reached via get_or_create below:
         # re-syncing an existing number never saves (nothing to update), while
         # a genuinely-new cross-company number raises and hard-fails this
         # company's sync (deliberate — the data must be fixed, not skipped).
         phone_type = phone_entry.get("_phone_type") or ""
         try:
-            _, created = ClientContactMethod.objects.get_or_create(
+            _, created = ContactMethod.objects.get_or_create(
                 company=company,
-                contact=None,
-                method_type=ClientContactMethod.MethodType.PHONE,
+                method_type=ContactMethod.MethodType.PHONE,
                 normalized_value=normalized,
                 defaults={
                     "value": value,
                     "label": phone_type,
                     "is_primary": phone_type == "DEFAULT",
-                    "source": ClientContactMethod.Source.IMPORTED,
+                    "source": ContactMethod.Source.IMPORTED,
                 },
             )
         except AlreadyLoggedException:
@@ -268,8 +268,6 @@ def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
         "email",
         "address",
         "is_account_customer",
-        "primary_contact_name",
-        "primary_contact_email",
         "xero_archived",
     ]
     old_values = {}
@@ -372,71 +370,48 @@ def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
         "_is_customer", company.is_account_customer
     )
 
-    contact_first_name = raw_json.get("_first_name", None)
-    contact_last_name = raw_json.get("_last_name", None)
-
-    match (contact_first_name, contact_last_name):
-        case (str() as first, str() as last) if first and last:
-            company.primary_contact_name = f"{first} {last}"
-        case (str() as first, None) if first:
-            company.primary_contact_name = first
-        case (None, str() as last) if last:
-            company.primary_contact_name = last
-        case _:
-            company.primary_contact_name = "Unnamed Contact"
-
-    contact_email = raw_json.get("_email_address", None)
-    if contact_email:
-        company.primary_contact_email = contact_email
-
-    additional_persons = raw_json.get("_contact_persons", [])
-    if len(additional_persons) > 0:
-        company.additional_contact_persons = [
-            {
-                "name": (person.get("_first_name") or "")
-                + (" " + person.get("_last_name") if person.get("_last_name") else ""),
-                "email": person.get("_email_address"),
-            }
-            for person in additional_persons
-            if isinstance(person, dict)
-        ]
-        for person in additional_persons:
-            if isinstance(person, dict):
-                first_name = person.get("_first_name") or ""
-                last_name = person.get("_last_name") or ""
-                name = (first_name + (" " + last_name if last_name else "")).strip()
-
-                # Skip contacts with empty names - they're pointless
-                if not name:
-                    logger.debug(
-                        f"Skipping contact with empty name for company {company.name}"
-                    )
-                    continue
-
-                # Use None instead of empty string for nullable fields
-                email = person.get("_email_address") or None
-
-                try:
-                    contact, created = ClientContact.objects.get_or_create(
-                        company=company,
-                        name=name,
-                        defaults={"email": email},
-                    )
-                    # Update email if contact exists and email changed
-                    if not created and contact.email != email:
-                        contact.email = email
-                        contact.save()
-                except ClientContact.MultipleObjectsReturned as exc:
-                    # Should NEVER happen after migrations + constraint.
-                    # If we hit this, data integrity is broken - fail fast.
-                    persist_and_raise(
-                        exc,
-                        additional_context={
-                            "operation": "set_company_fields_duplicate_contact",
-                            "client_id": str(company.id),
-                            "contact_name": name,
-                        },
-                    )
+    for person_payload in raw_json.get("_contact_persons", []):
+        if not isinstance(person_payload, dict):
+            continue
+        first_name = person_payload.get("_first_name") or ""
+        last_name = person_payload.get("_last_name") or ""
+        xero_name = (first_name + (" " + last_name if last_name else "")).strip()
+        if not xero_name:
+            logger.debug("Skipping Xero contact person with empty name for %s", company)
+            continue
+        email = person_payload.get("_email_address") or None
+        try:
+            link = (
+                CompanyPersonLink.objects.filter(
+                    company=company,
+                    xero_name=xero_name,
+                )
+                .select_related("person")
+                .get()
+            )
+            if not link.is_active:
+                link.is_active = True
+                link.save(update_fields=["is_active", "updated_at"])
+            if link.person.email != email:
+                link.person.email = email
+                link.person.save(update_fields=["email", "updated_at"])
+        except CompanyPersonLink.DoesNotExist:
+            person = Person.objects.create(name=xero_name, email=email)
+            CompanyPersonLink.objects.create(
+                company=company,
+                person=person,
+                xero_name=xero_name,
+                is_active=True,
+            )
+        except CompanyPersonLink.MultipleObjectsReturned as exc:
+            persist_and_raise(
+                exc,
+                additional_context={
+                    "operation": "set_company_fields_duplicate_person_link",
+                    "client_id": str(company.id),
+                    "xero_name": xero_name,
+                },
+            )
 
     # Handle xero_last_modified
     updated_date_utc_str = raw_json.get("_updated_date_utc")
diff --git a/apps/workflow/api/xero/seed.py b/apps/workflow/api/xero/seed.py
index d1d4408aa..acb42c949 100644
--- a/apps/workflow/api/xero/seed.py
+++ b/apps/workflow/api/xero/seed.py
@@ -24,8 +24,8 @@
 logger = logging.getLogger("xero")
 
 
-def seed_companies_to_xero(clients):
-    """Bulk process clients: link existing contacts + create missing ones in batches of 50"""
+def seed_companies_to_xero(companies):
+    """Bulk process companies: link existing Xero contacts or create missing ones."""
     # Get all existing Xero contacts (one API call)
     try:
         existing_contacts = get_all_xero_contacts()
@@ -34,7 +34,7 @@ def seed_companies_to_xero(clients):
         raise  # FAIL EARLY
 
     # Multimap: a single Xero name can map to multiple contact_ids (Xero
-    # allows duplicate contact names). Local clients with shared names
+    # allows duplicate contact names). Local companies with shared names
     # (legitimate — different real customers in Morris/MSM data) must each
     # claim a distinct Xero contact_id; the column is unique-constrained.
     existing_by_name = defaultdict(list)
@@ -43,23 +43,23 @@ def seed_companies_to_xero(clients):
 
     results = {"linked": 0, "created": 0, "failed": []}
 
-    # Separate clients into link vs create lists
-    clients_to_link = []
-    clients_to_create = []
+    # Separate companies into link vs create lists
+    companies_to_link = []
+    companies_to_create = []
 
-    for company in clients:
+    for company in companies:
         candidates = existing_by_name.get(company.name.lower())
         if candidates:
             # Pop one candidate so a second local company with the same name
             # doesn't race onto the same xero_contact_id; it falls through
             # to create instead.
             existing_contact_id = candidates.pop(0)
-            clients_to_link.append((company, existing_contact_id))
+            companies_to_link.append((company, existing_contact_id))
         else:
-            clients_to_create.append(company)
+            companies_to_create.append(company)
 
     # Process linking (fast, no API calls)
-    for company, existing_contact_id in clients_to_link:
+    for company, existing_contact_id in companies_to_link:
         try:
             company.xero_contact_id = existing_contact_id
             company.save(update_fields=["xero_contact_id"])
@@ -75,8 +75,8 @@ def seed_companies_to_xero(clients):
     # bulk_create_contacts_in_xero relies on Xero preserving submission
     # order in the response. If you suspect that's changed, run
     # scripts/integration/verify_xero_batch_order.py before this seed.
-    if clients_to_create:
-        results["created"] = bulk_create_contacts_in_xero(clients_to_create)
+    if companies_to_create:
+        results["created"] = bulk_create_contacts_in_xero(companies_to_create)
 
     return results
 
diff --git a/apps/workflow/fixtures/company_defaults.json b/apps/workflow/fixtures/company_defaults.json
index f9880f264..aea4ab0a0 100644
--- a/apps/workflow/fixtures/company_defaults.json
+++ b/apps/workflow/fixtures/company_defaults.json
@@ -13,9 +13,6 @@
       "allow_jobs": true,
       "xero_last_modified": "2024-01-01T00:00:00Z",
       "raw_json": {},
-      "primary_contact_name": null,
-      "primary_contact_email": null,
-      "additional_contact_persons": [],
       "django_created_at": "2024-01-01T00:00:00Z",
       "django_updated_at": "2024-01-01T00:00:00Z",
       "xero_last_synced": "2024-01-01T00:00:00Z",
diff --git a/apps/workflow/fixtures/company_defaults_prospect.json b/apps/workflow/fixtures/company_defaults_prospect.json
index eee5b85d7..7069382ba 100644
--- a/apps/workflow/fixtures/company_defaults_prospect.json
+++ b/apps/workflow/fixtures/company_defaults_prospect.json
@@ -13,9 +13,6 @@
       "allow_jobs": true,
       "xero_last_modified": "2024-01-01T00:00:00Z",
       "raw_json": {},
-      "primary_contact_name": null,
-      "primary_contact_email": null,
-      "additional_contact_persons": [],
       "django_created_at": "2024-01-01T00:00:00Z",
       "django_updated_at": "2024-01-01T00:00:00Z",
       "xero_last_synced": "2024-01-01T00:00:00Z",
diff --git a/apps/workflow/management/commands/e2e_cleanup.py b/apps/workflow/management/commands/e2e_cleanup.py
index 20b5bd4f4..4448dab3a 100644
--- a/apps/workflow/management/commands/e2e_cleanup.py
+++ b/apps/workflow/management/commands/e2e_cleanup.py
@@ -15,14 +15,14 @@
 from django.db import transaction
 
 from apps.accounting.models import Invoice, Quote
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink
 from apps.job.models import Job, QuoteSpreadsheet
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine
 
 logger = logging.getLogger(__name__)
 
 TEST_DATA_PREFIX = "[TEST]"
-TEST_CLIENT_NAME = "ABC Carpet Cleaning TEST IGNORE"
+TEST_COMPANY_NAME = "ABC Carpet Cleaning TEST IGNORE"
 LEGACY_E2E_PREFIXES = ["E2E Test Client", "E2E Modal Client", "E2E Test Supplier"]
 
 
@@ -41,70 +41,74 @@ def handle(self, *args, **options):
 
         # Collect what to delete
         test_jobs = Job.objects.filter(name__startswith=TEST_DATA_PREFIX)
-        test_contacts = ClientContact.objects.filter(name__startswith=TEST_DATA_PREFIX)
-        test_clients = Company.objects.filter(name__startswith=TEST_DATA_PREFIX)
+        test_people = CompanyPersonLink.objects.filter(
+            person__name__startswith=TEST_DATA_PREFIX
+        )
+        test_companies = Company.objects.filter(name__startswith=TEST_DATA_PREFIX)
         # Swept so Job.company PROTECT doesn't block the [TEST] company delete.
-        test_prefix_client_jobs = Job.objects.filter(company__in=test_clients)
-        test_prefix_client_contacts = ClientContact.objects.filter(
-            company__in=test_clients
+        test_prefix_company_jobs = Job.objects.filter(company__in=test_companies)
+        test_prefix_company_people = CompanyPersonLink.objects.filter(
+            company__in=test_companies
         )
 
-        # Legacy E2E-prefixed clients and their data
+        # Legacy E2E-prefixed companies and their data
         from django.db.models import Q
 
         legacy_q = Q()
         for prefix in LEGACY_E2E_PREFIXES:
             legacy_q |= Q(name__startswith=prefix)
-        legacy_clients = Company.objects.filter(legacy_q)
-        legacy_client_jobs = Job.objects.filter(company__in=legacy_clients)
-        legacy_client_contacts = ClientContact.objects.filter(
-            company__in=legacy_clients
+        legacy_companies = Company.objects.filter(legacy_q)
+        legacy_company_jobs = Job.objects.filter(company__in=legacy_companies)
+        legacy_company_people = CompanyPersonLink.objects.filter(
+            company__in=legacy_companies
         )
 
-        # Test company data (all jobs/contacts on the test company are test artifacts)
-        test_client_qs = Company.objects.filter(name=TEST_CLIENT_NAME)
-        test_client_jobs = Job.objects.filter(company__in=test_client_qs)
-        test_client_contacts = ClientContact.objects.filter(company__in=test_client_qs)
+        # Test company data (all jobs/people on the test company are test artifacts)
+        test_company_qs = Company.objects.filter(name=TEST_COMPANY_NAME)
+        test_company_jobs = Job.objects.filter(company__in=test_company_qs)
+        test_company_people = CompanyPersonLink.objects.filter(
+            company__in=test_company_qs
+        )
 
         # Report
         self.stdout.write("\n=== E2E Test Data ===\n")
 
         self._report_queryset("[TEST]-prefixed jobs", test_jobs, "name")
-        self._report_queryset("[TEST]-prefixed contacts", test_contacts, "name")
-        self._report_queryset("[TEST]-prefixed clients", test_clients, "name")
-        self._report_queryset("Legacy E2E clients", legacy_clients, "name")
-        self._report_queryset("Legacy E2E company jobs", legacy_client_jobs, "name")
+        self._report_queryset("[TEST]-prefixed people", test_people, "person__name")
+        self._report_queryset("[TEST]-prefixed companies", test_companies, "name")
+        self._report_queryset("Legacy E2E companies", legacy_companies, "name")
+        self._report_queryset("Legacy E2E company jobs", legacy_company_jobs, "name")
         self._report_queryset(
-            "Legacy E2E company contacts", legacy_client_contacts, "name"
+            "Legacy E2E company people", legacy_company_people, "person__name"
         )
         self._report_queryset(
-            f"Jobs on test company ({TEST_CLIENT_NAME})", test_client_jobs, "name"
+            f"Jobs on test company ({TEST_COMPANY_NAME})", test_company_jobs, "name"
         )
         self._report_queryset(
-            f"Contacts on test company ({TEST_CLIENT_NAME})",
-            test_client_contacts,
-            "name",
+            f"People on test company ({TEST_COMPANY_NAME})",
+            test_company_people,
+            "person__name",
         )
         self._report_queryset(
-            "Jobs on [TEST]-prefixed clients", test_prefix_client_jobs, "name"
+            "Jobs on [TEST]-prefixed companies", test_prefix_company_jobs, "name"
         )
         self._report_queryset(
-            "Contacts on [TEST]-prefixed clients",
-            test_prefix_client_contacts,
-            "name",
+            "People on [TEST]-prefixed companies",
+            test_prefix_company_people,
+            "person__name",
         )
 
         total = (
             test_jobs.count()
-            + test_contacts.count()
-            + test_clients.count()
-            + legacy_clients.count()
-            + legacy_client_jobs.count()
-            + legacy_client_contacts.count()
-            + test_client_jobs.count()
-            + test_client_contacts.count()
-            + test_prefix_client_jobs.count()
-            + test_prefix_client_contacts.count()
+            + test_people.count()
+            + test_companies.count()
+            + legacy_companies.count()
+            + legacy_company_jobs.count()
+            + legacy_company_people.count()
+            + test_company_jobs.count()
+            + test_company_people.count()
+            + test_prefix_company_jobs.count()
+            + test_prefix_company_people.count()
         )
 
         if total == 0:
@@ -128,7 +132,10 @@ def handle(self, *args, **options):
 
         # Collect all jobs that will be deleted (union of all sources)
         all_jobs_to_delete = (
-            test_jobs | test_client_jobs | legacy_client_jobs | test_prefix_client_jobs
+            test_jobs
+            | test_company_jobs
+            | legacy_company_jobs
+            | test_prefix_company_jobs
         ).distinct()
 
         # Check for rows with PROTECTED FKs pointing at these jobs
@@ -164,15 +171,15 @@ def handle(self, *args, **options):
                 "sheet_id",
             )
 
-        # Collect all clients to delete
-        all_clients_to_delete = (test_clients | legacy_clients).distinct()
+        # Collect all companies to delete
+        all_companies_to_delete = (test_companies | legacy_companies).distinct()
 
-        # Find POs referencing these clients (PROTECTED FK on supplier)
-        linked_pos = PurchaseOrder.objects.filter(supplier__in=all_clients_to_delete)
+        # Find POs referencing these companies (PROTECTED FK on supplier)
+        linked_pos = PurchaseOrder.objects.filter(supplier__in=all_companies_to_delete)
 
         if linked_pos.exists():
             self._report_queryset(
-                "Purchase orders linked to test clients (will be deleted)",
+                "Purchase orders linked to test companies (will be deleted)",
                 linked_pos,
                 "id",
             )
@@ -187,7 +194,7 @@ def handle(self, *args, **options):
             if count:
                 self.stdout.write(f"  Invoices: {count} objects ({details})")
 
-            # 2. POs on test clients (PROTECTED FK on supplier)
+            # 2. POs on test companies (PROTECTED FK on supplier)
             count, details = linked_pos.delete()
             if count:
                 self.stdout.write(f"  Purchase orders: {count} objects ({details})")
@@ -206,41 +213,43 @@ def handle(self, *args, **options):
                 self.stdout.write(f"  Quote spreadsheets: {count} objects ({details})")
 
             # 4. Jobs on test company (cascade deletes cost sets, cost lines, etc.)
-            count, details = test_client_jobs.delete()
+            count, details = test_company_jobs.delete()
             self.stdout.write(f"  Test company jobs: {count} objects ({details})")
 
-            # 5. Contacts on test company
-            count, details = test_client_contacts.delete()
-            self.stdout.write(f"  Test company contacts: {count} objects ({details})")
+            # 5. People on test company
+            count, details = test_company_people.delete()
+            self.stdout.write(f"  Test company people: {count} objects ({details})")
 
             # 6. Legacy company data
-            count, details = legacy_client_jobs.delete()
+            count, details = legacy_company_jobs.delete()
             self.stdout.write(f"  Legacy company jobs: {count} objects ({details})")
 
-            count, details = legacy_client_contacts.delete()
-            self.stdout.write(f"  Legacy company contacts: {count} objects ({details})")
+            count, details = legacy_company_people.delete()
+            self.stdout.write(f"  Legacy company people: {count} objects ({details})")
 
-            count, details = legacy_clients.delete()
-            self.stdout.write(f"  Legacy clients: {count} objects ({details})")
+            count, details = legacy_companies.delete()
+            self.stdout.write(f"  Legacy companies: {count} objects ({details})")
 
             # 7. [TEST]-prefixed items (may overlap with above, that's fine)
             count, details = test_jobs.delete()
             self.stdout.write(f"  [TEST] jobs: {count} objects ({details})")
 
-            count, details = test_contacts.delete()
-            self.stdout.write(f"  [TEST] contacts: {count} objects ({details})")
+            count, details = test_people.delete()
+            self.stdout.write(f"  [TEST] people: {count} objects ({details})")
 
-            # 8. Jobs/contacts on [TEST]-prefixed clients (unblocks company delete)
-            count, details = test_prefix_client_jobs.delete()
-            self.stdout.write(f"  Jobs on [TEST] clients: {count} objects ({details})")
+            # 8. Jobs/people on [TEST]-prefixed companies (unblocks company delete)
+            count, details = test_prefix_company_jobs.delete()
+            self.stdout.write(
+                f"  Jobs on [TEST] companies: {count} objects ({details})"
+            )
 
-            count, details = test_prefix_client_contacts.delete()
+            count, details = test_prefix_company_people.delete()
             self.stdout.write(
-                f"  Contacts on [TEST] clients: {count} objects ({details})"
+                f"  People on [TEST] companies: {count} objects ({details})"
             )
 
-            count, details = test_clients.delete()
-            self.stdout.write(f"  [TEST] clients: {count} objects ({details})")
+            count, details = test_companies.delete()
+            self.stdout.write(f"  [TEST] companies: {count} objects ({details})")
 
         self.stdout.write("\nDone.")
 
diff --git a/apps/workflow/management/commands/relabel_client_app.py b/apps/workflow/management/commands/relabel_client_app.py
index d52395475..27ab6d533 100644
--- a/apps/workflow/management/commands/relabel_client_app.py
+++ b/apps/workflow/management/commands/relabel_client_app.py
@@ -73,12 +73,17 @@ def handle(
                 "UPDATE django_content_type SET app_label = 'company' "
                 "WHERE app_label = 'client'"
             )
+            renamed_tables = 0
             for old, new in TABLE_RENAMES:
+                cursor.execute("SELECT to_regclass(%s)", [old])
+                if cursor.fetchone()[0] is None:
+                    continue
                 cursor.execute(f'ALTER TABLE "{old}" RENAME TO "{new}"')
+                renamed_tables += 1
         self.stdout.write(
             self.style.SUCCESS(
                 f"Relabelled the client app: dropped {stale_rows - 1} historic "
                 "ledger rows, kept 0001_baseline, renamed content types and "
-                f"{len(TABLE_RENAMES)} tables."
+                f"{renamed_tables} tables."
             )
         )
diff --git a/apps/workflow/management/commands/seed_xero_from_database.py b/apps/workflow/management/commands/seed_xero_from_database.py
index 965cdc6a3..97502bbde 100644
--- a/apps/workflow/management/commands/seed_xero_from_database.py
+++ b/apps/workflow/management/commands/seed_xero_from_database.py
@@ -233,7 +233,7 @@ def process_accounts(self, dry_run):
         return updated + created
 
     def process_contacts(self, dry_run):
-        """Phase 1: Link/Create contacts for all clients with jobs + test company"""
+        """Phase 1: Link/create Xero contacts for all companies with jobs plus test company."""
         # Validate test company exists - required for testing Xero flows
         cd = CompanyDefaults.get_solo()
         if not cd.test_company_name:
@@ -241,48 +241,50 @@ def process_contacts(self, dry_run):
                 "CompanyDefaults.test_company_name is not set. "
                 "This is required for Xero sync testing."
             )
-        test_client = Company.objects.filter(name=cd.test_company_name).first()
-        if not test_client:
+        test_company = Company.objects.filter(name=cd.test_company_name).first()
+        if not test_company:
             raise ValueError(
                 f"Test company '{cd.test_company_name}' not found in database. "
                 "Ensure the test company is created before running Xero sync."
             )
 
-        # Find clients with jobs that need xero_contact_id
-        client_ids_needing_sync = set(
+        # Find companies with jobs that need xero_contact_id
+        company_ids_needing_sync = set(
             Company.objects.filter(
                 jobs__isnull=False, xero_contact_id__isnull=True
             ).values_list("id", flat=True)
         )
 
         # Also include test company if it needs syncing
-        if not test_client.xero_contact_id:
-            client_ids_needing_sync.add(test_client.id)
+        if not test_company.xero_contact_id:
+            company_ids_needing_sync.add(test_company.id)
             self.stdout.write(f"Including test company: {cd.test_company_name}")
 
-        clients_needing_sync = Company.objects.filter(id__in=client_ids_needing_sync)
+        companies_needing_sync = Company.objects.filter(id__in=company_ids_needing_sync)
 
         self.stdout.write(
-            f"Found {clients_needing_sync.count()} clients needing Xero contact IDs"
+            f"Found {companies_needing_sync.count()} companies needing Xero contact IDs"
         )
 
-        if not clients_needing_sync.exists():
-            self.stdout.write("All clients with jobs already have Xero contact IDs")
+        if not companies_needing_sync.exists():
+            self.stdout.write("All companies with jobs already have Xero contact IDs")
             return 0
 
         if dry_run:
-            for company in clients_needing_sync[:10]:  # Show first 10
+            for company in companies_needing_sync[:10]:  # Show first 10
                 job_count = company.jobs.count()
                 self.stdout.write(
                     f"  • Would process: {company.name} ({job_count} jobs)"
                 )
-            if clients_needing_sync.count() > 10:
-                self.stdout.write(f"  ... and {clients_needing_sync.count() - 10} more")
-            return clients_needing_sync.count()
+            if companies_needing_sync.count() > 10:
+                self.stdout.write(
+                    f"  ... and {companies_needing_sync.count() - 10} more"
+                )
+            return companies_needing_sync.count()
 
         # Call sync module for bulk processing
-        self.stdout.write("Processing clients with Xero sync module...")
-        results = seed_companies_to_xero(clients_needing_sync)
+        self.stdout.write("Processing companies with Xero sync module...")
+        results = seed_companies_to_xero(companies_needing_sync)
 
         # Report results
         self.stdout.write(
@@ -290,7 +292,7 @@ def process_contacts(self, dry_run):
         )
 
         if results["failed"]:
-            self.stdout.write(f"Failed to process {len(results['failed'])} clients:")
+            self.stdout.write(f"Failed to process {len(results['failed'])} companies:")
             for name in results["failed"][:5]:  # Show first 5 failures
                 self.stdout.write(f"  • {name}")
             if len(results["failed"]) > 5:
@@ -299,7 +301,7 @@ def process_contacts(self, dry_run):
         return results["linked"] + results["created"]
 
     def process_projects(self, dry_run):
-        """Phase 2: Create projects for all jobs whose clients have xero_contact_id"""
+        """Phase 2: Create projects for all jobs whose companies have xero_contact_id."""
         # Find jobs that need xero_project_id
         jobs_needing_sync = Job.objects.filter(
             company__xero_contact_id__isnull=False, xero_project_id__isnull=True
@@ -311,7 +313,7 @@ def process_projects(self, dry_run):
 
         if not jobs_needing_sync.exists():
             self.stdout.write(
-                "All jobs with valid clients already have Xero project IDs"
+                "All jobs with valid companies already have Xero project IDs"
             )
             return 0
 
diff --git a/apps/workflow/migrations/0007_rename_search_telemetry_client_domain.py b/apps/workflow/migrations/0007_rename_search_telemetry_client_domain.py
new file mode 100644
index 000000000..9ee772bb3
--- /dev/null
+++ b/apps/workflow/migrations/0007_rename_search_telemetry_client_domain.py
@@ -0,0 +1,35 @@
+from typing import Any
+
+from django.db import migrations, models
+
+
+def forwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    SearchTelemetryEvent.objects.filter(domain="client").update(domain="company")
+
+
+def backwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    SearchTelemetryEvent.objects.filter(domain="company").update(domain="client")
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("workflow", "0006_alter_companydefaults_shop_company_and_more"),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards, backwards),
+        migrations.AlterField(
+            model_name="searchtelemetryevent",
+            name="domain",
+            field=models.CharField(
+                choices=[
+                    ("company", "Company"),
+                    ("kanban", "Kanban"),
+                    ("stock", "Stock"),
+                ],
+                max_length=20,
+            ),
+        ),
+    ]
diff --git a/apps/workflow/models/search_telemetry_event.py b/apps/workflow/models/search_telemetry_event.py
index e0972e8b2..63b7274e4 100644
--- a/apps/workflow/models/search_telemetry_event.py
+++ b/apps/workflow/models/search_telemetry_event.py
@@ -13,7 +13,7 @@ class EventType(models.TextChoices):
         CLICK = "click", "Click"
 
     class Domain(models.TextChoices):
-        CLIENT = "client", "Client"
+        COMPANY = "company", "Company"
         KANBAN = "kanban", "Kanban"
         STOCK = "stock", "Stock"
 
diff --git a/apps/workflow/services/db_scrubber.py b/apps/workflow/services/db_scrubber.py
index f2810afd0..ae78ed963 100644
--- a/apps/workflow/services/db_scrubber.py
+++ b/apps/workflow/services/db_scrubber.py
@@ -31,7 +31,7 @@
 )
 from apps.accounts.models import SYSTEM_AUTOMATION_EMAIL, Staff
 from apps.accounts.staff_anonymization import create_staff_profile
-from apps.company.models import ClientContact, ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod, Person
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
 
@@ -115,12 +115,12 @@ def _unique_scrub_value(
     no two scrubbed contact methods can share a normalized value. That keeps the
     scrub clear of the per-owner unique constraints even against a real,
     not-yet-scrubbed number still in the table, without relying on the
-    one-number-one-company guard in ``ClientContactMethod.save()`` (which
+    one-number-one-company guard in ``ContactMethod.save()`` (which
     ``bulk_update`` deliberately bypasses).
     """
     for _ in range(1000):
         value = generate()
-        normalized = ClientContactMethod.normalize_value(method_type, value)
+        normalized = ContactMethod.normalize_value(method_type, value)
         key = (method_type, normalized)
         if normalized and key not in used:
             used.add(key)
@@ -131,16 +131,12 @@ def _unique_scrub_value(
 
 
 def _scrub_companies() -> None:
-    """Mirror legacy PII_CONFIG entries for company.company and company.clientcontact.
+    """Mirror legacy PII_CONFIG entries for companies and people.
 
-    Top-level fields touched: name (with allow-list), primary_contact_name,
-    primary_contact_email, email.
+    Top-level fields touched: company name/email and person name/email.
     raw_json paths touched: _name, _email_address, _bank_account_details,
     _phones[]._phone_number, _batch_payments._bank_account_number,
     _batch_payments._bank_account_name.
-
-    Anything else (address, additional_contact_persons, supplierpickupaddress,
-    other raw_json keys) is left untouched — matches today's behaviour exactly.
     """
     fake = Faker()
     preserved = _preserved_company_names()
@@ -157,8 +153,6 @@ def _scrub_companies() -> None:
                 "Failed to generate unique company name after 1000 attempts"
             )
         company.name = candidate
-        company.primary_contact_name = fake.name()
-        company.primary_contact_email = fake.email()
         company.email = fake.email()
 
         rj = company.raw_json or {}
@@ -181,27 +175,27 @@ def _scrub_companies() -> None:
         company.raw_json = rj
         company.save(using=SCRUB_ALIAS)
 
-    for contact in ClientContact.objects.using(SCRUB_ALIAS).all():
-        contact.name = fake.name()
-        contact.email = fake.email()
-        contact.save(
+    for person in Person.objects.using(SCRUB_ALIAS).all():
+        person.name = fake.name()
+        person.email = fake.email()
+        person.save(
             using=SCRUB_ALIAS,
             update_fields=["name", "email"],
         )
 
     # Preserved companies (shop, test, enabled scrapers) keep their real contact
     # methods, matching the name/email exclusion above. A method is preserved
-    # whether it is owned directly by the company or via one of its contacts.
+    # whether it is owned directly by the company or by a linked person.
     used_method_values: set[tuple[str, str]] = set()
-    methods_to_update: list[ClientContactMethod] = []
+    methods_to_update: list[ContactMethod] = []
     for method in (
-        ClientContactMethod.objects.using(SCRUB_ALIAS)
+        ContactMethod.objects.using(SCRUB_ALIAS)
         .exclude(company__name__in=preserved)
-        .exclude(contact__company__name__in=preserved)
+        .exclude(person__company_links__company__name__in=preserved)
     ):
-        if method.method_type == ClientContactMethod.MethodType.PHONE:
+        if method.method_type == ContactMethod.MethodType.PHONE:
             generate = fake.phone_number
-        elif method.method_type == ClientContactMethod.MethodType.EMAIL:
+        elif method.method_type == ContactMethod.MethodType.EMAIL:
             generate = fake.email
         else:
             continue
@@ -211,10 +205,10 @@ def _scrub_companies() -> None:
         method.value = value
         method.normalized_value = normalized
         methods_to_update.append(method)
-    # bulk_update bypasses ClientContactMethod.save(), so the one-number-one-company
+    # bulk_update bypasses ContactMethod.save(), so the one-number-one-company
     # guard and primary-demotion logic (neither of which is a business operation
     # during a scrub) never run and cannot abort the transaction on a collision.
-    ClientContactMethod.objects.using(SCRUB_ALIAS).bulk_update(
+    ContactMethod.objects.using(SCRUB_ALIAS).bulk_update(
         methods_to_update, ["value", "normalized_value"], batch_size=500
     )
 
diff --git a/apps/workflow/tests/test_data_versions_view.py b/apps/workflow/tests/test_data_versions_view.py
index ada90278b..366732e95 100644
--- a/apps/workflow/tests/test_data_versions_view.py
+++ b/apps/workflow/tests/test_data_versions_view.py
@@ -10,7 +10,7 @@
 from rest_framework.test import APIClient
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.crm.models import PhoneCallRecord, PhoneCallRecording
 from apps.job.models import Job
 from apps.job.services.job_service import JobStaffService
@@ -202,16 +202,21 @@ def test_related_display_changes_change_kanban_version(
     auth_client, office_staff, kanban_prerequisites
 ):
     company = _client(name="Original Company")
-    contact = ClientContact.objects.create(company=company, name="Original Contact")
-    _job(office_staff, company=company, contact=contact)
+    person = Person.objects.create(name="Original Person")
+    CompanyPersonLink.objects.create(
+        company=company,
+        person=person,
+        xero_name=person.name,
+    )
+    _job(office_staff, company=company, person=person)
     before = auth_client.get("/api/data-versions/").json()["kanban"]
-    contact.name = "Updated Contact"
-    contact.save(update_fields=["name"])
+    person.name = "Updated Person"
+    person.save(update_fields=["name"])
     after = auth_client.get("/api/data-versions/").json()["kanban"]
     assert before != after
 
 
-def test_client_partial_save_changes_kanban_version(
+def test_company_partial_save_changes_kanban_version(
     auth_client: APIClient, office_staff: Staff, kanban_prerequisites: None
 ) -> None:
     company = _client(name="Original Company")
diff --git a/apps/workflow/tests/test_db_scrubber.py b/apps/workflow/tests/test_db_scrubber.py
index af622759d..b7c034794 100644
--- a/apps/workflow/tests/test_db_scrubber.py
+++ b/apps/workflow/tests/test_db_scrubber.py
@@ -7,10 +7,10 @@
 
 from django.test import SimpleTestCase
 
-from apps.company.models import ClientContactMethod
+from apps.company.models import ContactMethod
 from apps.workflow.services.db_scrubber import _unique_scrub_value
 
-PHONE = ClientContactMethod.MethodType.PHONE
+PHONE = ContactMethod.MethodType.PHONE
 
 
 class UniqueScrubValueTests(SimpleTestCase):
@@ -19,7 +19,7 @@ def test_returns_value_and_normalized_and_records_it(self) -> None:
         value, normalized = _unique_scrub_value(lambda: "021 111 111", PHONE, used)
 
         self.assertEqual(value, "021 111 111")
-        self.assertEqual(normalized, ClientContactMethod.normalize_phone("021 111 111"))
+        self.assertEqual(normalized, ContactMethod.normalize_phone("021 111 111"))
         self.assertIn((PHONE, normalized), used)
 
     def test_skips_values_that_normalize_to_an_already_used_number(self) -> None:
diff --git a/apps/workflow/tests/test_dev_demo_export.py b/apps/workflow/tests/test_dev_demo_export.py
index 1dfb0a96a..d4fc1013c 100644
--- a/apps/workflow/tests/test_dev_demo_export.py
+++ b/apps/workflow/tests/test_dev_demo_export.py
@@ -8,7 +8,7 @@
 from django.utils import timezone
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 from apps.crm.models import (
     PhoneCallRecord,
     PhoneCallRecording,
@@ -48,9 +48,9 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
         xero_last_modified=timezone.now(),
         raw_json={"_name": "Realistic Company Ltd"},
     )
-    ClientContactMethod.objects.create(
+    ContactMethod.objects.create(
         company=company,
-        method_type=ClientContactMethod.MethodType.PHONE,
+        method_type=ContactMethod.MethodType.PHONE,
         value="+64211234567",
         is_primary=True,
     )
@@ -146,7 +146,7 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     )
     SearchTelemetryEvent.objects.create(
         event_type=SearchTelemetryEvent.EventType.CLICK,
-        domain=SearchTelemetryEvent.Domain.CLIENT,
+        domain=SearchTelemetryEvent.Domain.COMPANY,
         query="company@example.test",
         normalized_query="company@example.test",
         selected_result_id=str(company.id),
@@ -224,7 +224,7 @@ def test_dev_demo_scrub_preserves_business_signal_and_redacts_risk():
     assert chunk.path == "/redacted"
 
     telemetry = SearchTelemetryEvent.objects.get()
-    assert telemetry.domain == SearchTelemetryEvent.Domain.CLIENT
+    assert telemetry.domain == SearchTelemetryEvent.Domain.COMPANY
     assert telemetry.query == ""
     assert telemetry.metadata == {}
 
diff --git a/apps/workflow/tests/test_push_contacts.py b/apps/workflow/tests/test_push_contacts.py
index 84c856a3d..4aded0b0d 100644
--- a/apps/workflow/tests/test_push_contacts.py
+++ b/apps/workflow/tests/test_push_contacts.py
@@ -14,7 +14,7 @@
 from django.utils import timezone
 from xero_python.accounting.models import Contact, Contacts
 
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 from apps.workflow.tests.fixtures.xero_responses import make_create_contacts_response
 
 
@@ -29,9 +29,9 @@ def _make_client(**overrides):
     defaults.update(overrides)
     company = Company.objects.create(**defaults)
     if phone is not None:
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=company,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value=phone,
             is_primary=True,
         )
@@ -96,7 +96,7 @@ def test_existing_client_calls_update_contact_with_sdk_contact(
 @patch("time.sleep")
 @patch("apps.workflow.api.xero.push.get_tenant_id", return_value="tenant-1")
 @patch("apps.workflow.api.xero.push.AccountingApi")
-class CreateClientContactInXeroTests(TestCase):
+class CreateCompanyPersonLinkInXeroTests(TestCase):
     """create_company_contact_in_xero — passes Contact, saves xero_contact_id."""
 
     def test_passes_sdk_contact_and_saves_id(
diff --git a/apps/workflow/tests/test_relabel_client_app.py b/apps/workflow/tests/test_relabel_client_app.py
index 0544fe2dc..caf556abc 100644
--- a/apps/workflow/tests/test_relabel_client_app.py
+++ b/apps/workflow/tests/test_relabel_client_app.py
@@ -43,8 +43,6 @@
 # live table name -> pre-surgery (legacy) table name
 LEGACY_TABLE_NAMES = [
     ("company_company", "client_client"),
-    ("company_clientcontact", "client_clientcontact"),
-    ("company_clientcontactmethod", "client_clientcontactmethod"),
     ("company_suppliersearchalias", "client_suppliersearchalias"),
     ("company_supplierpickupaddress", "client_supplierpickupaddress"),
 ]
diff --git a/apps/workflow/tests/test_search_telemetry.py b/apps/workflow/tests/test_search_telemetry.py
index 45126a92d..a43fce3f3 100644
--- a/apps/workflow/tests/test_search_telemetry.py
+++ b/apps/workflow/tests/test_search_telemetry.py
@@ -23,7 +23,7 @@ def test_search_click_endpoint_records_generic_event(db):
     resp = api.post(
         "/api/search-events/click/",
         {
-            "domain": "client",
+            "domain": "company",
             "query": "FUME",
             "selected_result_id": "client-123",
             "selected_label": "Fumecare Ltd",
@@ -38,7 +38,7 @@ def test_search_click_endpoint_records_generic_event(db):
     assert resp.status_code == 200, resp.content
     event = SearchTelemetryEvent.objects.get()
     assert event.event_type == SearchTelemetryEvent.EventType.CLICK
-    assert event.domain == SearchTelemetryEvent.Domain.CLIENT
+    assert event.domain == SearchTelemetryEvent.Domain.COMPANY
     assert event.query == "FUME"
     assert event.normalized_query == "fume"
     assert event.selected_result_id == "client-123"
diff --git a/apps/workflow/tests/test_sync_clients.py b/apps/workflow/tests/test_sync_clients.py
index ebbcdcee2..1d0f8eceb 100644
--- a/apps/workflow/tests/test_sync_clients.py
+++ b/apps/workflow/tests/test_sync_clients.py
@@ -8,7 +8,7 @@
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
-from apps.company.models import ClientContactMethod, Company
+from apps.company.models import Company, ContactMethod
 from apps.crm.models import PhoneCallRecord
 from apps.crm.services.phone_call_service import rematch_calls_for_numbers
 from apps.workflow.api.xero.reprocess_xero import (
@@ -285,9 +285,9 @@ def test_duplicate_phone_owner_crashes_sync_and_persists_app_error(self) -> None
             xero_last_modified=timezone.now(),
         )
         imported = self._client_with_phone("Imported Phone Owner")
-        ClientContactMethod.objects.create(
+        ContactMethod.objects.create(
             company=existing,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
         before = AppError.objects.count()
@@ -315,23 +315,21 @@ def test_resync_of_existing_number_is_grandfathered(self) -> None:
         other = Company.objects.create(
             name="Legacy Other Owner", xero_last_modified=timezone.now()
         )
-        legacy = ClientContactMethod(
+        legacy = ContactMethod(
             company=other,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        legacy.normalized_value = ClientContactMethod.normalize_phone("021 555 123")
-        ClientContactMethod.objects.bulk_create([legacy])
+        legacy.normalized_value = ContactMethod.normalize_phone("021 555 123")
+        ContactMethod.objects.bulk_create([legacy])
         # owner already stores the number too (its own row).
-        owner_method = ClientContactMethod(
+        owner_method = ContactMethod(
             company=owner,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="021 555 123",
         )
-        owner_method.normalized_value = ClientContactMethod.normalize_phone(
-            "021 555 123"
-        )
-        ClientContactMethod.objects.bulk_create([owner_method])
+        owner_method.normalized_value = ContactMethod.normalize_phone("021 555 123")
+        ContactMethod.objects.bulk_create([owner_method])
 
         created = sync_xero_phone_methods(owner)  # must not raise
 
@@ -344,20 +342,20 @@ def test_user_edited_label_and_primary_survive_resync(self) -> None:
         owner = self._client_with_phone("Phone Owner")
         created = sync_xero_phone_methods(owner)
         self.assertEqual(created, ["+6421555123"])
-        imported_method = ClientContactMethod.objects.get(company=owner)
+        imported_method = ContactMethod.objects.get(company=owner)
         self.assertEqual(imported_method.label, "DEFAULT")
         self.assertTrue(imported_method.is_primary)
 
         # CRM user relabels the imported number and picks a LOCAL primary.
         imported_method.label = "Reception"
         imported_method.save()
-        local_primary = ClientContactMethod.objects.create(
+        local_primary = ContactMethod.objects.create(
             company=owner,
-            method_type=ClientContactMethod.MethodType.PHONE,
+            method_type=ContactMethod.MethodType.PHONE,
             value="09 555 000",
             label="After hours",
             is_primary=True,
-            source=ClientContactMethod.Source.LOCAL,
+            source=ContactMethod.Source.LOCAL,
         )
 
         self.assertEqual(sync_xero_phone_methods(owner), [])
@@ -367,12 +365,12 @@ def test_user_edited_label_and_primary_survive_resync(self) -> None:
         self.assertEqual(imported_method.label, "Reception")
         self.assertFalse(imported_method.is_primary)
         self.assertTrue(local_primary.is_primary)
-        self.assertEqual(imported_method.source, ClientContactMethod.Source.IMPORTED)
+        self.assertEqual(imported_method.source, ContactMethod.Source.IMPORTED)
 
     def test_unchanged_resync_does_not_write_the_method_row(self) -> None:
         owner = self._client_with_phone("Phone Owner")
         sync_xero_phone_methods(owner)
-        method = ClientContactMethod.objects.get(company=owner)
+        method = ContactMethod.objects.get(company=owner)
         updated_at_before = method.updated_at
 
         with CaptureQueriesContext(connection) as ctx:
diff --git a/apps/workflow/views/data_versions_view.py b/apps/workflow/views/data_versions_view.py
index aad67ad14..04761d090 100644
--- a/apps/workflow/views/data_versions_view.py
+++ b/apps/workflow/views/data_versions_view.py
@@ -23,7 +23,7 @@
 from rest_framework.views import APIView
 
 from apps.accounts.models import Staff
-from apps.company.models import ClientContact, Company
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.crm.models import PhoneCallRecord, PhoneCallRecording
 from apps.job.models import Job
 from apps.purchasing.models import Stock
@@ -49,7 +49,8 @@ def _kanban_version() -> str:
         [
             _model_version(Job, "updated_at"),
             _model_version(Company, "django_updated_at"),
-            _model_version(ClientContact, "updated_at"),
+            _model_version(CompanyPersonLink, "updated_at"),
+            _model_version(Person, "updated_at"),
             _model_version(Staff, "updated_at"),
         ]
     )
@@ -63,7 +64,8 @@ def _crm_calls_version() -> str:
             _model_version(PhoneCallRecord, "updated_at"),
             _model_version(PhoneCallRecording, "updated_at"),
             _model_version(Company, "django_updated_at"),
-            _model_version(ClientContact, "updated_at"),
+            _model_version(CompanyPersonLink, "updated_at"),
+            _model_version(Person, "updated_at"),
             _model_version(Job, "updated_at"),
         ]
     )
diff --git a/docs/adr/0030-first-class-people-and-company-links.md b/docs/adr/0030-first-class-people-and-company-links.md
new file mode 100644
index 000000000..6fc512422
--- /dev/null
+++ b/docs/adr/0030-first-class-people-and-company-links.md
@@ -0,0 +1,40 @@
+# 0030: First-class People and Company links
+
+## Status
+
+Accepted
+
+## Context
+
+The CRM originally treated a company contact as a row owned by one company. That
+matched Xero's contact-person payload but made humans second-class: jobs, calls,
+and phone numbers pointed at a company-specific contact shape instead of the
+person. It also mixed two different concepts in one row: identity
+(`name`, `email`) and relationship-at-company (`position`, `is_primary`, notes,
+Xero import key).
+
+## Decision
+
+People are first-class records. `Person` owns human identity and person-owned
+contact methods. `CompanyPersonLink` owns relationship-at-company data and the
+stable `xero_name` key used to reconcile Xero contact persons for one company.
+
+Jobs and phone call records point to `Person`. Company contact APIs expose link
+rows with embedded person identity fields. Contact methods are owned by exactly
+one `Company` or one `Person`. Phone sharing is allowed only when all owners
+trace to at least one common company; unchanged legacy rows are grandfathered
+until edited.
+
+Xero company `contact_id` and `xero_contact_id` terminology remains unchanged
+because those are external Xero identifiers, not CRM people.
+
+## Consequences
+
+- A person may have links to multiple companies; deduplicating equivalent people
+  remains a separate data-quality task.
+- Xero may create or reactivate links keyed by `(company, xero_name)`, but
+  `Person.name` is user-owned after the initial seed.
+- Company merge moves company-owned contact methods, company links, jobs, and
+  call company ownership. It does not move person-owned contact methods.
+- API callers use `person_id` and `person_name` for jobs, calls, Kanban, and
+  search. Legacy `contact_id` survives only where it refers to Xero.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 5cce90040..936b02040 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -39,3 +39,4 @@ See [`_template.md`](_template.md). Copy, renumber, fill in.
 | 0027 | A capability deploys with the means to operate it |
 | 0028 | Type annotations are data contracts |
 | 0029 | Servers run the production branch |
+| 0030 | First-class People and Company links |
diff --git a/docs/test_plans/client_contact_management_test_plan.md b/docs/test_plans/client_contact_management_test_plan.md
index b07ff894d..deffa8fb0 100644
--- a/docs/test_plans/client_contact_management_test_plan.md
+++ b/docs/test_plans/client_contact_management_test_plan.md
@@ -1,102 +1,104 @@
-# Test Plan: Client Contact Management Feature
+# Test Plan: Company People Management Feature
 
 ## Overview
 
-This test plan covers the new client contact management system that replaces Xero contact syncing with local contact storage.
+This test plan covers company people management: people are stored locally,
+linked to companies, and selected on jobs without relying on Xero contact-person
+sync for day-to-day job assignment.
 
 ## Prerequisites
 
 - [ ] Ensure migrations have been applied (`python manage.py migrate`)
-- [ ] Have at least one client in the system
+- [ ] Have at least one company in the system
 - [ ] Have access to create and edit jobs
 
 ## Test Cases
 
-### 1. View Existing Contact Data
+### 1. View Existing Person Data
 
-- [ ] Navigate to an existing job that previously had contact_person/contact_phone data
-- [ ] Verify the contact information is displayed in the read-only field
+- [ ] Navigate to an existing job that has person and phone data
+- [ ] Verify the person information is displayed in the read-only field
 - [ ] Verify format is "Name - Phone" or just "Name" if no phone
 
-### 2. Open Contact Management Modal
+### 2. Open Person Management Modal
 
-- [ ] Click the "Manage" button next to Contact Person field
+- [ ] Click the "Manage" button next to the Person field
 - [ ] Verify modal opens with:
-  - [ ] Client name displayed at top
-  - [ ] List of existing contacts (if any)
-  - [ ] Form to add new contact
+  - [ ] Company name displayed at top
+  - [ ] List of existing people (if any)
+  - [ ] Form to add a new person
 
-### 3. Create New Contact
+### 3. Create New Person
 
-- [ ] In the modal, fill in the new contact form:
+- [ ] In the modal, fill in the new person form:
   - Name: "John Smith" (required)
   - Position: "Project Manager" (optional)
   - Email: "john@example.com" (optional)
   - Phone: "555-1234" (optional)
   - Notes: "Primary contact for all orders" (optional)
   - Check "Set as primary contact"
-- [ ] Click "Save Contact"
+- [ ] Click "Save Person"
 - [ ] Verify modal closes
-- [ ] Verify contact display updates to "John Smith - 555-1234"
-- [ ] Verify hidden contact_id field is populated
+- [ ] Verify person display updates to "John Smith - 555-1234"
+- [ ] Verify hidden person_id field is populated
 - [ ] Verify autosave triggers (check network tab or console)
 
-### 4. Select Existing Contact
+### 4. Select Existing Person
 
 - [ ] Open modal again
-- [ ] Verify "John Smith" appears in the existing contacts list with "Primary" badge
-- [ ] Add another contact "Jane Doe" without marking as primary
+- [ ] Verify "John Smith" appears in the existing people list with "Primary" badge
+- [ ] Add another person "Jane Doe" without marking as primary
 - [ ] Close and reopen modal
 - [ ] Click "Select" button next to "Jane Doe"
-- [ ] Click "Save Contact"
-- [ ] Verify contact display updates to "Jane Doe"
+- [ ] Click "Save Person"
+- [ ] Verify person display updates to "Jane Doe"
 
-### 5. Contact Without Client
+### 5. Person Without Company
 
-- [ ] Create a new job or use one without a client selected
-- [ ] Click "Manage" contact button
-- [ ] Verify modal shows warning: "Please select a client first."
+- [ ] Create a new job or use one without a company selected
+- [ ] Click "Manage" person button
+- [ ] Verify modal shows warning: "Please select a company first."
 - [ ] Verify Save button is disabled
 
-### 6. Primary Contact Behavior
+### 6. Primary Person Behavior
 
-- [ ] For a client with multiple contacts, mark a different one as primary
-- [ ] Verify only one contact can be primary at a time
-- [ ] Verify primary contacts appear first in the list
+- [ ] For a company with multiple people, mark a different one as primary
+- [ ] Verify only one person can be primary at a time
+- [ ] Verify primary people appear first in the list
 
 ### 7. Autosave Integration
 
-- [ ] Select/create a contact for a job
+- [ ] Select/create a person for a job
 - [ ] Make another change to the job (e.g., change job name)
 - [ ] Verify both changes are saved
 - [ ] Refresh the page
-- [ ] Verify contact selection persists
+- [ ] Verify person selection persists
 
 ### 8. API Testing (Developer Console)
 
-- [ ] Test fetching contacts:
+- [ ] Test fetching company people:
 
 ```javascript
-// Replace [CLIENT_ID] with actual client UUID
-fetch("/clients/api/client/[CLIENT_ID]/contacts/")
+// Replace [COMPANY_ID] with actual company UUID
+fetch("/api/companies/person-links/?company_id=[COMPANY_ID]")
   .then((r) => r.json())
   .then(console.log);
 ```
 
-- [ ] Test creating contact:
+- [ ] Test creating a person link:
 
 ```javascript
-// Replace [CLIENT_ID] with actual client UUID
-fetch("/clients/api/client/contact/", {
+// Replace [COMPANY_ID] with actual company UUID
+fetch("/api/companies/person-links/", {
   method: "POST",
   headers: {
     "Content-Type": "application/json",
     "X-CSRFToken": document.querySelector("[name=csrfmiddlewaretoken]").value,
   },
   body: JSON.stringify({
-    client: "[CLIENT_ID]",
-    name: "Test Contact",
-    email: "test@example.com",
+    company: "[COMPANY_ID]",
+    person_name: "Test Person",
+    person_email: "test@example.com",
     phone: "555-5555",
     is_primary: false,
   }),
@@ -107,17 +109,17 @@ fetch("/clients/api/client/contact/", {
 
 ### 9. Edge Cases
 
-- [ ] Try to save without selecting any contact (should close modal without changes)
-- [ ] Create contact with only name (minimum required field)
-- [ ] Create contact with very long name/phone/email
-- [ ] Try special characters in contact fields
+- [ ] Try to save without selecting any person (should close modal without changes)
+- [ ] Create a person with only name (minimum required field)
+- [ ] Create a person with very long name/phone/email
+- [ ] Try special characters in person fields
 
-### 10. Legacy Data Compatibility
+### 10. Migrated Data
 
-- [ ] Find a job with old contact_person/contact_phone data
+- [ ] Find a job with migrated person/phone data
 - [ ] Verify it displays correctly
-- [ ] Select a new contact from modal
-- [ ] Verify old fields are updated in background (check hidden fields)
+- [ ] Select a new person from modal
+- [ ] Verify the job stores the selected person_id
 
 ### 11. Multiple Browser Testing
 
@@ -128,31 +130,30 @@ fetch("/clients/api/client/contact/", {
 
 ### 12. Performance Testing
 
-- [ ] Test with a client that has 50+ contacts
+- [ ] Test with a company that has 50+ people
 - [ ] Verify modal loads quickly
-- [ ] Verify contact list is scrollable and responsive
+- [ ] Verify people list is scrollable and responsive
 
 ## Expected Results
 
-- All contact data is stored locally in ClientContact model
-- No API calls to Xero for contact management
+- All person data is stored locally in Person and CompanyPersonLink models
+- No API calls to Xero for person management
 - Smooth user experience with modal interface
-- Backward compatibility with legacy contact fields
-- Primary contact designation works correctly
+- Primary person designation works correctly
 
 ## Known Limitations
 
-- Contact email is not currently displayed in the selection (only name and phone)
-- No search/filter functionality in contact list yet
-- No bulk import of contacts
+- Person email is not currently displayed in the selection (only name and phone)
+- No search/filter functionality in the people list yet
+- No bulk import of people
 
 ## Rollback Plan
 
 If critical issues are found:
 
-1. The migration can be reversed: `python manage.py migrate job 0015`
-2. Legacy contact_person and contact_phone fields are preserved
-3. The modal can be hidden by removing the "Manage" button from template
+1. Reverse to the previous migration checkpoint in a development copy.
+2. Restore the previous branch if production rollout is blocked.
+3. Hide the modal by removing the "Manage" button from the template if needed.
 
 ## Sign-off
 
@@ -163,5 +164,5 @@ If critical issues are found:
 ---
 
 _Test Plan Created: 2025-06-09_
-_Feature: Client Contact Management_
+_Feature: Company People Management_
 _Version: 1.0_
diff --git a/docs/urls/client.md b/docs/urls/client.md
index 0a733641e..ac223602d 100644
--- a/docs/urls/client.md
+++ b/docs/urls/client.md
@@ -1,45 +1,45 @@
-# Client URLs Documentation
+# Company URLs Documentation
 
 <!-- This file is auto-generated. To regenerate, run: python scripts/generate_url_docs.py -->
 
 ### Addresses Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/addresses/validate/` | `address_views.AddressValidateView` | `clients:address_validate` | Validate and clean an address using Google Address Validation API. |
+| `/addresses/validate/` | `address_views.AddressValidateView` | `companies:address_validate` | Validate and clean an address using Google Address Validation API. |
 
 ### All Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/all/` | `client_rest_views.ClientListAllRestView` | `clients:client_list_all_rest` | REST view for listing all clients. |
+| `/all/` | `company_rest_views.CompanyListAllRestView` | `companies:company_list_all_rest` | REST view for listing all companies. |
 
 ### Create Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/create/` | `client_rest_views.ClientCreateRestView` | `clients:client_create_rest` | REST view for creating new clients. |
+| `/create/` | `company_rest_views.CompanyCreateRestView` | `companies:company_create_rest` | REST view for creating new companies. |
 
 ### Jobs Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/<uuid:client_id>/jobs/` | `client_rest_views.ClientJobsRestView` | `clients:client_jobs_rest` | REST view for fetching all jobs for a specific client. |
-| `/jobs/<uuid:job_id>/contact/` | `client_rest_views.JobContactRestView` | `clients:job_contact_rest` | REST view for contact information operations for a job. |
+| `/<uuid:company_id>/jobs/` | `company_rest_views.CompanyJobsRestView` | `companies:company_jobs_rest` | REST view for fetching all jobs for a specific company. |
+| `/jobs/<uuid:job_id>/person/` | `company_rest_views.JobPersonRestView` | `companies:job_person_rest` | REST view for person information operations for a job. |
 
 ### Other
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/<uuid:client_id>/` | `client_rest_views.ClientRetrieveRestView` | `clients:client_retrieve_rest` | REST view for retrieving a specific client by ID. |
+| `/<uuid:company_id>/` | `company_rest_views.CompanyRetrieveRestView` | `companies:company_retrieve_rest` | REST view for retrieving a specific company by ID. |
 
 ### Search Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/search/` | `client_rest_views.ClientSearchRestView` | `clients:client_search_rest` | REST view for client search with pagination and sorting. |
+| `/search/` | `company_rest_views.CompanySearchRestView` | `companies:company_search_rest` | REST view for company search with pagination and sorting. |
 
 ### Supplier-Aliases Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/<uuid:client_id>/supplier-aliases/` | `supplier_search_alias_views.ClientSupplierAliasListCreateView` | `clients:client_supplier_aliases_rest` | List and create search aliases for a client/supplier contact. |
-| `/supplier-aliases/<uuid:alias_id>/` | `supplier_search_alias_views.SupplierAliasDetailView` | `clients:supplier_alias_detail_rest` | Deactivate a supplier search alias. |
+| `/<uuid:company_id>/supplier-aliases/` | `supplier_search_alias_views.CompanySupplierAliasListCreateView` | `companies:company_supplier_aliases_rest` | List and create search aliases for a company/supplier contact. |
+| `/supplier-aliases/<uuid:alias_id>/` | `supplier_search_alias_views.SupplierAliasDetailView` | `companies:supplier_alias_detail_rest` | Deactivate a supplier search alias. |
 
 ### Update Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
-| `/<uuid:client_id>/update/` | `client_rest_views.ClientUpdateRestView` | `clients:client_update_rest` | REST view for updating client information. |
+| `/<uuid:company_id>/update/` | `company_rest_views.CompanyUpdateRestView` | `companies:company_update_rest` | REST view for updating company information. |
diff --git a/docs/urls/company.md b/docs/urls/company.md
index 6ec6bd2f7..17640ba1a 100644
--- a/docs/urls/company.md
+++ b/docs/urls/company.md
@@ -27,7 +27,7 @@
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
 | `/<uuid:company_id>/jobs/` | `company_rest_views.CompanyJobsRestView` | `companies:company_jobs_rest` | REST view for fetching all jobs for a specific company. |
-| `/jobs/<uuid:job_id>/contact/` | `company_rest_views.JobContactRestView` | `companies:job_contact_rest` | REST view for contact information operations for a job. |
+| `/jobs/<uuid:job_id>/person/` | `company_rest_views.JobPersonRestView` | `companies:job_person_rest` | REST view for person information operations for a job. |
 
 ### Other
 | URL Pattern | View | Name | Description |
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 175f04b7a..8bb9a7a49 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -1462,18 +1462,13 @@ paths:
   /api/companies/contact-methods/:
     get:
       operationId: companies_contact_methods_list
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       parameters:
         - in: query
           name: company_id
           schema:
             type: string
             format: uuid
-        - in: query
-          name: contact_id
-          schema:
-            type: string
-            format: uuid
         - in: query
           name: method_type
           schema:
@@ -1486,6 +1481,11 @@ paths:
           name: page_size
           schema:
             type: integer
+        - in: query
+          name: person_id
+          schema:
+            type: string
+            format: uuid
       tags:
         - companies
       security:
@@ -1495,24 +1495,24 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/PaginatedClientContactMethodList'
+                $ref: '#/components/schemas/PaginatedContactMethodList'
           description: ''
     post:
       operationId: companies_contact_methods_create
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       tags:
         - companies
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
         required: true
       security:
         - cookieAuth: []
@@ -1521,12 +1521,12 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContactMethod'
+                $ref: '#/components/schemas/ContactMethod'
           description: ''
   /api/companies/contact-methods/{id}/:
     get:
       operationId: companies_contact_methods_retrieve
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1544,11 +1544,11 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContactMethod'
+                $ref: '#/components/schemas/ContactMethod'
           description: ''
     put:
       operationId: companies_contact_methods_update
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1563,13 +1563,13 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientContactMethodRequest'
+              $ref: '#/components/schemas/ContactMethodRequest'
         required: true
       security:
         - cookieAuth: []
@@ -1578,11 +1578,11 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContactMethod'
+                $ref: '#/components/schemas/ContactMethod'
           description: ''
     patch:
       operationId: companies_contact_methods_partial_update
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1597,13 +1597,13 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactMethodRequest'
+              $ref: '#/components/schemas/PatchedContactMethodRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactMethodRequest'
+              $ref: '#/components/schemas/PatchedContactMethodRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactMethodRequest'
+              $ref: '#/components/schemas/PatchedContactMethodRequest'
       security:
         - cookieAuth: []
       responses:
@@ -1611,11 +1611,11 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContactMethod'
+                $ref: '#/components/schemas/ContactMethod'
           description: ''
     delete:
       operationId: companies_contact_methods_destroy
-      description: CRUD API for canonical company/contact phone and email methods.
+      description: CRUD API for canonical company/person phone and email methods.
       parameters:
         - in: path
           name: id
@@ -1631,17 +1631,159 @@ paths:
       responses:
         '204':
           description: No response body
-  /api/companies/contacts/:
+  /api/companies/create/:
+    post:
+      operationId: companies_create_create
+      description: Creates a new company in Xero first, then syncs locally. Requires
+        valid Xero authentication.
+      summary: Create a new company
+      tags:
+        - Companies
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompanyCreateRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/CompanyCreateRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/CompanyCreateRequest'
+        required: true
+      security:
+        - cookieAuth: []
+      responses:
+        '201':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyCreateResponse'
+          description: ''
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyDuplicateErrorResponse'
+          description: ''
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+  /api/companies/jobs/{job_id}/person/:
+    get:
+      operationId: companies_jobs_person_retrieve
+      description: Retrieve person information for a specific job.
+      summary: Get job person
+      parameters:
+        - in: path
+          name: job_id
+          schema:
+            type: string
+            format: uuid
+          description: UUID of the job
+          required: true
+      tags:
+        - Companies
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobPersonResponse'
+          description: ''
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+    put:
+      operationId: companies_jobs_person_update
+      description: Update the person associated with a specific job.
+      summary: Update job person
+      parameters:
+        - in: path
+          name: job_id
+          schema:
+            type: string
+            format: uuid
+          description: UUID of the job
+          required: true
+      tags:
+        - Companies
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JobPersonUpdateRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/JobPersonUpdateRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/JobPersonUpdateRequest'
+        required: true
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobPersonResponse'
+          description: ''
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyErrorResponse'
+          description: ''
+  /api/companies/person-links/:
     get:
-      operationId: companies_contacts_list
-      description: List all contacts, optionally filtered by company_id.
+      operationId: companies_person_links_list
+      description: List all company-person links, optionally filtered by company_id.
       parameters:
         - in: query
           name: company_id
           schema:
             type: string
             format: uuid
-          description: Filter contacts by company UUID
+          description: Filter links by company UUID
       tags:
         - companies
       security:
@@ -1653,36 +1795,36 @@ paths:
               schema:
                 type: array
                 items:
-                  $ref: '#/components/schemas/ClientContact'
+                  $ref: '#/components/schemas/CompanyPersonLink'
           description: ''
     post:
-      operationId: companies_contacts_create
+      operationId: companies_person_links_create
       description: |-
-        ViewSet for ClientContact CRUD operations.
+        ViewSet for CompanyPersonLink CRUD operations.
 
         Endpoints:
-        - GET    /api/companies/contacts/           - list all contacts
-        - POST   /api/companies/contacts/           - create contact
-        - GET    /api/companies/contacts/<id>/      - retrieve contact
-        - PUT    /api/companies/contacts/<id>/      - full update
-        - PATCH  /api/companies/contacts/<id>/      - partial update
-        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/person-links/       - list all company-person links
+        - POST   /api/companies/person-links/       - create link
+        - GET    /api/companies/person-links/<id>/  - retrieve link
+        - PUT    /api/companies/person-links/<id>/  - full update
+        - PATCH  /api/companies/person-links/<id>/  - partial update
+        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
         Query Parameters:
-        - company_id: Filter contacts by company UUID
+        - company_id: Filter links by company UUID
       tags:
         - companies
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
         required: true
       security:
         - cookieAuth: []
@@ -1691,24 +1833,24 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContact'
+                $ref: '#/components/schemas/CompanyPersonLink'
           description: ''
-  /api/companies/contacts/{id}/:
+  /api/companies/person-links/{id}/:
     get:
-      operationId: companies_contacts_retrieve
+      operationId: companies_person_links_retrieve
       description: |-
-        ViewSet for ClientContact CRUD operations.
+        ViewSet for CompanyPersonLink CRUD operations.
 
         Endpoints:
-        - GET    /api/companies/contacts/           - list all contacts
-        - POST   /api/companies/contacts/           - create contact
-        - GET    /api/companies/contacts/<id>/      - retrieve contact
-        - PUT    /api/companies/contacts/<id>/      - full update
-        - PATCH  /api/companies/contacts/<id>/      - partial update
-        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/person-links/       - list all company-person links
+        - POST   /api/companies/person-links/       - create link
+        - GET    /api/companies/person-links/<id>/  - retrieve link
+        - PUT    /api/companies/person-links/<id>/  - full update
+        - PATCH  /api/companies/person-links/<id>/  - partial update
+        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
         Query Parameters:
-        - company_id: Filter contacts by company UUID
+        - company_id: Filter links by company UUID
       parameters:
         - in: path
           name: id
@@ -1726,23 +1868,23 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContact'
+                $ref: '#/components/schemas/CompanyPersonLink'
           description: ''
     put:
-      operationId: companies_contacts_update
+      operationId: companies_person_links_update
       description: |-
-        ViewSet for ClientContact CRUD operations.
+        ViewSet for CompanyPersonLink CRUD operations.
 
         Endpoints:
-        - GET    /api/companies/contacts/           - list all contacts
-        - POST   /api/companies/contacts/           - create contact
-        - GET    /api/companies/contacts/<id>/      - retrieve contact
-        - PUT    /api/companies/contacts/<id>/      - full update
-        - PATCH  /api/companies/contacts/<id>/      - partial update
-        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/person-links/       - list all company-person links
+        - POST   /api/companies/person-links/       - create link
+        - GET    /api/companies/person-links/<id>/  - retrieve link
+        - PUT    /api/companies/person-links/<id>/  - full update
+        - PATCH  /api/companies/person-links/<id>/  - partial update
+        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
         Query Parameters:
-        - company_id: Filter contacts by company UUID
+        - company_id: Filter links by company UUID
       parameters:
         - in: path
           name: id
@@ -1757,13 +1899,13 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/ClientContactRequest'
+              $ref: '#/components/schemas/CompanyPersonLinkRequest'
         required: true
       security:
         - cookieAuth: []
@@ -1772,23 +1914,23 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContact'
+                $ref: '#/components/schemas/CompanyPersonLink'
           description: ''
     patch:
-      operationId: companies_contacts_partial_update
+      operationId: companies_person_links_partial_update
       description: |-
-        ViewSet for ClientContact CRUD operations.
+        ViewSet for CompanyPersonLink CRUD operations.
 
         Endpoints:
-        - GET    /api/companies/contacts/           - list all contacts
-        - POST   /api/companies/contacts/           - create contact
-        - GET    /api/companies/contacts/<id>/      - retrieve contact
-        - PUT    /api/companies/contacts/<id>/      - full update
-        - PATCH  /api/companies/contacts/<id>/      - partial update
-        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/person-links/       - list all company-person links
+        - POST   /api/companies/person-links/       - create link
+        - GET    /api/companies/person-links/<id>/  - retrieve link
+        - PUT    /api/companies/person-links/<id>/  - full update
+        - PATCH  /api/companies/person-links/<id>/  - partial update
+        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
         Query Parameters:
-        - company_id: Filter contacts by company UUID
+        - company_id: Filter links by company UUID
       parameters:
         - in: path
           name: id
@@ -1803,13 +1945,13 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactRequest'
+              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
           application/x-www-form-urlencoded:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactRequest'
+              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
           multipart/form-data:
             schema:
-              $ref: '#/components/schemas/PatchedClientContactRequest'
+              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
       security:
         - cookieAuth: []
       responses:
@@ -1817,23 +1959,23 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ClientContact'
+                $ref: '#/components/schemas/CompanyPersonLink'
           description: ''
     delete:
-      operationId: companies_contacts_destroy
+      operationId: companies_person_links_destroy
       description: |-
-        ViewSet for ClientContact CRUD operations.
+        ViewSet for CompanyPersonLink CRUD operations.
 
         Endpoints:
-        - GET    /api/companies/contacts/           - list all contacts
-        - POST   /api/companies/contacts/           - create contact
-        - GET    /api/companies/contacts/<id>/      - retrieve contact
-        - PUT    /api/companies/contacts/<id>/      - full update
-        - PATCH  /api/companies/contacts/<id>/      - partial update
-        - DELETE /api/companies/contacts/<id>/      - soft delete (sets is_active=False)
+        - GET    /api/companies/person-links/       - list all company-person links
+        - POST   /api/companies/person-links/       - create link
+        - GET    /api/companies/person-links/<id>/  - retrieve link
+        - PUT    /api/companies/person-links/<id>/  - full update
+        - PATCH  /api/companies/person-links/<id>/  - partial update
+        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
 
         Query Parameters:
-        - company_id: Filter contacts by company UUID
+        - company_id: Filter links by company UUID
       parameters:
         - in: path
           name: id
@@ -1849,148 +1991,6 @@ paths:
       responses:
         '204':
           description: No response body
-  /api/companies/create/:
-    post:
-      operationId: companies_create_create
-      description: Creates a new company in Xero first, then syncs locally. Requires
-        valid Xero authentication.
-      summary: Create a new company
-      tags:
-        - Companies
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CompanyCreateRequest'
-          application/x-www-form-urlencoded:
-            schema:
-              $ref: '#/components/schemas/CompanyCreateRequest'
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/CompanyCreateRequest'
-        required: true
-      security:
-        - cookieAuth: []
-      responses:
-        '201':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyCreateResponse'
-          description: ''
-        '400':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-        '401':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-        '409':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyDuplicateErrorResponse'
-          description: ''
-        '500':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-  /api/companies/jobs/{job_id}/contact/:
-    get:
-      operationId: companies_jobs_contact_retrieve
-      description: Retrieve contact information for a specific job.
-      summary: Get job contact
-      parameters:
-        - in: path
-          name: job_id
-          schema:
-            type: string
-            format: uuid
-          description: UUID of the job
-          required: true
-      tags:
-        - Companies
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/JobContactResponse'
-          description: ''
-        '404':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-        '500':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-    put:
-      operationId: companies_jobs_contact_update
-      description: Update the contact person associated with a specific job.
-      summary: Update job contact
-      parameters:
-        - in: path
-          name: job_id
-          schema:
-            type: string
-            format: uuid
-          description: UUID of the job
-          required: true
-      tags:
-        - Companies
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/JobContactUpdateRequest'
-          application/x-www-form-urlencoded:
-            schema:
-              $ref: '#/components/schemas/JobContactUpdateRequest'
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/JobContactUpdateRequest'
-        required: true
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/JobContactResponse'
-          description: ''
-        '400':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-        '404':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
-        '500':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyErrorResponse'
-          description: ''
   /api/companies/pickup-addresses/:
     get:
       operationId: companies_pickup_addresses_list
@@ -2582,11 +2582,6 @@ paths:
           schema:
             type: string
             format: uuid
-        - in: query
-          name: contact
-          schema:
-            type: string
-            format: uuid
         - in: query
           name: destination_endpoint
           schema:
@@ -4933,11 +4928,6 @@ paths:
           schema:
             type: string
           description: Filter by company name
-        - in: query
-          name: contact_person
-          schema:
-            type: string
-          description: Filter by contact person
         - in: query
           name: created_after
           schema:
@@ -4978,6 +4968,11 @@ paths:
           schema:
             type: string
           description: Filter by paid status
+        - in: query
+          name: person_name
+          schema:
+            type: string
+          description: Filter by person name
         - in: query
           name: q
           schema:
@@ -10068,336 +10063,122 @@ components:
         - ''
     BrokenFKReference:
       type: object
-      description: Details of a broken foreign key reference.
-      properties:
-        model:
-          type: string
-          description: Model name
-        record_id:
-          type: string
-          description: Record's UUID
-        field:
-          type: string
-          description: FK field name
-        target_model:
-          type: string
-          description: Target model that doesn't exist
-        target_id:
-          type: string
-          description: Target UUID that doesn't exist
-      required:
-        - field
-        - model
-        - record_id
-        - target_id
-        - target_model
-    BrokenJSONReference:
-      type: object
-      description: Details of a broken JSON field reference.
-      properties:
-        model:
-          type: string
-          description: Model name
-        record_id:
-          type: string
-          description: Record's UUID
-        field:
-          type: string
-          description: JSON field path (e.g., meta.staff_id)
-        staff_id:
-          type: string
-          nullable: true
-          description: Invalid staff UUID
-        stock_id:
-          type: string
-          nullable: true
-          description: Invalid stock UUID
-        purchase_order_line_id:
-          type: string
-          nullable: true
-          description: Invalid PO line UUID
-        issue:
-          type: string
-          nullable: true
-          description: Issue description
-      required:
-        - field
-        - model
-        - record_id
-    BuildId:
-      type: object
-      properties:
-        build_id:
-          type: string
-      required:
-        - build_id
-    BusinessRuleViolation:
-      type: object
-      description: Details of a business rule violation.
-      properties:
-        model:
-          type: string
-          description: Model name
-        record_id:
-          type: string
-          description: Record's UUID
-        field:
-          type: string
-          description: Field name
-        rule:
-          type: string
-          description: Business rule that was violated
-        expected:
-          type: string
-          nullable: true
-          description: Expected value
-        actual:
-          type: string
-          nullable: true
-          description: Actual value
-        path:
-          type: array
-          items:
-            type: string
-          nullable: true
-          description: Path for circular references
-        expected_path:
-          type: string
-          nullable: true
-          description: Expected file path
-      required:
-        - field
-        - model
-        - record_id
-        - rule
-    CategoriesResponse:
-      type: object
-      properties:
-        procedures:
-          type: array
-          items:
-            type: string
-        forms:
-          type: array
-          items:
-            type: string
-      required:
-        - forms
-        - procedures
-    ClientContact:
-      type: object
-      description: Serializer for ClientContact model.
-      properties:
-        id:
-          type: string
-          format: uuid
-          readOnly: true
-        company:
-          type: string
-          format: uuid
-          description: The company this contact belongs to
-        person:
-          type: string
-          format: uuid
-          nullable: true
-        name:
-          type: string
-          description: Full name of the contact person
-          maxLength: 255
-        email:
-          type: string
-          format: email
-          nullable: true
-          description: Email address of the contact
-          maxLength: 254
-        xero_name:
-          type: string
-          nullable: true
-          maxLength: 255
-        position:
-          type: string
-          nullable: true
-          description: Job title if it's helpful - else leave blank
-          maxLength: 255
-        is_primary:
-          type: boolean
-          description: Indicates if this is the primary contact for the company
-        notes:
-          type: string
-          nullable: true
-          description: Additional notes about this contact
-        is_active:
-          type: boolean
-          readOnly: true
-          description: Soft delete flag - inactive contacts are hidden from normal
-            queries
-        created_at:
-          type: string
-          format: date-time
-          readOnly: true
-        updated_at:
-          type: string
-          format: date-time
-          readOnly: true
-        phone:
-          type: string
-          nullable: true
-          default: ''
-      required:
-        - company
-        - created_at
-        - id
-        - is_active
-        - name
-        - updated_at
-    ClientContactMethod:
-      type: object
-      description: Serializer for canonical company/contact phone and email methods.
-      properties:
-        id:
-          type: string
-          format: uuid
-          readOnly: true
-        company:
-          type: string
-          format: uuid
-          nullable: true
-        owner_company:
-          type: string
-          readOnly: true
-        company_name:
-          type: string
-          readOnly: true
-        contact:
-          type: string
-          format: uuid
-          nullable: true
-        contact_name:
-          type: string
-          readOnly: true
-        person:
-          type: string
-          format: uuid
-          nullable: true
-        method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
-        value:
+      description: Details of a broken foreign key reference.
+      properties:
+        model:
           type: string
-          maxLength: 255
-        normalized_value:
+          description: Model name
+        record_id:
           type: string
-          readOnly: true
-        label:
+          description: Record's UUID
+        field:
           type: string
-          maxLength: 255
-        is_primary:
-          type: boolean
-        source:
-          $ref: '#/components/schemas/ClientContactMethodSourceEnum'
-        created_at:
+          description: FK field name
+        target_model:
           type: string
-          format: date-time
-          readOnly: true
-        updated_at:
+          description: Target model that doesn't exist
+        target_id:
           type: string
-          format: date-time
-          readOnly: true
+          description: Target UUID that doesn't exist
       required:
-        - company_name
-        - contact_name
-        - created_at
-        - id
-        - method_type
-        - normalized_value
-        - owner_company
-        - updated_at
-        - value
-    ClientContactMethodRequest:
+        - field
+        - model
+        - record_id
+        - target_id
+        - target_model
+    BrokenJSONReference:
       type: object
-      description: Serializer for canonical company/contact phone and email methods.
+      description: Details of a broken JSON field reference.
       properties:
-        company:
+        model:
+          type: string
+          description: Model name
+        record_id:
+          type: string
+          description: Record's UUID
+        field:
+          type: string
+          description: JSON field path (e.g., meta.staff_id)
+        staff_id:
           type: string
-          format: uuid
           nullable: true
-        contact:
+          description: Invalid staff UUID
+        stock_id:
           type: string
-          format: uuid
           nullable: true
-        person:
+          description: Invalid stock UUID
+        purchase_order_line_id:
           type: string
-          format: uuid
           nullable: true
-        method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
-        value:
+          description: Invalid PO line UUID
+        issue:
           type: string
-          minLength: 1
-          maxLength: 255
-        label:
+          nullable: true
+          description: Issue description
+      required:
+        - field
+        - model
+        - record_id
+    BuildId:
+      type: object
+      properties:
+        build_id:
           type: string
-          maxLength: 255
-        is_primary:
-          type: boolean
-        source:
-          $ref: '#/components/schemas/ClientContactMethodSourceEnum'
       required:
-        - method_type
-        - value
-    ClientContactMethodSourceEnum:
-      enum:
-        - imported
-        - local
-      type: string
-      description: |-
-        * `imported` - Imported
-        * `local` - Local
-    ClientContactRequest:
+        - build_id
+    BusinessRuleViolation:
       type: object
-      description: Serializer for ClientContact model.
+      description: Details of a business rule violation.
       properties:
-        company:
+        model:
           type: string
-          format: uuid
-          description: The company this contact belongs to
-        person:
+          description: Model name
+        record_id:
           type: string
-          format: uuid
-          nullable: true
-        name:
+          description: Record's UUID
+        field:
           type: string
-          minLength: 1
-          description: Full name of the contact person
-          maxLength: 255
-        email:
+          description: Field name
+        rule:
           type: string
-          format: email
-          nullable: true
-          description: Email address of the contact
-          maxLength: 254
-        xero_name:
+          description: Business rule that was violated
+        expected:
           type: string
           nullable: true
-          maxLength: 255
-        position:
+          description: Expected value
+        actual:
           type: string
           nullable: true
-          description: Job title if it's helpful - else leave blank
-          maxLength: 255
-        is_primary:
-          type: boolean
-          description: Indicates if this is the primary contact for the company
-        notes:
-          type: string
+          description: Actual value
+        path:
+          type: array
+          items:
+            type: string
           nullable: true
-          description: Additional notes about this contact
-        phone:
+          description: Path for circular references
+        expected_path:
           type: string
           nullable: true
-          default: ''
+          description: Expected file path
       required:
-        - company
-        - name
+        - field
+        - model
+        - record_id
+        - rule
+    CategoriesResponse:
+      type: object
+      properties:
+        procedures:
+          type: array
+          items:
+            type: string
+        forms:
+          type: array
+          items:
+            type: string
+      required:
+        - forms
+        - procedures
     CompanyCreateRequest:
       type: object
       description: Serializer for company creation request
@@ -11192,13 +10973,6 @@ components:
           type: string
         xero_tenant_id:
           type: string
-        primary_contact_name:
-          type: string
-        primary_contact_email:
-          type: string
-        additional_contact_persons:
-          type: array
-          items: {}
         xero_last_modified:
           type: string
           format: date-time
@@ -11241,8 +11015,6 @@ components:
         - merged_into
         - name
         - phone
-        - primary_contact_email
-        - primary_contact_name
         - total_spend
         - xero_archived
         - xero_contact_id
@@ -11312,53 +11084,154 @@ components:
           type: string
           format: date-time
           nullable: true
-        paid:
-          type: boolean
-        rejected_flag:
-          type: boolean
-        min_people:
-          type: integer
-        max_people:
-          type: integer
+        paid:
+          type: boolean
+        rejected_flag:
+          type: boolean
+        min_people:
+          type: integer
+        max_people:
+          type: integer
+      required:
+        - company
+        - fully_invoiced
+        - has_quote_in_xero
+        - is_fixed_price
+        - job_id
+        - job_number
+        - max_people
+        - min_people
+        - name
+        - paid
+        - pricing_methodology
+        - quote_acceptance_date
+        - rejected_flag
+        - speed_quality_tradeoff
+        - status
+    CompanyJobsResponse:
+      type: object
+      description: Serializer for company jobs list response
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/CompanyJobHeader'
+      required:
+        - results
+    CompanyNameOnly:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+      required:
+        - id
+        - name
+    CompanyPersonLink:
+      type: object
+      description: Serializer for a person's relationship to a company.
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        company:
+          type: string
+          format: uuid
+          description: The company this contact belongs to
+        person:
+          type: string
+          format: uuid
+          readOnly: true
+        person_name:
+          type: string
+        person_email:
+          type: string
+          format: email
+          nullable: true
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
+        position:
+          type: string
+          nullable: true
+          description: Job title if it's helpful - else leave blank
+          maxLength: 255
+        is_primary:
+          type: boolean
+          description: Indicates if this is the primary contact for the company
+        notes:
+          type: string
+          nullable: true
+          description: Additional notes about this contact
+        is_active:
+          type: boolean
+          readOnly: true
+          description: Soft delete flag - inactive contacts are hidden from normal
+            queries
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+        updated_at:
+          type: string
+          format: date-time
+          readOnly: true
+        phone:
+          type: string
+          nullable: true
+          default: ''
       required:
         - company
-        - fully_invoiced
-        - has_quote_in_xero
-        - is_fixed_price
-        - job_id
-        - job_number
-        - max_people
-        - min_people
-        - name
-        - paid
-        - pricing_methodology
-        - quote_acceptance_date
-        - rejected_flag
-        - speed_quality_tradeoff
-        - status
-    CompanyJobsResponse:
-      type: object
-      description: Serializer for company jobs list response
-      properties:
-        results:
-          type: array
-          items:
-            $ref: '#/components/schemas/CompanyJobHeader'
-      required:
-        - results
-    CompanyNameOnly:
+        - created_at
+        - id
+        - is_active
+        - person
+        - person_name
+        - updated_at
+    CompanyPersonLinkRequest:
       type: object
+      description: Serializer for a person's relationship to a company.
       properties:
-        id:
+        company:
           type: string
           format: uuid
-          readOnly: true
-        name:
+          description: The company this contact belongs to
+        person_name:
           type: string
-          readOnly: true
+          minLength: 1
+        person_email:
+          type: string
+          format: email
+          nullable: true
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
+        position:
+          type: string
+          nullable: true
+          description: Job title if it's helpful - else leave blank
+          maxLength: 255
+        is_primary:
+          type: boolean
+          description: Indicates if this is the primary contact for the company
+        notes:
+          type: string
+          nullable: true
+          description: Additional notes about this contact
+        phone:
+          type: string
+          nullable: true
+          default: ''
       required:
-        - id
-        - name
+        - company
+        - person_name
     CompanySearchResponse:
       type: object
       description: Serializer for paginated company search response
@@ -11506,6 +11379,102 @@ components:
         - not_cancelled
         - not_invoiced
         - not_paid
+    ContactMethod:
+      type: object
+      description: Serializer for canonical company/person phone and email methods.
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        company:
+          type: string
+          format: uuid
+          nullable: true
+        owner_company:
+          type: string
+          readOnly: true
+        company_name:
+          type: string
+          readOnly: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
+        person_name:
+          type: string
+          readOnly: true
+        method_type:
+          $ref: '#/components/schemas/MethodTypeEnum'
+        value:
+          type: string
+          maxLength: 255
+        normalized_value:
+          type: string
+          readOnly: true
+        label:
+          type: string
+          maxLength: 255
+        is_primary:
+          type: boolean
+          default: false
+        source:
+          $ref: '#/components/schemas/ContactMethodSourceEnum'
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+        updated_at:
+          type: string
+          format: date-time
+          readOnly: true
+      required:
+        - company_name
+        - created_at
+        - id
+        - method_type
+        - normalized_value
+        - owner_company
+        - person_name
+        - updated_at
+        - value
+    ContactMethodRequest:
+      type: object
+      description: Serializer for canonical company/person phone and email methods.
+      properties:
+        company:
+          type: string
+          format: uuid
+          nullable: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
+        method_type:
+          $ref: '#/components/schemas/MethodTypeEnum'
+        value:
+          type: string
+          minLength: 1
+          maxLength: 255
+        label:
+          type: string
+          maxLength: 255
+        is_primary:
+          type: boolean
+          default: false
+        source:
+          $ref: '#/components/schemas/ContactMethodSourceEnum'
+      required:
+        - method_type
+        - value
+    ContactMethodSourceEnum:
+      enum:
+        - imported
+        - local
+      type: string
+      description: |-
+        * `imported` - Imported
+        * `local` - Local
     CostLine:
       type: object
       description: Serializer for CostLine model - read-only with basic depth
@@ -12184,12 +12153,12 @@ components:
         * `unknown` - Unknown
     DomainEnum:
       enum:
-        - client
+        - company
         - kanban
         - stock
       type: string
       description: |-
-        * `client` - Client
+        * `company` - Company
         * `kanban` - Kanban
         * `stock` - Stock
     DraftLine:
@@ -13008,14 +12977,6 @@ components:
           type: string
           readOnly: true
           nullable: true
-        contact_id:
-          type: string
-          format: uuid
-          nullable: true
-        contact_name:
-          type: string
-          readOnly: true
-          nullable: true
         person_id:
           type: string
           format: uuid
@@ -13181,7 +13142,6 @@ components:
           description: Whether this job requires urgent rates and priority handling
       required:
         - company_name
-        - contact_name
         - created_at
         - default_xero_pay_item_name
         - fully_invoiced
@@ -13300,102 +13260,47 @@ components:
           nullable: true
         order_number:
           type: string
-          nullable: true
-        notes:
-          type: string
-          nullable: true
-      required:
-        - delivery_date
-        - description
-        - notes
-        - order_number
-    JobBreakdown:
-      type: object
-      description: Serializer for job breakdown data
-      properties:
-        job_id:
-          type: string
-        job_number:
-          type: integer
-        job_name:
-          type: string
-        company:
-          type: string
-        hours:
-          type: number
-          format: double
-        revenue:
-          type: number
-          format: double
-        cost:
-          type: number
-          format: double
-        is_billable:
-          type: boolean
-      required:
-        - company
-        - cost
-        - hours
-        - is_billable
-        - job_id
-        - job_name
-        - job_number
-        - revenue
-    JobContactResponse:
-      type: object
-      description: Serializer for job contact information response
-      properties:
-        id:
-          type: string
-          format: uuid
-        name:
-          type: string
-        email:
-          type: string
-          nullable: true
-        position:
-          type: string
-          nullable: true
-        is_primary:
-          type: boolean
-        notes:
-          type: string
-          nullable: true
-      required:
-        - email
-        - id
-        - is_primary
-        - name
-        - notes
-        - position
-    JobContactUpdateRequest:
-      type: object
-      description: Serializer for job contact update request
-      properties:
-        id:
-          type: string
-          format: uuid
-        name:
-          type: string
-          minLength: 1
-        email:
-          type: string
-          nullable: true
-        position:
-          type: string
-          nullable: true
-        is_primary:
-          type: boolean
+          nullable: true
         notes:
           type: string
           nullable: true
       required:
-        - email
-        - id
-        - is_primary
-        - name
+        - delivery_date
+        - description
         - notes
-        - position
+        - order_number
+    JobBreakdown:
+      type: object
+      description: Serializer for job breakdown data
+      properties:
+        job_id:
+          type: string
+        job_number:
+          type: integer
+        job_name:
+          type: string
+        company:
+          type: string
+        hours:
+          type: number
+          format: double
+        revenue:
+          type: number
+          format: double
+        cost:
+          type: number
+          format: double
+        is_billable:
+          type: boolean
+      required:
+        - company
+        - cost
+        - hours
+        - is_billable
+        - job_id
+        - job_name
+        - job_number
+        - revenue
     JobCostSetSummary:
       type: object
       description: Serializer for cost set summary data in job views
@@ -13455,7 +13360,7 @@ components:
           type: string
         notes:
           type: string
-        contact_id:
+        person_id:
           type: string
           format: uuid
           nullable: true
@@ -13966,12 +13871,12 @@ components:
           type: string
           readOnly: true
           nullable: true
-        contact_id:
+        person_id:
           type: string
           format: uuid
           readOnly: true
           nullable: true
-        contact_name:
+        person_name:
           type: string
           readOnly: true
           nullable: true
@@ -14082,13 +13987,13 @@ components:
       required:
         - company_id
         - company_name
-        - contact_id
-        - contact_name
         - default_xero_pay_item_id
         - default_xero_pay_item_name
         - job_id
         - job_number
         - name
+        - person_id
+        - person_name
         - quoted
     JobInvoicesResponse:
       type: object
@@ -14176,6 +14081,39 @@ components:
         - total_actual_profit
         - total_estimated_profit
         - total_profit
+    JobPersonResponse:
+      type: object
+      description: Serializer for job person information response
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        email:
+          type: string
+          nullable: true
+      required:
+        - email
+        - id
+        - name
+    JobPersonUpdateRequest:
+      type: object
+      description: Serializer for job person update request
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+          minLength: 1
+        email:
+          type: string
+          nullable: true
+      required:
+        - email
+        - id
+        - name
     JobProfitabilityItem:
       type: object
       description: Per-job profitability data.
@@ -14568,14 +14506,6 @@ components:
           type: string
           readOnly: true
           nullable: true
-        contact_id:
-          type: string
-          format: uuid
-          nullable: true
-        contact_name:
-          type: string
-          readOnly: true
-          nullable: true
         person_id:
           type: string
           format: uuid
@@ -14741,7 +14671,6 @@ components:
           description: Whether this job requires urgent rates and priority handling
       required:
         - company_name
-        - contact_name
         - created_at
         - default_xero_pay_item_name
         - fully_invoiced
@@ -15184,7 +15113,7 @@ components:
           nullable: true
         company_name:
           type: string
-        contact_person:
+        person_name:
           type: string
         people:
           type: array
@@ -15241,7 +15170,6 @@ components:
         - badge_color
         - badge_label
         - company_name
-        - contact_person
         - created_at
         - created_by_id
         - delivery_date
@@ -15256,6 +15184,7 @@ components:
         - over_budget
         - paid
         - people
+        - person_name
         - priority
         - quote_revenue
         - rejected_flag
@@ -15294,7 +15223,7 @@ components:
           type: integer
         company_name:
           type: string
-        contact_person:
+        person_name:
           type: string
         people:
           type: array
@@ -15346,7 +15275,6 @@ components:
           type: integer
       required:
         - company_name
-        - contact_person
         - created_at
         - created_by_id
         - delivery_date
@@ -15361,6 +15289,7 @@ components:
         - over_budget
         - paid
         - people
+        - person_name
         - priority
         - quote_revenue
         - rejected_flag
@@ -16018,31 +15947,6 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/AppError'
-    PaginatedClientContactMethodList:
-      type: object
-      required:
-        - results
-        - count
-        - page
-        - page_size
-        - total_pages
-      properties:
-        results:
-          type: array
-          items:
-            $ref: '#/components/schemas/ClientContactMethod'
-        count:
-          type: integer
-          example: 123
-        page:
-          type: integer
-          example: 1
-        page_size:
-          type: integer
-          example: 50
-        total_pages:
-          type: integer
-          example: 3
     PaginatedCompleteJobList:
       type: object
       required:
@@ -16066,6 +15970,31 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/CompleteJob'
+    PaginatedContactMethodList:
+      type: object
+      required:
+        - results
+        - count
+        - page
+        - page_size
+        - total_pages
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/ContactMethod'
+        count:
+          type: integer
+          example: 123
+        page:
+          type: integer
+          example: 1
+        page_size:
+          type: integer
+          example: 50
+        total_pages:
+          type: integer
+          example: 3
     PaginatedPhoneCallRecordList:
       type: object
       required:
@@ -16193,78 +16122,6 @@ components:
           writeOnly: true
           description: API Key for the provider. Leave blank to keep unchanged on
             update.
-    PatchedClientContactMethodRequest:
-      type: object
-      description: Serializer for canonical company/contact phone and email methods.
-      properties:
-        company:
-          type: string
-          format: uuid
-          nullable: true
-        contact:
-          type: string
-          format: uuid
-          nullable: true
-        person:
-          type: string
-          format: uuid
-          nullable: true
-        method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
-        value:
-          type: string
-          minLength: 1
-          maxLength: 255
-        label:
-          type: string
-          maxLength: 255
-        is_primary:
-          type: boolean
-        source:
-          $ref: '#/components/schemas/ClientContactMethodSourceEnum'
-    PatchedClientContactRequest:
-      type: object
-      description: Serializer for ClientContact model.
-      properties:
-        company:
-          type: string
-          format: uuid
-          description: The company this contact belongs to
-        person:
-          type: string
-          format: uuid
-          nullable: true
-        name:
-          type: string
-          minLength: 1
-          description: Full name of the contact person
-          maxLength: 255
-        email:
-          type: string
-          format: email
-          nullable: true
-          description: Email address of the contact
-          maxLength: 254
-        xero_name:
-          type: string
-          nullable: true
-          maxLength: 255
-        position:
-          type: string
-          nullable: true
-          description: Job title if it's helpful - else leave blank
-          maxLength: 255
-        is_primary:
-          type: boolean
-          description: Indicates if this is the primary contact for the company
-        notes:
-          type: string
-          nullable: true
-          description: Additional notes about this contact
-        phone:
-          type: string
-          nullable: true
-          default: ''
     PatchedCompanyDefaultsRequest:
       type: object
       properties:
@@ -16607,6 +16464,41 @@ components:
           type: string
           format: uuid
           description: Internal company used for tracking shop work.
+    PatchedCompanyPersonLinkRequest:
+      type: object
+      description: Serializer for a person's relationship to a company.
+      properties:
+        company:
+          type: string
+          format: uuid
+          description: The company this contact belongs to
+        person_name:
+          type: string
+          minLength: 1
+        person_email:
+          type: string
+          format: email
+          nullable: true
+        xero_name:
+          type: string
+          nullable: true
+          maxLength: 255
+        position:
+          type: string
+          nullable: true
+          description: Job title if it's helpful - else leave blank
+          maxLength: 255
+        is_primary:
+          type: boolean
+          description: Indicates if this is the primary contact for the company
+        notes:
+          type: string
+          nullable: true
+          description: Additional notes about this contact
+        phone:
+          type: string
+          nullable: true
+          default: ''
     PatchedCompanyUpdateRequest:
       type: object
       description: Serializer for company update request
@@ -16627,6 +16519,32 @@ components:
           type: boolean
         allow_jobs:
           type: boolean
+    PatchedContactMethodRequest:
+      type: object
+      description: Serializer for canonical company/person phone and email methods.
+      properties:
+        company:
+          type: string
+          format: uuid
+          nullable: true
+        person:
+          type: string
+          format: uuid
+          nullable: true
+        method_type:
+          $ref: '#/components/schemas/MethodTypeEnum'
+        value:
+          type: string
+          minLength: 1
+          maxLength: 255
+        label:
+          type: string
+          maxLength: 255
+        is_primary:
+          type: boolean
+          default: false
+        source:
+          $ref: '#/components/schemas/ContactMethodSourceEnum'
     PatchedCostLineCreateUpdateRequest:
       type: object
       description: Serializer for CostLine creation and updates - full write capabilities
@@ -17699,14 +17617,6 @@ components:
         company_name:
           type: string
           readOnly: true
-        contact:
-          type: string
-          format: uuid
-          readOnly: true
-          nullable: true
-        contact_name:
-          type: string
-          readOnly: true
         person:
           type: string
           format: uuid
@@ -17762,8 +17672,6 @@ components:
         - charge
         - company
         - company_name
-        - contact
-        - contact_name
         - description
         - destination
         - destination_endpoint
@@ -17946,7 +17854,7 @@ components:
         company:
           type: string
           format: uuid
-        contact:
+        person:
           type: string
           format: uuid
           nullable: true
@@ -22627,7 +22535,7 @@ components:
           type: integer
         company_name:
           type: string
-        contact_person:
+        person_name:
           type: string
           nullable: true
         people:
@@ -22636,12 +22544,12 @@ components:
             $ref: '#/components/schemas/KanbanJobPerson'
       required:
         - company_name
-        - contact_person
         - description
         - id
         - job_number
         - name
         - people
+        - person_name
     WorkshopPDFResponse:
       type: object
       description: Serializer for workshop PDF generation response
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index 7e2cc1c64..f2b8bec51 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -633,9 +633,6 @@ const CompanyDetailResponse = z.object({
   allow_jobs: z.boolean(),
   xero_contact_id: z.string(),
   xero_tenant_id: z.string(),
-  primary_contact_name: z.string(),
-  primary_contact_email: z.string(),
-  additional_contact_persons: z.array(z.unknown()).optional(),
   xero_last_modified: z.string().datetime({ offset: true }).nullable(),
   xero_last_synced: z.string().datetime({ offset: true }).nullable(),
   xero_archived: z.boolean(),
@@ -709,81 +706,48 @@ const PatchedCompanyUpdateRequest = z
   .partial()
 const CompanyNameOnly = z.object({ id: z.string().uuid(), name: z.string() })
 const MethodTypeEnum = z.enum(['phone', 'email'])
-const ClientContactMethodSourceEnum = z.enum(['imported', 'local'])
-const ClientContactMethod = z.object({
+const ContactMethodSourceEnum = z.enum(['imported', 'local'])
+const ContactMethod = z.object({
   id: z.string().uuid(),
   company: z.string().uuid().nullish(),
   owner_company: z.string(),
   company_name: z.string(),
-  contact: z.string().uuid().nullish(),
-  contact_name: z.string(),
+  person: z.string().uuid().nullish(),
+  person_name: z.string(),
   method_type: MethodTypeEnum,
   value: z.string().max(255),
   normalized_value: z.string(),
   label: z.string().max(255).optional(),
   is_primary: z.boolean().optional().default(false),
-  source: ClientContactMethodSourceEnum.optional(),
+  source: ContactMethodSourceEnum.optional(),
   created_at: z.string().datetime({ offset: true }),
   updated_at: z.string().datetime({ offset: true }),
 })
-const PaginatedClientContactMethodList = z.object({
-  results: z.array(ClientContactMethod),
+const PaginatedContactMethodList = z.object({
+  results: z.array(ContactMethod),
   count: z.number().int(),
   page: z.number().int(),
   page_size: z.number().int(),
   total_pages: z.number().int(),
 })
-const ClientContactMethodRequest = z.object({
+const ContactMethodRequest = z.object({
   company: z.string().uuid().nullish(),
-  contact: z.string().uuid().nullish(),
+  person: z.string().uuid().nullish(),
   method_type: MethodTypeEnum,
   value: z.string().min(1).max(255),
   label: z.string().max(255).optional(),
   is_primary: z.boolean().optional().default(false),
-  source: ClientContactMethodSourceEnum.optional(),
+  source: ContactMethodSourceEnum.optional(),
 })
-const PatchedClientContactMethodRequest = z
+const PatchedContactMethodRequest = z
   .object({
     company: z.string().uuid().nullable(),
-    contact: z.string().uuid().nullable(),
+    person: z.string().uuid().nullable(),
     method_type: MethodTypeEnum,
     value: z.string().min(1).max(255),
     label: z.string().max(255),
     is_primary: z.boolean().default(false),
-    source: ClientContactMethodSourceEnum,
-  })
-  .partial()
-const ClientContact = z.object({
-  id: z.string().uuid(),
-  company: z.string().uuid(),
-  name: z.string().max(255),
-  email: z.string().max(254).email().nullish(),
-  position: z.string().max(255).nullish(),
-  is_primary: z.boolean().optional(),
-  notes: z.string().nullish(),
-  is_active: z.boolean(),
-  created_at: z.string().datetime({ offset: true }),
-  updated_at: z.string().datetime({ offset: true }),
-  phone: z.string().nullish().default(''),
-})
-const ClientContactRequest = z.object({
-  company: z.string().uuid(),
-  name: z.string().min(1).max(255),
-  email: z.string().max(254).email().nullish(),
-  position: z.string().max(255).nullish(),
-  is_primary: z.boolean().optional(),
-  notes: z.string().nullish(),
-  phone: z.string().nullish().default(''),
-})
-const PatchedClientContactRequest = z
-  .object({
-    company: z.string().uuid(),
-    name: z.string().min(1).max(255),
-    email: z.string().max(254).email().nullable(),
-    position: z.string().max(255).nullable(),
-    is_primary: z.boolean(),
-    notes: z.string().nullable(),
-    phone: z.string().nullable().default(''),
+    source: ContactMethodSourceEnum,
   })
   .partial()
 const CompanyCreateRequest = z.object({
@@ -817,22 +781,53 @@ const CompanyDuplicateErrorResponse = z.object({
   error: z.string(),
   existing_company: z.object({}).partial().passthrough(),
 })
-const JobContactResponse = z.object({
+const JobPersonResponse = z.object({
   id: z.string().uuid(),
   name: z.string(),
   email: z.string().nullable(),
-  position: z.string().nullable(),
-  is_primary: z.boolean(),
-  notes: z.string().nullable(),
 })
-const JobContactUpdateRequest = z.object({
+const JobPersonUpdateRequest = z.object({
   id: z.string().uuid(),
   name: z.string().min(1),
   email: z.string().nullable(),
-  position: z.string().nullable(),
-  is_primary: z.boolean(),
-  notes: z.string().nullable(),
 })
+const CompanyPersonLink = z.object({
+  id: z.string().uuid(),
+  company: z.string().uuid(),
+  person: z.string().uuid(),
+  person_name: z.string(),
+  person_email: z.string().email().nullish(),
+  xero_name: z.string().max(255).nullish(),
+  position: z.string().max(255).nullish(),
+  is_primary: z.boolean().optional(),
+  notes: z.string().nullish(),
+  is_active: z.boolean(),
+  created_at: z.string().datetime({ offset: true }),
+  updated_at: z.string().datetime({ offset: true }),
+  phone: z.string().nullish().default(''),
+})
+const CompanyPersonLinkRequest = z.object({
+  company: z.string().uuid(),
+  person_name: z.string().min(1),
+  person_email: z.string().email().nullish(),
+  xero_name: z.string().max(255).nullish(),
+  position: z.string().max(255).nullish(),
+  is_primary: z.boolean().optional(),
+  notes: z.string().nullish(),
+  phone: z.string().nullish().default(''),
+})
+const PatchedCompanyPersonLinkRequest = z
+  .object({
+    company: z.string().uuid(),
+    person_name: z.string().min(1),
+    person_email: z.string().email().nullable(),
+    xero_name: z.string().max(255).nullable(),
+    position: z.string().max(255).nullable(),
+    is_primary: z.boolean(),
+    notes: z.string().nullable(),
+    phone: z.string().nullable().default(''),
+  })
+  .partial()
 const SupplierPickupAddress = z.object({
   id: z.string().uuid(),
   company: z.string().uuid(),
@@ -1141,8 +1136,8 @@ const PhoneCallRecord = z.object({
   charge: z.number().gt(-100000000).lt(100000000).nullable(),
   company: z.string().uuid().nullable(),
   company_name: z.string(),
-  contact: z.string().uuid().nullable(),
-  contact_name: z.string(),
+  person: z.string().uuid().nullable(),
+  person_name: z.string(),
   job: z.string().uuid().nullable(),
   job_number: z.number().int().nullable(),
   job_name: z.string(),
@@ -1162,7 +1157,7 @@ const PaginatedPhoneCallRecordList = z.object({
 })
 const PhoneNumberAssignmentRequest = z.object({
   company: z.string().uuid(),
-  contact: z.string().uuid().nullish(),
+  person: z.string().uuid().nullish(),
   is_primary: z.boolean().optional().default(false),
   label: z.string().max(255).optional().default(''),
 })
@@ -1402,7 +1397,7 @@ const JobCreateRequest = z.object({
   description: z.string().optional(),
   order_number: z.string().optional(),
   notes: z.string().optional(),
-  contact_id: z.string().uuid().nullish(),
+  person_id: z.string().uuid().nullish(),
   pricing_methodology: z.string().nullish(),
   estimated_materials: z.number().gte(0).lt(100000000),
   estimated_time: z.number().gte(0).lt(100000000),
@@ -1497,8 +1492,8 @@ const Job = z.object({
   name: z.string().max(100),
   company_id: z.string().uuid().nullish(),
   company_name: z.string().nullable(),
-  contact_id: z.string().uuid().nullish(),
-  contact_name: z.string().nullable(),
+  person_id: z.string().uuid().nullish(),
+  person_name: z.string().nullable(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
   notes: z.string().nullish(),
   order_number: z.string().max(100).nullish(),
@@ -1710,8 +1705,8 @@ const JobHeaderResponse = z.object({
   job_id: z.string().uuid(),
   company_id: z.string().uuid().nullable(),
   company_name: z.string().nullable(),
-  contact_id: z.string().uuid().nullable(),
-  contact_name: z.string().nullable(),
+  person_id: z.string().uuid().nullable(),
+  person_name: z.string().nullable(),
   quoted: z.boolean(),
   default_xero_pay_item_id: z.string().uuid().nullable(),
   default_xero_pay_item_name: z.string().nullable(),
@@ -1836,8 +1831,8 @@ const JobSummary = z.object({
   name: z.string().max(100),
   company_id: z.string().uuid().nullish(),
   company_name: z.string().nullable(),
-  contact_id: z.string().uuid().nullish(),
-  contact_name: z.string().nullable(),
+  person_id: z.string().uuid().nullish(),
+  person_name: z.string().nullable(),
   job_number: z.number().int().gte(-2147483648).lte(2147483647),
   notes: z.string().nullish(),
   order_number: z.string().max(100).nullish(),
@@ -1977,7 +1972,7 @@ const KanbanJob = z.object({
   description: z.string().nullable(),
   job_number: z.number().int(),
   company_name: z.string(),
-  contact_person: z.string(),
+  person_name: z.string(),
   people: z.array(KanbanJobPerson),
   status: z.string(),
   status_key: z.string(),
@@ -2045,7 +2040,7 @@ const KanbanColumnJob = z.object({
   name: z.string(),
   description: z.string().nullable(),
   company_name: z.string(),
-  contact_person: z.string(),
+  person_name: z.string(),
   people: z.array(KanbanJobPerson),
   status: z.string(),
   status_key: z.string(),
@@ -2116,7 +2111,7 @@ const WorkshopJob = z.object({
   description: z.string().nullable(),
   job_number: z.number().int(),
   company_name: z.string(),
-  contact_person: z.string().nullable(),
+  person_name: z.string().nullable(),
   people: z.array(KanbanJobPerson),
 })
 const LabourSubtype = z.object({
@@ -3061,7 +3056,7 @@ const AppErrorListResponse = z.object({
   previous: z.string().nullish(),
   results: z.array(AppError),
 })
-const DomainEnum = z.enum(['client', 'kanban', 'stock'])
+const DomainEnum = z.enum(['company', 'kanban', 'stock'])
 const SearchTelemetryClickRequestRequest = z.object({
   domain: DomainEnum,
   query: z.string().max(255),
@@ -3604,20 +3599,20 @@ export const schemas = {
   PatchedCompanyUpdateRequest,
   CompanyNameOnly,
   MethodTypeEnum,
-  ClientContactMethodSourceEnum,
-  ClientContactMethod,
-  PaginatedClientContactMethodList,
-  ClientContactMethodRequest,
-  PatchedClientContactMethodRequest,
-  ClientContact,
-  ClientContactRequest,
-  PatchedClientContactRequest,
+  ContactMethodSourceEnum,
+  ContactMethod,
+  PaginatedContactMethodList,
+  ContactMethodRequest,
+  PatchedContactMethodRequest,
   CompanyCreateRequest,
   CompanySearchResult,
   CompanyCreateResponse,
   CompanyDuplicateErrorResponse,
-  JobContactResponse,
-  JobContactUpdateRequest,
+  JobPersonResponse,
+  JobPersonUpdateRequest,
+  CompanyPersonLink,
+  CompanyPersonLinkRequest,
+  PatchedCompanyPersonLinkRequest,
   SupplierPickupAddress,
   SupplierPickupAddressRequest,
   PatchedSupplierPickupAddressRequest,
@@ -4993,7 +4988,7 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
     method: 'get',
     path: '/api/companies/contact-methods/',
     alias: 'companies_contact_methods_list',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5001,11 +4996,6 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         type: 'Query',
         schema: z.string().uuid().optional(),
       },
-      {
-        name: 'contact_id',
-        type: 'Query',
-        schema: z.string().uuid().optional(),
-      },
       {
         name: 'method_type',
         type: 'Query',
@@ -5021,29 +5011,34 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         type: 'Query',
         schema: z.number().int().optional(),
       },
+      {
+        name: 'person_id',
+        type: 'Query',
+        schema: z.string().uuid().optional(),
+      },
     ],
-    response: PaginatedClientContactMethodList,
+    response: PaginatedContactMethodList,
   },
   {
     method: 'post',
     path: '/api/companies/contact-methods/',
     alias: 'companies_contact_methods_create',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientContactMethodRequest,
+        schema: ContactMethodRequest,
       },
     ],
-    response: ClientContactMethod,
+    response: ContactMethod,
   },
   {
     method: 'get',
     path: '/api/companies/contact-methods/:id/',
     alias: 'companies_contact_methods_retrieve',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5052,19 +5047,19 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContactMethod,
+    response: ContactMethod,
   },
   {
     method: 'put',
     path: '/api/companies/contact-methods/:id/',
     alias: 'companies_contact_methods_update',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientContactMethodRequest,
+        schema: ContactMethodRequest,
       },
       {
         name: 'id',
@@ -5072,19 +5067,19 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContactMethod,
+    response: ContactMethod,
   },
   {
     method: 'patch',
     path: '/api/companies/contact-methods/:id/',
     alias: 'companies_contact_methods_partial_update',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: PatchedClientContactMethodRequest,
+        schema: PatchedContactMethodRequest,
       },
       {
         name: 'id',
@@ -5092,13 +5087,13 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContactMethod,
+    response: ContactMethod,
   },
   {
     method: 'delete',
     path: '/api/companies/contact-methods/:id/',
     alias: 'companies_contact_methods_destroy',
-    description: `CRUD API for canonical company/contact phone and email methods.`,
+    description: `CRUD API for canonical company/person phone and email methods.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5109,11 +5104,103 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
     ],
     response: z.void(),
   },
+  {
+    method: 'post',
+    path: '/api/companies/create/',
+    alias: 'companies_create_create',
+    description: `Creates a new company in Xero first, then syncs locally. Requires valid Xero authentication.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: CompanyCreateRequest,
+      },
+    ],
+    response: CompanyCreateResponse,
+    errors: [
+      {
+        status: 400,
+        schema: CompanyErrorResponse,
+      },
+      {
+        status: 401,
+        schema: CompanyErrorResponse,
+      },
+      {
+        status: 409,
+        schema: CompanyDuplicateErrorResponse,
+      },
+      {
+        status: 500,
+        schema: CompanyErrorResponse,
+      },
+    ],
+  },
   {
     method: 'get',
-    path: '/api/companies/contacts/',
-    alias: 'companies_contacts_list',
-    description: `List all contacts, optionally filtered by company_id.`,
+    path: '/api/companies/jobs/:job_id/person/',
+    alias: 'companies_jobs_person_retrieve',
+    description: `Retrieve person information for a specific job.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'job_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: JobPersonResponse,
+    errors: [
+      {
+        status: 404,
+        schema: CompanyErrorResponse,
+      },
+      {
+        status: 500,
+        schema: CompanyErrorResponse,
+      },
+    ],
+  },
+  {
+    method: 'put',
+    path: '/api/companies/jobs/:job_id/person/',
+    alias: 'companies_jobs_person_update',
+    description: `Update the person associated with a specific job.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: JobPersonUpdateRequest,
+      },
+      {
+        name: 'job_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: JobPersonResponse,
+    errors: [
+      {
+        status: 400,
+        schema: CompanyErrorResponse,
+      },
+      {
+        status: 404,
+        schema: CompanyErrorResponse,
+      },
+      {
+        status: 500,
+        schema: CompanyErrorResponse,
+      },
+    ],
+  },
+  {
+    method: 'get',
+    path: '/api/companies/person-links/',
+    alias: 'companies_person_links_list',
+    description: `List all company-person links, optionally filtered by company_id.`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5122,50 +5209,50 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
         schema: z.string().uuid().optional(),
       },
     ],
-    response: z.array(ClientContact),
+    response: z.array(CompanyPersonLink),
   },
   {
     method: 'post',
-    path: '/api/companies/contacts/',
-    alias: 'companies_contacts_create',
-    description: `ViewSet for ClientContact CRUD operations.
+    path: '/api/companies/person-links/',
+    alias: 'companies_person_links_create',
+    description: `ViewSet for CompanyPersonLink CRUD operations.
 
 Endpoints:
-- GET    /api/companies/contacts/           - list all contacts
-- POST   /api/companies/contacts/           - create contact
-- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/person-links/       - list all company-person links
+- POST   /api/companies/person-links/       - create link
+- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
+- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
+- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
+- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- company_id: Filter contacts by company UUID`,
+- company_id: Filter links by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientContactRequest,
+        schema: CompanyPersonLinkRequest,
       },
     ],
-    response: ClientContact,
+    response: CompanyPersonLink,
   },
   {
     method: 'get',
-    path: '/api/companies/contacts/:id/',
-    alias: 'companies_contacts_retrieve',
-    description: `ViewSet for ClientContact CRUD operations.
+    path: '/api/companies/person-links/:id/',
+    alias: 'companies_person_links_retrieve',
+    description: `ViewSet for CompanyPersonLink CRUD operations.
 
 Endpoints:
-- GET    /api/companies/contacts/           - list all contacts
-- POST   /api/companies/contacts/           - create contact
-- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/person-links/       - list all company-person links
+- POST   /api/companies/person-links/       - create link
+- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
+- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
+- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
+- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- company_id: Filter contacts by company UUID`,
+- company_id: Filter links by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5174,30 +5261,30 @@ Query Parameters:
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContact,
+    response: CompanyPersonLink,
   },
   {
     method: 'put',
-    path: '/api/companies/contacts/:id/',
-    alias: 'companies_contacts_update',
-    description: `ViewSet for ClientContact CRUD operations.
+    path: '/api/companies/person-links/:id/',
+    alias: 'companies_person_links_update',
+    description: `ViewSet for CompanyPersonLink CRUD operations.
 
 Endpoints:
-- GET    /api/companies/contacts/           - list all contacts
-- POST   /api/companies/contacts/           - create contact
-- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/person-links/       - list all company-person links
+- POST   /api/companies/person-links/       - create link
+- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
+- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
+- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
+- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- company_id: Filter contacts by company UUID`,
+- company_id: Filter links by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: ClientContactRequest,
+        schema: CompanyPersonLinkRequest,
       },
       {
         name: 'id',
@@ -5205,30 +5292,30 @@ Query Parameters:
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContact,
+    response: CompanyPersonLink,
   },
   {
     method: 'patch',
-    path: '/api/companies/contacts/:id/',
-    alias: 'companies_contacts_partial_update',
-    description: `ViewSet for ClientContact CRUD operations.
+    path: '/api/companies/person-links/:id/',
+    alias: 'companies_person_links_partial_update',
+    description: `ViewSet for CompanyPersonLink CRUD operations.
 
 Endpoints:
-- GET    /api/companies/contacts/           - list all contacts
-- POST   /api/companies/contacts/           - create contact
-- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/person-links/       - list all company-person links
+- POST   /api/companies/person-links/       - create link
+- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
+- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
+- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
+- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- company_id: Filter contacts by company UUID`,
+- company_id: Filter links by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
         name: 'body',
         type: 'Body',
-        schema: PatchedClientContactRequest,
+        schema: PatchedCompanyPersonLinkRequest,
       },
       {
         name: 'id',
@@ -5236,24 +5323,24 @@ Query Parameters:
         schema: z.string().uuid(),
       },
     ],
-    response: ClientContact,
+    response: CompanyPersonLink,
   },
   {
     method: 'delete',
-    path: '/api/companies/contacts/:id/',
-    alias: 'companies_contacts_destroy',
-    description: `ViewSet for ClientContact CRUD operations.
+    path: '/api/companies/person-links/:id/',
+    alias: 'companies_person_links_destroy',
+    description: `ViewSet for CompanyPersonLink CRUD operations.
 
 Endpoints:
-- GET    /api/companies/contacts/           - list all contacts
-- POST   /api/companies/contacts/           - create contact
-- GET    /api/companies/contacts/&lt;id&gt;/      - retrieve contact
-- PUT    /api/companies/contacts/&lt;id&gt;/      - full update
-- PATCH  /api/companies/contacts/&lt;id&gt;/      - partial update
-- DELETE /api/companies/contacts/&lt;id&gt;/      - soft delete (sets is_active&#x3D;False)
+- GET    /api/companies/person-links/       - list all company-person links
+- POST   /api/companies/person-links/       - create link
+- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
+- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
+- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
+- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
 
 Query Parameters:
-- company_id: Filter contacts by company UUID`,
+- company_id: Filter links by company UUID`,
     requestFormat: 'json',
     parameters: [
       {
@@ -5264,98 +5351,6 @@ Query Parameters:
     ],
     response: z.void(),
   },
-  {
-    method: 'post',
-    path: '/api/companies/create/',
-    alias: 'companies_create_create',
-    description: `Creates a new company in Xero first, then syncs locally. Requires valid Xero authentication.`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'body',
-        type: 'Body',
-        schema: CompanyCreateRequest,
-      },
-    ],
-    response: CompanyCreateResponse,
-    errors: [
-      {
-        status: 400,
-        schema: CompanyErrorResponse,
-      },
-      {
-        status: 401,
-        schema: CompanyErrorResponse,
-      },
-      {
-        status: 409,
-        schema: CompanyDuplicateErrorResponse,
-      },
-      {
-        status: 500,
-        schema: CompanyErrorResponse,
-      },
-    ],
-  },
-  {
-    method: 'get',
-    path: '/api/companies/jobs/:job_id/contact/',
-    alias: 'companies_jobs_contact_retrieve',
-    description: `Retrieve contact information for a specific job.`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'job_id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: JobContactResponse,
-    errors: [
-      {
-        status: 404,
-        schema: CompanyErrorResponse,
-      },
-      {
-        status: 500,
-        schema: CompanyErrorResponse,
-      },
-    ],
-  },
-  {
-    method: 'put',
-    path: '/api/companies/jobs/:job_id/contact/',
-    alias: 'companies_jobs_contact_update',
-    description: `Update the contact person associated with a specific job.`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'body',
-        type: 'Body',
-        schema: JobContactUpdateRequest,
-      },
-      {
-        name: 'job_id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: JobContactResponse,
-    errors: [
-      {
-        status: 400,
-        schema: CompanyErrorResponse,
-      },
-      {
-        status: 404,
-        schema: CompanyErrorResponse,
-      },
-      {
-        status: 500,
-        schema: CompanyErrorResponse,
-      },
-    ],
-  },
   {
     method: 'get',
     path: '/api/companies/pickup-addresses/',
@@ -5773,11 +5768,6 @@ DELETE: Clear a logo field and remove the file from disk.`,
         type: 'Query',
         schema: z.string().uuid().optional(),
       },
-      {
-        name: 'contact',
-        type: 'Query',
-        schema: z.string().uuid().optional(),
-      },
       {
         name: 'destination_endpoint',
         type: 'Query',
@@ -5823,6 +5813,11 @@ DELETE: Clear a logo field and remove the file from disk.`,
         type: 'Query',
         schema: z.number().int().optional(),
       },
+      {
+        name: 'person',
+        type: 'Query',
+        schema: z.string().uuid().optional(),
+      },
       {
         name: 'q',
         type: 'Query',
@@ -7359,11 +7354,6 @@ Expected JSON:
         type: 'Query',
         schema: z.string().optional(),
       },
-      {
-        name: 'contact_person',
-        type: 'Query',
-        schema: z.string().optional(),
-      },
       {
         name: 'created_after',
         type: 'Query',
@@ -7404,6 +7394,11 @@ Expected JSON:
         type: 'Query',
         schema: z.string().optional(),
       },
+      {
+        name: 'person_name',
+        type: 'Query',
+        schema: z.string().optional(),
+      },
       {
         name: 'q',
         type: 'Query',
diff --git a/frontend/src/components/AdvancedSearchDialog.vue b/frontend/src/components/AdvancedSearchDialog.vue
index 71d1e10ec..7f1335895 100644
--- a/frontend/src/components/AdvancedSearchDialog.vue
+++ b/frontend/src/components/AdvancedSearchDialog.vue
@@ -58,12 +58,12 @@
           </div>
 
           <div>
-            <label class="block text-sm font-medium text-gray-700 mb-1">Contact Person</label>
+            <label class="block text-sm font-medium text-gray-700 mb-1">Person</label>
             <input
-              v-model="localFilters.contact_person"
+              v-model="localFilters.person_name"
               type="text"
               class="w-full px-3 py-2 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent text-sm"
-              placeholder="Contact person"
+              placeholder="Person"
             />
           </div>
         </div>
diff --git a/frontend/src/components/JobCard.vue b/frontend/src/components/JobCard.vue
index 487c930d2..d00d3519d 100644
--- a/frontend/src/components/JobCard.vue
+++ b/frontend/src/components/JobCard.vue
@@ -164,9 +164,9 @@
       {{ descriptionOrName }}
     </p>
 
-    <!-- Contact only (company line removed by request) -->
-    <div v-if="job.contact_person" class="text-[0.8rem] text-gray-600 truncate font-medium">
-      <span class="font-semibold">Contact:</span> {{ job.contact_person }}
+    <!-- Person only (company line removed by request) -->
+    <div v-if="job.person_name" class="text-[0.8rem] text-gray-600 truncate font-medium">
+      <span class="font-semibold">Person:</span> {{ job.person_name }}
     </div>
 
     <div v-if="dueDateDisplay" class="text-[0.8rem] truncate font-bold" :class="dueDateColor">
diff --git a/frontend/src/components/KanbanColumn.vue b/frontend/src/components/KanbanColumn.vue
index c8f83e268..34b03670b 100644
--- a/frontend/src/components/KanbanColumn.vue
+++ b/frontend/src/components/KanbanColumn.vue
@@ -114,7 +114,7 @@
           <p class="text-xs text-gray-500 mb-2">{{ job.description }}</p>
           <div class="text-xs text-gray-400">
             <p>{{ job.company_name }}</p>
-            <p>{{ job.contact_person }}</p>
+            <p>{{ job.person_name }}</p>
           </div>
         </div>
 
diff --git a/frontend/src/components/ContactSelectionModal.vue b/frontend/src/components/PersonSelectionModal.vue
similarity index 77%
rename from frontend/src/components/ContactSelectionModal.vue
rename to frontend/src/components/PersonSelectionModal.vue
index 500e58eaa..3ce31380d 100644
--- a/frontend/src/components/ContactSelectionModal.vue
+++ b/frontend/src/components/PersonSelectionModal.vue
@@ -3,9 +3,9 @@
     <DialogContent
       class="modal-content overflow-hidden flex flex-col fixed top-1/2 left-1/2 transform -translate-x-1/2 -translate-y-1/2 !max-w-[950px]"
     >
-      <div data-automation-id="ContactSelectionModal-container">
+      <div data-automation-id="PersonSelectionModal-container">
         <DialogHeader class="flex-shrink-0 pb-4 border-b border-gray-200">
-          <DialogTitle class="text-lg font-semibold">Select Contact</DialogTitle>
+          <DialogTitle class="text-lg font-semibold">Select Person</DialogTitle>
           <DialogDescription class="text-sm text-gray-600">
             Company:
             <span class="font-medium text-gray-900">{{
@@ -17,8 +17,8 @@
         <div
           class="modal-body flex-1 overflow-hidden flex flex-col xl:flex-row gap-4 lg:gap-6 py-4"
         >
-          <!-- Existing Contacts Section -->
-          <div class="contacts-section flex-1 min-h-0 flex flex-col relative">
+          <!-- Existing People Section -->
+          <div class="people-section flex-1 min-h-0 flex flex-col relative">
             <!-- Delete Confirmation Overlay -->
             <div
               v-if="showDeleteConfirm"
@@ -30,17 +30,17 @@
                 >
                   <AlertTriangle class="w-6 h-6 text-red-600" />
                 </div>
-                <h4 class="text-lg font-semibold text-gray-900 mb-2">Delete Contact?</h4>
+                <h4 class="text-lg font-semibold text-gray-900 mb-2">Delete Person?</h4>
                 <p class="text-sm text-gray-600 mb-4">
                   Are you sure you want to remove
-                  <strong>{{ contactToDelete?.name }}</strong
-                  >? The contact will be marked as inactive.
+                  <strong>{{ personToDelete?.person_name }}</strong
+                  >? The person will be marked as inactive.
                 </p>
                 <p
-                  v-if="contactToDelete?.is_primary"
+                  v-if="personToDelete?.is_primary"
                   class="text-sm text-amber-600 font-medium mb-4"
                 >
-                  This is the primary contact for this company.
+                  This is the primary person for this company.
                 </p>
                 <div class="flex gap-3 justify-center">
                   <button
@@ -64,38 +64,38 @@
                 <div
                   class="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-600 mx-auto"
                 ></div>
-                <p class="mt-2 text-sm text-gray-500">Loading contacts...</p>
+                <p class="mt-2 text-sm text-gray-500">Loading people...</p>
               </div>
             </div>
 
             <div v-else class="flex-1 flex flex-col min-h-0">
-              <div v-if="contacts.length > 0" class="flex-1 flex flex-col min-h-0">
+              <div v-if="people.length > 0" class="flex-1 flex flex-col min-h-0">
                 <h4 class="section-title text-sm font-semibold text-gray-900 mb-3 flex-shrink-0">
-                  Existing Contacts ({{ contacts.length }})
+                  Existing People ({{ people.length }})
                 </h4>
 
-                <!-- Contacts Grid Container -->
+                <!-- People Grid Container -->
                 <div
-                  class="contacts-grid-container flex-1 overflow-y-auto scrollbar-thin scrollbar-thumb-gray-300 scrollbar-track-gray-100 pr-1"
+                  class="people-grid-container flex-1 overflow-y-auto scrollbar-thin scrollbar-thumb-gray-300 scrollbar-track-gray-100 pr-1"
                 >
-                  <div class="contacts-grid grid gap-3 pb-2">
+                  <div class="people-grid grid gap-3 pb-2">
                     <div
-                      v-for="contact in contacts || []"
-                      :key="contact?.id || ''"
-                      :data-automation-id="`ContactSelectionModal-card-${contact?.id}`"
+                      v-for="person in people || []"
+                      :key="person?.id || ''"
+                      :data-automation-id="`PersonSelectionModal-card-${person?.id}`"
                       class="group relative bg-white border border-gray-200 rounded-lg p-2 cursor-pointer transition-all duration-200 hover:shadow-md hover:border-blue-300 hover:-translate-y-0.5"
                       :class="{
                         'ring-2 ring-blue-500 bg-blue-50 border-blue-500 shadow-md mt-1':
-                          selectedContact?.id === contact?.id,
+                          selectedPerson?.id === person?.id,
                         'ring-2 ring-amber-500 bg-amber-50 border-amber-500':
-                          editingContact?.id === contact?.id,
+                          editingPersonLink?.id === person?.id,
                         'hover:bg-gray-50':
-                          selectedContact?.id !== contact?.id && editingContact?.id !== contact?.id,
+                          selectedPerson?.id !== person?.id && editingPersonLink?.id !== person?.id,
                       }"
-                      @click="selectContact(contact)"
+                      @click="selectPerson(person)"
                     >
                       <!-- Primary Badge -->
-                      <div v-if="contact?.is_primary" class="absolute -top-1 -right-1">
+                      <div v-if="person?.is_primary" class="absolute -top-1 -right-1">
                         <span
                           class="inline-flex items-center px-2 py-0.5 rounded-full text-xs font-medium bg-green-500 text-white shadow-sm"
                         >
@@ -103,19 +103,19 @@
                         </span>
                       </div>
 
-                      <!-- Contact Info -->
+                      <!-- Person Info -->
                       <div class="space-y-1">
                         <div class="font-medium text-gray-900 text-sm truncate pr-4">
-                          {{ contact?.name || '' }}
+                          {{ person?.person_name || '' }}
                         </div>
 
-                        <div v-if="contact?.position" class="text-xs text-gray-600 truncate">
-                          {{ contact?.position }}
+                        <div v-if="person?.position" class="text-xs text-gray-600 truncate">
+                          {{ person?.position }}
                         </div>
 
                         <div class="space-y-0.5">
                           <div
-                            v-if="contact?.email"
+                            v-if="person?.person_email"
                             class="text-xs text-gray-500 truncate flex items-center"
                           >
                             <svg
@@ -128,11 +128,11 @@
                               />
                               <path d="M18 8.118l-8 4-8-4V14a2 2 0 002 2h12a2 2 0 002-2V8.118z" />
                             </svg>
-                            {{ contact?.email }}
+                            {{ person?.person_email }}
                           </div>
 
                           <div
-                            v-if="contact?.phone"
+                            v-if="person?.phone"
                             class="text-xs text-gray-500 truncate flex items-center"
                           >
                             <svg
@@ -144,7 +144,7 @@
                                 d="M2 3a1 1 0 011-1h2.153a1 1 0 01.986.836l.74 4.435a1 1 0 01-.54 1.06l-1.548.773a11.037 11.037 0 006.105 6.105l.774-1.548a1 1 0 011.059-.54l4.435.74a1 1 0 01.836.986V17a1 1 0 01-1 1h-2C7.82 18 2 12.18 2 5V3z"
                               />
                             </svg>
-                            {{ contact?.phone }}
+                            {{ person?.phone }}
                           </div>
                         </div>
                       </div>
@@ -155,23 +155,23 @@
                       >
                         <button
                           class="px-2.5 py-1 text-xs font-medium bg-blue-600 text-white rounded-md shadow-sm hover:bg-blue-700 transition-colors"
-                          data-automation-id="ContactSelectionModal-select-button"
-                          @click.stop="selectContact(contact)"
-                          title="Select this contact"
+                          data-automation-id="PersonSelectionModal-select-button"
+                          @click.stop="selectPerson(person)"
+                          title="Select this person"
                         >
                           Select
                         </button>
                         <button
                           class="p-1.5 text-xs font-medium bg-gray-600 text-white rounded-md shadow-sm hover:bg-gray-700 transition-colors"
-                          @click.stop="emit('edit-contact', contact)"
-                          title="Edit contact"
+                          @click.stop="emit('edit-person', person)"
+                          title="Edit person"
                         >
                           <PencilLine class="w-3.5 h-3.5" />
                         </button>
                         <button
                           class="p-1.5 text-xs font-medium bg-red-600 text-white rounded-md shadow-sm hover:bg-red-700 transition-colors"
-                          @click.stop="confirmDeleteContact(contact)"
-                          title="Delete contact"
+                          @click.stop="confirmDeletePerson(person)"
+                          title="Delete person"
                         >
                           <Trash2 class="w-3.5 h-3.5" />
                         </button>
@@ -184,20 +184,20 @@
               <div v-else class="flex-1 flex items-center justify-center">
                 <div class="text-center text-gray-500">
                   <Users class="w-12 h-12 mx-auto mb-3 text-gray-300" />
-                  <p class="font-medium">No existing contacts</p>
-                  <p class="text-xs mt-1">Create a new contact to get started</p>
+                  <p class="font-medium">No existing people</p>
+                  <p class="text-xs mt-1">Create a new person to get started</p>
                 </div>
               </div>
             </div>
           </div>
 
-          <!-- Create/Edit Contact Section -->
+          <!-- Create/Edit Person Section -->
           <div
             class="create-contact-section w-full xl:w-80 2xl:w-96 flex-shrink-0 border-t xl:border-t-0 xl:border-l border-gray-200 pt-4 xl:pt-0 xl:pl-6"
           >
             <div class="flex items-center justify-between mb-4">
               <h4 class="section-title text-sm font-semibold text-gray-900">
-                {{ isEditing ? 'Edit Contact' : 'Create New Contact' }}
+                {{ isEditing ? 'Edit Person' : 'Create New Person' }}
               </h4>
               <button
                 v-if="isEditing"
@@ -215,18 +215,18 @@
                   Name <span class="text-red-500">*</span>
                 </label>
                 <input
-                  v-model="localContactForm.name"
+                  v-model="localPersonForm.name"
                   type="text"
-                  data-automation-id="ContactSelectionModal-name-input"
+                  data-automation-id="PersonSelectionModal-name-input"
                   class="w-full px-3 py-2 text-sm border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-colors"
-                  placeholder="Contact name"
+                  placeholder="Person name"
                 />
               </div>
 
               <div>
                 <label class="block text-xs font-medium text-gray-700 mb-1">Position</label>
                 <input
-                  v-model="localContactForm.position"
+                  v-model="localPersonForm.position"
                   type="text"
                   class="w-full px-3 py-2 text-sm border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-colors"
                   placeholder="Job title/position"
@@ -236,9 +236,9 @@
               <div>
                 <label class="block text-xs font-medium text-gray-700 mb-1">Phone</label>
                 <input
-                  v-model="localContactForm.phone"
+                  v-model="localPersonForm.phone"
                   type="tel"
-                  data-automation-id="ContactSelectionModal-phone-input"
+                  data-automation-id="PersonSelectionModal-phone-input"
                   class="w-full px-3 py-2 text-sm border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-colors"
                   placeholder="Phone number"
                 />
@@ -247,9 +247,9 @@
               <div>
                 <label class="block text-xs font-medium text-gray-700 mb-1">Email</label>
                 <input
-                  v-model="localContactForm.email"
+                  v-model="localPersonForm.email"
                   type="email"
-                  data-automation-id="ContactSelectionModal-email-input"
+                  data-automation-id="PersonSelectionModal-email-input"
                   class="w-full px-3 py-2 text-sm border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-colors"
                   placeholder="Email address"
                 />
@@ -258,7 +258,7 @@
               <div>
                 <label class="block text-xs font-medium text-gray-700 mb-1">Notes</label>
                 <textarea
-                  v-model="localContactForm.notes"
+                  v-model="localPersonForm.notes"
                   rows="2"
                   class="w-full px-3 py-2 text-sm border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500 focus:border-transparent transition-colors resize-none"
                   placeholder="Additional notes"
@@ -268,15 +268,15 @@
               <div>
                 <label class="flex items-center">
                   <input
-                    v-model="localContactForm.is_primary"
+                    v-model="localPersonForm.is_primary"
                     type="checkbox"
                     class="rounded border-gray-300 text-blue-600 focus:ring-blue-500"
-                    :disabled="contacts.length === 0"
+                    :disabled="people.length === 0"
                   />
-                  <span class="ml-2 text-xs text-gray-700">Set as primary contact</span>
+                  <span class="ml-2 text-xs text-gray-700">Set as primary person</span>
                 </label>
-                <p v-if="contacts.length === 0" class="mt-1 text-xs text-green-600 font-medium">
-                  ✓ Automatically set for first contact
+                <p v-if="people.length === 0" class="mt-1 text-xs text-green-600 font-medium">
+                  ✓ Automatically set for first person
                 </p>
               </div>
 
@@ -295,12 +295,12 @@
           </button>
           <button
             type="button"
-            data-automation-id="ContactSelectionModal-submit"
+            data-automation-id="PersonSelectionModal-submit"
             class="ml-3 px-4 py-2 text-sm font-medium text-white bg-blue-600 border border-transparent rounded-md hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
             @click="handleSave"
-            :disabled="isLoading || !localContactForm.name.trim()"
+            :disabled="isLoading || !localPersonForm.name.trim()"
           >
-            {{ isLoading ? 'Saving...' : isEditing ? 'Update Contact' : 'Create Contact' }}
+            {{ isLoading ? 'Saving...' : isEditing ? 'Update Person' : 'Create Person' }}
           </button>
         </DialogFooter>
       </div>
@@ -313,7 +313,7 @@ import { ref, watch, reactive } from 'vue'
 import { Users, PencilLine, Trash2, AlertTriangle } from 'lucide-vue-next'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
-import type { ContactFormData } from '@/composables/useContactManagement'
+import type { PersonFormData } from '@/composables/usePersonManagement'
 import {
   Dialog,
   DialogContent,
@@ -324,49 +324,49 @@ import {
 } from '../components/ui/dialog'
 
 // Type aliases for schema-based types
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 
 const props = defineProps<{
   isOpen: boolean
   companyId: string
   companyName: string
-  contacts: ClientContact[]
-  selectedContact: ClientContact | null
+  people: CompanyPersonLink[]
+  selectedPerson: CompanyPersonLink | null
   isLoading: boolean
-  newContactForm: ContactFormData
-  editingContact: ClientContact | null
+  personForm: PersonFormData
+  editingPersonLink: CompanyPersonLink | null
   isEditing: boolean
 }>()
 const emit = defineEmits<{
   close: []
-  'select-contact': [contact: ClientContact]
-  'save-contact': [newContact: ContactFormData]
-  'edit-contact': [contact: ClientContact]
-  'delete-contact': [contactId: string]
+  'select-person': [person: CompanyPersonLink]
+  'save-person': [newPerson: PersonFormData]
+  'edit-person': [person: CompanyPersonLink]
+  'delete-person': [personLinkId: string]
   'cancel-edit': []
 }>()
 
 const nameError = ref('')
 
-type ContactForm = ContactFormData
-const localContactForm = reactive<ContactForm>({ ...props.newContactForm })
+type PersonForm = PersonFormData
+const localPersonForm = reactive<PersonForm>({ ...props.personForm })
 
 watch(
-  () => props.newContactForm,
+  () => props.personForm,
   (val) => {
-    Object.assign(localContactForm, val)
+    Object.assign(localPersonForm, val)
   },
   { deep: true, immediate: true },
 )
 
-// Watch for changes in contacts length to auto-set primary for first contact
+// Watch for changes in people length to auto-set primary for first person
 watch(
-  () => props.contacts.length,
-  (contactsLength) => {
-    console.log('[CONTACTS] Modal received:', contactsLength, 'contacts')
-    if (contactsLength === 0) {
-      // Automatically set as primary if this is the first contact
-      localContactForm.is_primary = true
+  () => props.people.length,
+  (peopleLength) => {
+    console.log('[PEOPLE] Modal received:', peopleLength, 'people')
+    if (peopleLength === 0) {
+      // Automatically set as primary if this is the first person
+      localPersonForm.is_primary = true
     }
   },
   { immediate: true },
@@ -374,12 +374,12 @@ watch(
 
 // Sync changes back to parent
 watch(
-  localContactForm,
+  localPersonForm,
   (val) => {
     // Update the parent's form data
     Object.keys(val).forEach((key) => {
-      if (key in props.newContactForm) {
-        ;(props.newContactForm as Record<string, unknown>)[key] = val[key as keyof typeof val]
+      if (key in props.personForm) {
+        ;(props.personForm as Record<string, unknown>)[key] = val[key as keyof typeof val]
       }
     })
   },
@@ -387,35 +387,35 @@ watch(
 )
 
 const handleSave = () => {
-  if (!localContactForm.name?.trim()) {
+  if (!localPersonForm.name?.trim()) {
     nameError.value = 'Name is required.'
     return
   }
   nameError.value = ''
-  emit('save-contact', { ...localContactForm })
+  emit('save-person', { ...localPersonForm })
 }
 
-const selectContact = (contact: ClientContact) => {
-  emit('select-contact', contact)
+const selectPerson = (person: CompanyPersonLink) => {
+  emit('select-person', person)
 }
 
 // Delete confirmation state
-const contactToDelete = ref<ClientContact | null>(null)
+const personToDelete = ref<CompanyPersonLink | null>(null)
 const showDeleteConfirm = ref(false)
 
-const confirmDeleteContact = (contact: ClientContact) => {
-  contactToDelete.value = contact
+const confirmDeletePerson = (person: CompanyPersonLink) => {
+  personToDelete.value = person
   showDeleteConfirm.value = true
 }
 
 const cancelDelete = () => {
-  contactToDelete.value = null
+  personToDelete.value = null
   showDeleteConfirm.value = false
 }
 
 const executeDelete = () => {
-  if (contactToDelete.value?.id) {
-    emit('delete-contact', contactToDelete.value.id)
+  if (personToDelete.value?.id) {
+    emit('delete-person', personToDelete.value.id)
   }
   cancelDelete()
 }
@@ -457,7 +457,7 @@ const executeDelete = () => {
     gap: 1rem;
   }
 
-  .contacts-section {
+  .people-section {
     min-height: 250px;
   }
 
@@ -482,7 +482,7 @@ const executeDelete = () => {
     gap: 1.5rem;
   }
 
-  .contacts-section {
+  .people-section {
     flex: 2;
     min-height: 400px;
   }
@@ -509,7 +509,7 @@ const executeDelete = () => {
     gap: 2rem;
   }
 
-  .contacts-section {
+  .people-section {
     flex: 2;
     min-height: 450px;
   }
@@ -536,7 +536,7 @@ const executeDelete = () => {
     gap: 2rem;
   }
 
-  .contacts-section {
+  .people-section {
     flex: 2;
     min-width: 0;
     min-height: 500px;
@@ -563,15 +563,15 @@ const executeDelete = () => {
   }
 }
 
-/* ===== CONTACTS GRID RESPONSIVE LAYOUT ===== */
-.contacts-grid {
+/* ===== PEOPLE GRID RESPONSIVE LAYOUT ===== */
+.people-grid {
   /* Base: 1 column for mobile */
   grid-template-columns: 1fr;
   gap: 0.75rem;
 }
 
 @media (min-width: 640px) {
-  .contacts-grid {
+  .people-grid {
     /* 2 columns for small screens */
     grid-template-columns: repeat(2, 1fr);
     gap: 1rem;
@@ -579,7 +579,7 @@ const executeDelete = () => {
 }
 
 @media (min-width: 768px) {
-  .contacts-grid {
+  .people-grid {
     /* 3 columns for tablets and up - optimal balance */
     grid-template-columns: repeat(3, 1fr);
     gap: 1rem;
@@ -587,7 +587,7 @@ const executeDelete = () => {
 }
 
 @media (min-width: 1024px) {
-  .contacts-grid {
+  .people-grid {
     /* Keep 3 columns for better card width and readability */
     grid-template-columns: repeat(3, 1fr);
     gap: 1.25rem;
@@ -595,7 +595,7 @@ const executeDelete = () => {
 }
 
 @media (min-width: 1280px) {
-  .contacts-grid {
+  .people-grid {
     /* 3 columns with more spacing for wider modal */
     grid-template-columns: repeat(3, 1fr);
     gap: 0.5rem;
@@ -603,7 +603,7 @@ const executeDelete = () => {
 }
 
 @media (min-width: 1536px) {
-  .contacts-grid {
+  .people-grid {
     /* Keep 3 columns even on very wide screens for optimal readability */
     grid-template-columns: repeat(3, 1fr);
     gap: 1.5rem;
@@ -611,8 +611,8 @@ const executeDelete = () => {
 }
 
 /* ===== SECTION STYLING ===== */
-.contacts-section {
-  /* Ensure minimum space for contacts */
+.people-section {
+  /* Ensure minimum space for people */
   min-height: 200px;
 }
 
@@ -757,7 +757,7 @@ const executeDelete = () => {
     transform: none;
   }
 
-  .contacts-grid {
+  .people-grid {
     grid-template-columns: 1fr;
     gap: 0.5rem;
   }
@@ -769,7 +769,7 @@ const executeDelete = () => {
     max-height: 95vh;
   }
 
-  .contacts-section {
+  .people-section {
     min-height: 200px;
   }
 }
@@ -780,7 +780,7 @@ const executeDelete = () => {
     width: min(85vw, 1600px);
   }
 
-  .contacts-grid {
+  .people-grid {
     grid-template-columns: repeat(7, 1fr);
   }
 }
diff --git a/frontend/src/components/ContactSelector.vue b/frontend/src/components/PersonSelector.vue
similarity index 50%
rename from frontend/src/components/ContactSelector.vue
rename to frontend/src/components/PersonSelector.vue
index 0fcbf5877..34d433454 100644
--- a/frontend/src/components/ContactSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -14,7 +14,7 @@
           type="text"
           :placeholder="placeholder"
           readonly
-          data-automation-id="ContactSelector-display"
+          data-automation-id="PersonSelector-display"
           class="w-full px-3 py-2 border border-gray-300 rounded-md bg-gray-50 cursor-pointer focus:ring-2 focus:ring-blue-500 focus:border-transparent"
           @click="handleOpenModal"
         />
@@ -22,7 +22,7 @@
 
       <button
         type="button"
-        data-automation-id="ContactSelector-modal-button"
+        data-automation-id="PersonSelector-modal-button"
         class="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 transition-colors"
         @click="handleOpenModal"
         :disabled="!companyId"
@@ -31,9 +31,9 @@
       </button>
 
       <button
-        v-if="selectedContact"
+        v-if="selectedPerson"
         type="button"
-        data-automation-id="ContactSelector-clear-button"
+        data-automation-id="PersonSelector-clear-button"
         class="px-2 py-2 text-gray-400 hover:text-red-600 transition-colors"
         @click="clearSelection"
         title="Clear selection"
@@ -45,21 +45,21 @@
     <p v-if="!companyId" class="mt-1 text-xs text-gray-500">Please select a company first</p>
   </div>
 
-  <ContactSelectionModal
+  <PersonSelectionModal
     :is-open="isModalOpen"
     :company-id="companyId"
     :company-name="companyName"
-    :contacts="activeContacts"
-    :selected-contact="selectedContact"
+    :people="activePersonLinks"
+    :selected-person="selectedPerson"
     :is-loading="isLoading"
-    :new-contact-form="newContactForm"
-    :editing-contact="editingContact"
+    :person-form="personForm"
+    :editing-person-link="editingPersonLink"
     :is-editing="isEditing"
     @close="closeModal"
-    @select-contact="selectExistingContact"
-    @save-contact="handleSaveContact"
-    @edit-contact="handleEditContact"
-    @delete-contact="handleDeleteContact"
+    @select-person="selectExistingPerson"
+    @save-person="handleSavePerson"
+    @edit-person="handleEditPerson"
+    @delete-person="handleDeletePerson"
     @cancel-edit="cancelEdit"
   />
 </template>
@@ -70,12 +70,12 @@ import { toast } from 'vue-sonner'
 
 import { ref, watch } from 'vue'
 import { Users, X } from 'lucide-vue-next'
-import { useContactManagement } from '../composables/useContactManagement'
-import ContactSelectionModal from './ContactSelectionModal.vue'
+import { usePersonManagement } from '../composables/usePersonManagement'
+import PersonSelectionModal from './PersonSelectionModal.vue'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
 
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 
 const props = withDefaults(
   defineProps<{
@@ -86,88 +86,88 @@ const props = withDefaults(
     companyId: string
     companyName: string
     modelValue?: string
-    initialContactId?: string
+    initialPersonId?: string
   }>(),
   {
-    placeholder: 'No contact selected',
+    placeholder: 'No person selected',
     optional: true,
     modelValue: '',
-    initialContactId: '',
+    initialPersonId: '',
   },
 )
 
 const emit = defineEmits<{
   'update:modelValue': [value: string]
-  'update:selectedContact': [contact: ClientContact | null]
+  'update:selectedPerson': [person: CompanyPersonLink | null]
 }>()
 
 const {
   isModalOpen,
-  contacts,
-  selectedContact,
+  people,
+  selectedPerson,
   isLoading,
-  newContactForm,
+  personForm,
   displayValue,
   openModal,
   closeModal,
-  loadContactsOnly,
-  setSelectedContact,
-  selectExistingContact: selectFromComposable,
-  saveContact,
+  loadPeopleOnly,
+  setSelectedPerson,
+  selectExistingPerson: selectFromComposable,
+  savePerson,
   clearSelection: clearFromComposable,
-  findPrimaryContact,
+  findPrimaryPerson,
   // Edit mode state and functions
-  editingContact,
+  editingPersonLink,
   isEditing,
-  activeContacts,
-  startEditContact,
+  activePersonLinks,
+  startEditPerson,
   cancelEdit,
-  updateContact,
-  deleteContact,
-} = useContactManagement()
+  updatePerson,
+  deletePerson,
+} = usePersonManagement()
 
 const suppressEmit = ref(false)
 const isHydrating = ref(true)
 let loadToken = 0
 
 const handleOpenModal = async () => {
-  debugLog('ContactSelector - handleOpenModal called:', {
+  debugLog('PersonSelector - handleOpenModal called:', {
     companyId: props.companyId,
     companyName: props.companyName,
-    initialContactId: props.initialContactId,
-    contacts: contacts.value,
-    selectedContact: selectedContact.value,
-    newContactForm: newContactForm.value,
+    initialPersonId: props.initialPersonId,
+    people: people.value,
+    selectedPerson: selectedPerson.value,
+    personForm: personForm.value,
   })
 
   if (!props.companyId) {
-    debugLog('Cannot open contact modal without company')
+    debugLog('Cannot open person modal without company')
     return
   }
 
   await openModal(props.companyId, props.companyName)
-  debugLog('ContactSelector - after openModal:', {
+  debugLog('PersonSelector - after openModal:', {
     isModalOpen: isModalOpen.value,
-    contacts: contacts.value,
-    selectedContact: selectedContact.value,
-    newContactForm: newContactForm.value,
+    people: people.value,
+    selectedPerson: selectedPerson.value,
+    personForm: personForm.value,
   })
 }
 
-const selectExistingContact = (contact: ClientContact) => {
-  debugLog('ContactSelector - selectExistingContact:', contact)
-  selectFromComposable(contact)
+const selectExistingPerson = (person: CompanyPersonLink) => {
+  debugLog('PersonSelector - selectExistingPerson:', person)
+  selectFromComposable(person)
 }
 
-const handleSaveContact = async () => {
-  debugLog('ContactSelector - handleSaveContact: before save', {
-    newContactForm: newContactForm.value,
-    selectedContact: selectedContact.value,
+const handleSavePerson = async () => {
+  debugLog('PersonSelector - handleSavePerson: before save', {
+    personForm: personForm.value,
+    selectedPerson: selectedPerson.value,
     isEditing: isEditing.value,
   })
 
   // Validate email format before saving
-  const rawEmail = newContactForm.value.email
+  const rawEmail = personForm.value.email
   const emailInput = typeof rawEmail === 'string' ? rawEmail.trim() : ''
   if (emailInput && !isValidEmail(emailInput)) {
     toast.error('Please enter a valid email address')
@@ -175,52 +175,52 @@ const handleSaveContact = async () => {
   }
 
   const actionLabel = isEditing.value ? 'Updating' : 'Creating'
-  toast.info(`${actionLabel} contact...`, { id: 'save-contact' })
+  toast.info(`${actionLabel} person...`, { id: 'save-person' })
 
   let success: boolean
   if (isEditing.value) {
-    success = await updateContact()
+    success = await updatePerson()
   } else {
-    success = await saveContact()
+    success = await savePerson()
   }
 
-  toast.dismiss('save-contact')
+  toast.dismiss('save-person')
 
-  debugLog('ContactSelector - handleSaveContact: after save', {
+  debugLog('PersonSelector - handleSavePerson: after save', {
     success,
-    newContactForm: newContactForm.value,
-    selectedContact: selectedContact.value,
+    personForm: personForm.value,
+    selectedPerson: selectedPerson.value,
   })
 
   if (success) {
-    toast.success(`Contact ${isEditing.value ? 'updated' : 'created'} successfully!`, {
+    toast.success(`Person ${isEditing.value ? 'updated' : 'created'} successfully!`, {
       dismissible: true,
       position: 'top-left',
     })
   } else {
     toast.error(
-      `Failed to ${isEditing.value ? 'update' : 'create'} contact. Please check the form and try again.`,
+      `Failed to ${isEditing.value ? 'update' : 'create'} person. Please check the form and try again.`,
     )
   }
 }
 
-const handleEditContact = (contact: ClientContact) => {
-  debugLog('ContactSelector - handleEditContact:', contact)
-  startEditContact(contact)
+const handleEditPerson = (person: CompanyPersonLink) => {
+  debugLog('PersonSelector - handleEditPerson:', person)
+  startEditPerson(person)
 }
 
-const handleDeleteContact = async (contactId: string) => {
-  debugLog('ContactSelector - handleDeleteContact:', contactId)
-  toast.info('Deleting contact...', { id: 'delete-contact' })
+const handleDeletePerson = async (contactId: string) => {
+  debugLog('PersonSelector - handleDeletePerson:', contactId)
+  toast.info('Deleting person...', { id: 'delete-person' })
 
-  const success = await deleteContact(contactId)
+  const success = await deletePerson(contactId)
 
-  toast.dismiss('delete-contact')
+  toast.dismiss('delete-person')
 
   if (success) {
-    toast.success('Contact removed successfully')
+    toast.success('Person removed successfully')
   } else {
-    toast.error('Failed to remove contact. Please try again.')
+    toast.error('Failed to remove person. Please try again.')
   }
 }
 
@@ -231,75 +231,75 @@ const isValidEmail = (email: string): boolean => {
 }
 
 const clearSelection = () => {
-  debugLog('ContactSelector - clearSelection')
+  debugLog('PersonSelector - clearSelection')
   clearFromComposable()
 }
 
-const selectPrimaryContact = async () => {
-  debugLog('ContactSelector - selectPrimaryContact called', {
+const selectPrimaryPerson = async () => {
+  debugLog('PersonSelector - selectPrimaryPerson called', {
     companyId: props.companyId,
-    contactsLength: contacts.value.length,
+    peopleLength: people.value.length,
   })
 
   if (!props.companyId) {
-    debugLog('Cannot select primary contact without company', {
+    debugLog('Cannot select primary person without company', {
       companyId: props.companyId,
       propsCompanyId: props.companyId,
     })
     return
   }
 
-  // Load contacts if not already loaded
-  if (contacts.value.length === 0) {
-    debugLog('Loading contacts for company:', props.companyId)
-    await loadContactsOnly(props.companyId)
+  // Load people if not already loaded
+  if (people.value.length === 0) {
+    debugLog('Loading people for company:', props.companyId)
+    await loadPeopleOnly(props.companyId)
   }
 
-  // Find and select the primary contact (without closing modal)
-  const primaryContact = findPrimaryContact()
-  debugLog('selectPrimaryContact:', {
-    contactsLength: contacts.value.length,
-    primaryContact,
-    currentSelectedContact: selectedContact.value,
-    sameReference: primaryContact === selectedContact.value,
+  // Find and select the primary person (without closing modal)
+  const primaryPerson = findPrimaryPerson()
+  debugLog('selectPrimaryPerson:', {
+    peopleLength: people.value.length,
+    primaryPerson,
+    currentSelectedPerson: selectedPerson.value,
+    sameReference: primaryPerson === selectedPerson.value,
   })
-  if (primaryContact) {
-    debugLog('Found primary contact:', primaryContact)
-    setSelectedContact(primaryContact)
+  if (primaryPerson) {
+    debugLog('Found primary person:', primaryPerson)
+    setSelectedPerson(primaryPerson)
     // Explicitly emit for JobCreateView - decideAndSelect uses suppressEmit but
-    // selectPrimaryContact is called by parent components that need the emit
+    // selectPrimaryPerson is called by parent components that need the emit
     emitUpdates()
   } else {
-    debugLog('No primary contact found', {
-      totalContacts: contacts.value.length,
-      contacts: contacts.value,
+    debugLog('No primary person found', {
+      totalPeople: people.value.length,
+      people: people.value,
     })
     clearFromComposable()
-    // Also emit for clearing case so parent knows contact was cleared
+    // Also emit for clearing case so parent knows person was cleared
     emitUpdates()
   }
 }
 
 // Expose the method for parent components
 defineExpose({
-  selectPrimaryContact,
+  selectPrimaryPerson,
   clearSelection,
 })
 
 const emitUpdates = () => {
   if (suppressEmit.value) return
-  debugLog('ContactSelector - emitUpdates', {
+  debugLog('PersonSelector - emitUpdates', {
     displayValue: displayValue.get(),
-    selectedContact: selectedContact.value,
+    selectedPerson: selectedPerson.value,
   })
   emit('update:modelValue', displayValue.get())
-  emit('update:selectedContact', selectedContact.value)
+  emit('update:selectedPerson', selectedPerson.value)
 }
 
 watch(
-  selectedContact,
+  selectedPerson,
   () => {
-    debugLog('ContactSelector - selectedContact changed:', selectedContact.value)
+    debugLog('PersonSelector - selectedPerson changed:', selectedPerson.value)
     emitUpdates()
     isHydrating.value = false
   },
@@ -307,15 +307,15 @@ watch(
 )
 
 watch(
-  () => [props.companyId, props.initialContactId],
+  () => [props.companyId, props.initialPersonId],
   async ([companyId, initialId]) => {
-    debugLog('ContactSelector - unified watch:', { companyId, initialId })
+    debugLog('PersonSelector - unified watch:', { companyId, initialId })
 
     // Quando mudar o cliente: limpe estado local (sem emitir)
     suppressEmit.value = true
     displayValue.set('')
-    selectedContact.value = null
-    contacts.value = []
+    selectedPerson.value = null
+    people.value = []
     suppressEmit.value = false
 
     if (!companyId) {
@@ -327,25 +327,25 @@ watch(
     const token = ++loadToken
 
     // Carrega contatos do cliente atual
-    await loadContactsOnly(companyId)
+    await loadPeopleOnly(companyId)
     if (token !== loadToken) return // request antigo, ignora
 
     // Selection priority:
-    // 1) If initialId provided → select that contact
-    // 2) Else if primary contact exists → select primary
+    // 1) If initialId provided → select that person
+    // 2) Else if primary person exists → select primary
     // 3) Else → clear selection
     // NOTE: suppressEmit=true prevents API calls during initialization/company change
     // (auto-selection should not trigger saves - only user actions should)
     const decideAndSelect = () => {
       const choose =
-        (initialId && contacts.value.find((c: ClientContact) => c.id === initialId)) ||
-        (!initialId && findPrimaryContact()) ||
+        (initialId && people.value.find((c: CompanyPersonLink) => c.person === initialId)) ||
+        (!initialId && findPrimaryPerson()) ||
         null
 
       suppressEmit.value = true
       if (choose) {
-        // Use setSelectedContact to avoid closing modal during auto-selection
-        setSelectedContact(choose)
+        // Use setSelectedPerson to avoid closing modal during auto-selection
+        setSelectedPerson(choose)
       } else {
         clearFromComposable()
       }
diff --git a/frontend/src/components/__tests__/CompanyLookup.test.ts b/frontend/src/components/__tests__/CompanyLookup.test.ts
index e6c420483..42fe857cb 100644
--- a/frontend/src/components/__tests__/CompanyLookup.test.ts
+++ b/frontend/src/components/__tests__/CompanyLookup.test.ts
@@ -29,7 +29,7 @@ function buildComposableStub(suggestions: Company[]) {
     displayValue: ref(''),
     searchCompanies: vi.fn(),
     selectCompany: vi.fn(),
-    loadClientContacts: vi.fn(),
+    loadCompanyPersonLinks: vi.fn(),
     getPrimaryContact: vi.fn(),
     clearSelection: vi.fn(),
     handleInputChange: vi.fn(),
diff --git a/frontend/src/components/board/ActiveJobCard.vue b/frontend/src/components/board/ActiveJobCard.vue
index eeec99276..a188298fe 100644
--- a/frontend/src/components/board/ActiveJobCard.vue
+++ b/frontend/src/components/board/ActiveJobCard.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { Button } from '@/components/ui/button'
-import { RefreshCw, ExternalLink, Briefcase, NotebookText, Contact } from 'lucide-vue-next'
+import { RefreshCw, ExternalLink, Briefcase, NotebookText, UserRound } from 'lucide-vue-next'
 import StaffAvatar from '@/components/StaffAvatar.vue'
 import { schemas } from '@/api/generated/api'
 import type { z } from 'zod'
@@ -69,12 +69,12 @@ const getJobDescription = (job: WorkshopJob) => {
         </div>
 
         <div
-          v-if="job.contact_person"
+          v-if="job.person_name"
           class="text-xl text-black font-semibold flex items-center gap-2"
         >
-          <Contact class="h-5 w-5 text-gray-500 flex-shrink-0" />
-          <span>Contact:</span>
-          <span class="text-gray-600 font-medium">{{ job.contact_person }}</span>
+          <UserRound class="h-5 w-5 text-gray-500 flex-shrink-0" />
+          <span>Person:</span>
+          <span class="text-gray-600 font-medium">{{ job.person_name }}</span>
         </div>
       </div>
 
diff --git a/frontend/src/components/crm/PhoneCallTable.vue b/frontend/src/components/crm/PhoneCallTable.vue
index 79aed3462..c338a327f 100644
--- a/frontend/src/components/crm/PhoneCallTable.vue
+++ b/frontend/src/components/crm/PhoneCallTable.vue
@@ -25,7 +25,7 @@
               {{ call.company_name || call.external_number || '-' }}
             </div>
             <div class="flex flex-wrap items-center gap-2 text-xs text-gray-500">
-              <span>{{ call.contact_name || call.external_number || '-' }}</span>
+              <span>{{ call.person_name || call.external_number || '-' }}</span>
               <Button
                 v-if="allowNumberAssignment && !call.company && call.external_number"
                 variant="ghost"
diff --git a/frontend/src/components/crm/PhoneNumberManager.vue b/frontend/src/components/crm/PhoneNumberManager.vue
index a17cad3e1..b3d40c393 100644
--- a/frontend/src/components/crm/PhoneNumberManager.vue
+++ b/frontend/src/components/crm/PhoneNumberManager.vue
@@ -54,13 +54,13 @@
           </option>
         </select>
         <select
-          v-model="selectedContactId"
+          v-model="selectedPersonId"
           class="rounded-md border border-gray-300 p-2 text-sm"
           :disabled="!selectedCompanyId"
         >
-          <option value="">No specific contact</option>
-          <option v-for="contact in contactOptions" :key="contact.id" :value="contact.id">
-            {{ contact.name }}
+          <option value="">No specific person</option>
+          <option v-for="contact in contactOptions" :key="contact.id" :value="contact.person">
+            {{ contact.person_name }}
           </option>
         </select>
       </div>
@@ -71,7 +71,7 @@
             <tr>
               <th class="p-3 text-left font-semibold text-gray-700">Phone Number</th>
               <th class="p-3 text-left font-semibold text-gray-700">Company</th>
-              <th class="p-3 text-left font-semibold text-gray-700">Contact</th>
+              <th class="p-3 text-left font-semibold text-gray-700">Person</th>
               <th class="p-3 text-left font-semibold text-gray-700">Label</th>
               <th class="p-3 text-left font-semibold text-gray-700">Primary</th>
               <th class="p-3 text-right font-semibold text-gray-700">Actions</th>
@@ -84,7 +84,7 @@
             <tr v-for="method in phoneMethods" :key="method.id" class="border-b last:border-b-0">
               <td class="p-3 font-medium text-gray-900">{{ method.value }}</td>
               <td class="p-3 text-gray-700">{{ method.company_name }}</td>
-              <td class="p-3 text-gray-700">{{ method.contact_name || '-' }}</td>
+              <td class="p-3 text-gray-700">{{ method.person_name || '-' }}</td>
               <td class="p-3 text-gray-700">{{ method.label || '-' }}</td>
               <td class="p-3 text-gray-700">{{ method.is_primary ? 'Yes' : '-' }}</td>
               <td class="p-3">
@@ -123,9 +123,9 @@ import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
 import type { z } from 'zod'
 
-type ClientContactMethod = z.infer<typeof schemas.ClientContactMethod>
-type ClientContactMethodRequest = z.infer<typeof schemas.ClientContactMethodRequest>
-type PatchedClientContactMethodRequest = z.infer<typeof schemas.PatchedClientContactMethodRequest>
+type ContactMethod = z.infer<typeof schemas.ContactMethod>
+type ContactMethodRequest = z.infer<typeof schemas.ContactMethodRequest>
+type PatchedContactMethodRequest = z.infer<typeof schemas.PatchedContactMethodRequest>
 
 const props = withDefaults(
   defineProps<{
@@ -148,7 +148,7 @@ const emit = defineEmits<{
   changed: []
 }>()
 
-const phoneMethods = ref<ClientContactMethod[]>([])
+const phoneMethods = ref<ContactMethod[]>([])
 const phoneMethodCount = ref(0)
 const editingMethodId = ref('')
 const isSaving = ref(false)
@@ -156,14 +156,14 @@ const phoneNumber = ref(props.initialPhoneNumber)
 const phoneLabel = ref('')
 const isPrimary = ref(false)
 const selectedCompanyId = ref(props.fixedCompanyId)
-const selectedContactId = ref('')
+const selectedPersonId = ref('')
 
 const {
   searchQuery: companySearch,
   suggestions: companyOptions,
   contacts: contactOptions,
   browseCompanies,
-  loadClientContacts: loadContacts,
+  loadCompanyPersonLinks: loadContacts,
   logSelectedCompanyClick,
 } = useCompanyLookup()
 
@@ -185,11 +185,11 @@ function logSelectedCompanySearchClick(): void {
   logSelectedCompanyClick(selectedCompanyId.value, props.searchContext)
 }
 
-function phoneMethodBody(): ClientContactMethodRequest {
-  if (selectedContactId.value) {
+function phoneMethodBody(): ContactMethodRequest {
+  if (selectedPersonId.value) {
     return {
       company: null,
-      contact: selectedContactId.value,
+      person: selectedPersonId.value,
       method_type: 'phone',
       value: phoneNumber.value,
       label: phoneLabel.value,
@@ -199,7 +199,7 @@ function phoneMethodBody(): ClientContactMethodRequest {
   }
   return {
     company: selectedCompanyId.value,
-    contact: null,
+    person: null,
     method_type: 'phone',
     value: phoneNumber.value,
     label: phoneLabel.value,
@@ -213,7 +213,7 @@ async function savePhoneMethod(): Promise<void> {
   isSaving.value = true
   try {
     if (editingMethodId.value) {
-      const body: PatchedClientContactMethodRequest = phoneMethodBody()
+      const body: PatchedContactMethodRequest = phoneMethodBody()
       await api.companies_contact_methods_partial_update(body, {
         params: { id: editingMethodId.value },
       })
@@ -234,17 +234,17 @@ async function savePhoneMethod(): Promise<void> {
   }
 }
 
-async function editMethod(method: ClientContactMethod): Promise<void> {
+async function editMethod(method: ContactMethod): Promise<void> {
   editingMethodId.value = method.id
   phoneNumber.value = method.value
   phoneLabel.value = method.label || ''
   isPrimary.value = Boolean(method.is_primary)
   selectedCompanyId.value = method.owner_company
-  selectedContactId.value = method.contact || ''
+  selectedPersonId.value = method.person || ''
   await loadContacts(method.owner_company)
 }
 
-async function deleteMethod(method: ClientContactMethod): Promise<void> {
+async function deleteMethod(method: ContactMethod): Promise<void> {
   if (!window.confirm(`Remove phone number ${method.value}?`)) return
   try {
     await api.companies_contact_methods_destroy(undefined, { params: { id: method.id } })
@@ -265,7 +265,7 @@ function resetForm(): void {
   phoneLabel.value = ''
   isPrimary.value = false
   selectedCompanyId.value = props.fixedCompanyId
-  selectedContactId.value = ''
+  selectedPersonId.value = ''
   if (!props.fixedCompanyId) {
     companySearch.value = ''
     companyOptions.value = []
@@ -293,7 +293,7 @@ watch(
 
 watch(selectedCompanyId, (companyId) => {
   if (!companyId) {
-    selectedContactId.value = ''
+    selectedPersonId.value = ''
   }
   void loadContacts(companyId)
 })
diff --git a/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts b/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
index 00b476c81..1b12da6d3 100644
--- a/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
+++ b/frontend/src/components/crm/__tests__/PhoneCallTable.recording.test.ts
@@ -24,7 +24,7 @@ function callWithRecording() {
     call_datetime: '2026-06-02T03:13:01Z',
     company: null,
     company_name: '',
-    contact_name: '',
+    person_name: '',
     external_number: '+64272255846',
     our_number: '+6496365131',
     direction: 'outbound',
diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index 960df8784..85ace8b0c 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -78,7 +78,7 @@
         <Card class="lg:col-span-1">
           <CardHeader>
             <CardTitle>Company Information</CardTitle>
-            <CardDescription>Company details and contact information</CardDescription>
+            <CardDescription>Company details and person information</CardDescription>
           </CardHeader>
           <CardContent class="space-y-4">
             <div>
@@ -158,17 +158,17 @@
             </div>
 
             <div>
-              <ContactSelector
+              <PersonSelector
                 id="contact"
-                label="Contact Person"
+                label="Person"
                 :optional="true"
                 :company-id="localJobData.company_id || ''"
                 :company-name="localJobData.company_name || ''"
-                :initial-contact-id="
-                  typeof localJobData.contact_id === 'string' ? localJobData.contact_id : undefined
+                :initial-person-id="
+                  typeof localJobData.person_id === 'string' ? localJobData.person_id : undefined
                 "
-                v-model="contactDisplayValue"
-                @update:selected-contact="handleContactSelected"
+                v-model="personDisplayValue"
+                @update:selected-person="handlePersonSelected"
               />
             </div>
 
@@ -373,7 +373,7 @@ import { useJobsStore } from '../../stores/jobs'
 import { createJobAutosave } from '../../composables/useJobAutosave'
 import RichTextEditor from '../RichTextEditor.vue'
 import CompanyLookup from '../CompanyLookup.vue'
-import ContactSelector from '../ContactSelector.vue'
+import PersonSelector from '../PersonSelector.vue'
 import CreateCompanyModal from '../CreateCompanyModal.vue'
 import type { Company } from '../../composables/useCompanyLookup'
 import { debugLog } from '../../utils/debug'
@@ -384,7 +384,7 @@ import { onConcurrencyRetry } from '@/composables/useConcurrencyEvents'
 import { useSaveFeedback } from '@/composables/useSaveFeedback'
 import { requiredNumber } from '@/utils/requiredNumber'
 
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 
 // Use the existing JobHeaderResponse schema from generated API
 type Job = z.infer<typeof schemas.JobHeaderResponse>
@@ -571,7 +571,7 @@ const newCompanyId = ref('')
 const newCompanyName = ref('')
 const selectedNewCompany = ref<Company | null>(null)
 
-const contactDisplayValue = ref('')
+const personDisplayValue = ref('')
 const showEditCompanyModal = ref(false)
 
 const jobStatusChoices = ref<{ value: string; label: string }[]>([])
@@ -770,8 +770,8 @@ watch(
         name: '',
         company_id: null,
         company_name: null,
-        contact_id: undefined,
-        contact_name: undefined,
+        person_id: undefined,
+        person_name: undefined,
         status: '' as Job['status'],
         pricing_methodology: (props.pricingMethodology ||
           'time_materials') as Job['pricing_methodology'],
@@ -795,7 +795,7 @@ watch(
 
       localJobData.value = { ...defaultJobData }
       serverBaseline.value = { ...defaultJobData }
-      contactDisplayValue.value = ''
+      personDisplayValue.value = ''
       return
     }
     // Received valid jobData, initializing
@@ -832,7 +832,7 @@ watch(
       notes: localJobData.value?.notes ?? '',
     }
 
-    // Keep original snapshot with current state (including separated company/contact fields for delta)
+    // Keep original snapshot with current state (including separated company/person fields for delta)
     serverBaseline.value = {
       ...localJobData.value,
       description: normalizeNullable(localJobData.value.description),
@@ -841,34 +841,34 @@ watch(
       notes: normalizeNullable(localJobData.value.notes),
       price_cap: localJobData.value.price_cap ?? null,
       default_xero_pay_item_id: localJobData.value.default_xero_pay_item_id ?? null,
-      contact_id: localJobData.value.contact_id ?? null,
-      contact_name: localJobData.value.contact_name ?? null,
+      person_id: localJobData.value.person_id ?? null,
+      person_name: localJobData.value.person_name ?? null,
     }
 
-    // Load contact information using the job contacts endpoint
+    // Load person information using the job person endpoint
     // IMPORTANT: Do NOT trigger autosave here - this is just loading initial data
     try {
-      const contactResponse = await api.companies_jobs_contact_retrieve({
+      const contactResponse = await api.companies_jobs_person_retrieve({
         params: { job_id: newJobData.job_id },
       })
       if (contactResponse) {
-        // The response is a single contact object
-        localJobData.value.contact_id = contactResponse.id
-        localJobData.value.contact_name = contactResponse.name
-        contactDisplayValue.value = contactResponse.name || ''
+        // The response is a single person object
+        localJobData.value.person_id = contactResponse.id
+        localJobData.value.person_name = contactResponse.name
+        personDisplayValue.value = contactResponse.name || ''
       }
     } catch (error: unknown) {
       // Handle 404 when no contact is associated with the job - simply ignore
       const axiosError = error as { response?: { status?: number } }
       if (axiosError?.response?.status === 404) {
-        debugLog('No contact associated with this job - ignoring 404')
-        localJobData.value.contact_id = undefined
-        localJobData.value.contact_name = undefined
-        contactDisplayValue.value = ''
+        debugLog('No person associated with this job - ignoring 404')
+        localJobData.value.person_id = undefined
+        localJobData.value.person_name = undefined
+        personDisplayValue.value = ''
       } else {
-        console.error('Failed to load contact information:', error)
-        toast.error('Failed to load contact information')
-        contactDisplayValue.value = ''
+        console.error('Failed to load person information:', error)
+        toast.error('Failed to load person information')
+        personDisplayValue.value = ''
       }
     }
 
@@ -987,8 +987,8 @@ watch(
       if (basicInfo.notes !== undefined) {
         serverBaseline.value.notes = normalizeNullable(basicInfo.notes ?? null)
       }
-      serverBaseline.value.contact_id = localJobData.value.contact_id ?? null
-      serverBaseline.value.contact_name = localJobData.value.contact_name ?? null
+      serverBaseline.value.person_id = localJobData.value.person_id ?? null
+      serverBaseline.value.person_name = localJobData.value.person_name ?? null
 
       // Trigger reactivity
       localJobData.value = { ...localJobData.value }
@@ -1078,7 +1078,7 @@ const confirmCompanyChange = () => {
   localJobData.value.company_id = companyId
   localJobData.value.company_name = companyName
 
-  contactDisplayValue.value = ''
+  personDisplayValue.value = ''
 
   resetCompanyChangeState()
 
@@ -1139,51 +1139,45 @@ const handleCompanyUpdated = (updatedCompany: Company) => {
   toast.success('Company updated successfully')
 }
 
-const handleContactSelected = async (contact: ClientContact | null) => {
+const handlePersonSelected = async (contact: CompanyPersonLink | null) => {
   if (contact) {
-    // Skip API call if contact is already set to this value
+    // Skip API call if person is already set to this value
     // This handles:
-    // - Scenario 4: Company change - backend sets contact in response, no duplicate API call needed
+    // - Scenario 4: Company change - backend sets person in response, no duplicate API call needed
     // - User re-selecting the same contact
-    if (localJobData.value.contact_id === contact.id) {
+    if (localJobData.value.person_id === contact.person) {
       // Still update display value in case it's stale
-      localJobData.value.contact_name = contact.name
-      contactDisplayValue.value = contact.name
+      localJobData.value.person_name = contact.person_name
+      personDisplayValue.value = contact.person_name
       return
     }
 
-    localJobData.value.contact_id = contact.id
-    localJobData.value.contact_name = contact.name
-    contactDisplayValue.value = contact.name
+    localJobData.value.person_id = contact.person
+    localJobData.value.person_name = contact.person_name
+    personDisplayValue.value = contact.person_name
 
     // Ensure all fields are present for Zod validation (convert undefined to null)
     const contactToSend = {
-      id: contact.id,
-      name: contact.name,
-      email: contact.email ?? null,
-      position: contact.position ?? null,
-      notes: contact.notes ?? null,
-      is_primary: contact.is_primary ?? false,
-    } satisfies z.input<typeof schemas.JobContactUpdateRequest>
-
-    // Save contact directly (not through header autosave)
+      id: contact.person,
+      name: contact.person_name,
+      email: contact.person_email ?? null,
+    } satisfies z.input<typeof schemas.JobPersonUpdateRequest>
+
+    // Save person directly (not through header autosave)
     try {
-      await api.companies_jobs_contact_update(
-        contactToSend as z.input<typeof schemas.JobContactUpdateRequest>,
-        {
-          params: { job_id: props.jobId },
-        },
-      )
-      toast.success('Contact updated successfully')
+      await api.companies_jobs_person_update(contactToSend, {
+        params: { job_id: props.jobId },
+      })
+      toast.success('Person updated successfully')
     } catch (error) {
       toast.error('Failed to update contact')
       console.error('Failed to update contact:', error)
     }
   } else {
-    // Clear contact locally - no API call needed since clearing means no contact association
-    localJobData.value.contact_id = undefined
-    localJobData.value.contact_name = undefined
-    contactDisplayValue.value = ''
+    // Clear person locally - no API call needed since clearing means no contact association
+    localJobData.value.person_id = undefined
+    localJobData.value.person_name = undefined
+    personDisplayValue.value = ''
   }
 }
 
@@ -1210,8 +1204,8 @@ const autosave = createJobAutosave({
       job_number: data.job_number,
       name: data.name,
       company_id: data.company_id ?? null,
-      contact_id: data.contact_id,
-      contact_name: data.contact_name,
+      person_id: data.person_id,
+      person_name: data.person_name,
       job_status: data.status,
       pricing_methodology: data.pricing_methodology,
       speed_quality_tradeoff: data.speed_quality_tradeoff,
@@ -1231,13 +1225,13 @@ const autosave = createJobAutosave({
   },
   applyOptimistic: (patch) => {
     Object.entries(patch).forEach(([k, v]) => {
-      // Apply all fields including separated company/contact fields
+      // Apply all fields including separated company/person fields
       ;(localJobData.value as Record<string, unknown>)[k] = v as unknown
     })
   },
   rollbackOptimistic: (previous) => {
     Object.entries(previous).forEach(([k, v]) => {
-      // Rollback all fields including separated company/contact fields
+      // Rollback all fields including separated company/person fields
       ;(localJobData.value as Record<string, unknown>)[k] = v as unknown
     })
   },
@@ -1441,23 +1435,23 @@ const autosave = createJobAutosave({
           headerPatch.company_id = serverJobDetail.company_id ?? null
           headerPatch.company_name = serverJobDetail.company_name ?? null
 
-          // Backend auto-sets contact when company changes - update from response
-          // This prevents a redundant API call when ContactSelector emits
-          if (serverJobDetail.contact_id !== undefined) {
-            nextBaseline.contact_id = serverJobDetail.contact_id ?? null
-            nextBaseline.contact_name = serverJobDetail.contact_name ?? null
-            localJobData.value.contact_id = serverJobDetail.contact_id ?? null
-            localJobData.value.contact_name = serverJobDetail.contact_name ?? null
-            contactDisplayValue.value = serverJobDetail.contact_name ?? ''
+          // Backend auto-sets person when company changes - update from response
+          // This prevents a redundant API call when PersonSelector emits
+          if (serverJobDetail.person_id !== undefined) {
+            nextBaseline.person_id = serverJobDetail.person_id ?? null
+            nextBaseline.person_name = serverJobDetail.person_name ?? null
+            localJobData.value.person_id = serverJobDetail.person_id ?? null
+            localJobData.value.person_name = serverJobDetail.person_name ?? null
+            personDisplayValue.value = serverJobDetail.person_name ?? ''
           }
         }
-        if (touchedKeys.includes('contact_id')) {
-          nextBaseline.contact_id = serverJobDetail.contact_id ?? null
-          localJobData.value.contact_id = serverJobDetail.contact_id ?? null
+        if (touchedKeys.includes('person_id')) {
+          nextBaseline.person_id = serverJobDetail.person_id ?? null
+          localJobData.value.person_id = serverJobDetail.person_id ?? null
         }
-        if (touchedKeys.includes('contact_name')) {
-          nextBaseline.contact_name = serverJobDetail.contact_name ?? null
-          localJobData.value.contact_name = serverJobDetail.contact_name ?? null
+        if (touchedKeys.includes('person_name')) {
+          nextBaseline.person_name = serverJobDetail.person_name ?? null
+          localJobData.value.person_name = serverJobDetail.person_name ?? null
         }
       } else {
         if (touchedKeys.includes('description')) {
@@ -1568,18 +1562,18 @@ const autosave = createJobAutosave({
           headerPatch.company_name = companyName
 
           // Note: When no serverJobDetail, we can't get the auto-set contact
-          // The ContactSelector will re-fetch contacts for the new company
+          // The PersonSelector will re-fetch people for the new company
         }
-        if (touchedKeys.includes('contact_id')) {
-          const contactId = coerceNullableString(partialPayload.contact_id)
-          nextBaseline.contact_id = contactId
-          localJobData.value.contact_id = contactId
+        if (touchedKeys.includes('person_id')) {
+          const contactId = coerceNullableString(partialPayload.person_id)
+          nextBaseline.person_id = contactId
+          localJobData.value.person_id = contactId
         }
-        if (touchedKeys.includes('contact_name')) {
-          const contactName = coerceNullableString(partialPayload.contact_name)
-          nextBaseline.contact_name = contactName
-          localJobData.value.contact_name = contactName
-          contactDisplayValue.value = contactName ?? ''
+        if (touchedKeys.includes('person_name')) {
+          const contactName = coerceNullableString(partialPayload.person_name)
+          nextBaseline.person_name = contactName
+          localJobData.value.person_name = contactName
+          personDisplayValue.value = contactName ?? ''
         }
       }
 
@@ -1678,8 +1672,8 @@ onMounted(() => {
           delivery_date: normalizeNullable(localJobData.value.delivery_date),
           order_number: normalizeNullable(localJobData.value.order_number),
           notes: normalizeNullable(localJobData.value.notes),
-          contact_id: localJobData.value.contact_id ?? null,
-          contact_name: localJobData.value.contact_name ?? null,
+          person_id: localJobData.value.person_id ?? null,
+          person_name: localJobData.value.person_name ?? null,
         }
 
         // Reload basic info to ensure consistency
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
index 57610a6ca..a74b3529f 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
@@ -69,7 +69,7 @@ vi.mock('@/api/client', () => ({
       is_urgent: false,
     }),
     workflow_xero_pay_items_list: vi.fn().mockResolvedValue([]),
-    companies_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
+    companies_jobs_person_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
   },
 }))
 
@@ -153,7 +153,7 @@ const mountTab = () =>
         CardContent: passthrough,
         RichTextEditor: { template: '<div />' },
         CompanyLookup: { template: '<div />' },
-        ContactSelector: { template: '<div />' },
+        PersonSelector: { template: '<div />' },
         CreateCompanyModal: { template: '<div />' },
       },
     },
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
index fd254d611..da7b5e2aa 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
@@ -67,7 +67,7 @@ vi.mock('@/api/client', () => ({
       is_urgent: true,
     }),
     workflow_xero_pay_items_list: vi.fn().mockResolvedValue([]),
-    companies_jobs_contact_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
+    companies_jobs_person_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
   },
 }))
 
@@ -147,7 +147,7 @@ describe('JobSettingsTab urgent autosave', () => {
           CardContent: passthrough,
           RichTextEditor: { template: '<div />' },
           CompanyLookup: { template: '<div />' },
-          ContactSelector: { template: '<div />' },
+          PersonSelector: { template: '<div />' },
           CreateCompanyModal: { template: '<div />' },
         },
       },
diff --git a/frontend/src/components/workshop/WorkshopJobHeader.vue b/frontend/src/components/workshop/WorkshopJobHeader.vue
index 2b8db4edf..f962ef37e 100644
--- a/frontend/src/components/workshop/WorkshopJobHeader.vue
+++ b/frontend/src/components/workshop/WorkshopJobHeader.vue
@@ -81,8 +81,8 @@ const emit = defineEmits<{
                 </span>
                 <span class="inline-flex items-center gap-1">
                   <UserRound class="h-4 w-4" />
-                  <span class="font-medium text-foreground">Contact:</span>
-                  {{ job.contact_name || '-' }}
+                  <span class="font-medium text-foreground">Person:</span>
+                  {{ job.person_name || '-' }}
                 </span>
               </div>
             </div>
diff --git a/frontend/src/composables/__tests__/useContactManagement.test.ts b/frontend/src/composables/__tests__/useContactManagement.test.ts
deleted file mode 100644
index 2c1f41b70..000000000
--- a/frontend/src/composables/__tests__/useContactManagement.test.ts
+++ /dev/null
@@ -1,107 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { z } from 'zod'
-
-vi.mock('@/api/client', () => ({
-  api: {
-    clients_contacts_list: vi.fn(),
-    clients_contacts_create: vi.fn(),
-    clients_contacts_partial_update: vi.fn(),
-    clients_contacts_destroy: vi.fn(),
-  },
-}))
-
-vi.mock('@/utils/debug', () => ({
-  debugLog: vi.fn(),
-}))
-
-import { useContactManagement } from '../useContactManagement'
-import { schemas } from '@/api/generated/api'
-
-type ClientContact = z.infer<typeof schemas.ClientContact>
-
-const buildContact = (overrides: Partial<ClientContact> = {}): ClientContact => ({
-  id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0001',
-  client: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0002',
-  name: 'Jane Doe',
-  email: 'jane@example.com',
-  position: null,
-  is_primary: true,
-  notes: null,
-  is_active: true,
-  created_at: '2026-01-01T00:00:00+00:00',
-  updated_at: '2026-01-01T00:00:00+00:00',
-  phone: '+64 21 555 0100',
-  ...overrides,
-})
-
-describe('useContactManagement displayValue (KAN-281)', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('returns empty string when no contact is selected', () => {
-    const { displayValue } = useContactManagement()
-    expect(displayValue.get()).toBe('')
-  })
-
-  it('formats the selected contact as "name - phone - email"', () => {
-    const { displayValue, setSelectedContact } = useContactManagement()
-    setSelectedContact(buildContact())
-    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100 - jane@example.com')
-  })
-
-  it('skips the phone segment when the contact has no phone', () => {
-    const { displayValue, setSelectedContact } = useContactManagement()
-    setSelectedContact(buildContact({ phone: '' }))
-    expect(displayValue.get()).toBe('Jane Doe - jane@example.com')
-  })
-
-  it('skips the email segment when the contact has no email', () => {
-    const { displayValue, setSelectedContact } = useContactManagement()
-    setSelectedContact(buildContact({ email: null }))
-    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100')
-  })
-
-  it('shows only the name when the contact has neither phone nor email', () => {
-    const { displayValue, setSelectedContact } = useContactManagement()
-    setSelectedContact(buildContact({ phone: '', email: null }))
-    expect(displayValue.get()).toBe('Jane Doe')
-  })
-
-  it('set() splits "name - phone - email" into the selected contact', () => {
-    const { displayValue, setSelectedContact, selectedContact } = useContactManagement()
-    setSelectedContact(buildContact())
-
-    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
-
-    expect(selectedContact.value).toMatchObject({
-      name: 'Bob Smith',
-      phone: '09 555 1234',
-      email: 'bob@example.com',
-    })
-  })
-
-  it('set() populates the new-contact form when nothing is selected', () => {
-    const { displayValue, newContactForm } = useContactManagement()
-
-    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
-
-    expect(newContactForm.value).toMatchObject({
-      name: 'Bob Smith',
-      phone: '09 555 1234',
-      email: 'bob@example.com',
-    })
-  })
-
-  it('set() with a blank value clears name, phone and email on the form', () => {
-    const { displayValue, newContactForm } = useContactManagement()
-
-    displayValue.set('')
-
-    expect(newContactForm.value).toMatchObject({
-      name: '',
-      phone: '',
-      email: '',
-    })
-  })
-})
diff --git a/frontend/src/composables/__tests__/useOptimizedKanban.test.ts b/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
index e223fd98d..15e9d3a2d 100644
--- a/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
+++ b/frontend/src/composables/__tests__/useOptimizedKanban.test.ts
@@ -185,7 +185,7 @@ function buildKanbanJob(overrides: Partial<Record<string, unknown>> = {}) {
     description: overrides.description ?? '',
     job_number: overrides.job_number ?? 9001,
     company_name: overrides.company_name ?? 'Weaver, Decker and Schultz',
-    contact_person: overrides.contact_person ?? 'Molly Wainwright',
+    person_name: overrides.person_name ?? 'Molly Wainwright',
     people: overrides.people ?? [],
     status: overrides.status ?? 'in_progress',
     status_key: overrides.status_key ?? 'in_progress',
@@ -339,7 +339,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       name: '',
       description: '',
       company_name: '',
-      contact_person: '',
+      person_name: '',
       created_by: '',
       created_after: '',
       created_before: '',
@@ -505,7 +505,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       name: '',
       description: '',
       company_name: '',
-      contact_person: '',
+      person_name: '',
       created_by: '',
       created_after: '',
       created_before: '',
@@ -538,7 +538,7 @@ describe('useOptimizedKanban search reconciliation', () => {
       name: '',
       description: '',
       company_name: '',
-      contact_person: '',
+      person_name: '',
       created_by: '',
       created_after: '',
       created_before: '',
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
new file mode 100644
index 000000000..d7a5ba44d
--- /dev/null
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { z } from 'zod'
+
+vi.mock('@/api/client', () => ({
+  api: {
+    companies_person_links_list: vi.fn(),
+    companies_person_links_create: vi.fn(),
+    companies_person_links_partial_update: vi.fn(),
+    companies_person_links_destroy: vi.fn(),
+  },
+}))
+
+vi.mock('@/utils/debug', () => ({
+  debugLog: vi.fn(),
+}))
+
+import { usePersonManagement } from '../usePersonManagement'
+import { schemas } from '@/api/generated/api'
+
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+
+const buildPerson = (overrides: Partial<CompanyPersonLink> = {}): CompanyPersonLink => ({
+  id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0001',
+  company: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0002',
+  person: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0003',
+  person_name: 'Jane Doe',
+  person_email: 'jane@example.com',
+  xero_name: 'Jane Doe',
+  position: null,
+  is_primary: true,
+  notes: null,
+  is_active: true,
+  created_at: '2026-01-01T00:00:00+00:00',
+  updated_at: '2026-01-01T00:00:00+00:00',
+  phone: '+64 21 555 0100',
+  ...overrides,
+})
+
+describe('usePersonManagement displayValue (KAN-281)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns empty string when no person is selected', () => {
+    const { displayValue } = usePersonManagement()
+    expect(displayValue.get()).toBe('')
+  })
+
+  it('formats the selected person as "name - phone - email"', () => {
+    const { displayValue, setSelectedPerson } = usePersonManagement()
+    setSelectedPerson(buildPerson())
+    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100 - jane@example.com')
+  })
+
+  it('skips the phone segment when the person has no phone', () => {
+    const { displayValue, setSelectedPerson } = usePersonManagement()
+    setSelectedPerson(buildPerson({ phone: '' }))
+    expect(displayValue.get()).toBe('Jane Doe - jane@example.com')
+  })
+
+  it('skips the email segment when the person has no email', () => {
+    const { displayValue, setSelectedPerson } = usePersonManagement()
+    setSelectedPerson(buildPerson({ person_email: null }))
+    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100')
+  })
+
+  it('shows only the name when the person has neither phone nor email', () => {
+    const { displayValue, setSelectedPerson } = usePersonManagement()
+    setSelectedPerson(buildPerson({ phone: '', person_email: null }))
+    expect(displayValue.get()).toBe('Jane Doe')
+  })
+
+  it('set() splits "name - phone - email" into the selected contact', () => {
+    const { displayValue, setSelectedPerson, selectedPerson } = usePersonManagement()
+    setSelectedPerson(buildPerson())
+
+    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
+
+    expect(selectedPerson.value).toMatchObject({
+      person_name: 'Bob Smith',
+      phone: '09 555 1234',
+      person_email: 'bob@example.com',
+    })
+  })
+
+  it('set() populates the new-person form when nothing is selected', () => {
+    const { displayValue, personForm } = usePersonManagement()
+
+    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
+
+    expect(personForm.value).toMatchObject({
+      name: 'Bob Smith',
+      phone: '09 555 1234',
+      email: 'bob@example.com',
+    })
+  })
+
+  it('set() with a blank value clears name, phone and email on the form', () => {
+    const { displayValue, personForm } = usePersonManagement()
+
+    displayValue.set('')
+
+    expect(personForm.value).toMatchObject({
+      name: '',
+      phone: '',
+      email: '',
+    })
+  })
+})
diff --git a/frontend/src/composables/useCompanyLookup.ts b/frontend/src/composables/useCompanyLookup.ts
index 1ab57cb27..eb3b99f6c 100644
--- a/frontend/src/composables/useCompanyLookup.ts
+++ b/frontend/src/composables/useCompanyLookup.ts
@@ -8,7 +8,7 @@ import { logSearchResultClick } from '@/services/searchTelemetry.service'
 
 // Use generated schemas
 export type Company = z.infer<typeof schemas.CompanySearchResult>
-export type ClientContact = z.infer<typeof schemas.ClientContact>
+export type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 
 type UseCompanyLookupOptions = {
   supplierLookup?: { value: boolean }
@@ -27,7 +27,7 @@ export async function logCompanySearchClick(
 
   try {
     await logSearchResultClick({
-      domain: 'client',
+      domain: 'company',
       query: trimmedQuery,
       selectedResultId: company.id,
       selectedLabel: company.name,
@@ -45,7 +45,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
   const isLoading = ref(false)
   const showSuggestions = ref(false)
   const selectedCompany = ref<Company | null>(null)
-  const contacts = ref<ClientContact[]>([])
+  const contacts = ref<CompanyPersonLink[]>([])
 
   const hasValidXeroId = computed(() => {
     debugLog('Selected company value: ', selectedCompany.value)
@@ -138,17 +138,17 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
 
     contacts.value = []
 
-    await loadClientContacts(company.id)
+    await loadCompanyPersonLinks(company.id)
   }
 
-  const loadClientContacts = async (companyId: string) => {
+  const loadCompanyPersonLinks = async (companyId: string) => {
     if (!companyId) {
       contacts.value = []
       return
     }
 
     try {
-      const response = await api.companies_contacts_list({
+      const response = await api.companies_person_links_list({
         queries: { company_id: companyId },
       })
       contacts.value = response || []
@@ -159,7 +159,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     }
   }
 
-  const getPrimaryContact = (): ClientContact | null => {
+  const getPrimaryContact = (): CompanyPersonLink | null => {
     if (contacts.value.length === 0) {
       return null
     }
@@ -258,7 +258,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     browseCompanies,
     logSelectedCompanyClick,
     selectCompany,
-    loadClientContacts,
+    loadCompanyPersonLinks,
     getPrimaryContact,
     clearSelection,
     handleInputChange,
diff --git a/frontend/src/composables/useContactManagement.ts b/frontend/src/composables/useContactManagement.ts
deleted file mode 100644
index 965e4b2b0..000000000
--- a/frontend/src/composables/useContactManagement.ts
+++ /dev/null
@@ -1,486 +0,0 @@
-import { ref, computed } from 'vue'
-import { schemas } from '@/api/generated/api'
-import { api } from '@/api/client'
-import { z } from 'zod'
-import { debugLog } from '@/utils/debug'
-
-// Schema-derived types (no custom interfaces)
-type ClientContact = z.infer<typeof schemas.ClientContact>
-type ContactCreateRequest = z.input<typeof schemas.ClientContactRequest>
-type ContactUpdateRequest = z.input<typeof schemas.PatchedClientContactRequest>
-type ContactFormFields = {
-  name: ContactCreateRequest['name']
-  position: ContactCreateRequest['position']
-  email: ContactCreateRequest['email']
-  phone: ContactCreateRequest['phone']
-  notes: ContactCreateRequest['notes']
-  is_primary: boolean
-}
-export type ContactFormData = ContactFormFields
-
-/**
- * Composable for managing company contacts
- *
- * Provides functionality for loading, creating, selecting, and managing company contacts.
- * Handles modal state, form validation, and API interactions for contact management.
- *
- * @returns Object containing reactive state and methods for contact management
- */
-export function useContactManagement() {
-  const isModalOpen = ref(false)
-  const contacts = ref<ClientContact[]>([])
-  const selectedContact = ref<ClientContact | null>(null)
-  const isLoading = ref(false)
-  const currentCompanyId = ref<string>('')
-  const currentCompanyName = ref<string>('')
-
-  const newContactForm = ref<ContactFormData>({
-    name: '',
-    position: '',
-    email: '',
-    phone: '',
-    notes: '',
-    is_primary: false,
-  })
-
-  // Edit mode state
-  const editingContact = ref<ClientContact | null>(null)
-  const isEditing = computed(() => editingContact.value !== null)
-
-  // Filter out inactive contacts for display
-  const activeContacts = computed(() =>
-    contacts.value.filter((contact) => contact.is_active !== false),
-  )
-
-  const hasContacts = computed(() => contacts.value.length > 0)
-
-  const displayValue = {
-    get() {
-      if (!selectedContact.value) return ''
-      const contact = selectedContact.value
-      const parts = [contact.name]
-      if (contact.phone) parts.push(contact.phone)
-      if (contact.email) parts.push(contact.email)
-      return parts.join(' - ')
-    },
-    set(val: string) {
-      // Expecting format: "name - phone - email"
-      const [name, phone, email] = val.split(' - ')
-      if (selectedContact.value) {
-        selectedContact.value = {
-          ...selectedContact.value,
-          name,
-          phone: phone || '',
-          email: email || '',
-        }
-      } else {
-        newContactForm.value = {
-          ...newContactForm.value,
-          name,
-          phone: phone || '',
-          email: email || '',
-        }
-      }
-    },
-  }
-
-  /**
-   * Opens the contact selection modal for a specific company
-   *
-   * @param companyId - The ID of the company to load contacts for
-   * @param companyName - The name of the company (for display purposes)
-   */
-  const openModal = async (companyId: string, companyName: string) => {
-    if (!companyId) {
-      debugLog('Cannot open contact modal without company ID')
-      return
-    }
-
-    currentCompanyId.value = companyId
-    currentCompanyName.value = companyName
-    isModalOpen.value = true
-
-    resetNewContactForm()
-
-    await loadContacts(companyId)
-  }
-
-  /**
-   * Closes the contact selection modal and resets the form
-   */
-  const closeModal = () => {
-    isModalOpen.value = false
-    editingContact.value = null
-    resetNewContactForm()
-  }
-
-  /**
-   * Loads contacts for a specific company from the API
-   *
-   * @param companyId - The ID of the company to load contacts for
-   */
-  const loadContacts = async (companyId: string) => {
-    if (!companyId) {
-      contacts.value = []
-      newContactForm.value.is_primary = true
-      return
-    }
-
-    isLoading.value = true
-    try {
-      const response = await api.companies_contacts_list({
-        queries: { company_id: companyId },
-      })
-      contacts.value = response || []
-      newContactForm.value.is_primary = contacts.value.length === 0
-    } catch (error) {
-      debugLog('Error loading contacts:', error)
-      contacts.value = []
-      newContactForm.value.is_primary = true
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  /**
-   * Loads contacts for a company without opening the modal
-   *
-   * @param companyId - The ID of the company to load contacts for
-   */
-  const loadContactsOnly = async (companyId: string) => {
-    await loadContacts(companyId)
-  }
-
-  /**
-   * Sets the selected contact without closing the modal
-   * Use this for programmatic/auto-selection (e.g., selecting primary contact on load)
-   *
-   * @param contact - The contact to select
-   */
-  const setSelectedContact = (contact: ClientContact) => {
-    selectedContact.value = contact
-  }
-
-  /**
-   * Selects an existing contact and closes the modal
-   * Use this for explicit user selection from the modal UI
-   *
-   * @param contact - The contact to select
-   */
-  const selectExistingContact = (contact: ClientContact) => {
-    selectedContact.value = contact
-    closeModal()
-  }
-
-  /**
-   * Creates a new contact for the current company
-   *
-   * Automatically sets the contact as primary if it's the first contact for the company.
-   * After creation, reloads the contacts list and selects the newly created contact.
-   *
-   * @returns Promise<boolean> - True if contact was created successfully, false otherwise
-   */
-  const createNewContact = async (): Promise<boolean> => {
-    if (!currentCompanyId.value) {
-      debugLog('Cannot create contact without company ID')
-      return false
-    }
-
-    if (!newContactForm.value.name.trim()) {
-      debugLog('Contact name is required')
-      return false
-    }
-
-    isLoading.value = true
-
-    try {
-      // If this is the first contact for the company, automatically make it primary
-      const shouldBePrimary = newContactForm.value.is_primary || contacts.value.length === 0
-
-      const trimmedPosition = newContactForm.value.position?.trim()
-      const trimmedEmail = newContactForm.value.email?.trim()
-      const trimmedPhone = newContactForm.value.phone?.trim()
-      const trimmedNotes = newContactForm.value.notes?.trim()
-
-      const contactData: ContactCreateRequest = {
-        company: currentCompanyId.value,
-        name: newContactForm.value.name.trim(),
-        is_primary: shouldBePrimary,
-        position: trimmedPosition || undefined,
-        email: trimmedEmail || undefined,
-        notes: trimmedNotes || undefined,
-        // Omit phone entirely when blank so the backend leaves contact methods untouched
-        ...(trimmedPhone ? { phone: trimmedPhone } : {}),
-      }
-
-      debugLog('Creating new contact:', contactData)
-
-      const response = await api.companies_contacts_create(contactData)
-
-      if (!response || !response.id) {
-        throw new Error('Invalid response from server')
-      }
-
-      const newContact = response as ClientContact
-
-      debugLog('Contact created successfully:', newContact)
-
-      // Reload contacts first to get the updated list
-      await loadContacts(currentCompanyId.value)
-
-      // Then find and select the newly created contact
-      const createdContact = contacts.value.find((contact) => contact.id === newContact.id)
-      if (createdContact) {
-        selectedContact.value = createdContact
-        debugLog('New contact selected:', createdContact)
-      } else {
-        selectedContact.value = newContact
-        debugLog('Using response contact:', newContact)
-      }
-
-      closeModal()
-      return true
-    } catch (error) {
-      debugLog('Error creating contact:', error)
-      return false
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  /**
-   * Resets the new contact form to its initial empty state
-   */
-  const resetNewContactForm = () => {
-    newContactForm.value = {
-      name: '',
-      position: '',
-      email: '',
-      phone: '',
-      notes: '',
-      is_primary: contacts.value.length === 0,
-    }
-  }
-
-  /**
-   * Starts editing an existing contact
-   * Populates the form with the contact's current data
-   *
-   * @param contact - The contact to edit
-   */
-  const startEditContact = (contact: ClientContact) => {
-    editingContact.value = contact
-    newContactForm.value = {
-      name: contact.name,
-      position: contact.position || '',
-      email: contact.email || '',
-      phone: contact.phone || '',
-      notes: contact.notes || '',
-      is_primary: contact.is_primary || false,
-    }
-  }
-
-  /**
-   * Cancels the current edit operation and resets the form
-   */
-  const cancelEdit = () => {
-    editingContact.value = null
-    resetNewContactForm()
-  }
-
-  /**
-   * Updates an existing contact with the current form data
-   *
-   * @returns Promise<boolean> - True if update was successful, false otherwise
-   */
-  const updateContact = async (): Promise<boolean> => {
-    if (!editingContact.value?.id) {
-      debugLog('Cannot update contact without ID')
-      return false
-    }
-
-    if (!newContactForm.value.name.trim()) {
-      debugLog('Contact name is required')
-      return false
-    }
-
-    isLoading.value = true
-
-    try {
-      const trimmedPhone = newContactForm.value.phone?.trim()
-
-      const contactData: ContactUpdateRequest = {
-        name: newContactForm.value.name.trim(),
-        is_primary: newContactForm.value.is_primary,
-        position: newContactForm.value.position?.trim() || null,
-        email: newContactForm.value.email?.trim() || null,
-        notes: newContactForm.value.notes?.trim() || null,
-        // Omit phone entirely when blank so the backend leaves contact methods untouched
-        ...(trimmedPhone ? { phone: trimmedPhone } : {}),
-      }
-
-      debugLog('Updating contact:', editingContact.value.id, contactData)
-
-      await api.companies_contacts_partial_update(contactData, {
-        params: { id: editingContact.value.id },
-      })
-
-      debugLog('Contact updated successfully')
-
-      // Reload contacts to get updated list
-      await loadContacts(currentCompanyId.value)
-
-      // If the updated contact was selected, update the selection
-      if (selectedContact.value?.id === editingContact.value.id) {
-        const updated = contacts.value.find((c) => c.id === editingContact.value!.id)
-        if (updated) {
-          selectedContact.value = updated
-        }
-      }
-
-      cancelEdit()
-      closeModal()
-      return true
-    } catch (error) {
-      debugLog('Error updating contact:', error)
-      return false
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  /**
-   * Soft deletes a contact (sets is_active=false)
-   *
-   * @param contactId - The ID of the contact to delete
-   * @returns Promise<boolean> - True if delete was successful, false otherwise
-   */
-  const deleteContact = async (contactId: string): Promise<boolean> => {
-    if (!contactId) {
-      debugLog('Cannot delete contact without ID')
-      return false
-    }
-
-    isLoading.value = true
-
-    try {
-      debugLog('Deleting contact:', contactId)
-
-      await api.companies_contacts_destroy(undefined, {
-        params: { id: contactId },
-      })
-
-      debugLog('Contact deleted successfully')
-
-      // Reload contacts to get updated list (inactive contacts filtered out)
-      await loadContacts(currentCompanyId.value)
-
-      // Clear selection if deleted contact was selected
-      if (selectedContact.value?.id === contactId) {
-        selectedContact.value = null
-      }
-
-      // Clear editing state if we were editing the deleted contact
-      if (editingContact.value?.id === contactId) {
-        cancelEdit()
-      }
-
-      return true
-    } catch (error) {
-      debugLog('Error deleting contact:', error)
-      return false
-    } finally {
-      isLoading.value = false
-    }
-  }
-
-  /**
-   * Saves the contact based on current form state
-   *
-   * If new contact data is provided, creates a new contact.
-   * If an existing contact is selected, closes the modal.
-   *
-   * @returns Promise<boolean> - True if save operation was successful, false otherwise
-   */
-  const saveContact = async (): Promise<boolean> => {
-    const hasNewContactData = newContactForm.value.name.trim().length > 0
-
-    switch (true) {
-      case hasNewContactData:
-        return await createNewContact()
-
-      case selectedContact.value !== null:
-        closeModal()
-        return true
-
-      default:
-        debugLog('Please select an existing contact or create a new one')
-        return false
-    }
-  }
-
-  /**
-   * Clears the currently selected contact
-   */
-  const clearSelection = () => {
-    selectedContact.value = null
-  }
-
-  /**
-   * Updates the contacts list with new data
-   *
-   * @param newContacts - Array of contacts to replace the current list
-   */
-  const updateContactsList = (newContacts: ClientContact[]) => {
-    contacts.value = newContacts
-  }
-
-  /**
-   * Finds the primary contact from the current contacts list
-   *
-   * @returns ClientContact | null - The primary contact if found, null otherwise
-   */
-  const findPrimaryContact = (): ClientContact | null => {
-    if (contacts.value.length === 0) {
-      return null
-    }
-
-    return contacts.value.find((contact) => contact.is_primary) || null
-  }
-
-  return {
-    isModalOpen,
-    contacts,
-    selectedContact,
-    isLoading,
-    currentCompanyName,
-    newContactForm,
-
-    // Edit mode state
-    editingContact,
-    isEditing,
-    activeContacts,
-
-    hasContacts,
-    displayValue,
-
-    openModal,
-    closeModal,
-    loadContacts,
-    loadContactsOnly,
-    setSelectedContact,
-    selectExistingContact,
-    createNewContact,
-    saveContact,
-    clearSelection,
-    updateContactsList,
-    findPrimaryContact,
-    resetNewContactForm,
-
-    // Edit/delete functions
-    startEditContact,
-    cancelEdit,
-    updateContact,
-    deleteContact,
-  }
-}
diff --git a/frontend/src/composables/useJobAutosave.ts b/frontend/src/composables/useJobAutosave.ts
index 58aecfb1d..4a9f39047 100644
--- a/frontend/src/composables/useJobAutosave.ts
+++ b/frontend/src/composables/useJobAutosave.ts
@@ -286,10 +286,10 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
     for (const [k, v] of changeBuffer.entries()) rawPatch[k] = v
 
     if ('company_id' in rawPatch) {
-      rawPatch['contact_id'] = null
-      rawPatch['contact_name'] = null
-      pendingKeys.value.add('contact_id')
-      pendingKeys.value.add('contact_name')
+      rawPatch['person_id'] = null
+      rawPatch['person_name'] = null
+      pendingKeys.value.add('person_id')
+      pendingKeys.value.add('person_name')
     }
 
     const effectivePatch: Record<string, unknown> = {}
@@ -309,14 +309,14 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
     }
 
     if ('company_id' in effectivePatch) {
-      if (!('contact_id' in effectivePatch)) effectivePatch['contact_id'] = null
-      if (!('contact_name' in effectivePatch)) effectivePatch['contact_name'] = null
+      if (!('person_id' in effectivePatch)) effectivePatch['person_id'] = null
+      if (!('person_name' in effectivePatch)) effectivePatch['person_name'] = null
     }
 
     // completeness rule (example)
     const virtualSnapshot = { ...originalSnapshot, ...effectivePatch }
     if (
-      ('contact_id' in effectivePatch || 'contact_name' in effectivePatch) &&
+      ('person_id' in effectivePatch || 'person_name' in effectivePatch) &&
       !virtualSnapshot['company_id']
     ) {
       log('⛔ canSave=false (contact_* change without company_id)', { reason })
diff --git a/frontend/src/composables/useJobHeaderAutosave.ts b/frontend/src/composables/useJobHeaderAutosave.ts
index 272174ffa..82bef185e 100644
--- a/frontend/src/composables/useJobHeaderAutosave.ts
+++ b/frontend/src/composables/useJobHeaderAutosave.ts
@@ -157,8 +157,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
             const payloadJob: Record<string, unknown> = { ...filteredPatch }
 
             if ('company_id' in (filteredPatch as Partial<Job>)) {
-              payloadJob.contact_id = null
-              payloadJob.contact_name = null
+              payloadJob.person_id = null
+              payloadJob.person_name = null
             }
 
             const fields = Object.keys(payloadJob)
@@ -195,11 +195,11 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
                 case 'quote_acceptance_date':
                   beforeValues[field] = headerSnapshot.quote_acceptance_date
                   break
-                case 'contact_id':
-                  beforeValues[field] = detail?.job?.contact_id ?? null
+                case 'person_id':
+                  beforeValues[field] = detail?.job?.person_id ?? null
                   break
-                case 'contact_name':
-                  beforeValues[field] = detail?.job?.contact_name ?? null
+                case 'person_name':
+                  beforeValues[field] = detail?.job?.person_name ?? null
                   break
                 default:
                   beforeValues[field] = detail?.job
@@ -290,8 +290,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
     autosave.queueChanges({
       company_id: company.id,
       company_name: company.name,
-      contact_id: null,
-      contact_name: null,
+      person_id: null,
+      person_name: null,
     })
     void autosave.flush('company-change')
   }
diff --git a/frontend/src/composables/useOptimizedKanban.ts b/frontend/src/composables/useOptimizedKanban.ts
index 0bc0a4f26..2c3f82611 100644
--- a/frontend/src/composables/useOptimizedKanban.ts
+++ b/frontend/src/composables/useOptimizedKanban.ts
@@ -185,7 +185,7 @@ export function useOptimizedKanban(onJobsLoaded?: () => void) {
         job.description?.toLowerCase().includes(normalizedQuery) ||
         job.company_name?.toLowerCase().includes(normalizedQuery) ||
         String(job.job_number).toLowerCase().includes(normalizedQuery) ||
-        job.contact_person?.toLowerCase().includes(normalizedQuery)
+        job.person_name?.toLowerCase().includes(normalizedQuery)
       )
     })
   }
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
new file mode 100644
index 000000000..df3560416
--- /dev/null
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -0,0 +1,486 @@
+import { ref, computed } from 'vue'
+import { schemas } from '@/api/generated/api'
+import { api } from '@/api/client'
+import { z } from 'zod'
+import { debugLog } from '@/utils/debug'
+
+// Schema-derived types (no custom interfaces)
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type PersonCreateRequest = z.input<typeof schemas.CompanyPersonLinkRequest>
+type PersonUpdateRequest = z.input<typeof schemas.PatchedCompanyPersonLinkRequest>
+type PersonFormFields = {
+  name: PersonCreateRequest['person_name']
+  position: PersonCreateRequest['position']
+  email: PersonCreateRequest['person_email']
+  phone: PersonCreateRequest['phone']
+  notes: PersonCreateRequest['notes']
+  is_primary: boolean
+}
+export type PersonFormData = PersonFormFields
+
+/**
+ * Composable for managing company people
+ *
+ * Provides functionality for loading, creating, selecting, and managing company people.
+ * Handles modal state, form validation, and API interactions for person management.
+ *
+ * @returns Object containing reactive state and methods for person management
+ */
+export function usePersonManagement() {
+  const isModalOpen = ref(false)
+  const people = ref<CompanyPersonLink[]>([])
+  const selectedPerson = ref<CompanyPersonLink | null>(null)
+  const isLoading = ref(false)
+  const currentCompanyId = ref<string>('')
+  const currentCompanyName = ref<string>('')
+
+  const personForm = ref<PersonFormData>({
+    name: '',
+    position: '',
+    email: '',
+    phone: '',
+    notes: '',
+    is_primary: false,
+  })
+
+  // Edit mode state
+  const editingPersonLink = ref<CompanyPersonLink | null>(null)
+  const isEditing = computed(() => editingPersonLink.value !== null)
+
+  // Filter out inactive people for display
+  const activePersonLinks = computed(() =>
+    people.value.filter((person) => person.is_active !== false),
+  )
+
+  const hasPeople = computed(() => people.value.length > 0)
+
+  const displayValue = {
+    get() {
+      if (!selectedPerson.value) return ''
+      const person = selectedPerson.value
+      const parts = [person.person_name]
+      if (person.phone) parts.push(person.phone)
+      if (person.person_email) parts.push(person.person_email)
+      return parts.join(' - ')
+    },
+    set(val: string) {
+      // Expecting format: "name - phone - email"
+      const [name, phone, email] = val.split(' - ')
+      if (selectedPerson.value) {
+        selectedPerson.value = {
+          ...selectedPerson.value,
+          person_name: name,
+          phone: phone || '',
+          person_email: email || '',
+        }
+      } else {
+        personForm.value = {
+          ...personForm.value,
+          name,
+          phone: phone || '',
+          email: email || '',
+        }
+      }
+    },
+  }
+
+  /**
+   * Opens the person selection modal for a specific company
+   *
+   * @param companyId - The ID of the company to load people for
+   * @param companyName - The name of the company (for display purposes)
+   */
+  const openModal = async (companyId: string, companyName: string) => {
+    if (!companyId) {
+      debugLog('Cannot open person modal without company ID')
+      return
+    }
+
+    currentCompanyId.value = companyId
+    currentCompanyName.value = companyName
+    isModalOpen.value = true
+
+    resetPersonForm()
+
+    await loadPeople(companyId)
+  }
+
+  /**
+   * Closes the person selection modal and resets the form
+   */
+  const closeModal = () => {
+    isModalOpen.value = false
+    editingPersonLink.value = null
+    resetPersonForm()
+  }
+
+  /**
+   * Loads people for a specific company from the API
+   *
+   * @param companyId - The ID of the company to load people for
+   */
+  const loadPeople = async (companyId: string) => {
+    if (!companyId) {
+      people.value = []
+      personForm.value.is_primary = true
+      return
+    }
+
+    isLoading.value = true
+    try {
+      const response = await api.companies_person_links_list({
+        queries: { company_id: companyId },
+      })
+      people.value = response || []
+      personForm.value.is_primary = people.value.length === 0
+    } catch (error) {
+      debugLog('Error loading contacts:', error)
+      people.value = []
+      personForm.value.is_primary = true
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Loads people for a company without opening the modal
+   *
+   * @param companyId - The ID of the company to load people for
+   */
+  const loadPeopleOnly = async (companyId: string) => {
+    await loadPeople(companyId)
+  }
+
+  /**
+   * Sets the selected person without closing the modal
+   * Use this for programmatic/auto-selection (e.g., selecting primary person on load)
+   *
+   * @param person - The person to select
+   */
+  const setSelectedPerson = (person: CompanyPersonLink) => {
+    selectedPerson.value = person
+  }
+
+  /**
+   * Selects an existing person and closes the modal
+   * Use this for explicit user selection from the modal UI
+   *
+   * @param person - The person to select
+   */
+  const selectExistingPerson = (person: CompanyPersonLink) => {
+    selectedPerson.value = person
+    closeModal()
+  }
+
+  /**
+   * Creates a new person for the current company
+   *
+   * Automatically sets the person as primary if it's the first person for the company.
+   * After creation, reloads the people list and selects the newly created person.
+   *
+   * @returns Promise<boolean> - True if person was created successfully, false otherwise
+   */
+  const createNewPerson = async (): Promise<boolean> => {
+    if (!currentCompanyId.value) {
+      debugLog('Cannot create person without company ID')
+      return false
+    }
+
+    if (!personForm.value.name.trim()) {
+      debugLog('Person name is required')
+      return false
+    }
+
+    isLoading.value = true
+
+    try {
+      // If this is the first person for the company, automatically make it primary
+      const shouldBePrimary = personForm.value.is_primary || people.value.length === 0
+
+      const trimmedPosition = personForm.value.position?.trim()
+      const trimmedEmail = personForm.value.email?.trim()
+      const trimmedPhone = personForm.value.phone?.trim()
+      const trimmedNotes = personForm.value.notes?.trim()
+
+      const personData: PersonCreateRequest = {
+        company: currentCompanyId.value,
+        person_name: personForm.value.name.trim(),
+        is_primary: shouldBePrimary,
+        position: trimmedPosition || undefined,
+        person_email: trimmedEmail || undefined,
+        notes: trimmedNotes || undefined,
+        // Omit phone entirely when blank so the backend leaves person methods untouched
+        ...(trimmedPhone ? { phone: trimmedPhone } : {}),
+      }
+
+      debugLog('Creating new person:', personData)
+
+      const response = await api.companies_person_links_create(personData)
+
+      if (!response || !response.id) {
+        throw new Error('Invalid response from server')
+      }
+
+      const newPerson = response as CompanyPersonLink
+
+      debugLog('Person created successfully:', newPerson)
+
+      // Reload people first to get the updated list
+      await loadPeople(currentCompanyId.value)
+
+      // Then find and select the newly created person
+      const createdPerson = people.value.find((person) => person.id === newPerson.id)
+      if (createdPerson) {
+        selectedPerson.value = createdPerson
+        debugLog('New person selected:', createdPerson)
+      } else {
+        selectedPerson.value = newPerson
+        debugLog('Using response person:', newPerson)
+      }
+
+      closeModal()
+      return true
+    } catch (error) {
+      debugLog('Error creating person:', error)
+      return false
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Resets the new person form to its initial empty state
+   */
+  const resetPersonForm = () => {
+    personForm.value = {
+      name: '',
+      position: '',
+      email: '',
+      phone: '',
+      notes: '',
+      is_primary: people.value.length === 0,
+    }
+  }
+
+  /**
+   * Starts editing an existing person
+   * Populates the form with the person's current data
+   *
+   * @param person - The person to edit
+   */
+  const startEditPerson = (person: CompanyPersonLink) => {
+    editingPersonLink.value = person
+    personForm.value = {
+      name: person.person_name,
+      position: person.position || '',
+      email: person.person_email || '',
+      phone: person.phone || '',
+      notes: person.notes || '',
+      is_primary: person.is_primary || false,
+    }
+  }
+
+  /**
+   * Cancels the current edit operation and resets the form
+   */
+  const cancelEdit = () => {
+    editingPersonLink.value = null
+    resetPersonForm()
+  }
+
+  /**
+   * Updates an existing person with the current form data
+   *
+   * @returns Promise<boolean> - True if update was successful, false otherwise
+   */
+  const updatePerson = async (): Promise<boolean> => {
+    if (!editingPersonLink.value?.id) {
+      debugLog('Cannot update person without ID')
+      return false
+    }
+
+    if (!personForm.value.name.trim()) {
+      debugLog('Person name is required')
+      return false
+    }
+
+    isLoading.value = true
+
+    try {
+      const trimmedPhone = personForm.value.phone?.trim()
+
+      const personData: PersonUpdateRequest = {
+        person_name: personForm.value.name.trim(),
+        is_primary: personForm.value.is_primary,
+        position: personForm.value.position?.trim() || null,
+        person_email: personForm.value.email?.trim() || null,
+        notes: personForm.value.notes?.trim() || null,
+        // Omit phone entirely when blank so the backend leaves person methods untouched
+        ...(trimmedPhone ? { phone: trimmedPhone } : {}),
+      }
+
+      debugLog('Updating person:', editingPersonLink.value.id, personData)
+
+      await api.companies_person_links_partial_update(personData, {
+        params: { id: editingPersonLink.value.id },
+      })
+
+      debugLog('Person updated successfully')
+
+      // Reload people to get updated list
+      await loadPeople(currentCompanyId.value)
+
+      // If the updated person was selected, update the selection
+      if (selectedPerson.value?.id === editingPersonLink.value.id) {
+        const updated = people.value.find((c) => c.id === editingPersonLink.value!.id)
+        if (updated) {
+          selectedPerson.value = updated
+        }
+      }
+
+      cancelEdit()
+      closeModal()
+      return true
+    } catch (error) {
+      debugLog('Error updating person:', error)
+      return false
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Soft deletes a person (sets is_active=false)
+   *
+   * @param personLinkId - The ID of the person to delete
+   * @returns Promise<boolean> - True if delete was successful, false otherwise
+   */
+  const deletePerson = async (personLinkId: string): Promise<boolean> => {
+    if (!personLinkId) {
+      debugLog('Cannot delete person without ID')
+      return false
+    }
+
+    isLoading.value = true
+
+    try {
+      debugLog('Deleting person:', personLinkId)
+
+      await api.companies_person_links_destroy(undefined, {
+        params: { id: personLinkId },
+      })
+
+      debugLog('Person deleted successfully')
+
+      // Reload people to get updated list (inactive people filtered out)
+      await loadPeople(currentCompanyId.value)
+
+      // Clear selection if deleted person was selected
+      if (selectedPerson.value?.id === personLinkId) {
+        selectedPerson.value = null
+      }
+
+      // Clear editing state if we were editing the deleted contact
+      if (editingPersonLink.value?.id === personLinkId) {
+        cancelEdit()
+      }
+
+      return true
+    } catch (error) {
+      debugLog('Error deleting person:', error)
+      return false
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Saves the person based on current form state
+   *
+   * If new person data is provided, creates a new person.
+   * If an existing person is selected, closes the modal.
+   *
+   * @returns Promise<boolean> - True if save operation was successful, false otherwise
+   */
+  const savePerson = async (): Promise<boolean> => {
+    const hasNewPersonData = personForm.value.name.trim().length > 0
+
+    switch (true) {
+      case hasNewPersonData:
+        return await createNewPerson()
+
+      case selectedPerson.value !== null:
+        closeModal()
+        return true
+
+      default:
+        debugLog('Please select an existing person or create a new one')
+        return false
+    }
+  }
+
+  /**
+   * Clears the currently selected contact
+   */
+  const clearSelection = () => {
+    selectedPerson.value = null
+  }
+
+  /**
+   * Updates the people list with new data
+   *
+   * @param newPeople - Array of people to replace the current list
+   */
+  const updatePersonsList = (newPeople: CompanyPersonLink[]) => {
+    people.value = newPeople
+  }
+
+  /**
+   * Finds the primary person from the current people list
+   *
+   * @returns CompanyPersonLink | null - The primary person if found, null otherwise
+   */
+  const findPrimaryPerson = (): CompanyPersonLink | null => {
+    if (people.value.length === 0) {
+      return null
+    }
+
+    return people.value.find((person) => person.is_primary) || null
+  }
+
+  return {
+    isModalOpen,
+    people,
+    selectedPerson,
+    isLoading,
+    currentCompanyName,
+    personForm,
+
+    // Edit mode state
+    editingPersonLink,
+    isEditing,
+    activePersonLinks,
+
+    hasPeople,
+    displayValue,
+
+    openModal,
+    closeModal,
+    loadPeople,
+    loadPeopleOnly,
+    setSelectedPerson,
+    selectExistingPerson,
+    createNewPerson,
+    savePerson,
+    clearSelection,
+    updatePersonsList,
+    findPrimaryPerson,
+    resetPersonForm,
+
+    // Edit/delete functions
+    startEditPerson,
+    cancelEdit,
+    updatePerson,
+    deletePerson,
+  }
+}
diff --git a/frontend/src/constants/advanced-filters.ts b/frontend/src/constants/advanced-filters.ts
index 7d3905da2..96030d289 100644
--- a/frontend/src/constants/advanced-filters.ts
+++ b/frontend/src/constants/advanced-filters.ts
@@ -16,7 +16,7 @@ export const AdvancedFiltersSchema = z.object({
   name: z.string().optional().default(''),
   description: z.string().optional().default(''),
   company_name: z.string().optional().default(''),
-  contact_person: z.string().optional().default(''),
+  person_name: z.string().optional().default(''),
   created_by: z.string().optional().default(''),
   status: z.array(z.string()).optional().default([]),
   created_after: z.string().optional().default(''),
@@ -37,7 +37,7 @@ export const DEFAULT_ADVANCED_FILTERS: AdvancedFilters = {
   name: '',
   description: '',
   company_name: '',
-  contact_person: '',
+  person_name: '',
   created_by: '',
   status: [],
   created_after: '',
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index cf7bc0d84..7481ad058 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -35,7 +35,7 @@
                 <Input
                   v-model="searchQuery"
                   class="pl-9"
-                  placeholder="Search number, company, contact, job, or description"
+                  placeholder="Search number, company, person, job, or description"
                   @keydown.enter.prevent="loadCalls"
                 />
               </div>
@@ -117,13 +117,13 @@
               </option>
             </select>
             <select
-              v-model="selectedContactId"
+              v-model="selectedPersonId"
               class="rounded-md border border-gray-300 p-2 text-sm"
               :disabled="!selectedCompanyId"
             >
-              <option value="">No specific contact</option>
-              <option v-for="contact in contactOptions" :key="contact.id" :value="contact.id">
-                {{ contact.name }}
+              <option value="">No specific person</option>
+              <option v-for="contact in contactOptions" :key="contact.id" :value="contact.person">
+                {{ contact.person_name }}
               </option>
             </select>
           </div>
@@ -200,7 +200,7 @@ const directionFilter = ref<DirectionFilter>('all')
 const recordingsOnly = ref(false)
 const selectedCall = ref<PhoneCallRecord | null>(null)
 const selectedCompanyId = ref('')
-const selectedContactId = ref('')
+const selectedPersonId = ref('')
 const phoneLabel = ref('')
 const isPrimary = ref(false)
 const isAssigningNumber = ref(false)
@@ -211,7 +211,7 @@ const {
   suggestions: companyOptions,
   contacts: contactOptions,
   browseCompanies: searchCompanies,
-  loadClientContacts,
+  loadCompanyPersonLinks,
   logSelectedCompanyClick,
 } = useCompanyLookup()
 
@@ -223,7 +223,7 @@ const QUEUE_META: Record<CallsTab, { title: string; description: string }> = {
   unmatched: {
     title: 'Unmatched Calls',
     description:
-      'Assign these numbers to companies or contacts so future and historical calls land in the right CRM history.',
+      'Assign these numbers to companies or people so future and historical calls land in the right CRM history.',
   },
   unlinked: {
     title: 'Matched Calls Needing Job Link',
@@ -279,7 +279,7 @@ async function loadCalls(): Promise<void> {
 function handleAssignNumber(call: PhoneCallRecord): void {
   selectedCall.value = call
   selectedCompanyId.value = ''
-  selectedContactId.value = ''
+  selectedPersonId.value = ''
   phoneLabel.value = ''
   isPrimary.value = false
   companyOptions.value = []
@@ -307,7 +307,7 @@ async function assignSelectedCallNumber(): Promise<void> {
     const updatedCall = await api.assignPhoneCallNumber(
       {
         company: selectedCompanyId.value,
-        contact: selectedContactId.value || null,
+        person: selectedPersonId.value || null,
         label: phoneLabel.value,
         is_primary: isPrimary.value,
       },
@@ -331,7 +331,7 @@ function resetAssignmentForm(): void {
   companyOptions.value = []
   contactOptions.value = []
   selectedCompanyId.value = ''
-  selectedContactId.value = ''
+  selectedPersonId.value = ''
   phoneLabel.value = ''
   isPrimary.value = false
 }
@@ -346,9 +346,9 @@ watch([activeTab, directionFilter, recordingsOnly], () => {
 
 watch(selectedCompanyId, (companyId) => {
   if (!companyId) {
-    selectedContactId.value = ''
+    selectedPersonId.value = ''
   }
-  void loadClientContacts(companyId)
+  void loadCompanyPersonLinks(companyId)
 })
 
 onMounted(() => {
diff --git a/frontend/src/pages/crm/companies/[id].vue b/frontend/src/pages/crm/companies/[id].vue
index 5a3c501df..e839d4075 100644
--- a/frontend/src/pages/crm/companies/[id].vue
+++ b/frontend/src/pages/crm/companies/[id].vue
@@ -86,12 +86,12 @@
                 <p class="text-gray-900">{{ company.address || '-' }}</p>
               </div>
               <div>
-                <label class="text-sm font-medium text-gray-500">Primary Contact</label>
-                <p class="text-gray-900">{{ company.primary_contact_name || '-' }}</p>
+                <label class="text-sm font-medium text-gray-500">Primary Person</label>
+                <p class="text-gray-900">{{ primaryPerson?.person_name || '-' }}</p>
               </div>
               <div>
-                <label class="text-sm font-medium text-gray-500">Primary Contact Email</label>
-                <p class="text-gray-900">{{ company.primary_contact_email || '-' }}</p>
+                <label class="text-sm font-medium text-gray-500">Primary Person Email</label>
+                <p class="text-gray-900">{{ primaryPerson?.person_email || '-' }}</p>
               </div>
             </CardContent>
           </Card>
@@ -183,7 +183,7 @@
                   <UserCircle class="w-5 h-5 text-gray-400 mt-0.5" />
                   <div class="flex-1">
                     <div class="flex items-center gap-2">
-                      <p class="font-medium text-gray-900">{{ contact.name }}</p>
+                      <p class="font-medium text-gray-900">{{ contact.person_name }}</p>
                       <Badge v-if="contact.is_primary" variant="default" class="text-xs"
                         >Primary</Badge
                       >
@@ -192,7 +192,7 @@
                       {{ contact.position }}
                     </p>
                     <div class="flex flex-col gap-1 mt-1 text-sm text-gray-600">
-                      <span v-if="contact.email">{{ contact.email }}</span>
+                      <span v-if="contact.person_email">{{ contact.person_email }}</span>
                       <span v-if="contact.phone">{{ contact.phone }}</span>
                     </div>
                   </div>
@@ -465,6 +465,10 @@ const contacts = computed(() => {
   return companyStore.companyContacts[props.id] || []
 })
 
+const primaryPerson = computed(() => {
+  return contacts.value.find((contact) => contact.is_primary) ?? contacts.value[0] ?? null
+})
+
 const relatedJobs = computed(() => {
   return companyStore.companyJobs[props.id] || []
 })
@@ -612,7 +616,7 @@ async function loadCompanyData() {
 
     // Load contacts
     try {
-      await companyStore.fetchClientContacts(props.id)
+      await companyStore.fetchCompanyPersonLinks(props.id)
     } catch (err) {
       console.error('Failed to load contacts:', err)
       // Don't show error for contacts, just log it
diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index 5f2ca8b08..97703d0af 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -57,16 +57,16 @@
                 </div>
 
                 <div>
-                  <ContactSelector
-                    ref="contactSelectorRef"
+                  <PersonSelector
+                    ref="personSelectorRef"
                     id="contact"
-                    v-model="contactDisplayName"
+                    v-model="personDisplayName"
                     :company-id="formData.company_id as string"
                     :company-name="companyDisplayName"
-                    label="Contact"
-                    placeholder="Search or add contact person"
+                    label="Person"
+                    placeholder="Search or add person"
                     :optional="true"
-                    @update:selected-contact="updateSelectedContact"
+                    @update:selected-person="updateSelectedPerson"
                   />
                 </div>
 
@@ -244,7 +244,7 @@ import { ref, computed, onMounted, nextTick, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import AppLayout from '@/components/AppLayout.vue'
 import CompanyLookup from '@/components/CompanyLookup.vue'
-import ContactSelector from '@/components/ContactSelector.vue'
+import PersonSelector from '@/components/PersonSelector.vue'
 import RichTextEditor from '@/components/RichTextEditor.vue'
 import { jobService, type JobCreateData } from '@/services/job.service'
 import { schemas } from '@/api/generated/api'
@@ -252,10 +252,10 @@ import { z } from 'zod'
 import { debugLog } from '@/utils/debug'
 
 type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 import { toast } from 'vue-sonner'
 
-const contactSelectorRef = ref<InstanceType<typeof ContactSelector> | null>(null)
+const personSelectorRef = ref<InstanceType<typeof PersonSelector> | null>(null)
 
 const filterNumericInput = (event: KeyboardEvent) => {
   // Allow control keys, arrow keys, and numeric keys on numpad
@@ -301,7 +301,7 @@ const formData = ref<JobCreateData>({
   description: '',
   order_number: '',
   notes: '',
-  contact_id: null,
+  person_id: null,
   estimated_materials: 0,
   estimated_time: 0,
   is_urgent: false,
@@ -311,8 +311,8 @@ const formData = ref<JobCreateData>({
 const companyDisplayName = ref('')
 
 const selectedCompany = ref<CompanySearchResult | null>(null)
-const selectedContact = ref<ClientContact | null>(null)
-const contactDisplayName = ref('')
+const selectedPerson = ref<CompanyPersonLink | null>(null)
+const personDisplayName = ref('')
 
 const errors = ref<Record<string, string>>({})
 const isSubmitting = ref(false)
@@ -322,39 +322,39 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
   debugLog('JobCreateView - handleCompanySelection:', {
     company,
     previousCompanyId: formData.value.company_id,
-    previousContactId: formData.value.contact_id,
+    previousContactId: formData.value.person_id,
   })
 
   selectedCompany.value = company
 
   // Always clear contact person when company changes (even if same company selected)
-  formData.value.contact_id = null
-  selectedContact.value = null
-  contactDisplayName.value = ''
+  formData.value.person_id = null
+  selectedPerson.value = null
+  personDisplayName.value = ''
 
-  // Clear the ContactSelector's internal state first
-  if (contactSelectorRef.value) {
-    contactSelectorRef.value.clearSelection()
+  // Clear the PersonSelector's internal state first
+  if (personSelectorRef.value) {
+    personSelectorRef.value.clearSelection()
   }
 
   if (company) {
     companyDisplayName.value = company.name
     formData.value.company_id = company.id
 
-    debugLog('JobCreateView - Company selected, waiting for ContactSelector to update')
+    debugLog('JobCreateView - Company selected, waiting for PersonSelector to update')
 
     // Wait for the next DOM update cycle to ensure the ref is ready
-    // and the new company ID has propagated to the ContactSelector.
+    // and the new company ID has propagated to the PersonSelector.
     await nextTick()
 
-    // Give the ContactSelector's watcher time to process the companyId change
+    // Give the PersonSelector's watcher time to process the companyId change
     await new Promise((resolve) => setTimeout(resolve, 100))
 
-    if (contactSelectorRef.value) {
-      debugLog('JobCreateView - Calling selectPrimaryContact')
-      // The `selectPrimaryContact` method within the composable
+    if (personSelectorRef.value) {
+      debugLog('JobCreateView - Calling selectPrimaryPerson')
+      // The `selectPrimaryPerson` method within the composable
       // will handle loading contacts and finding the primary.
-      await contactSelectorRef.value.selectPrimaryContact()
+      await personSelectorRef.value.selectPrimaryPerson()
     }
   } else {
     // Clear company fields if company is deselected
@@ -364,15 +364,15 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
   }
 }
 
-const updateSelectedContact = (contact: ClientContact | null) => {
-  selectedContact.value = contact
+const updateSelectedPerson = (contact: CompanyPersonLink | null) => {
+  selectedPerson.value = contact
   if (contact) {
-    // Save the contact ID for the API and display name for the UI
-    formData.value.contact_id = contact.id
-    contactDisplayName.value = contact.name
+    // Save the person ID for the API and display name for the UI
+    formData.value.person_id = contact.person
+    personDisplayName.value = contact.person_name
   } else {
-    formData.value.contact_id = null
-    contactDisplayName.value = ''
+    formData.value.person_id = null
+    personDisplayName.value = ''
   }
 }
 
@@ -525,7 +525,7 @@ onMounted(() => {
     formData.value.description = ''
     formData.value.order_number = ''
     formData.value.notes = ''
-    formData.value.contact_id = null
+    formData.value.person_id = null
     formData.value.estimated_materials = 0
     formData.value.estimated_time = 0
     formData.value.pricing_methodology = 'time_materials'
diff --git a/frontend/src/pages/purchasing/po/[id].vue b/frontend/src/pages/purchasing/po/[id].vue
index 6ed51d289..8036cc031 100644
--- a/frontend/src/pages/purchasing/po/[id].vue
+++ b/frontend/src/pages/purchasing/po/[id].vue
@@ -166,7 +166,7 @@ type Job = z.infer<typeof schemas.JobForPurchasing>
 type AllocationItem = z.infer<typeof schemas.AllocationItem>
 type DeliveryAllocation = z.infer<typeof schemas.DeliveryReceiptAllocationRequest>
 type PurchaseOrderEmailResponse = z.infer<typeof schemas.PurchaseOrderEmailResponse>
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 type PurchaseOrderEmailResponseWithLegacy = PurchaseOrderEmailResponse & { email?: string }
 type PurchaseOrderStatus = z.infer<typeof schemas.PurchaseOrderDetailStatusEnum>
 
@@ -811,14 +811,16 @@ async function resolveSupplierEmail(): Promise<string | null> {
   }
 
   try {
-    const contacts = await api.companies_contacts_list({
+    const contacts = await api.companies_person_links_list({
       queries: { company_id: supplierId },
     })
 
-    const contactsArray: ClientContact[] = Array.isArray(contacts) ? contacts : []
-    const primaryContact = contactsArray.find((contact) => contact.is_primary && !!contact.email)
-    const fallbackContact = contactsArray.find((contact) => !!contact.email)
-    const resolvedEmail = primaryContact?.email ?? fallbackContact?.email ?? null
+    const contactsArray: CompanyPersonLink[] = Array.isArray(contacts) ? contacts : []
+    const primaryContact = contactsArray.find(
+      (contact) => contact.is_primary && !!contact.person_email,
+    )
+    const fallbackContact = contactsArray.find((contact) => !!contact.person_email)
+    const resolvedEmail = primaryContact?.person_email ?? fallbackContact?.person_email ?? null
 
     supplierEmailCache.value = {
       ...supplierEmailCache.value,
diff --git a/frontend/src/pages/reports/data-quality/duplicate-phones.vue b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
index ea7382866..ff81641df 100644
--- a/frontend/src/pages/reports/data-quality/duplicate-phones.vue
+++ b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
@@ -207,7 +207,7 @@ const ISSUE_CLASSES: Record<string, string> = {
 
 const OWNER_KIND_LABELS: Record<string, string> = {
   company: 'Company',
-  contact: 'Contact',
+  person: 'Person',
 }
 
 const issueLabel = (issue: string): string => ISSUE_LABELS[issue] ?? issue
diff --git a/frontend/src/services/job.service.ts b/frontend/src/services/job.service.ts
index 2af684f83..9080bce2a 100644
--- a/frontend/src/services/job.service.ts
+++ b/frontend/src/services/job.service.ts
@@ -30,8 +30,8 @@ async function updateJobHeaderPartial(
       'quote_acceptance_date',
       'price_cap',
       'default_xero_pay_item_id',
-      // include 'contact_name' if ever present
-      'contact_name',
+      // include 'person_name' if ever present
+      'person_name',
     ])
     const normalizeBefore = (k: string, v: unknown) => {
       if (v === undefined) return nullableKeys.has(k) ? null : v
diff --git a/frontend/src/services/searchTelemetry.service.ts b/frontend/src/services/searchTelemetry.service.ts
index 6c1977fc8..353545e27 100644
--- a/frontend/src/services/searchTelemetry.service.ts
+++ b/frontend/src/services/searchTelemetry.service.ts
@@ -1,7 +1,7 @@
 import { api } from '@/api/client'
 import { debugLog } from '@/utils/debug'
 
-type SearchDomain = 'client' | 'kanban' | 'stock'
+type SearchDomain = 'company' | 'kanban' | 'stock'
 
 export async function logSearchResultClick(params: {
   domain: SearchDomain
diff --git a/frontend/src/stores/__tests__/jobs.test.ts b/frontend/src/stores/__tests__/jobs.test.ts
index 5cc4bfcb4..0e961553c 100644
--- a/frontend/src/stores/__tests__/jobs.test.ts
+++ b/frontend/src/stores/__tests__/jobs.test.ts
@@ -27,7 +27,7 @@ function buildKanbanJob(overrides: Partial<Record<string, unknown>> = {}) {
     description: overrides.description ?? '',
     job_number: overrides.job_number ?? 9001,
     company_name: overrides.company_name ?? 'Company',
-    contact_person: overrides.contact_person ?? '',
+    person_name: overrides.person_name ?? '',
     people: overrides.people ?? [],
     status: overrides.status ?? 'In Progress',
     status_key: overrides.status_key ?? 'in_progress',
diff --git a/frontend/src/stores/companyStore.ts b/frontend/src/stores/companyStore.ts
index e39f4016b..b4ac9c6e1 100644
--- a/frontend/src/stores/companyStore.ts
+++ b/frontend/src/stores/companyStore.ts
@@ -8,7 +8,7 @@ import type { z } from 'zod'
 type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
 type CompanySearchResponse = z.infer<typeof schemas.CompanySearchResponse>
 type CompanyDetail = z.infer<typeof schemas.CompanyDetailResponse>
-type ClientContact = z.infer<typeof schemas.ClientContact>
+type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
 type CompanyJobsResponse = z.infer<typeof schemas.CompanyJobsResponse>
 
 // Type for company jobs - inferred from generated schema
@@ -35,7 +35,7 @@ export const useCompanyStore = defineStore('companies', () => {
 
   // State - company details and related data
   const detailedCompanies = ref<Record<string, CompanyDetail>>({})
-  const companyContacts = ref<Record<string, ClientContact[]>>({})
+  const companyContacts = ref<Record<string, CompanyPersonLink[]>>({})
   const companyJobs = ref<Record<string, CompanyJob[]>>({})
   const isLoading = ref(false)
   const isLoadingDetail = ref(false)
@@ -107,11 +107,11 @@ export const useCompanyStore = defineStore('companies', () => {
    * Fetch contacts for a specific company
    * @param companyId UUID of the company
    */
-  async function fetchClientContacts(companyId: string) {
+  async function fetchCompanyPersonLinks(companyId: string) {
     isLoadingContacts.value = true
 
     try {
-      const response = await api.companies_contacts_list({
+      const response = await api.companies_person_links_list({
         queries: { company_id: companyId },
       })
       companyContacts.value[companyId] = response
@@ -140,11 +140,11 @@ export const useCompanyStore = defineStore('companies', () => {
    * Get cached company contacts or fetch if not available
    * @param companyId UUID of the company
    */
-  async function getClientContacts(companyId: string): Promise<ClientContact[]> {
+  async function getCompanyPersonLinks(companyId: string): Promise<CompanyPersonLink[]> {
     if (companyContacts.value[companyId]) {
       return companyContacts.value[companyId]
     }
-    return await fetchClientContacts(companyId)
+    return await fetchCompanyPersonLinks(companyId)
   }
 
   /**
@@ -220,10 +220,10 @@ export const useCompanyStore = defineStore('companies', () => {
     // Actions
     fetchCompanies,
     fetchCompanyDetail,
-    fetchClientContacts,
+    fetchCompanyPersonLinks,
     fetchCompanyJobs,
     getCompanyDetail,
-    getClientContacts,
+    getCompanyPersonLinks,
     getCompanyJobs,
     clearCache,
   }
diff --git a/frontend/src/stores/jobs.ts b/frontend/src/stores/jobs.ts
index 46ab4e0b2..087661e38 100644
--- a/frontend/src/stores/jobs.ts
+++ b/frontend/src/stores/jobs.ts
@@ -321,7 +321,7 @@ export const useJobsStore = defineStore('jobs', () => {
           name: detailedJob.job.name,
           status: detailedJob.job.job_status,
           company_name: detailedJob.job.company_name || '',
-          contact_person: detailedJob.job.contact_name || kanbanJob.contact_person,
+          person_name: detailedJob.job.person_name || kanbanJob.person_name,
           paid: detailedJob.job.paid || false,
         },
       }
@@ -488,8 +488,8 @@ export const useJobsStore = defineStore('jobs', () => {
       name: job.name,
       company_id: job.company_id ?? null,
       company_name: job.company_name ?? null,
-      contact_id: job.contact_id ?? null,
-      contact_name: job.contact_name ?? null,
+      person_id: job.person_id ?? null,
+      person_name: job.person_name ?? null,
       status: job.job_status as JobHeaderResponse['status'],
       pricing_methodology: job.pricing_methodology ?? undefined,
       fully_invoiced: job.fully_invoiced,
diff --git a/frontend/src/views/WorkshopKanbanView.vue b/frontend/src/views/WorkshopKanbanView.vue
index ab1e00468..3273705e3 100644
--- a/frontend/src/views/WorkshopKanbanView.vue
+++ b/frontend/src/views/WorkshopKanbanView.vue
@@ -7,7 +7,7 @@ import { Card, CardHeader, CardTitle, CardContent, CardAction } from '@/componen
 import { Skeleton } from '@/components/ui/skeleton'
 import AppLayout from '@/components/AppLayout.vue'
 import router from '@/router'
-import { Contact, NotebookText, Briefcase } from 'lucide-vue-next'
+import { UserRound, NotebookText, Briefcase } from 'lucide-vue-next'
 import StaffAvatar from '@/components/StaffAvatar.vue'
 import { debugLog } from '@/utils/debug'
 import { toast } from 'vue-sonner'
@@ -90,9 +90,9 @@ onMounted(async () => {
                 Description:
                 <span class="text-gray font-medium text-lg">{{ getJobDescription(job) }}</span>
               </div>
-              <div class="text-xl text-black font-semibold" v-if="job.contact_person">
-                <Contact class="inline-block" />
-                Contact: <span class="text-gray font-medium text-lg">{{ job.contact_person }}</span>
+              <div class="text-xl text-black font-semibold" v-if="job.person_name">
+                <UserRound class="inline-block" />
+                Person: <span class="text-gray font-medium text-lg">{{ job.person_name }}</span>
               </div>
             </CardContent>
           </Card>
diff --git a/frontend/src/views/WorkshopView.vue b/frontend/src/views/WorkshopView.vue
index 9db3c04a6..9269c6094 100644
--- a/frontend/src/views/WorkshopView.vue
+++ b/frontend/src/views/WorkshopView.vue
@@ -7,7 +7,7 @@ import { Card, CardHeader, CardTitle, CardContent, CardAction } from '@/componen
 import { Skeleton } from '@/components/ui/skeleton'
 import AppLayout from '@/components/AppLayout.vue'
 import router from '@/router'
-import { Contact, NotebookText, Briefcase } from 'lucide-vue-next'
+import { UserRound, NotebookText, Briefcase } from 'lucide-vue-next'
 import StaffAvatar from '@/components/StaffAvatar.vue'
 import { debugLog } from '@/utils/debug'
 import { toast } from 'vue-sonner'
@@ -90,9 +90,9 @@ onMounted(async () => {
                 Description:
                 <span class="text-gray font-medium text-lg">{{ getJobDescription(job) }}</span>
               </div>
-              <div class="text-xl text-black font-semibold" v-if="job.contact_person">
-                <Contact class="inline-block" />
-                Contact: <span class="text-gray font-medium text-lg">{{ job.contact_person }}</span>
+              <div class="text-xl text-black font-semibold" v-if="job.person_name">
+                <UserRound class="inline-block" />
+                Person: <span class="text-gray font-medium text-lg">{{ job.person_name }}</span>
               </div>
             </CardContent>
           </Card>
@@ -126,9 +126,9 @@ onMounted(async () => {
                 <span class="text-gray font-medium text-lg">{{ getJobDescription(job) }}</span>
               </div> -->
               <Skeleton class="h-4 max-w-50" />
-              <!-- <div class="text-xl text-black font-semibold" v-if="job.contact_person">
-                <Contact class="inline-block" />
-                Contact: <span class="text-gray font-medium text-lg">{{ job.contact_person }}</span>
+              <!-- <div class="text-xl text-black font-semibold" v-if="job.person_name">
+                <UserRound class="inline-block" />
+                Person: <span class="text-gray font-medium text-lg">{{ job.person_name }}</span>
               </div> -->
               <Skeleton class="h-4 max-w-50" />
             </CardContent>
diff --git a/frontend/tests/fixtures/auth.ts b/frontend/tests/fixtures/auth.ts
index bac06118c..cdb93db05 100644
--- a/frontend/tests/fixtures/auth.ts
+++ b/frontend/tests/fixtures/auth.ts
@@ -307,26 +307,24 @@ export const test = base.extend<AuthFixtures, WorkerFixtures>({
         'sharedEditJobUrl: select or create contact',
         SHARED_EDIT_JOB_BUDGET_MS.contactSelection,
         async () => {
-          await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
-          await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+          await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
+          await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
-          const selectButtons = autoId(page, 'ContactSelectionModal-select-button')
+          const selectButtons = autoId(page, 'PersonSelectionModal-select-button')
           const selectButtonCount = await selectButtons.count()
 
           if (selectButtonCount > 0) {
             await selectButtons.first().click()
           } else {
-            const submitButton = autoId(page, 'ContactSelectionModal-submit')
-            await autoId(page, 'ContactSelectionModal-name-input').fill(
-              `[TEST] Contact ${timestamp}`,
-            )
-            await autoId(page, 'ContactSelectionModal-email-input').fill(
+            const submitButton = autoId(page, 'PersonSelectionModal-submit')
+            await autoId(page, 'PersonSelectionModal-name-input').fill(`[TEST] Person ${timestamp}`)
+            await autoId(page, 'PersonSelectionModal-email-input').fill(
               `test${timestamp}@example.com`,
             )
             await submitButton.click()
           }
 
-          await autoId(page, 'ContactSelectionModal-container').waitFor({
+          await autoId(page, 'PersonSelectionModal-container').waitFor({
             state: 'hidden',
             timeout: 10000,
           })
diff --git a/frontend/tests/fixtures/helpers.ts b/frontend/tests/fixtures/helpers.ts
index 74b9de94a..d40f55524 100644
--- a/frontend/tests/fixtures/helpers.ts
+++ b/frontend/tests/fixtures/helpers.ts
@@ -444,36 +444,36 @@ export async function createTestJob(page: Page, jobNameSuffix: string): Promise<
   })
 
   // Select contact
-  await expectStepUnder('createTestJob: open contact modal', 1000, async () => {
-    await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
-    await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+  await expectStepUnder('createTestJob: open person modal', 1000, async () => {
+    await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
+    await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
   })
 
   const selectButtonCount = await expectStepUnder(
-    'createTestJob: inspect contact modal branch',
+    'createTestJob: inspect person modal branch',
     250,
     async () => {
-      const selectButtons = autoId(page, 'ContactSelectionModal-select-button')
+      const selectButtons = autoId(page, 'PersonSelectionModal-select-button')
       return await selectButtons.count()
     },
   )
 
   if (selectButtonCount > 0) {
     await expectStepUnder('createTestJob: select existing contact', 1000, async () => {
-      await autoId(page, 'ContactSelectionModal-select-button').first().click()
+      await autoId(page, 'PersonSelectionModal-select-button').first().click()
     })
   } else {
-    await expectStepUnder('createTestJob: create new contact', 2000, async () => {
-      const submitButton = autoId(page, 'ContactSelectionModal-submit')
-      await expect(submitButton).toHaveText('Create Contact', { timeout: 10000 })
-      await autoId(page, 'ContactSelectionModal-name-input').fill(`[TEST] Contact ${timestamp}`)
-      await autoId(page, 'ContactSelectionModal-email-input').fill(`test${timestamp}@example.com`)
+    await expectStepUnder('createTestJob: create new person', 2000, async () => {
+      const submitButton = autoId(page, 'PersonSelectionModal-submit')
+      await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
+      await autoId(page, 'PersonSelectionModal-name-input').fill(`[TEST] Person ${timestamp}`)
+      await autoId(page, 'PersonSelectionModal-email-input').fill(`test${timestamp}@example.com`)
       await submitButton.click()
     })
   }
 
-  await expectStepUnder('createTestJob: wait for contact modal to close', 1500, async () => {
-    await autoId(page, 'ContactSelectionModal-container').waitFor({
+  await expectStepUnder('createTestJob: wait for person modal to close', 1500, async () => {
+    await autoId(page, 'PersonSelectionModal-container').waitFor({
       state: 'hidden',
       timeout: 10000,
     })
diff --git a/frontend/tests/job/create-job-with-new-company.spec.ts b/frontend/tests/job/create-job-with-new-company.spec.ts
index f6ee85b92..e9d65f937 100644
--- a/frontend/tests/job/create-job-with-new-company.spec.ts
+++ b/frontend/tests/job/create-job-with-new-company.spec.ts
@@ -59,22 +59,22 @@ test.describe('create job with new xero company', () => {
     await autoId(page, 'JobCreateView-estimated-time').fill('4')
 
     // Select contact - click the modal button
-    await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
-    await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+    await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
+    await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
     // For a new company, there won't be existing contacts - fill in the create form
     // The form fields are always visible for new companies
-    await autoId(page, 'ContactSelectionModal-name-input').fill(`[TEST] Contact ${randomSuffix}`)
+    await autoId(page, 'PersonSelectionModal-name-input').fill(`[TEST] Person ${randomSuffix}`)
     await page.waitForTimeout(200)
-    await autoId(page, 'ContactSelectionModal-email-input').fill(`test${randomSuffix}@example.com`)
+    await autoId(page, 'PersonSelectionModal-email-input').fill(`test${randomSuffix}@example.com`)
     await page.waitForTimeout(200)
 
     // Wait for the submit button to be enabled and click it
-    const submitButton = autoId(page, 'ContactSelectionModal-submit')
+    const submitButton = autoId(page, 'PersonSelectionModal-submit')
     await expect(submitButton).toBeEnabled({ timeout: 5000 })
     await submitButton.click()
 
-    await autoId(page, 'ContactSelectionModal-container').waitFor({
+    await autoId(page, 'PersonSelectionModal-container').waitFor({
       state: 'hidden',
       timeout: 10000,
     })
@@ -150,23 +150,23 @@ test.describe('create job with new xero company', () => {
     await autoId(page, 'JobCreateView-estimated-materials').fill('100')
     await autoId(page, 'JobCreateView-estimated-time').fill('2')
 
-    // Handle contact selection
-    await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
-    await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+    // Handle person selection
+    await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
+    await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
     // Fill in contact details
-    await autoId(page, 'ContactSelectionModal-name-input').fill(
+    await autoId(page, 'PersonSelectionModal-name-input').fill(
       `[TEST] Modal Contact ${randomSuffix}`,
     )
     await page.waitForTimeout(200)
-    await autoId(page, 'ContactSelectionModal-email-input').fill(`modal${randomSuffix}@example.com`)
+    await autoId(page, 'PersonSelectionModal-email-input').fill(`modal${randomSuffix}@example.com`)
     await page.waitForTimeout(200)
 
-    const submitButton = autoId(page, 'ContactSelectionModal-submit')
+    const submitButton = autoId(page, 'PersonSelectionModal-submit')
     await expect(submitButton).toBeEnabled({ timeout: 5000 })
     await submitButton.click()
 
-    await autoId(page, 'ContactSelectionModal-container').waitFor({
+    await autoId(page, 'PersonSelectionModal-container').waitFor({
       state: 'hidden',
       timeout: 10000,
     })
diff --git a/frontend/tests/job/create-job.spec.ts b/frontend/tests/job/create-job.spec.ts
index d50d293a8..3cf32977e 100644
--- a/frontend/tests/job/create-job.spec.ts
+++ b/frontend/tests/job/create-job.spec.ts
@@ -11,18 +11,18 @@ import {
 /**
  * Sequential test cases for job creation.
  * These tests MUST run in order as each builds on the previous state:
- * - Test 1: Company has 0 contacts → creates first contact (becomes primary)
+ * - Test 1: Company has 0 contacts → creates first person (becomes primary)
  * - Test 2: Company has 1 contact → creates second contact
- * - Test 3: Company has 2 contacts → selects non-primary contact
+ * - Test 3: Company has 2 contacts → selects non-primary person
  */
 const jobTestCases = [
   {
-    name: 'T&M with first contact',
+    name: 'T&M with first person',
     pricingValue: 'time_materials',
     ballparkMaterials: '500',
     ballparkHours: '4',
     createContact: true,
-    contactToCreate: { name: '[TEST] Contact Person', email: 'test@example.com' },
+    contactToCreate: { name: '[TEST] Person', email: 'test@example.com' },
     expectedTab: 'estimate',
   },
   {
@@ -31,16 +31,16 @@ const jobTestCases = [
     ballparkMaterials: '1000',
     ballparkHours: '8',
     createContact: true,
-    contactToCreate: { name: '[TEST] Another Contact', email: 'another@example.com' },
+    contactToCreate: { name: '[TEST] Another Person', email: 'another@example.com' },
     expectedTab: 'quote',
   },
   {
-    name: 'Fixed Price selecting non-primary contact',
+    name: 'Fixed Price selecting non-primary person',
     pricingValue: 'fixed_price',
     ballparkMaterials: '750',
     ballparkHours: '6',
     createContact: false,
-    contactToSelect: '[TEST] Another Contact', // Select the non-primary contact
+    contactToSelect: '[TEST] Another Person', // Select the non-primary person
     expectedTab: 'quote',
   },
 ] as const
@@ -100,26 +100,26 @@ test.describe.serial('create job', () => {
         'select or create contact person',
         CREATE_JOB_BUDGET_MS.contactSelection,
         async () => {
-          // Click the button to open contact modal
-          console.log('Opening contact modal...')
-          await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
+          // Click the button to open person modal
+          console.log('Opening person modal...')
+          await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
 
           // Wait for modal
           console.log('Waiting for modal...')
-          await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+          await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
           if (tc.createContact && tc.contactToCreate) {
-            console.log(`Creating new contact: ${tc.contactToCreate.name}`)
+            console.log(`Creating new person: ${tc.contactToCreate.name}`)
 
             // Debug: capture button state
-            const submitButton = autoId(page, 'ContactSelectionModal-submit')
+            const submitButton = autoId(page, 'PersonSelectionModal-submit')
             const buttonText = await submitButton.textContent()
             const buttonDisabled = await submitButton.isDisabled()
             console.log(`Button text: "${buttonText}", disabled: ${buttonDisabled}`)
 
-            // Wait for form to be ready - button should show "Create Contact" not "Saving..."
+            // Wait for form to be ready - button should show "Create Person" not "Saving..."
             try {
-              await expect(submitButton).toHaveText('Create Contact', { timeout: 10000 })
+              await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
             } catch (e) {
               // Capture state on failure
               const finalText = await submitButton.textContent()
@@ -128,34 +128,34 @@ test.describe.serial('create job', () => {
               throw e
             }
 
-            // Fill the Create New Contact form
-            await autoId(page, 'ContactSelectionModal-name-input').fill(tc.contactToCreate.name)
-            await autoId(page, 'ContactSelectionModal-email-input').fill(tc.contactToCreate.email)
+            // Fill the Create New Person form
+            await autoId(page, 'PersonSelectionModal-name-input').fill(tc.contactToCreate.name)
+            await autoId(page, 'PersonSelectionModal-email-input').fill(tc.contactToCreate.email)
 
-            // Click Create Contact
+            // Click Create Person
             await submitButton.click()
           } else if (tc.contactToSelect) {
             console.log(`Selecting existing contact: ${tc.contactToSelect}`)
             // Wait for contacts list
-            await autoId(page, 'ContactSelectionModal-select-button')
+            await autoId(page, 'PersonSelectionModal-select-button')
               .first()
               .waitFor({ timeout: 10000 })
 
-            // Find the contact card by name and click its Select button
+            // Find the person card by name and click its Select button
             const contactCard = page
-              .locator(`[data-automation-id^="ContactSelectionModal-card-"]`)
+              .locator(`[data-automation-id^="PersonSelectionModal-card-"]`)
               .filter({
                 hasText: tc.contactToSelect,
               })
             await contactCard.hover()
             await contactCard
-              .locator('[data-automation-id="ContactSelectionModal-select-button"]')
+              .locator('[data-automation-id="PersonSelectionModal-select-button"]')
               .click()
           }
 
           // Wait for modal to close
           console.log('Waiting for modal to close...')
-          await autoId(page, 'ContactSelectionModal-container').waitFor({
+          await autoId(page, 'PersonSelectionModal-container').waitFor({
             state: 'hidden',
             timeout: 10000,
           })
@@ -225,28 +225,28 @@ test.describe('new job default pay item', () => {
         await autoId(page, 'JobCreateView-name-input').fill(jobName)
 
         // Select contact - open modal and create or select one
-        await autoId(page, 'ContactSelector-modal-button').click({ timeout: 10000 })
-        await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+        await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
+        await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
         // Check if there are existing contacts to select
-        const selectButtons = autoId(page, 'ContactSelectionModal-select-button')
+        const selectButtons = autoId(page, 'PersonSelectionModal-select-button')
         const hasExistingContacts = (await selectButtons.count()) > 0
 
         if (hasExistingContacts) {
           // Select the first existing contact
           await selectButtons.first().click()
         } else {
-          // Create a new contact
-          const submitButton = autoId(page, 'ContactSelectionModal-submit')
-          await expect(submitButton).toHaveText('Create Contact', { timeout: 10000 })
-          await autoId(page, 'ContactSelectionModal-name-input').fill(`[TEST] Contact ${timestamp}`)
-          await autoId(page, 'ContactSelectionModal-email-input').fill(
+          // Create a new person
+          const submitButton = autoId(page, 'PersonSelectionModal-submit')
+          await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
+          await autoId(page, 'PersonSelectionModal-name-input').fill(`[TEST] Person ${timestamp}`)
+          await autoId(page, 'PersonSelectionModal-email-input').fill(
             `test${timestamp}@example.com`,
           )
           await submitButton.click()
         }
 
-        await autoId(page, 'ContactSelectionModal-container').waitFor({
+        await autoId(page, 'PersonSelectionModal-container').waitFor({
           state: 'hidden',
           timeout: 10000,
         })
diff --git a/frontend/tests/job/edit-job-settings.spec.ts b/frontend/tests/job/edit-job-settings.spec.ts
index 67dbddc53..8b0cf0c1d 100644
--- a/frontend/tests/job/edit-job-settings.spec.ts
+++ b/frontend/tests/job/edit-job-settings.spec.ts
@@ -462,31 +462,31 @@ test.describe.serial('edit job', () => {
 
     // Navigate to Job Settings tab
     await autoId(page, 'JobViewTabs-jobSettings').click()
-    await autoId(page, 'ContactSelector-modal-button').waitFor({ timeout: 10000 })
+    await autoId(page, 'PersonSelector-modal-button').waitFor({ timeout: 10000 })
     await waitForSettingsInitialized(page)
 
-    await test.step('open contact selection modal', async () => {
-      await autoId(page, 'ContactSelector-modal-button').click()
-      await autoId(page, 'ContactSelectionModal-container').waitFor({ timeout: 10000 })
+    await test.step('open person selection modal', async () => {
+      await autoId(page, 'PersonSelector-modal-button').click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
     })
 
     await expectStepUnder(
-      'create a new contact to switch to',
+      'create a new person to switch to',
       EDIT_JOB_BUDGET_MS.createOrSwitchContact,
       async () => {
         // Wait for the form to be ready
-        const submitButton = autoId(page, 'ContactSelectionModal-submit')
-        await expect(submitButton).toHaveText('Create Contact', { timeout: 10000 })
+        const submitButton = autoId(page, 'PersonSelectionModal-submit')
+        await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
 
         const timestamp = Date.now()
-        await autoId(page, 'ContactSelectionModal-name-input').fill(`New Contact ${timestamp}`)
-        await autoId(page, 'ContactSelectionModal-email-input').fill(
+        await autoId(page, 'PersonSelectionModal-name-input').fill(`New Person ${timestamp}`)
+        await autoId(page, 'PersonSelectionModal-email-input').fill(
           `newcontact${timestamp}@example.com`,
         )
         await submitButton.click()
 
         // Wait for modal to close
-        await autoId(page, 'ContactSelectionModal-container').waitFor({
+        await autoId(page, 'PersonSelectionModal-container').waitFor({
           state: 'hidden',
           timeout: 10000,
         })
@@ -494,8 +494,8 @@ test.describe.serial('edit job', () => {
     )
 
     await test.step('verify contact was updated', async () => {
-      const contactDisplay = autoId(page, 'ContactSelector-display')
-      await expect(contactDisplay).toHaveValue(/New Contact/, { timeout: 10000 })
+      const contactDisplay = autoId(page, 'PersonSelector-display')
+      await expect(contactDisplay).toHaveValue(/New Person/, { timeout: 10000 })
     })
   })
 
diff --git a/frontend/tests/timesheet/urgent-job-defaults.spec.ts b/frontend/tests/timesheet/urgent-job-defaults.spec.ts
index b1f0a39d4..c27347b9c 100644
--- a/frontend/tests/timesheet/urgent-job-defaults.spec.ts
+++ b/frontend/tests/timesheet/urgent-job-defaults.spec.ts
@@ -70,7 +70,7 @@ async function createUrgentJob(page: Page): Promise<{ jobId: string; jobNumber:
       description: '',
       order_number: '',
       notes: '',
-      contact_id: null,
+      person_id: null,
       estimated_materials: 0,
       estimated_time: 0,
       is_urgent: true,
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index 00f144fef..a343b3449 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -91,7 +91,6 @@ apps/accounting/models/invoice.py:0: error: Generator has incompatible item type
 apps/accounting/models/invoice.py:0: error: "BaseXeroInvoiceDocument" has no attribute "line_items"  [attr-defined]
 apps/job/helpers.py:0: error: Argument 1 to "join" has incompatible type "str | None"; expected "str"  [arg-type]
 apps/company/models.py:0: error: Missing type arguments for generic type "QuerySet"  [type-arg]
-apps/company/models.py:0: error: Need type annotation for "CLIENTCONTACT_INTERNAL_FIELDS" (hint: "CLIENTCONTACT_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
 apps/company/models.py:0: error: Incompatible type for lookup 'company_id': (got "UUID | None", expected "UUID | str")  [misc]
 apps/company/models.py:0: error: Need type annotation for "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS" (hint: "SUPPLIERPICKUPADDRESS_INTERNAL_FIELDS: list[<type>] = ...")  [var-annotated]
 apps/workflow/models/company_defaults.py:0: error: Call to untyped function "_recompute_all_staff_wage_rates" in typed context  [no-untyped-call]
@@ -418,7 +417,6 @@ apps/job/tests/test_job_delta_rejection_resolution.py:0: error: Function is miss
 apps/job/tests/test_job_delta_rejection_resolution.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/job/tests/_pdf_golden_fixtures.py:0: error: Call to untyped function "save" in typed context  [no-untyped-call]
 apps/job/tests/_pdf_golden_fixtures.py:0: error: Incompatible types in assignment (expression has type "Company", variable has type "CompanyDefaults")  [assignment]
-apps/job/tests/_pdf_golden_fixtures.py:0: error: Incompatible type for "company" of "ClientContact" (got "CompanyDefaults", expected "Company | Combinable")  [misc]
 apps/job/tests/_pdf_golden_fixtures.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
 apps/job/services/job_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/job/services/job_service.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -479,10 +477,6 @@ apps/job/importers/quote_spreadsheet.py:0: error: Function is missing a type ann
 apps/job/importers/google_sheets.py:0: error: Call to untyped function "from_service_account_file" of "Credentials" in typed context  [no-untyped-call]
 apps/crm/services/phone_call_service.py:0: error: Module "django.utils.timezone" does not explicitly export attribute "timedelta"  [attr-defined]
 apps/crm/services/phone_call_service.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/crm/services/phone_call_service.py:0: error: Dict entry 0 has incompatible type "str": "Company"; expected "str": "ClientContact | None"  [dict-item]
-apps/crm/services/phone_call_service.py:0: error: Item "None" of "ClientContact | None" has no attribute "is_active"  [union-attr]
-apps/crm/services/phone_call_service.py:0: error: Item "None" of "ClientContact | None" has no attribute "company_id"  [union-attr]
-apps/crm/services/phone_call_service.py:0: error: Item "None" of "Company | None" has no attribute "allow_jobs"  [union-attr]
 apps/accounting/services/sales_pipeline_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/accounting/services/sales_pipeline_service.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types in assignment (expression has type "float | None", target has type "float")  [assignment]
@@ -1434,7 +1428,6 @@ apps/company/views/contact_viewset.py:0: error: Function is missing a type annot
 apps/company/views/contact_method_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
 apps/company/views/contact_method_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/views/contact_method_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/company/views/contact_method_viewset.py:0: error: Incompatible type for lookup 'contact_id': (got "str", expected "ClientContact | UUID | None")  [misc]
 apps/workflow/views/data_versions_view.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/workflow/api/reports/job_movement.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/reports/job_movement.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -1556,9 +1549,6 @@ apps/company/views/company_rest_views.py:0: error: Argument 1 to "update_company
 apps/company/views/company_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/company/views/company_rest_views.py:0: error: Incompatible types in assignment (expression has type "CompanyDuplicateErrorResponseSerializer", variable has type "CompanyErrorResponseSerializer")  [assignment]
 apps/company/views/company_rest_views.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/company/views/company_rest_views.py:0: error: Argument 1 to "get_job_contact" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/company/views/company_rest_views.py:0: error: Argument 1 to "update_job_contact" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
-apps/company/views/company_rest_views.py:0: error: Argument 3 to "update_job_contact" of "CompanyRestService" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
 apps/company/views/company_rest_views.py:0: error: Argument 1 to "get_company_jobs" of "CompanyRestService" has incompatible type "str"; expected "UUID"  [arg-type]
 apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/tests/test_company_invoice_summary.py:0: error: Function is missing a type annotation  [no-untyped-def]
@@ -1595,8 +1585,6 @@ apps/job/services/quote_sync_service.py:0: error: Function is missing a type ann
 apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/api/xero/reprocess_xero.py:0: error: Item "None" of "type[InvoiceLineItem] | type[BillLineItem] | type[CreditNoteLineItem] | None" has no attribute "objects"  [union-attr]
 apps/workflow/api/xero/reprocess_xero.py:0: error: Argument after ** must have string keys  [arg-type]
-apps/workflow/api/xero/reprocess_xero.py:0: error: Unsupported operand types for + ("str" and "None")  [operator]
-apps/workflow/api/xero/reprocess_xero.py:0: note: Right operand is of type "Any | None"
 apps/workflow/api/xero/reprocess_xero.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/api/xero/reprocess_xero.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/api/xero/reprocess_xero.py:0: error: Call to untyped function "set_invoice_or_bill_fields" in typed context  [no-untyped-call]
@@ -3723,7 +3711,6 @@ apps/job/services/job_rest_service.py:0: error: "ValueError" has no attribute "d
 apps/job/services/job_rest_service.py:0: error: Assignment to variable "exc" outside except: block  [misc]
 apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
 apps/job/services/job_rest_service.py:0: error: Trying to read deleted variable "exc"  [misc]
-apps/job/services/job_rest_service.py:0: error: Incompatible type for lookup 'company_id': (got "UUID | Any | None", expected "UUID | str")  [misc]
 apps/job/services/job_rest_service.py:0: error: Missing return statement  [return]
 apps/job/services/job_rest_service.py:0: error: Call to untyped function "create_safe" of "JobEvent" in typed context  [no-untyped-call]
 apps/job/services/job_rest_service.py:0: error: Argument "key" to "sort" of "list" has incompatible type "Callable[[dict[str, int | datetime | UUID | str | Any | None]], int | datetime | UUID | str | Any | None]"; expected "Callable[[dict[str, int | datetime | UUID | str | Any | None]], SupportsDunderLT[Any] | SupportsDunderGT[Any]]"  [arg-type]

From 30a53d471807b79aa57b14d44d70f272f139d91b Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 13:05:18 +1200
Subject: [PATCH 08/73] fix: align frontend people terminology

---
 .../src/components/PersonSelectionModal.vue   | 14 ++--
 frontend/src/components/PersonSelector.vue    |  6 +-
 .../__tests__/CompanyLookup.test.ts           |  4 +-
 .../src/components/crm/PhoneNumberManager.vue | 16 ++---
 .../src/components/job/JobSettingsTab.vue     | 64 +++++++++----------
 .../__tests__/usePersonManagement.test.ts     |  2 +-
 frontend/src/composables/useCompanyLookup.ts  | 32 +++++-----
 frontend/src/composables/useJobAutosave.ts    |  2 +-
 .../src/composables/usePersonManagement.ts    |  6 +-
 frontend/src/pages/crm/calls.vue              | 10 +--
 frontend/src/pages/crm/companies/[id].vue     | 46 ++++++-------
 frontend/src/pages/jobs/create.vue            | 18 +++---
 frontend/src/pages/purchasing/po/[id].vue     | 14 ++--
 frontend/src/stores/companyStore.ts           | 28 ++++----
 frontend/tests/fixtures/auth.ts               |  6 +-
 frontend/tests/fixtures/helpers.ts            |  4 +-
 .../job/create-job-with-new-company.spec.ts   |  8 +--
 frontend/tests/job/create-job.spec.ts         | 60 ++++++++---------
 frontend/tests/job/edit-job-settings.spec.ts  | 14 ++--
 frontend/tests/scripts/db-backup-utils.ts     | 12 ++--
 20 files changed, 181 insertions(+), 185 deletions(-)

diff --git a/frontend/src/components/PersonSelectionModal.vue b/frontend/src/components/PersonSelectionModal.vue
index 3ce31380d..4ab90f3ec 100644
--- a/frontend/src/components/PersonSelectionModal.vue
+++ b/frontend/src/components/PersonSelectionModal.vue
@@ -193,7 +193,7 @@
 
           <!-- Create/Edit Person Section -->
           <div
-            class="create-contact-section w-full xl:w-80 2xl:w-96 flex-shrink-0 border-t xl:border-t-0 xl:border-l border-gray-200 pt-4 xl:pt-0 xl:pl-6"
+            class="create-person-section w-full xl:w-80 2xl:w-96 flex-shrink-0 border-t xl:border-t-0 xl:border-l border-gray-200 pt-4 xl:pt-0 xl:pl-6"
           >
             <div class="flex items-center justify-between mb-4">
               <h4 class="section-title text-sm font-semibold text-gray-900">
@@ -461,7 +461,7 @@ const executeDelete = () => {
     min-height: 250px;
   }
 
-  .create-contact-section {
+  .create-person-section {
     width: 100% !important;
     border-top: 1px solid #e5e7eb;
     border-left: none !important;
@@ -487,7 +487,7 @@ const executeDelete = () => {
     min-height: 400px;
   }
 
-  .create-contact-section {
+  .create-person-section {
     width: 280px !important;
     flex-shrink: 0;
     border-top: none !important;
@@ -514,7 +514,7 @@ const executeDelete = () => {
     min-height: 450px;
   }
 
-  .create-contact-section {
+  .create-person-section {
     width: 290px !important;
     flex-shrink: 0;
     border-top: none !important;
@@ -542,7 +542,7 @@ const executeDelete = () => {
     min-height: 500px;
   }
 
-  .create-contact-section {
+  .create-person-section {
     width: 300px !important;
     flex-shrink: 0;
     border-top: none !important;
@@ -558,7 +558,7 @@ const executeDelete = () => {
     max-width: 725px !important;
   }
 
-  .create-contact-section {
+  .create-person-section {
     width: 310px !important;
   }
 }
@@ -616,7 +616,7 @@ const executeDelete = () => {
   min-height: 200px;
 }
 
-.create-contact-section {
+.create-person-section {
   /* Ensure form is always visible and accessible */
   min-height: fit-content;
   max-height: 100%;
diff --git a/frontend/src/components/PersonSelector.vue b/frontend/src/components/PersonSelector.vue
index 34d433454..1e0392283 100644
--- a/frontend/src/components/PersonSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -209,11 +209,11 @@ const handleEditPerson = (person: CompanyPersonLink) => {
   startEditPerson(person)
 }
 
-const handleDeletePerson = async (contactId: string) => {
-  debugLog('PersonSelector - handleDeletePerson:', contactId)
+const handleDeletePerson = async (personLinkId: string) => {
+  debugLog('PersonSelector - handleDeletePerson:', personLinkId)
   toast.info('Deleting person...', { id: 'delete-person' })
 
-  const success = await deletePerson(contactId)
+  const success = await deletePerson(personLinkId)
 
   toast.dismiss('delete-person')
 
diff --git a/frontend/src/components/__tests__/CompanyLookup.test.ts b/frontend/src/components/__tests__/CompanyLookup.test.ts
index 42fe857cb..4c14bd5e1 100644
--- a/frontend/src/components/__tests__/CompanyLookup.test.ts
+++ b/frontend/src/components/__tests__/CompanyLookup.test.ts
@@ -24,13 +24,13 @@ function buildComposableStub(suggestions: Company[]) {
     isLoading: ref(false),
     showSuggestions: ref(true),
     selectedCompany: ref(null),
-    contacts: ref([]),
+    people: ref([]),
     hasValidXeroId: ref(false),
     displayValue: ref(''),
     searchCompanies: vi.fn(),
     selectCompany: vi.fn(),
     loadCompanyPersonLinks: vi.fn(),
-    getPrimaryContact: vi.fn(),
+    getPrimaryPerson: vi.fn(),
     clearSelection: vi.fn(),
     handleInputChange: vi.fn(),
     createNewCompany: vi.fn(),
diff --git a/frontend/src/components/crm/PhoneNumberManager.vue b/frontend/src/components/crm/PhoneNumberManager.vue
index b3d40c393..933796911 100644
--- a/frontend/src/components/crm/PhoneNumberManager.vue
+++ b/frontend/src/components/crm/PhoneNumberManager.vue
@@ -59,8 +59,8 @@
           :disabled="!selectedCompanyId"
         >
           <option value="">No specific person</option>
-          <option v-for="contact in contactOptions" :key="contact.id" :value="contact.person">
-            {{ contact.person_name }}
+          <option v-for="person in personOptions" :key="person.id" :value="person.person">
+            {{ person.person_name }}
           </option>
         </select>
       </div>
@@ -161,9 +161,9 @@ const selectedPersonId = ref('')
 const {
   searchQuery: companySearch,
   suggestions: companyOptions,
-  contacts: contactOptions,
+  people: personOptions,
   browseCompanies,
-  loadCompanyPersonLinks: loadContacts,
+  loadCompanyPersonLinks: loadPeople,
   logSelectedCompanyClick,
 } = useCompanyLookup()
 
@@ -241,7 +241,7 @@ async function editMethod(method: ContactMethod): Promise<void> {
   isPrimary.value = Boolean(method.is_primary)
   selectedCompanyId.value = method.owner_company
   selectedPersonId.value = method.person || ''
-  await loadContacts(method.owner_company)
+  await loadPeople(method.owner_company)
 }
 
 async function deleteMethod(method: ContactMethod): Promise<void> {
@@ -283,7 +283,7 @@ watch(
   () => props.fixedCompanyId,
   (companyId) => {
     selectedCompanyId.value = companyId
-    void loadContacts(companyId)
+    void loadPeople(companyId)
     void loadPhoneMethods().catch((error) => {
       console.error('Failed to reload phone numbers:', error)
       toast.error('Failed to load phone numbers')
@@ -295,11 +295,11 @@ watch(selectedCompanyId, (companyId) => {
   if (!companyId) {
     selectedPersonId.value = ''
   }
-  void loadContacts(companyId)
+  void loadPeople(companyId)
 })
 
 onMounted(() => {
-  void loadContacts(selectedCompanyId.value)
+  void loadPeople(selectedCompanyId.value)
   void loadPhoneMethods().catch((error) => {
     console.error('Failed to load phone numbers:', error)
     toast.error('Failed to load phone numbers')
diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index 85ace8b0c..103c995f7 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -159,7 +159,7 @@
 
             <div>
               <PersonSelector
-                id="contact"
+                id="person"
                 label="Person"
                 :optional="true"
                 :company-id="localJobData.company_id || ''"
@@ -848,17 +848,17 @@ watch(
     // Load person information using the job person endpoint
     // IMPORTANT: Do NOT trigger autosave here - this is just loading initial data
     try {
-      const contactResponse = await api.companies_jobs_person_retrieve({
+      const personResponse = await api.companies_jobs_person_retrieve({
         params: { job_id: newJobData.job_id },
       })
-      if (contactResponse) {
+      if (personResponse) {
         // The response is a single person object
-        localJobData.value.person_id = contactResponse.id
-        localJobData.value.person_name = contactResponse.name
-        personDisplayValue.value = contactResponse.name || ''
+        localJobData.value.person_id = personResponse.id
+        localJobData.value.person_name = personResponse.name
+        personDisplayValue.value = personResponse.name || ''
       }
     } catch (error: unknown) {
-      // Handle 404 when no contact is associated with the job - simply ignore
+      // Handle 404 when no person is associated with the job - simply ignore
       const axiosError = error as { response?: { status?: number } }
       if (axiosError?.response?.status === 404) {
         debugLog('No person associated with this job - ignoring 404')
@@ -1139,42 +1139,42 @@ const handleCompanyUpdated = (updatedCompany: Company) => {
   toast.success('Company updated successfully')
 }
 
-const handlePersonSelected = async (contact: CompanyPersonLink | null) => {
-  if (contact) {
+const handlePersonSelected = async (personLink: CompanyPersonLink | null) => {
+  if (personLink) {
     // Skip API call if person is already set to this value
     // This handles:
     // - Scenario 4: Company change - backend sets person in response, no duplicate API call needed
-    // - User re-selecting the same contact
-    if (localJobData.value.person_id === contact.person) {
+    // - User re-selecting the same person
+    if (localJobData.value.person_id === personLink.person) {
       // Still update display value in case it's stale
-      localJobData.value.person_name = contact.person_name
-      personDisplayValue.value = contact.person_name
+      localJobData.value.person_name = personLink.person_name
+      personDisplayValue.value = personLink.person_name
       return
     }
 
-    localJobData.value.person_id = contact.person
-    localJobData.value.person_name = contact.person_name
-    personDisplayValue.value = contact.person_name
+    localJobData.value.person_id = personLink.person
+    localJobData.value.person_name = personLink.person_name
+    personDisplayValue.value = personLink.person_name
 
     // Ensure all fields are present for Zod validation (convert undefined to null)
-    const contactToSend = {
-      id: contact.person,
-      name: contact.person_name,
-      email: contact.person_email ?? null,
+    const personToSend = {
+      id: personLink.person,
+      name: personLink.person_name,
+      email: personLink.person_email ?? null,
     } satisfies z.input<typeof schemas.JobPersonUpdateRequest>
 
     // Save person directly (not through header autosave)
     try {
-      await api.companies_jobs_person_update(contactToSend, {
+      await api.companies_jobs_person_update(personToSend, {
         params: { job_id: props.jobId },
       })
       toast.success('Person updated successfully')
     } catch (error) {
-      toast.error('Failed to update contact')
-      console.error('Failed to update contact:', error)
+      toast.error('Failed to update person')
+      console.error('Failed to update person:', error)
     }
   } else {
-    // Clear person locally - no API call needed since clearing means no contact association
+    // Clear person locally - no API call needed since clearing means no person association
     localJobData.value.person_id = undefined
     localJobData.value.person_name = undefined
     personDisplayValue.value = ''
@@ -1561,19 +1561,19 @@ const autosave = createJobAutosave({
           headerPatch.company_id = companyId
           headerPatch.company_name = companyName
 
-          // Note: When no serverJobDetail, we can't get the auto-set contact
+          // Note: When no serverJobDetail, we can't get the auto-set person
           // The PersonSelector will re-fetch people for the new company
         }
         if (touchedKeys.includes('person_id')) {
-          const contactId = coerceNullableString(partialPayload.person_id)
-          nextBaseline.person_id = contactId
-          localJobData.value.person_id = contactId
+          const personId = coerceNullableString(partialPayload.person_id)
+          nextBaseline.person_id = personId
+          localJobData.value.person_id = personId
         }
         if (touchedKeys.includes('person_name')) {
-          const contactName = coerceNullableString(partialPayload.person_name)
-          nextBaseline.person_name = contactName
-          localJobData.value.person_name = contactName
-          personDisplayValue.value = contactName ?? ''
+          const personName = coerceNullableString(partialPayload.person_name)
+          nextBaseline.person_name = personName
+          localJobData.value.person_name = personName
+          personDisplayValue.value = personName ?? ''
         }
       }
 
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
index d7a5ba44d..48d95d493 100644
--- a/frontend/src/composables/__tests__/usePersonManagement.test.ts
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -70,7 +70,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
     expect(displayValue.get()).toBe('Jane Doe')
   })
 
-  it('set() splits "name - phone - email" into the selected contact', () => {
+  it('set() splits "name - phone - email" into the selected person', () => {
     const { displayValue, setSelectedPerson, selectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson())
 
diff --git a/frontend/src/composables/useCompanyLookup.ts b/frontend/src/composables/useCompanyLookup.ts
index eb3b99f6c..531f513a9 100644
--- a/frontend/src/composables/useCompanyLookup.ts
+++ b/frontend/src/composables/useCompanyLookup.ts
@@ -45,7 +45,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
   const isLoading = ref(false)
   const showSuggestions = ref(false)
   const selectedCompany = ref<Company | null>(null)
-  const contacts = ref<CompanyPersonLink[]>([])
+  const people = ref<CompanyPersonLink[]>([])
 
   const hasValidXeroId = computed(() => {
     debugLog('Selected company value: ', selectedCompany.value)
@@ -136,14 +136,14 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     searchQuery.value = company.name
     showSuggestions.value = false
 
-    contacts.value = []
+    people.value = []
 
     await loadCompanyPersonLinks(company.id)
   }
 
   const loadCompanyPersonLinks = async (companyId: string) => {
     if (!companyId) {
-      contacts.value = []
+      people.value = []
       return
     }
 
@@ -151,22 +151,22 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
       const response = await api.companies_person_links_list({
         queries: { company_id: companyId },
       })
-      contacts.value = response || []
+      people.value = response || []
     } catch (error) {
-      console.error('Error loading company contacts:', error)
-      contacts.value = []
-      toast.error('Failed to load company contacts')
+      console.error('Error loading company people:', error)
+      people.value = []
+      toast.error('Failed to load company people')
     }
   }
 
-  const getPrimaryContact = (): CompanyPersonLink | null => {
-    if (contacts.value.length === 0) {
+  const getPrimaryPerson = (): CompanyPersonLink | null => {
+    if (people.value.length === 0) {
       return null
     }
 
-    const primaryContact = contacts.value.find((contact) => contact.is_primary)
+    const primaryPerson = people.value.find((person) => person.is_primary)
 
-    return primaryContact || contacts.value[0]
+    return primaryPerson || people.value[0]
   }
 
   const clearSelection = () => {
@@ -174,7 +174,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     searchQuery.value = ''
     suggestions.value = []
     showSuggestions.value = false
-    contacts.value = []
+    people.value = []
   }
 
   const resetToInitialState = () => {
@@ -183,7 +183,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
       searchQuery.value = ''
       suggestions.value = []
       showSuggestions.value = false
-      contacts.value = []
+      people.value = []
     }
   }
 
@@ -205,7 +205,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
 
     if (selectedCompany.value && selectedCompany.value.name !== value) {
       selectedCompany.value = null
-      contacts.value = []
+      people.value = []
     }
 
     if (value.length >= 3) {
@@ -249,7 +249,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     isLoading,
     showSuggestions,
     selectedCompany,
-    contacts,
+    people,
 
     hasValidXeroId,
     displayValue,
@@ -259,7 +259,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     logSelectedCompanyClick,
     selectCompany,
     loadCompanyPersonLinks,
-    getPrimaryContact,
+    getPrimaryPerson,
     clearSelection,
     handleInputChange,
     createNewCompany,
diff --git a/frontend/src/composables/useJobAutosave.ts b/frontend/src/composables/useJobAutosave.ts
index 4a9f39047..fef225d98 100644
--- a/frontend/src/composables/useJobAutosave.ts
+++ b/frontend/src/composables/useJobAutosave.ts
@@ -319,7 +319,7 @@ export function createJobAutosave(opts: JobAutosaveOptions): JobAutosaveApi {
       ('person_id' in effectivePatch || 'person_name' in effectivePatch) &&
       !virtualSnapshot['company_id']
     ) {
-      log('⛔ canSave=false (contact_* change without company_id)', { reason })
+      log('canSave=false (person_* change without company_id)', { reason })
       return
     }
 
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
index df3560416..cb72a9e19 100644
--- a/frontend/src/composables/usePersonManagement.ts
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -134,7 +134,7 @@ export function usePersonManagement() {
       people.value = response || []
       personForm.value.is_primary = people.value.length === 0
     } catch (error) {
-      debugLog('Error loading contacts:', error)
+      debugLog('Error loading people:', error)
       people.value = []
       personForm.value.is_primary = true
     } finally {
@@ -380,7 +380,7 @@ export function usePersonManagement() {
         selectedPerson.value = null
       }
 
-      // Clear editing state if we were editing the deleted contact
+      // Clear editing state if we were editing the deleted person
       if (editingPersonLink.value?.id === personLinkId) {
         cancelEdit()
       }
@@ -420,7 +420,7 @@ export function usePersonManagement() {
   }
 
   /**
-   * Clears the currently selected contact
+   * Clears the currently selected person
    */
   const clearSelection = () => {
     selectedPerson.value = null
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index 7481ad058..1906e1f37 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -122,8 +122,8 @@
               :disabled="!selectedCompanyId"
             >
               <option value="">No specific person</option>
-              <option v-for="contact in contactOptions" :key="contact.id" :value="contact.person">
-                {{ contact.person_name }}
+              <option v-for="person in personOptions" :key="person.id" :value="person.person">
+                {{ person.person_name }}
               </option>
             </select>
           </div>
@@ -209,7 +209,7 @@ let unsubscribeCrmCallsFreshness: (() => void) | null = null
 const {
   searchQuery: companySearch,
   suggestions: companyOptions,
-  contacts: contactOptions,
+  people: personOptions,
   browseCompanies: searchCompanies,
   loadCompanyPersonLinks,
   logSelectedCompanyClick,
@@ -283,7 +283,7 @@ function handleAssignNumber(call: PhoneCallRecord): void {
   phoneLabel.value = ''
   isPrimary.value = false
   companyOptions.value = []
-  contactOptions.value = []
+  personOptions.value = []
   toast.info('Select a company for this call number')
 }
 
@@ -329,7 +329,7 @@ function resetAssignmentForm(): void {
   selectedCall.value = null
   companySearch.value = ''
   companyOptions.value = []
-  contactOptions.value = []
+  personOptions.value = []
   selectedCompanyId.value = ''
   selectedPersonId.value = ''
   phoneLabel.value = ''
diff --git a/frontend/src/pages/crm/companies/[id].vue b/frontend/src/pages/crm/companies/[id].vue
index e839d4075..88a2f7365 100644
--- a/frontend/src/pages/crm/companies/[id].vue
+++ b/frontend/src/pages/crm/companies/[id].vue
@@ -49,7 +49,7 @@
         <TabsList class="grid w-full grid-cols-4">
           <TabsTrigger value="details">
             <FileText class="w-4 h-4 mr-2" />
-            Details & Contacts
+            Details & People
           </TabsTrigger>
           <TabsTrigger value="financial">
             <DollarSign class="w-4 h-4 mr-2" />
@@ -65,7 +65,7 @@
           </TabsTrigger>
         </TabsList>
 
-        <!-- Details & Contacts Tab -->
+        <!-- Details & People Tab -->
         <TabsContent value="details" class="space-y-6 mt-6">
           <!-- Basic Information -->
           <Card>
@@ -158,42 +158,42 @@
             </CardContent>
           </Card>
 
-          <!-- Contact Persons -->
+          <!-- People -->
           <Card>
             <CardHeader>
-              <CardTitle>Contact Persons</CardTitle>
+              <CardTitle>People</CardTitle>
             </CardHeader>
             <CardContent>
               <div
-                v-if="companyStore.isLoadingContacts"
+                v-if="companyStore.isLoadingPeople"
                 class="flex items-center justify-center py-8"
               >
                 <Loader2 class="w-6 h-6 animate-spin text-indigo-600" />
               </div>
-              <div v-else-if="contacts.length === 0" class="text-center py-8 text-gray-500">
+              <div v-else-if="people.length === 0" class="text-center py-8 text-gray-500">
                 <UserCircle class="w-12 h-12 mx-auto mb-2 text-gray-400" />
-                <p>No additional contacts</p>
+                <p>No additional people</p>
               </div>
               <div v-else class="space-y-3">
                 <div
-                  v-for="contact in contacts"
-                  :key="contact.id"
+                  v-for="person in people"
+                  :key="person.id"
                   class="flex items-start gap-3 p-3 border border-gray-200 rounded-lg"
                 >
                   <UserCircle class="w-5 h-5 text-gray-400 mt-0.5" />
                   <div class="flex-1">
                     <div class="flex items-center gap-2">
-                      <p class="font-medium text-gray-900">{{ contact.person_name }}</p>
-                      <Badge v-if="contact.is_primary" variant="default" class="text-xs"
+                      <p class="font-medium text-gray-900">{{ person.person_name }}</p>
+                      <Badge v-if="person.is_primary" variant="default" class="text-xs"
                         >Primary</Badge
                       >
                     </div>
-                    <p v-if="contact.position" class="text-sm text-gray-500">
-                      {{ contact.position }}
+                    <p v-if="person.position" class="text-sm text-gray-500">
+                      {{ person.position }}
                     </p>
                     <div class="flex flex-col gap-1 mt-1 text-sm text-gray-600">
-                      <span v-if="contact.person_email">{{ contact.person_email }}</span>
-                      <span v-if="contact.phone">{{ contact.phone }}</span>
+                      <span v-if="person.person_email">{{ person.person_email }}</span>
+                      <span v-if="person.phone">{{ person.phone }}</span>
                     </div>
                   </div>
                 </div>
@@ -461,12 +461,12 @@ const company = computed(() => {
   return companyStore.detailedCompanies[props.id]
 })
 
-const contacts = computed(() => {
-  return companyStore.companyContacts[props.id] || []
+const people = computed(() => {
+  return companyStore.companyPeople[props.id] || []
 })
 
 const primaryPerson = computed(() => {
-  return contacts.value.find((contact) => contact.is_primary) ?? contacts.value[0] ?? null
+  return people.value.find((person) => person.is_primary) ?? people.value[0] ?? null
 })
 
 const relatedJobs = computed(() => {
@@ -490,10 +490,10 @@ const allowJobsBlockedReason = computed<string | null>(() => {
   const current = company.value
   if (!current) return null
   if (current.merged_into) {
-    return 'Blocked because this contact was merged into another company in Xero.'
+    return 'Blocked because this Xero contact was merged into another company in Xero.'
   }
   if (current.xero_archived) {
-    return 'Blocked because this contact is archived in Xero.'
+    return 'Blocked because this Xero contact is archived in Xero.'
   }
   return null
 })
@@ -614,12 +614,12 @@ async function loadCompanyData() {
     // Load supplier aliases
     await loadSupplierAliases()
 
-    // Load contacts
+    // Load people
     try {
       await companyStore.fetchCompanyPersonLinks(props.id)
     } catch (err) {
-      console.error('Failed to load contacts:', err)
-      // Don't show error for contacts, just log it
+      console.error('Failed to load people:', err)
+      // Don't show error for people, just log it
     }
 
     // Load related jobs
diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index 97703d0af..9d3b88766 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -59,7 +59,7 @@
                 <div>
                   <PersonSelector
                     ref="personSelectorRef"
-                    id="contact"
+                    id="person"
                     v-model="personDisplayName"
                     :company-id="formData.company_id as string"
                     :company-name="companyDisplayName"
@@ -322,12 +322,12 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
   debugLog('JobCreateView - handleCompanySelection:', {
     company,
     previousCompanyId: formData.value.company_id,
-    previousContactId: formData.value.person_id,
+    previousPersonId: formData.value.person_id,
   })
 
   selectedCompany.value = company
 
-  // Always clear contact person when company changes (even if same company selected)
+  // Always clear person when company changes (even if same company selected)
   formData.value.person_id = null
   selectedPerson.value = null
   personDisplayName.value = ''
@@ -353,7 +353,7 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
     if (personSelectorRef.value) {
       debugLog('JobCreateView - Calling selectPrimaryPerson')
       // The `selectPrimaryPerson` method within the composable
-      // will handle loading contacts and finding the primary.
+      // will handle loading people and finding the primary.
       await personSelectorRef.value.selectPrimaryPerson()
     }
   } else {
@@ -364,12 +364,12 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
   }
 }
 
-const updateSelectedPerson = (contact: CompanyPersonLink | null) => {
-  selectedPerson.value = contact
-  if (contact) {
+const updateSelectedPerson = (personLink: CompanyPersonLink | null) => {
+  selectedPerson.value = personLink
+  if (personLink) {
     // Save the person ID for the API and display name for the UI
-    formData.value.person_id = contact.person
-    personDisplayName.value = contact.person_name
+    formData.value.person_id = personLink.person
+    personDisplayName.value = personLink.person_name
   } else {
     formData.value.person_id = null
     personDisplayName.value = ''
diff --git a/frontend/src/pages/purchasing/po/[id].vue b/frontend/src/pages/purchasing/po/[id].vue
index 8036cc031..078f721a6 100644
--- a/frontend/src/pages/purchasing/po/[id].vue
+++ b/frontend/src/pages/purchasing/po/[id].vue
@@ -811,16 +811,14 @@ async function resolveSupplierEmail(): Promise<string | null> {
   }
 
   try {
-    const contacts = await api.companies_person_links_list({
+    const people = await api.companies_person_links_list({
       queries: { company_id: supplierId },
     })
 
-    const contactsArray: CompanyPersonLink[] = Array.isArray(contacts) ? contacts : []
-    const primaryContact = contactsArray.find(
-      (contact) => contact.is_primary && !!contact.person_email,
-    )
-    const fallbackContact = contactsArray.find((contact) => !!contact.person_email)
-    const resolvedEmail = primaryContact?.person_email ?? fallbackContact?.person_email ?? null
+    const peopleArray: CompanyPersonLink[] = Array.isArray(people) ? people : []
+    const primaryPerson = peopleArray.find((person) => person.is_primary && !!person.person_email)
+    const fallbackPerson = peopleArray.find((person) => !!person.person_email)
+    const resolvedEmail = primaryPerson?.person_email ?? fallbackPerson?.person_email ?? null
 
     supplierEmailCache.value = {
       ...supplierEmailCache.value,
@@ -829,7 +827,7 @@ async function resolveSupplierEmail(): Promise<string | null> {
 
     return resolvedEmail
   } catch (err) {
-    debugLog('Failed to resolve supplier contacts for email:', err)
+    debugLog('Failed to resolve supplier people for email:', err)
     supplierEmailCache.value = {
       ...supplierEmailCache.value,
       [supplierId]: null,
diff --git a/frontend/src/stores/companyStore.ts b/frontend/src/stores/companyStore.ts
index b4ac9c6e1..b13d61652 100644
--- a/frontend/src/stores/companyStore.ts
+++ b/frontend/src/stores/companyStore.ts
@@ -35,11 +35,11 @@ export const useCompanyStore = defineStore('companies', () => {
 
   // State - company details and related data
   const detailedCompanies = ref<Record<string, CompanyDetail>>({})
-  const companyContacts = ref<Record<string, CompanyPersonLink[]>>({})
+  const companyPeople = ref<Record<string, CompanyPersonLink[]>>({})
   const companyJobs = ref<Record<string, CompanyJob[]>>({})
   const isLoading = ref(false)
   const isLoadingDetail = ref(false)
-  const isLoadingContacts = ref(false)
+  const isLoadingPeople = ref(false)
   const isLoadingJobs = ref(false)
 
   // Getters
@@ -104,24 +104,24 @@ export const useCompanyStore = defineStore('companies', () => {
   }
 
   /**
-   * Fetch contacts for a specific company
+   * Fetch people for a specific company
    * @param companyId UUID of the company
    */
   async function fetchCompanyPersonLinks(companyId: string) {
-    isLoadingContacts.value = true
+    isLoadingPeople.value = true
 
     try {
       const response = await api.companies_person_links_list({
         queries: { company_id: companyId },
       })
-      companyContacts.value[companyId] = response
+      companyPeople.value[companyId] = response
       return response
     } catch (error) {
-      console.error('Failed to fetch company contacts:', error)
-      companyContacts.value[companyId] = []
+      console.error('Failed to fetch company people:', error)
+      companyPeople.value[companyId] = []
       throw error
     } finally {
-      isLoadingContacts.value = false
+      isLoadingPeople.value = false
     }
   }
 
@@ -137,12 +137,12 @@ export const useCompanyStore = defineStore('companies', () => {
   }
 
   /**
-   * Get cached company contacts or fetch if not available
+   * Get cached company people or fetch if not available
    * @param companyId UUID of the company
    */
   async function getCompanyPersonLinks(companyId: string): Promise<CompanyPersonLink[]> {
-    if (companyContacts.value[companyId]) {
-      return companyContacts.value[companyId]
+    if (companyPeople.value[companyId]) {
+      return companyPeople.value[companyId]
     }
     return await fetchCompanyPersonLinks(companyId)
   }
@@ -186,7 +186,7 @@ export const useCompanyStore = defineStore('companies', () => {
   function clearCache() {
     companies.value = []
     detailedCompanies.value = {}
-    companyContacts.value = {}
+    companyPeople.value = {}
     companyJobs.value = {}
     searchQuery.value = ''
     page.value = 1
@@ -207,11 +207,11 @@ export const useCompanyStore = defineStore('companies', () => {
 
     // State - other
     detailedCompanies,
-    companyContacts,
+    companyPeople,
     companyJobs,
     isLoading,
     isLoadingDetail,
-    isLoadingContacts,
+    isLoadingPeople,
     isLoadingJobs,
 
     // Getters
diff --git a/frontend/tests/fixtures/auth.ts b/frontend/tests/fixtures/auth.ts
index cdb93db05..97ef975c3 100644
--- a/frontend/tests/fixtures/auth.ts
+++ b/frontend/tests/fixtures/auth.ts
@@ -37,7 +37,7 @@ const SHARED_EDIT_JOB_BUDGET_MS = {
   navigateToCreatePage: 2500,
   searchAndSelectCompany: 1500,
   fillJobDetails: 1000,
-  contactSelection: 2500,
+  personSelection: 2500,
   submitAndRedirect: 3500,
 } as const
 
@@ -304,8 +304,8 @@ export const test = base.extend<AuthFixtures, WorkerFixtures>({
       )
 
       await expectStepUnder(
-        'sharedEditJobUrl: select or create contact',
-        SHARED_EDIT_JOB_BUDGET_MS.contactSelection,
+        'sharedEditJobUrl: select or create person',
+        SHARED_EDIT_JOB_BUDGET_MS.personSelection,
         async () => {
           await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
           await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
diff --git a/frontend/tests/fixtures/helpers.ts b/frontend/tests/fixtures/helpers.ts
index d40f55524..acc678d08 100644
--- a/frontend/tests/fixtures/helpers.ts
+++ b/frontend/tests/fixtures/helpers.ts
@@ -443,7 +443,7 @@ export async function createTestJob(page: Page, jobNameSuffix: string): Promise<
     await autoId(page, 'JobCreateView-estimated-time').fill('0')
   })
 
-  // Select contact
+  // Select person
   await expectStepUnder('createTestJob: open person modal', 1000, async () => {
     await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
     await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
@@ -459,7 +459,7 @@ export async function createTestJob(page: Page, jobNameSuffix: string): Promise<
   )
 
   if (selectButtonCount > 0) {
-    await expectStepUnder('createTestJob: select existing contact', 1000, async () => {
+    await expectStepUnder('createTestJob: select existing person', 1000, async () => {
       await autoId(page, 'PersonSelectionModal-select-button').first().click()
     })
   } else {
diff --git a/frontend/tests/job/create-job-with-new-company.spec.ts b/frontend/tests/job/create-job-with-new-company.spec.ts
index e9d65f937..6b76dc37a 100644
--- a/frontend/tests/job/create-job-with-new-company.spec.ts
+++ b/frontend/tests/job/create-job-with-new-company.spec.ts
@@ -58,11 +58,11 @@ test.describe('create job with new xero company', () => {
     await autoId(page, 'JobCreateView-estimated-materials').fill('500')
     await autoId(page, 'JobCreateView-estimated-time').fill('4')
 
-    // Select contact - click the modal button
+    // Select person - click the modal button
     await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
     await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
-    // For a new company, there won't be existing contacts - fill in the create form
+    // For a new company, there won't be existing persons - fill in the create form
     // The form fields are always visible for new companies
     await autoId(page, 'PersonSelectionModal-name-input').fill(`[TEST] Person ${randomSuffix}`)
     await page.waitForTimeout(200)
@@ -154,9 +154,9 @@ test.describe('create job with new xero company', () => {
     await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
     await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
-    // Fill in contact details
+    // Fill in person details
     await autoId(page, 'PersonSelectionModal-name-input').fill(
-      `[TEST] Modal Contact ${randomSuffix}`,
+      `[TEST] Modal Person ${randomSuffix}`,
     )
     await page.waitForTimeout(200)
     await autoId(page, 'PersonSelectionModal-email-input').fill(`modal${randomSuffix}@example.com`)
diff --git a/frontend/tests/job/create-job.spec.ts b/frontend/tests/job/create-job.spec.ts
index 3cf32977e..c004fe17f 100644
--- a/frontend/tests/job/create-job.spec.ts
+++ b/frontend/tests/job/create-job.spec.ts
@@ -11,9 +11,9 @@ import {
 /**
  * Sequential test cases for job creation.
  * These tests MUST run in order as each builds on the previous state:
- * - Test 1: Company has 0 contacts → creates first person (becomes primary)
- * - Test 2: Company has 1 contact → creates second contact
- * - Test 3: Company has 2 contacts → selects non-primary person
+ * - Test 1: Company has 0 people → creates first person (becomes primary)
+ * - Test 2: Company has 1 person → creates second person
+ * - Test 3: Company has 2 people → selects non-primary person
  */
 const jobTestCases = [
   {
@@ -21,17 +21,17 @@ const jobTestCases = [
     pricingValue: 'time_materials',
     ballparkMaterials: '500',
     ballparkHours: '4',
-    createContact: true,
-    contactToCreate: { name: '[TEST] Person', email: 'test@example.com' },
+    createPerson: true,
+    personToCreate: { name: '[TEST] Person', email: 'test@example.com' },
     expectedTab: 'estimate',
   },
   {
-    name: 'Fixed Price with second contact',
+    name: 'Fixed Price with second person',
     pricingValue: 'fixed_price',
     ballparkMaterials: '1000',
     ballparkHours: '8',
-    createContact: true,
-    contactToCreate: { name: '[TEST] Another Person', email: 'another@example.com' },
+    createPerson: true,
+    personToCreate: { name: '[TEST] Another Person', email: 'another@example.com' },
     expectedTab: 'quote',
   },
   {
@@ -39,8 +39,8 @@ const jobTestCases = [
     pricingValue: 'fixed_price',
     ballparkMaterials: '750',
     ballparkHours: '6',
-    createContact: false,
-    contactToSelect: '[TEST] Another Person', // Select the non-primary person
+    createPerson: false,
+    personToSelect: '[TEST] Another Person', // Select the non-primary person
     expectedTab: 'quote',
   },
 ] as const
@@ -48,7 +48,7 @@ const jobTestCases = [
 const CREATE_JOB_BUDGET_MS = {
   navigateToCreatePage: 2500,
   searchAndSelectCompany: 1500,
-  contactSelection: 2500,
+  personSelection: 2500,
   submitAndRedirect: 3500,
   defaultPayItemCreateJob: 4500,
   defaultPayItemSettingsLoad: 2500,
@@ -57,7 +57,7 @@ const CREATE_JOB_BUDGET_MS = {
 // Use describe.serial to ensure tests run in order (they depend on each other)
 test.describe.serial('create job', () => {
   for (const tc of jobTestCases) {
-    test(`create ${tc.name} job with company and contact`, async ({ authenticatedPage: page }) => {
+    test(`create ${tc.name} job with company and person`, async ({ authenticatedPage: page }) => {
       // Generate unique job name to avoid conflicts
       const timestamp = Date.now()
       const jobName = `[TEST] Job ${tc.name} ${timestamp}`
@@ -97,8 +97,8 @@ test.describe.serial('create job', () => {
       })
 
       await expectStepUnder(
-        'select or create contact person',
-        CREATE_JOB_BUDGET_MS.contactSelection,
+        'select or create person',
+        CREATE_JOB_BUDGET_MS.personSelection,
         async () => {
           // Click the button to open person modal
           console.log('Opening person modal...')
@@ -108,8 +108,8 @@ test.describe.serial('create job', () => {
           console.log('Waiting for modal...')
           await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
-          if (tc.createContact && tc.contactToCreate) {
-            console.log(`Creating new person: ${tc.contactToCreate.name}`)
+          if (tc.createPerson && tc.personToCreate) {
+            console.log(`Creating new person: ${tc.personToCreate.name}`)
 
             // Debug: capture button state
             const submitButton = autoId(page, 'PersonSelectionModal-submit')
@@ -129,26 +129,26 @@ test.describe.serial('create job', () => {
             }
 
             // Fill the Create New Person form
-            await autoId(page, 'PersonSelectionModal-name-input').fill(tc.contactToCreate.name)
-            await autoId(page, 'PersonSelectionModal-email-input').fill(tc.contactToCreate.email)
+            await autoId(page, 'PersonSelectionModal-name-input').fill(tc.personToCreate.name)
+            await autoId(page, 'PersonSelectionModal-email-input').fill(tc.personToCreate.email)
 
             // Click Create Person
             await submitButton.click()
-          } else if (tc.contactToSelect) {
-            console.log(`Selecting existing contact: ${tc.contactToSelect}`)
-            // Wait for contacts list
+          } else if (tc.personToSelect) {
+            console.log(`Selecting existing person: ${tc.personToSelect}`)
+            // Wait for people list
             await autoId(page, 'PersonSelectionModal-select-button')
               .first()
               .waitFor({ timeout: 10000 })
 
             // Find the person card by name and click its Select button
-            const contactCard = page
+            const personCard = page
               .locator(`[data-automation-id^="PersonSelectionModal-card-"]`)
               .filter({
-                hasText: tc.contactToSelect,
+                hasText: tc.personToSelect,
               })
-            await contactCard.hover()
-            await contactCard
+            await personCard.hover()
+            await personCard
               .locator('[data-automation-id="PersonSelectionModal-select-button"]')
               .click()
           }
@@ -224,16 +224,16 @@ test.describe('new job default pay item', () => {
         // Enter job name
         await autoId(page, 'JobCreateView-name-input').fill(jobName)
 
-        // Select contact - open modal and create or select one
+        // Select person - open modal and create or select one
         await autoId(page, 'PersonSelector-modal-button').click({ timeout: 10000 })
         await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
 
-        // Check if there are existing contacts to select
+        // Check if there are existing persons to select
         const selectButtons = autoId(page, 'PersonSelectionModal-select-button')
-        const hasExistingContacts = (await selectButtons.count()) > 0
+        const hasExistingPeople = (await selectButtons.count()) > 0
 
-        if (hasExistingContacts) {
-          // Select the first existing contact
+        if (hasExistingPeople) {
+          // Select the first existing person
           await selectButtons.first().click()
         } else {
           // Create a new person
diff --git a/frontend/tests/job/edit-job-settings.spec.ts b/frontend/tests/job/edit-job-settings.spec.ts
index 8b0cf0c1d..372af952d 100644
--- a/frontend/tests/job/edit-job-settings.spec.ts
+++ b/frontend/tests/job/edit-job-settings.spec.ts
@@ -15,7 +15,7 @@ const EDIT_JOB_BUDGET_MS = {
   verifyAfterRefresh: 3000,
   reloadVerify: 3500,
   changeCompanyFlow: 2000,
-  createOrSwitchContact: 2000,
+  createOrSwitchPerson: 2000,
 } as const
 
 /**
@@ -456,7 +456,7 @@ test.describe.serial('edit job', () => {
     )
   })
 
-  test('change contact person', async ({ authenticatedPage: page, sharedEditJobUrl }) => {
+  test('change person', async ({ authenticatedPage: page, sharedEditJobUrl }) => {
     await page.goto(sharedEditJobUrl)
     await page.waitForLoadState('networkidle')
 
@@ -472,7 +472,7 @@ test.describe.serial('edit job', () => {
 
     await expectStepUnder(
       'create a new person to switch to',
-      EDIT_JOB_BUDGET_MS.createOrSwitchContact,
+      EDIT_JOB_BUDGET_MS.createOrSwitchPerson,
       async () => {
         // Wait for the form to be ready
         const submitButton = autoId(page, 'PersonSelectionModal-submit')
@@ -481,7 +481,7 @@ test.describe.serial('edit job', () => {
         const timestamp = Date.now()
         await autoId(page, 'PersonSelectionModal-name-input').fill(`New Person ${timestamp}`)
         await autoId(page, 'PersonSelectionModal-email-input').fill(
-          `newcontact${timestamp}@example.com`,
+          `newperson${timestamp}@example.com`,
         )
         await submitButton.click()
 
@@ -493,9 +493,9 @@ test.describe.serial('edit job', () => {
       },
     )
 
-    await test.step('verify contact was updated', async () => {
-      const contactDisplay = autoId(page, 'PersonSelector-display')
-      await expect(contactDisplay).toHaveValue(/New Person/, { timeout: 10000 })
+    await test.step('verify person was updated', async () => {
+      const personDisplay = autoId(page, 'PersonSelector-display')
+      await expect(personDisplay).toHaveValue(/New Person/, { timeout: 10000 })
     })
   })
 
diff --git a/frontend/tests/scripts/db-backup-utils.ts b/frontend/tests/scripts/db-backup-utils.ts
index 630704059..9fbcdfb35 100644
--- a/frontend/tests/scripts/db-backup-utils.ts
+++ b/frontend/tests/scripts/db-backup-utils.ts
@@ -222,15 +222,13 @@ export function checkSafeToTest(dbConfig: DbConfig): SafetyCheckResult {
     issues.push(`${testJobCount} test jobs found (names starting with '${TEST_DATA_PREFIX}')`)
   }
 
-  // Check for [TEST]-prefixed contacts
-  const testContactCount = runPsql(
+  // Check for [TEST]-prefixed people
+  const testPersonCount = runPsql(
     dbConfig,
-    `SELECT COUNT(*) FROM company_clientcontact WHERE name LIKE '${prefix}%'`,
+    `SELECT COUNT(*) FROM company_person WHERE name LIKE '${prefix}%'`,
   )
-  if (parseInt(testContactCount) > 0) {
-    issues.push(
-      `${testContactCount} test contacts found (names starting with '${TEST_DATA_PREFIX}')`,
-    )
+  if (parseInt(testPersonCount) > 0) {
+    issues.push(`${testPersonCount} test people found (names starting with '${TEST_DATA_PREFIX}')`)
   }
 
   // Check for [TEST]-prefixed companies

From 42e4be3b260bf1173e3e429f783ea06c306ff310 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 13:25:41 +1200
Subject: [PATCH 09/73] fix: correct VS Code task label to Start Dev
 Environment

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .vscode/tasks.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index a6ab6f612..b90360605 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -120,7 +120,7 @@
       }
     },
     {
-      "label": "Start Hotfix Environment",
+      "label": "Start Dev Environment",
       "dependsOn": [
         "Frontend Dev Server",
         "Frontend Manual Dev Server",

From c193505b8d32a2f76306d08e5307a4c0d005e8ea Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 14:58:43 +1200
Subject: [PATCH 10/73] fix: preload contact method owner links

---
 apps/company/models.py                       |  2 ++
 apps/company/serializers.py                  | 22 +++++++++---
 apps/company/tests/test_contact_methods.py   | 38 ++++++++++++++++++++
 apps/company/views/contact_method_viewset.py |  8 ++++-
 4 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/apps/company/models.py b/apps/company/models.py
index a1a79d5c3..977069a26 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -634,6 +634,8 @@ def owner_company_ids(self) -> set[uuid.UUID]:
         if self.company_id:
             return {self.company_id}
         if self.person is not None:
+            if "company_links" in getattr(self.person, "_prefetched_objects_cache", {}):
+                return {link.company_id for link in self.person.company_links.all()}
             return set(self.person.company_links.values_list("company_id", flat=True))
         return set()
 
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 9211d01d9..4c1ed111d 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -15,6 +15,22 @@
 )
 
 
+def _ordered_company_links(person: Person) -> list[CompanyPersonLink]:
+    prefetched_links = getattr(person, "_prefetched_objects_cache", {}).get(
+        "company_links"
+    )
+    if prefetched_links is not None:
+        return sorted(
+            prefetched_links,
+            key=lambda link: (not link.is_primary, link.company.name),
+        )
+    return list(
+        person.company_links.select_related("company").order_by(
+            "-is_primary", "company__name"
+        )
+    )
+
+
 def set_primary_phone(owner: Company | Person, raw_value: str) -> None:
     """Point the owner's primary phone at ``raw_value`` (non-blank).
 
@@ -215,11 +231,7 @@ def get_company_name(self, obj: ContactMethod) -> str:
             person = obj.person
             if person is None:
                 raise RuntimeError(f"Contact method {obj.id} has no person")
-            link = (
-                person.company_links.select_related("company")
-                .order_by("-is_primary", "company__name")
-                .first()
-            )
+            link = next(iter(_ordered_company_links(person)), None)
             return link.company.name if link else ""
         return ""
 
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index 06b05ec5c..24bc1cfc6 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -2,11 +2,14 @@
 from typing import TYPE_CHECKING
 from unittest.mock import MagicMock, patch
 
+from django.conf import settings
 from django.core.exceptions import ValidationError
 from django.db import connection
 from django.test import TestCase
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
+from nplusone.core.profiler import Profiler
+from nplusone.ext.django.patch import apply_patches
 
 if TYPE_CHECKING:
     from apps.job.models import Job
@@ -1034,6 +1037,41 @@ def test_list_paginates_phone_contact_methods(self) -> None:
         self.assertEqual(payload["total_pages"], 2)
         self.assertEqual(len(payload["results"]), 2)
 
+    def test_list_serializes_person_owned_phone_methods_without_lazy_links(
+        self,
+    ) -> None:
+        """Catches CRM calls page 500s from person-owned phone numbers."""
+        self.client.force_authenticate(user=self.test_staff)
+        company = self._company("Acme Ltd")
+        contact = _link(company, "Jane Smith")
+        ContactMethod.objects.create(
+            company=company,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 555 100",
+        )
+        ContactMethod.objects.create(
+            person=contact.person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 555 200",
+        )
+
+        apply_patches()
+        with Profiler(whitelist=settings.NPLUSONE_WHITELIST):
+            response = self.client.get(
+                "/api/companies/contact-methods/",
+                {"method_type": "phone", "page_size": "50"},
+            )
+
+        self.assertEqual(response.status_code, 200)
+        payload = response.json()
+        person_method = next(
+            method
+            for method in payload["results"]
+            if method["person_name"] == "Jane Smith"
+        )
+        self.assertEqual(person_method["owner_company"], str(company.id))
+        self.assertEqual(person_method["company_name"], "Acme Ltd")
+
     def test_list_page_size_is_capped(self) -> None:
         """Catches accidental oversized contact-method responses."""
         self.client.force_authenticate(user=self.test_staff)
diff --git a/apps/company/views/contact_method_viewset.py b/apps/company/views/contact_method_viewset.py
index 920d12bd7..72809b673 100644
--- a/apps/company/views/contact_method_viewset.py
+++ b/apps/company/views/contact_method_viewset.py
@@ -2,12 +2,13 @@
 
 from typing import cast
 
+from django.db.models import Prefetch
 from drf_spectacular.types import OpenApiTypes
 from drf_spectacular.utils import OpenApiParameter, extend_schema
 from rest_framework import permissions, viewsets
 from rest_framework.serializers import BaseSerializer
 
-from apps.company.models import ContactMethod
+from apps.company.models import CompanyPersonLink, ContactMethod
 from apps.company.serializers import ContactMethodSerializer
 from apps.crm.tasks import rematch_phone_calls_task
 from apps.workflow.api.pagination import PageSizePagination
@@ -72,6 +73,11 @@ def get_queryset(self):
         queryset = ContactMethod.objects.select_related(
             "company",
             "person",
+        ).prefetch_related(
+            Prefetch(
+                "person__company_links",
+                queryset=CompanyPersonLink.objects.select_related("company"),
+            ),
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:

From c44fd5263dbb7f15cc8c8f1cbaef5bd05fc74bae Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 16:40:44 +1200
Subject: [PATCH 11/73] fix: harden e2e xero safety checks

---
 apps/workflow/serializers.py                  |  1 +
 .../tests/test_xero_readonly_provider.py      | 32 +++++++++++++-
 apps/workflow/views/xero/xero_view.py         | 25 +++++++++--
 docketworks/settings.py                       |  3 ++
 frontend/schema.yml                           |  3 ++
 frontend/src/api/generated/api.ts             |  1 +
 .../__tests__/sessionReplayService.test.ts    | 11 +++++
 frontend/src/services/sessionReplayService.ts | 11 +++++
 frontend/tests/fixtures/auth.ts               |  4 ++
 frontend/tests/scripts/global-setup.ts        | 44 ++++++++++++++-----
 10 files changed, 120 insertions(+), 15 deletions(-)

diff --git a/apps/workflow/serializers.py b/apps/workflow/serializers.py
index 2a0328dbd..65a773da2 100644
--- a/apps/workflow/serializers.py
+++ b/apps/workflow/serializers.py
@@ -429,6 +429,7 @@ class XeroPingResponseSerializer(serializers.Serializer):
 
     connected = serializers.BooleanField()
     xero_readonly = serializers.BooleanField()
+    xero_production_client = serializers.BooleanField()
 
 
 # ---------------------------------------------------------------------------
diff --git a/apps/workflow/tests/test_xero_readonly_provider.py b/apps/workflow/tests/test_xero_readonly_provider.py
index f357028c3..4fe495cad 100644
--- a/apps/workflow/tests/test_xero_readonly_provider.py
+++ b/apps/workflow/tests/test_xero_readonly_provider.py
@@ -20,7 +20,7 @@
 from apps.workflow.accounting.types import DocumentLineItem, POPayload
 from apps.workflow.accounting.xero.provider import XeroAccountingProvider
 from apps.workflow.accounting.xero.readonly_provider import XeroReadOnlyProvider
-from apps.workflow.models import AppError, XeroAccount
+from apps.workflow.models import AppError, XeroAccount, XeroApp
 from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
 
@@ -68,6 +68,36 @@ def test_ping_reports_readonly_true(self) -> None:
     def test_ping_reports_readonly_false(self) -> None:
         self.assertIs(self._ping_data()["xero_readonly"], False)
 
+    @override_settings(
+        PRODUCTION_XERO_CLIENT_IDS=["prod-client"],
+        XERO_READONLY=False,
+    )
+    def test_ping_reports_production_xero_client_true(self) -> None:
+        XeroApp.objects.create(
+            label="Production",
+            client_id="prod-client",
+            client_secret="secret",
+            redirect_uri="https://example.test/callback",
+            is_active=True,
+        )
+
+        self.assertIs(self._ping_data()["xero_production_client"], True)
+
+    @override_settings(
+        PRODUCTION_XERO_CLIENT_IDS=["prod-client"],
+        XERO_READONLY=False,
+    )
+    def test_ping_reports_production_xero_client_false(self) -> None:
+        XeroApp.objects.create(
+            label="Development",
+            client_id="dev-client",
+            client_secret="secret",
+            redirect_uri="https://example.test/callback",
+            is_active=True,
+        )
+
+        self.assertIs(self._ping_data()["xero_production_client"], False)
+
 
 @override_settings(XERO_READONLY=True)
 class XeroReadOnlyProviderTests(BaseTestCase):
diff --git a/apps/workflow/views/xero/xero_view.py b/apps/workflow/views/xero/xero_view.py
index 83ff1bbf2..b7dc2cdf2 100644
--- a/apps/workflow/views/xero/xero_view.py
+++ b/apps/workflow/views/xero/xero_view.py
@@ -95,6 +95,25 @@ class XeroAuthenticationResult:
     status_code: int = status.HTTP_200_OK
 
 
+def _xero_production_client() -> bool:
+    try:
+        active = get_active_app()
+    except NoActiveXeroApp:
+        return False
+    production_client_ids = {
+        client_id.strip().upper() for client_id in settings.PRODUCTION_XERO_CLIENT_IDS
+    }
+    return active.client_id.strip().upper() in production_client_ids
+
+
+def _xero_ping_payload(*, connected: bool) -> dict[str, bool]:
+    return {
+        "connected": connected,
+        "xero_readonly": settings.XERO_READONLY,
+        "xero_production_client": _xero_production_client(),
+    }
+
+
 def _build_xero_error_payload(
     exc: Exception,
     *,
@@ -960,13 +979,13 @@ def xero_disconnect(request):
         except NoActiveXeroApp:
             logger.info("xero_disconnect: no active XeroApp; nothing to do")
             return Response(
-                {"connected": False, "xero_readonly": settings.XERO_READONLY},
+                _xero_ping_payload(connected=False),
                 status=status.HTTP_200_OK,
             )
         wipe_tokens_and_quota(active)
         logger.info(f"Disconnected XeroApp {active.id} ({active.label})")
         return Response(
-            {"connected": False, "xero_readonly": settings.XERO_READONLY},
+            _xero_ping_payload(connected=False),
             status=status.HTTP_200_OK,
         )
     except AlreadyLoggedException:
@@ -1159,7 +1178,7 @@ def xero_ping(request):
         is_connected = bool(token)
         logger.info(f"Xero ping: connected={is_connected}")
         return Response(
-            {"connected": is_connected, "xero_readonly": settings.XERO_READONLY},
+            _xero_ping_payload(connected=is_connected),
             status=status.HTTP_200_OK,
         )
     except AlreadyLoggedException as exc:
diff --git a/docketworks/settings.py b/docketworks/settings.py
index 1e9c71eba..9704dc81b 100644
--- a/docketworks/settings.py
+++ b/docketworks/settings.py
@@ -828,6 +828,9 @@ def require_positive_int_env(name: str) -> int:
 # Hardcoded production Xero tenant ID
 PRODUCTION_XERO_TENANT_ID = "75e57cfd-302d-4f84-8734-8aae354e76a7"
 
+# Hardcoded production Xero app client IDs.
+PRODUCTION_XERO_CLIENT_IDS = ["DB22E7201251487F83D98B130946DAC1"]
+
 # Hardcoded production machine ID
 PRODUCTION_MACHINE_ID = "19d6339c35f7416b9f41d9a35dba6111"
 
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 8bb9a7a49..70d17fffc 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -23266,8 +23266,11 @@ components:
           type: boolean
         xero_readonly:
           type: boolean
+        xero_production_client:
+          type: boolean
       required:
         - connected
+        - xero_production_client
         - xero_readonly
     XeroQuote:
       type: object
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index f2b8bec51..0dd8ad41d 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -3499,6 +3499,7 @@ const XeroQuoteCreateRequest = z.object({ breakdown: z.boolean() })
 const XeroPingResponse = z.object({
   connected: z.boolean(),
   xero_readonly: z.boolean(),
+  xero_production_client: z.boolean(),
 })
 const XeroSyncStartResponse = z.object({
   status: z.string(),
diff --git a/frontend/src/services/__tests__/sessionReplayService.test.ts b/frontend/src/services/__tests__/sessionReplayService.test.ts
index e3d90403a..ccf6cad70 100644
--- a/frontend/src/services/__tests__/sessionReplayService.test.ts
+++ b/frontend/src/services/__tests__/sessionReplayService.test.ts
@@ -37,12 +37,23 @@ describe('sessionReplayService', () => {
   beforeEach(async () => {
     vi.clearAllMocks()
     vi.resetModules()
+    window.localStorage.clear()
     const state = await import('@/services/sessionReplayState')
     state.setSessionReplayId(null)
     apiMock.session_replay_recordings_create.mockResolvedValue({ id: 'replay-1' })
     apiMock.session_replay_recording_chunks_create.mockResolvedValue({ id: 'chunk-1' })
   })
 
+  it('does not start replay capture when E2E disables it in dev', async () => {
+    window.localStorage.setItem('e2e:disable-session-replay', 'true')
+    const { startSessionReplay } = await import('@/services/sessionReplayService')
+
+    await startSessionReplay()
+
+    expect(apiMock.session_replay_recordings_create).not.toHaveBeenCalled()
+    expect(recordMock).not.toHaveBeenCalled()
+  })
+
   it('drops duplicate chunk uploads and continues with the next sequence', async () => {
     const { startSessionReplay, flushSessionReplay } =
       await import('@/services/sessionReplayService')
diff --git a/frontend/src/services/sessionReplayService.ts b/frontend/src/services/sessionReplayService.ts
index 835d2854e..ef8511e6e 100644
--- a/frontend/src/services/sessionReplayService.ts
+++ b/frontend/src/services/sessionReplayService.ts
@@ -10,6 +10,7 @@ import {
 type StopRecording = () => void
 
 const FLUSH_INTERVAL_MS = 10_000
+const E2E_DISABLE_SESSION_REPLAY_KEY = 'e2e:disable-session-replay'
 
 let stopRecording: StopRecording | null = null
 let flushTimer: number | null = null
@@ -17,6 +18,15 @@ let sequence = 0
 let bufferedEvents: eventWithTime[] = []
 let isFlushing = false
 
+function sessionReplayDisabledForE2E(): boolean {
+  const isPlaywrightNgrokRun =
+    navigator.webdriver && window.location.hostname.endsWith('.ngrok-free.app')
+  return (
+    import.meta.env.DEV &&
+    (isPlaywrightNgrokRun || window.localStorage.getItem(E2E_DISABLE_SESSION_REPLAY_KEY) === 'true')
+  )
+}
+
 function responseStatus(error: unknown): number | null {
   if (typeof error !== 'object' || error === null || !('response' in error)) return null
   const response = (error as { response?: { status?: unknown } }).response
@@ -61,6 +71,7 @@ function viewport() {
 }
 
 export async function startSessionReplay(): Promise<void> {
+  if (sessionReplayDisabledForE2E()) return
   if (getCurrentSessionReplayId() || stopRecording) return
 
   const recording = await api.session_replay_recordings_create({
diff --git a/frontend/tests/fixtures/auth.ts b/frontend/tests/fixtures/auth.ts
index 97ef975c3..461db6ec3 100644
--- a/frontend/tests/fixtures/auth.ts
+++ b/frontend/tests/fixtures/auth.ts
@@ -176,6 +176,10 @@ export const test = base.extend<AuthFixtures, WorkerFixtures>({
   // Every test's page fails on unexpected browser console errors and uncaught
   // page exceptions. authenticatedPage wraps this fixture, so login is covered too.
   page: async ({ page, expectedConsoleErrors, sessionCheckConsoleAllowance }, use) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem('e2e:disable-session-replay', 'true')
+    })
+
     const captured: CapturedBrowserError[] = []
     page.on('response', (response) => {
       const url = new URL(response.url())
diff --git a/frontend/tests/scripts/global-setup.ts b/frontend/tests/scripts/global-setup.ts
index ad1eccdf6..b55a74eaf 100644
--- a/frontend/tests/scripts/global-setup.ts
+++ b/frontend/tests/scripts/global-setup.ts
@@ -52,21 +52,35 @@ async function getAuthCookie(frontendUrl: string): Promise<string> {
 }
 
 /**
- * Read-only check: verify Xero is connected and the backend is in
- * XERO_READONLY mode by hitting the ping endpoint.
+ * Safety check: verify Xero is connected and whether the backend is pointing at
+ * the production Xero app. Production Xero writes require XERO_READONLY.
  * Does NOT attempt to connect or refresh tokens.
  */
-async function checkXeroStatus(): Promise<{ connected: boolean; xeroReadonly: boolean }> {
+async function checkXeroStatus(): Promise<{
+  connected: boolean
+  xeroReadonly: boolean
+  productionClient: boolean | null
+}> {
   const frontendUrl = getFrontendUrl()
   const cookieValue = await getAuthCookie(frontendUrl)
 
   const response = await fetch(`${frontendUrl}/api/xero/ping/`, {
     headers: { Cookie: cookieValue },
   })
-  if (!response.ok) return { connected: false, xeroReadonly: false }
-  const data = (await response.json()) as { connected?: boolean; xero_readonly?: boolean }
-  // A missing xero_readonly field (old backend) must fail, not pass silently.
-  return { connected: data.connected === true, xeroReadonly: data.xero_readonly === true }
+  if (!response.ok) return { connected: false, xeroReadonly: false, productionClient: null }
+  const data = (await response.json()) as {
+    connected?: boolean
+    xero_readonly?: boolean
+    xero_production_client?: boolean
+  }
+  return {
+    connected: data.connected === true,
+    // Missing xero_readonly (old backend) must fail, not pass silently.
+    xeroReadonly: data.xero_readonly === true,
+    // Missing production-client classification must fail closed when connected.
+    productionClient:
+      typeof data.xero_production_client === 'boolean' ? data.xero_production_client : null,
+  }
 }
 
 export default async function globalSetup() {
@@ -87,13 +101,21 @@ export default async function globalSetup() {
   } else {
     console.log('[xero] Xero is connected.')
   }
-  if (!xeroStatus.xeroReadonly) {
+  if (xeroStatus.connected && xeroStatus.productionClient === null) {
+    issues.push(
+      'Backend did not report whether the active Xero app is production. ' +
+        'Deploy the backend ping update before running E2E.',
+    )
+  } else if (xeroStatus.productionClient && !xeroStatus.xeroReadonly) {
     issues.push(
-      'Backend is not running in XERO_READONLY mode — E2E would write to PROD Xero. ' +
-        'Restart the backend (and any celery worker) with XERO_READONLY=True.',
+      'Backend is using the production Xero app with writes enabled. ' +
+        'Restart the backend and any celery worker with XERO_READONLY=True, ' +
+        'or switch the active Xero app to a non-production client.',
     )
+  } else if (xeroStatus.productionClient) {
+    console.log('[xero] Backend is using the production Xero app in XERO_READONLY mode.')
   } else {
-    console.log('[xero] Backend is in XERO_READONLY mode.')
+    console.log('[xero] Backend is using a non-production Xero app.')
   }
 
   // Check database is clean

From 5d88117b847cb849d7c8986f378ea37624104722 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 9 Jul 2026 16:55:36 +1200
Subject: [PATCH 12/73] test: wait for job number in kanban e2e

---
 frontend/tests/kanban/kanban-drag-vanishing.spec.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/frontend/tests/kanban/kanban-drag-vanishing.spec.ts b/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
index 0594345bc..7d69ef32f 100644
--- a/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
+++ b/frontend/tests/kanban/kanban-drag-vanishing.spec.ts
@@ -195,7 +195,9 @@ test.describe('kanban drag vanishing', () => {
     // job's card can legitimately be absent until the search below filters
     // the board.
     await page.goto(sharedEditJobUrl)
-    const jobNumberText = await autoId(page, 'JobView-job-number').first().innerText()
+    const jobNumberLocator = autoId(page, 'JobView-job-number').first()
+    await expect(jobNumberLocator).toContainText(/\d+/)
+    const jobNumberText = await jobNumberLocator.innerText()
     const jobNumber = jobNumberText.match(/#(\d+)/)?.[1] ?? ''
     expect(jobNumber).not.toBe('')
 

From bc83bf3ab24dcb9ca95724ce8849de2e2603cfbe Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Fri, 10 Jul 2026 06:50:51 +1200
Subject: [PATCH 13/73] fix: address people model review feedback

---
 .../migrations/0005_backfill_person.py        | 39 +++++++++--
 apps/company/serializers.py                   |  7 ++
 apps/company/services/company_rest_service.py |  6 +-
 apps/company/tests/test_contact_methods.py    | 15 ++++-
 .../tests/test_people_backfill_migration.py   | 14 +++-
 apps/job/serializers/job_serializer.py        |  4 +-
 apps/job/services/data_integrity_service.py   |  4 +-
 apps/job/services/job_rest_service.py         |  4 +-
 apps/job/services/workshop_pdf_service.py     | 12 ++--
 apps/job/tests/test_workshop_pdf_service.py   |  2 +-
 apps/workflow/api/xero/reprocess_xero.py      | 50 +++++++++++---
 .../management/commands/e2e_cleanup.py        | 40 +++++++++---
 apps/workflow/tests/test_push_contacts.py     |  2 +-
 frontend/schema.yml                           | 18 ++---
 .../src/components/PersonSelectionModal.vue   |  9 +--
 frontend/src/components/PersonSelector.vue    | 15 +++--
 .../src/components/job/JobSettingsTab.vue     | 50 ++++++++++++--
 .../__tests__/usePersonManagement.test.ts     | 22 ++++---
 .../src/composables/useJobHeaderAutosave.ts   | 16 ++++-
 .../src/composables/usePersonManagement.ts    |  6 +-
 frontend/src/services/job.service.ts          |  2 +-
 .../src/stores/__tests__/companyStore.test.ts | 65 +++++++++++++++++++
 frontend/src/stores/__tests__/jobs.test.ts    | 30 +++++++++
 frontend/src/stores/companyStore.ts           | 19 ++++--
 frontend/src/stores/jobs.ts                   |  2 +-
 mypy-baseline.txt                             | 16 -----
 26 files changed, 364 insertions(+), 105 deletions(-)
 create mode 100644 frontend/src/stores/__tests__/companyStore.test.ts

diff --git a/apps/company/migrations/0005_backfill_person.py b/apps/company/migrations/0005_backfill_person.py
index c52680b8a..514eb0989 100644
--- a/apps/company/migrations/0005_backfill_person.py
+++ b/apps/company/migrations/0005_backfill_person.py
@@ -49,24 +49,49 @@ def backwards(apps: Any, schema_editor: Any) -> None:
     Job = apps.get_model("job", "Job")
     PhoneCallRecord = apps.get_model("crm", "PhoneCallRecord")
 
-    link_by_person_id = dict(
-        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
-            "person_id", "id"
+    def link_id_for_person(
+        *, person_id: Any, company_id: Any | None, owner: str
+    ) -> Any:
+        links = CompanyPersonLink.objects.filter(person_id=person_id)
+        if company_id is not None:
+            links = links.filter(company_id=company_id)
+        link_ids = list(links.order_by("id").values_list("id", flat=True)[:2])
+        if len(link_ids) == 1:
+            return link_ids[0]
+        if len(link_ids) == 0:
+            raise RuntimeError(
+                f"Cannot reverse people backfill for {owner}: "
+                f"person_id={person_id} has no matching company link"
+            )
+        raise RuntimeError(
+            f"Cannot reverse people backfill for {owner}: "
+            f"person_id={person_id} maps to multiple company links"
         )
-    )
 
     for call in PhoneCallRecord.objects.exclude(person__isnull=True).order_by("id"):
-        call.contact_id = link_by_person_id[call.person_id]
+        call.contact_id = link_id_for_person(
+            person_id=call.person_id,
+            company_id=call.company_id,
+            owner=f"PhoneCallRecord {call.id}",
+        )
         call.person_id = None
         call.save(update_fields=["contact", "person", "updated_at"])
 
     for job in Job.objects.exclude(person__isnull=True).order_by("id"):
-        job.contact_id = link_by_person_id[job.person_id]
+        job.contact_id = link_id_for_person(
+            person_id=job.person_id,
+            company_id=job.company_id,
+            owner=f"Job {job.id}",
+        )
         job.person_id = None
         job.save(update_fields=["contact", "person"])
 
     for method in ContactMethod.objects.exclude(person__isnull=True).order_by("id"):
-        method.contact_id = link_by_person_id[method.person_id]
+        method.contact_id = link_id_for_person(
+            person_id=method.person_id,
+            company_id=None,
+            owner=f"ContactMethod {method.id}",
+        )
         method.person_id = None
         method.save(update_fields=["contact", "person", "updated_at"])
 
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 4c1ed111d..5ab6e7b70 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -114,6 +114,13 @@ class Meta:
             "phone",
         ]
         read_only_fields = ["id", "is_active", "created_at", "updated_at"]
+        extra_kwargs = {
+            "company": {"help_text": "The company this person is linked to"},
+            "is_primary": {
+                "help_text": "Indicates if this is the primary person for the company"
+            },
+            "notes": {"help_text": "Additional notes about this person"},
+        }
 
     def to_internal_value(self, data: Any) -> Any:
         """Convert empty strings to None for nullable fields before validation."""
diff --git a/apps/company/services/company_rest_service.py b/apps/company/services/company_rest_service.py
index d20348aa4..05d6286cb 100644
--- a/apps/company/services/company_rest_service.py
+++ b/apps/company/services/company_rest_service.py
@@ -552,8 +552,8 @@ def update_job_person(
 
             try:
                 person = Person.objects.get(id=person_id)
-            except Person.DoesNotExist:
-                raise ValueError(f"Person with id {person_id} not found")
+            except Person.DoesNotExist as exc:
+                raise ValueError(f"Person with id {person_id} not found") from exc
 
             job.person = person
             job.save(staff=user)
@@ -576,6 +576,8 @@ def update_job_person(
 
         except AlreadyLoggedException:
             raise
+        except ValueError:
+            raise
         except Exception as exc:
             persist_and_raise(
                 exc,
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index 24bc1cfc6..9f2419478 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -362,6 +362,17 @@ def test_update_job_person_persists_new_person(self) -> None:
         job.refresh_from_db()
         self.assertEqual(job.person_id, new_contact.person_id)
 
+    def test_update_job_person_missing_person_is_business_error(self) -> None:
+        job, _company, _ = self._job_with_contact()
+        app_error_count = AppError.objects.count()
+
+        with self.assertRaises(ValueError):
+            CompanyRestService.update_job_person(
+                job.id, {"id": str(uuid.uuid4())}, self.test_staff
+            )
+
+        self.assertEqual(AppError.objects.count(), app_error_count)
+
 
 class CompanyListPhoneTests(TestCase):
     """Guards the Phone column of the companies list (restored after the
@@ -381,7 +392,7 @@ def _lazy_phone_queries(self, captured: CaptureQueriesContext) -> list[str]:
         return [
             q["sql"]
             for q in captured.captured_queries
-            if q["sql"].startswith('SELECT "company_clientcontactmethod"')
+            if q["sql"].startswith('SELECT "company_contactmethod"')
         ]
 
     def test_list_companies_rows_include_phone(self) -> None:
@@ -446,7 +457,7 @@ def test_list_includes_contact_phone_without_lazy_queries(self) -> None:
         lazy = [
             q["sql"]
             for q in captured.captured_queries
-            if q["sql"].startswith('SELECT "company_clientcontactmethod"')
+            if q["sql"].startswith('SELECT "company_contactmethod"')
         ]
         self.assertEqual(lazy, [])
 
diff --git a/apps/company/tests/test_people_backfill_migration.py b/apps/company/tests/test_people_backfill_migration.py
index 1903d7302..d450d3394 100644
--- a/apps/company/tests/test_people_backfill_migration.py
+++ b/apps/company/tests/test_people_backfill_migration.py
@@ -1,4 +1,5 @@
 import uuid
+from typing import ClassVar
 
 from django.db import connection, transaction
 from django.db.migrations.executor import MigrationExecutor
@@ -7,12 +8,14 @@
 
 
 class PeopleBackfillMigrationTests(TransactionTestCase):
-    migrate_from = [
+    migrate_from: ClassVar[tuple[tuple[str, str], ...]] = (
         ("company", "0004_person_link_structure"),
         ("job", "0004_job_person_alter_job_contact"),
         ("crm", "0005_phonecallrecord_person_alter_phonecallrecord_contact"),
-    ]
-    migrate_to = [("company", "0005_backfill_person")]
+    )
+    migrate_to: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("company", "0005_backfill_person"),
+    )
 
     def setUp(self) -> None:
         super().setUp()
@@ -20,6 +23,11 @@ def setUp(self) -> None:
         self.executor.migrate(self.migrate_from)
         self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
 
+    def tearDown(self) -> None:
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
+        super().tearDown()
+
     def test_backfill_and_reverse_restore_legacy_contact_ownership(self) -> None:
         Company = self.old_apps.get_model("company", "Company")
         CompanyPersonLink = self.old_apps.get_model("company", "CompanyPersonLink")
diff --git a/apps/job/serializers/job_serializer.py b/apps/job/serializers/job_serializer.py
index 43ff30354..e30951303 100644
--- a/apps/job/serializers/job_serializer.py
+++ b/apps/job/serializers/job_serializer.py
@@ -1136,8 +1136,8 @@ def validate_person_id(self, value):
         if value:
             try:
                 Person.objects.get(id=value)
-            except Person.DoesNotExist:
-                raise serializers.ValidationError("Person not found")
+            except Person.DoesNotExist as exc:
+                raise serializers.ValidationError("Person not found") from exc
         return value
 
     def validate(self, attrs):
diff --git a/apps/job/services/data_integrity_service.py b/apps/job/services/data_integrity_service.py
index e09bd378d..7a555a103 100644
--- a/apps/job/services/data_integrity_service.py
+++ b/apps/job/services/data_integrity_service.py
@@ -94,7 +94,7 @@ def _check_all_fk_references() -> list[dict[str, Any]]:
 
         # Company App
         issues.extend(DataIntegrityService._check_company_fks())
-        issues.extend(DataIntegrityService._check_clientcontact_fks())
+        issues.extend(DataIntegrityService._check_companypersonlink_fks())
 
         # Purchasing App
         issues.extend(DataIntegrityService._check_purchaseorder_fks())
@@ -592,7 +592,7 @@ def _check_company_fks() -> list[dict[str, Any]]:
         return issues
 
     @staticmethod
-    def _check_clientcontact_fks() -> list[dict[str, Any]]:
+    def _check_companypersonlink_fks() -> list[dict[str, Any]]:
         """Check CompanyPersonLink FK references."""
         issues = []
         valid_company_ids = set(Company.objects.values_list("id", flat=True))
diff --git a/apps/job/services/job_rest_service.py b/apps/job/services/job_rest_service.py
index ea1cbc55f..39cdb772d 100644
--- a/apps/job/services/job_rest_service.py
+++ b/apps/job/services/job_rest_service.py
@@ -287,8 +287,8 @@ def create_job(data: Dict[str, Any], user: Staff) -> Job:
             try:
                 person = Person.objects.get(id=person_id)
                 job_data["person"] = person
-            except Person.DoesNotExist:
-                raise ValueError(f"Person with id {person_id} not found")
+            except Person.DoesNotExist as exc:
+                raise ValueError(f"Person with id {person_id} not found") from exc
 
         if "is_urgent" in data:
             job_data["is_urgent"] = data["is_urgent"]
diff --git a/apps/job/services/workshop_pdf_service.py b/apps/job/services/workshop_pdf_service.py
index a9e2a0af2..412db2a4d 100644
--- a/apps/job/services/workshop_pdf_service.py
+++ b/apps/job/services/workshop_pdf_service.py
@@ -1314,17 +1314,21 @@ def add_delivery_docket_details_table(
     person_name = job.person.name if job.person else ""
 
     person_phone = _primary_phone_for_job(job)
-    person_info = f"{person_name}<br/>{person_phone}" if person_phone else person_name
+    person_info = (
+        f"{escape(person_name)}<br/>{escape(person_phone)}"
+        if person_phone
+        else escape(person_name or "N/A")
+    )
 
     # Delivery docket details - no workshop time or internal notes
     job_details = [
         [
-            Paragraph(company_name, header_company_style),
+            _plain_paragraph(company_name, header_company_style),
             Paragraph(person_info, header_contact_style),
         ],
         [
             Paragraph("DESCRIPTION", label_style),
-            Paragraph(job.description or "N/A", body_style),
+            _plain_paragraph(job.description, body_style),
         ],
         [
             Paragraph("ENTRY DATE", label_style),
@@ -1342,7 +1346,7 @@ def add_delivery_docket_details_table(
         ],
         [
             Paragraph("ORDER NUMBER", label_style),
-            Paragraph(job.order_number or "N/A", body_style),
+            _plain_paragraph(job.order_number, body_style),
         ],
     ]
 
diff --git a/apps/job/tests/test_workshop_pdf_service.py b/apps/job/tests/test_workshop_pdf_service.py
index 779aa9dd6..781bd7ed2 100644
--- a/apps/job/tests/test_workshop_pdf_service.py
+++ b/apps/job/tests/test_workshop_pdf_service.py
@@ -580,7 +580,7 @@ def test_preloaded_workshop_pdf_render_does_not_query_cost_lines(self) -> None:
         contact_method_queries = [
             query["sql"]
             for query in captured
-            if 'FROM "company_clientcontactmethod"' in query["sql"]
+            if 'FROM "company_contactmethod"' in query["sql"]
         ]
         self.assertEqual(cost_line_queries, [])
         self.assertEqual(contact_method_queries, [])
diff --git a/apps/workflow/api/xero/reprocess_xero.py b/apps/workflow/api/xero/reprocess_xero.py
index 8674d9158..f4d444835 100644
--- a/apps/workflow/api/xero/reprocess_xero.py
+++ b/apps/workflow/api/xero/reprocess_xero.py
@@ -4,7 +4,7 @@
 from collections.abc import Mapping
 
 from django.core.exceptions import ValidationError
-from django.db import transaction
+from django.db import IntegrityError, transaction
 from django.utils import timezone
 from django.utils.dateparse import parse_datetime
 
@@ -370,7 +370,13 @@ def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
         "_is_customer", company.is_account_customer
     )
 
-    for person_payload in raw_json.get("_contact_persons", []):
+    contact_persons_payload = raw_json.get("_contact_persons")
+    if isinstance(contact_persons_payload, list):
+        contact_persons = contact_persons_payload
+    else:
+        contact_persons = []
+
+    for person_payload in contact_persons:
         if not isinstance(person_payload, dict):
             continue
         first_name = person_payload.get("_first_name") or ""
@@ -396,13 +402,39 @@ def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
                 link.person.email = email
                 link.person.save(update_fields=["email", "updated_at"])
         except CompanyPersonLink.DoesNotExist:
-            person = Person.objects.create(name=xero_name, email=email)
-            CompanyPersonLink.objects.create(
-                company=company,
-                person=person,
-                xero_name=xero_name,
-                is_active=True,
-            )
+            try:
+                with transaction.atomic():
+                    person = Person.objects.create(name=xero_name, email=email)
+                    CompanyPersonLink.objects.create(
+                        company=company,
+                        person=person,
+                        xero_name=xero_name,
+                        is_active=True,
+                    )
+            except IntegrityError as exc:
+                try:
+                    CompanyPersonLink.objects.filter(
+                        company=company,
+                        xero_name=xero_name,
+                    ).select_related("person").get()
+                except CompanyPersonLink.DoesNotExist:
+                    persist_and_raise(
+                        exc,
+                        additional_context={
+                            "operation": "set_company_fields_person_link_race",
+                            "client_id": str(company.id),
+                            "xero_name": xero_name,
+                        },
+                    )
+                except CompanyPersonLink.MultipleObjectsReturned:
+                    persist_and_raise(
+                        exc,
+                        additional_context={
+                            "operation": "set_company_fields_person_link_race",
+                            "client_id": str(company.id),
+                            "xero_name": xero_name,
+                        },
+                    )
         except CompanyPersonLink.MultipleObjectsReturned as exc:
             persist_and_raise(
                 exc,
diff --git a/apps/workflow/management/commands/e2e_cleanup.py b/apps/workflow/management/commands/e2e_cleanup.py
index 4448dab3a..9666e77cd 100644
--- a/apps/workflow/management/commands/e2e_cleanup.py
+++ b/apps/workflow/management/commands/e2e_cleanup.py
@@ -13,9 +13,10 @@
 
 from django.core.management.base import BaseCommand
 from django.db import transaction
+from django.db.models import Model, Q, QuerySet
 
 from apps.accounting.models import Invoice, Quote
-from apps.company.models import Company, CompanyPersonLink
+from apps.company.models import Company, CompanyPersonLink, Person
 from apps.job.models import Job, QuoteSpreadsheet
 from apps.purchasing.models import PurchaseOrder, PurchaseOrderLine
 
@@ -50,9 +51,7 @@ def handle(self, *args, **options):
         test_prefix_company_people = CompanyPersonLink.objects.filter(
             company__in=test_companies
         )
-
-        # Legacy E2E-prefixed companies and their data
-        from django.db.models import Q
+        test_person_records = Person.objects.filter(name__startswith=TEST_DATA_PREFIX)
 
         legacy_q = Q()
         for prefix in LEGACY_E2E_PREFIXES:
@@ -75,6 +74,11 @@ def handle(self, *args, **options):
 
         self._report_queryset("[TEST]-prefixed jobs", test_jobs, "name")
         self._report_queryset("[TEST]-prefixed people", test_people, "person__name")
+        self._report_queryset(
+            "Underlying [TEST]-prefixed person records",
+            test_person_records,
+            "name",
+        )
         self._report_queryset("[TEST]-prefixed companies", test_companies, "name")
         self._report_queryset("Legacy E2E companies", legacy_companies, "name")
         self._report_queryset("Legacy E2E company jobs", legacy_company_jobs, "name")
@@ -98,9 +102,21 @@ def handle(self, *args, **options):
             "person__name",
         )
 
+        all_companies_to_delete = (test_companies | legacy_companies).distinct()
+        all_people_links_to_delete = (
+            test_company_people
+            | legacy_company_people
+            | test_people
+            | test_prefix_company_people
+        ).distinct()
+        people_ids_to_delete = set(
+            all_people_links_to_delete.values_list("person_id", flat=True)
+        ) | set(test_person_records.values_list("id", flat=True))
+
         total = (
             test_jobs.count()
             + test_people.count()
+            + test_person_records.count()
             + test_companies.count()
             + legacy_companies.count()
             + legacy_company_jobs.count()
@@ -171,9 +187,6 @@ def handle(self, *args, **options):
                 "sheet_id",
             )
 
-        # Collect all companies to delete
-        all_companies_to_delete = (test_companies | legacy_companies).distinct()
-
         # Find POs referencing these companies (PROTECTED FK on supplier)
         linked_pos = PurchaseOrder.objects.filter(supplier__in=all_companies_to_delete)
 
@@ -248,12 +261,23 @@ def handle(self, *args, **options):
                 f"  People on [TEST] companies: {count} objects ({details})"
             )
 
+            remaining_non_test_people_links = CompanyPersonLink.objects.exclude(
+                company__in=all_companies_to_delete
+            ).values_list("person_id", flat=True)
+            orphaned_test_people = Person.objects.filter(
+                id__in=people_ids_to_delete
+            ).exclude(id__in=remaining_non_test_people_links)
+            count, details = orphaned_test_people.delete()
+            self.stdout.write(
+                f"  Underlying test person records: {count} objects ({details})"
+            )
+
             count, details = test_companies.delete()
             self.stdout.write(f"  [TEST] companies: {count} objects ({details})")
 
         self.stdout.write("\nDone.")
 
-    def _report_queryset(self, label, qs, field):
+    def _report_queryset(self, label: str, qs: QuerySet[Model], field: str) -> None:
         count = qs.count()
         if count == 0:
             return
diff --git a/apps/workflow/tests/test_push_contacts.py b/apps/workflow/tests/test_push_contacts.py
index 4aded0b0d..8d3a54237 100644
--- a/apps/workflow/tests/test_push_contacts.py
+++ b/apps/workflow/tests/test_push_contacts.py
@@ -96,7 +96,7 @@ def test_existing_client_calls_update_contact_with_sdk_contact(
 @patch("time.sleep")
 @patch("apps.workflow.api.xero.push.get_tenant_id", return_value="tenant-1")
 @patch("apps.workflow.api.xero.push.AccountingApi")
-class CreateCompanyPersonLinkInXeroTests(TestCase):
+class CreateCompanyContactInXeroTests(TestCase):
     """create_company_contact_in_xero — passes Contact, saves xero_contact_id."""
 
     def test_passes_sdk_contact_and_saves_id(
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 70d17fffc..49a23ce6a 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -11142,7 +11142,7 @@ components:
         company:
           type: string
           format: uuid
-          description: The company this contact belongs to
+          description: The company this person is linked to
         person:
           type: string
           format: uuid
@@ -11164,11 +11164,11 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the company
+          description: Indicates if this is the primary person for the company
         notes:
           type: string
           nullable: true
-          description: Additional notes about this contact
+          description: Additional notes about this person
         is_active:
           type: boolean
           readOnly: true
@@ -11201,7 +11201,7 @@ components:
         company:
           type: string
           format: uuid
-          description: The company this contact belongs to
+          description: The company this person is linked to
         person_name:
           type: string
           minLength: 1
@@ -11220,11 +11220,11 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the company
+          description: Indicates if this is the primary person for the company
         notes:
           type: string
           nullable: true
-          description: Additional notes about this contact
+          description: Additional notes about this person
         phone:
           type: string
           nullable: true
@@ -16471,7 +16471,7 @@ components:
         company:
           type: string
           format: uuid
-          description: The company this contact belongs to
+          description: The company this person is linked to
         person_name:
           type: string
           minLength: 1
@@ -16490,11 +16490,11 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary contact for the company
+          description: Indicates if this is the primary person for the company
         notes:
           type: string
           nullable: true
-          description: Additional notes about this contact
+          description: Additional notes about this person
         phone:
           type: string
           nullable: true
diff --git a/frontend/src/components/PersonSelectionModal.vue b/frontend/src/components/PersonSelectionModal.vue
index 4ab90f3ec..357d20f98 100644
--- a/frontend/src/components/PersonSelectionModal.vue
+++ b/frontend/src/components/PersonSelectionModal.vue
@@ -344,6 +344,7 @@ const emit = defineEmits<{
   'edit-person': [person: CompanyPersonLink]
   'delete-person': [personLinkId: string]
   'cancel-edit': []
+  'update:personForm': [personForm: PersonFormData]
 }>()
 
 const nameError = ref('')
@@ -363,7 +364,6 @@ watch(
 watch(
   () => props.people.length,
   (peopleLength) => {
-    console.log('[PEOPLE] Modal received:', peopleLength, 'people')
     if (peopleLength === 0) {
       // Automatically set as primary if this is the first person
       localPersonForm.is_primary = true
@@ -376,12 +376,7 @@ watch(
 watch(
   localPersonForm,
   (val) => {
-    // Update the parent's form data
-    Object.keys(val).forEach((key) => {
-      if (key in props.personForm) {
-        ;(props.personForm as Record<string, unknown>)[key] = val[key as keyof typeof val]
-      }
-    })
+    emit('update:personForm', { ...val })
   },
   { deep: true },
 )
diff --git a/frontend/src/components/PersonSelector.vue b/frontend/src/components/PersonSelector.vue
index 1e0392283..c3e013239 100644
--- a/frontend/src/components/PersonSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -10,7 +10,7 @@
       <div class="flex-1">
         <input
           :id="id"
-          :value="displayValue.get()"
+          :value="displayValue"
           type="text"
           :placeholder="placeholder"
           readonly
@@ -61,6 +61,7 @@
     @edit-person="handleEditPerson"
     @delete-person="handleDeletePerson"
     @cancel-edit="cancelEdit"
+    @update:person-form="updatePersonForm"
   />
 </template>
 
@@ -70,7 +71,7 @@ import { toast } from 'vue-sonner'
 
 import { ref, watch } from 'vue'
 import { Users, X } from 'lucide-vue-next'
-import { usePersonManagement } from '../composables/usePersonManagement'
+import { usePersonManagement, type PersonFormData } from '../composables/usePersonManagement'
 import PersonSelectionModal from './PersonSelectionModal.vue'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
@@ -235,6 +236,10 @@ const clearSelection = () => {
   clearFromComposable()
 }
 
+const updatePersonForm = (updatedPersonForm: PersonFormData) => {
+  personForm.value = updatedPersonForm
+}
+
 const selectPrimaryPerson = async () => {
   debugLog('PersonSelector - selectPrimaryPerson called', {
     companyId: props.companyId,
@@ -289,10 +294,10 @@ defineExpose({
 const emitUpdates = () => {
   if (suppressEmit.value) return
   debugLog('PersonSelector - emitUpdates', {
-    displayValue: displayValue.get(),
+    displayValue: displayValue.value,
     selectedPerson: selectedPerson.value,
   })
-  emit('update:modelValue', displayValue.get())
+  emit('update:modelValue', displayValue.value)
   emit('update:selectedPerson', selectedPerson.value)
 }
 
@@ -313,7 +318,7 @@ watch(
 
     // Quando mudar o cliente: limpe estado local (sem emitir)
     suppressEmit.value = true
-    displayValue.set('')
+    displayValue.value = ''
     selectedPerson.value = null
     people.value = []
     suppressEmit.value = false
diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index 103c995f7..6cb93bd20 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -856,15 +856,31 @@ watch(
         localJobData.value.person_id = personResponse.id
         localJobData.value.person_name = personResponse.name
         personDisplayValue.value = personResponse.name || ''
+        serverBaseline.value.person_id = personResponse.id ?? null
+        serverBaseline.value.person_name = personResponse.name ?? null
+        if (newJobData.job_id) {
+          jobsStore.patchHeader(newJobData.job_id, {
+            person_id: personResponse.id ?? null,
+            person_name: personResponse.name ?? null,
+          })
+        }
       }
     } catch (error: unknown) {
       // Handle 404 when no person is associated with the job - simply ignore
       const axiosError = error as { response?: { status?: number } }
       if (axiosError?.response?.status === 404) {
         debugLog('No person associated with this job - ignoring 404')
-        localJobData.value.person_id = undefined
-        localJobData.value.person_name = undefined
+        localJobData.value.person_id = null
+        localJobData.value.person_name = null
         personDisplayValue.value = ''
+        serverBaseline.value.person_id = null
+        serverBaseline.value.person_name = null
+        if (newJobData.job_id) {
+          jobsStore.patchHeader(newJobData.job_id, {
+            person_id: null,
+            person_name: null,
+          })
+        }
       } else {
         console.error('Failed to load person information:', error)
         toast.error('Failed to load person information')
@@ -1149,6 +1165,10 @@ const handlePersonSelected = async (personLink: CompanyPersonLink | null) => {
       // Still update display value in case it's stale
       localJobData.value.person_name = personLink.person_name
       personDisplayValue.value = personLink.person_name
+      jobsStore.patchHeader(props.jobId, {
+        person_id: personLink.person,
+        person_name: personLink.person_name,
+      })
       return
     }
 
@@ -1168,16 +1188,29 @@ const handlePersonSelected = async (personLink: CompanyPersonLink | null) => {
       await api.companies_jobs_person_update(personToSend, {
         params: { job_id: props.jobId },
       })
+      serverBaseline.value.person_id = personLink.person
+      serverBaseline.value.person_name = personLink.person_name
+      jobsStore.patchHeader(props.jobId, {
+        person_id: personLink.person,
+        person_name: personLink.person_name,
+      })
       toast.success('Person updated successfully')
     } catch (error) {
       toast.error('Failed to update person')
       console.error('Failed to update person:', error)
     }
   } else {
-    // Clear person locally - no API call needed since clearing means no person association
-    localJobData.value.person_id = undefined
-    localJobData.value.person_name = undefined
+    localJobData.value.person_id = null
+    localJobData.value.person_name = null
     personDisplayValue.value = ''
+
+    if (!isInitializing.value && !isHydratingBasicInfo.value && !isSyncingFromStore.value) {
+      autosave.queueChanges({
+        person_id: null,
+        person_name: null,
+      })
+      void autosave.flush('person-clear')
+    }
   }
 }
 
@@ -1313,6 +1346,8 @@ const autosave = createJobAutosave({
         }
         if ('company_id' in payload) next.company_id = payload.company_id as string | null
         if ('company_name' in payload) next.company_name = payload.company_name as string | null
+        if ('person_id' in payload) next.person_id = payload.person_id as string | null
+        if ('person_name' in payload) next.person_name = payload.person_name as string | null
         if ('description' in payload)
           next.description = (payload.description as string | null) ?? null
         if ('delivery_date' in payload)
@@ -1448,10 +1483,13 @@ const autosave = createJobAutosave({
         if (touchedKeys.includes('person_id')) {
           nextBaseline.person_id = serverJobDetail.person_id ?? null
           localJobData.value.person_id = serverJobDetail.person_id ?? null
+          headerPatch.person_id = serverJobDetail.person_id ?? null
         }
         if (touchedKeys.includes('person_name')) {
           nextBaseline.person_name = serverJobDetail.person_name ?? null
           localJobData.value.person_name = serverJobDetail.person_name ?? null
+          personDisplayValue.value = serverJobDetail.person_name ?? ''
+          headerPatch.person_name = serverJobDetail.person_name ?? null
         }
       } else {
         if (touchedKeys.includes('description')) {
@@ -1568,12 +1606,14 @@ const autosave = createJobAutosave({
           const personId = coerceNullableString(partialPayload.person_id)
           nextBaseline.person_id = personId
           localJobData.value.person_id = personId
+          headerPatch.person_id = personId
         }
         if (touchedKeys.includes('person_name')) {
           const personName = coerceNullableString(partialPayload.person_name)
           nextBaseline.person_name = personName
           localJobData.value.person_name = personName
           personDisplayValue.value = personName ?? ''
+          headerPatch.person_name = personName
         }
       }
 
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
index 48d95d493..49a425a73 100644
--- a/frontend/src/composables/__tests__/usePersonManagement.test.ts
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -14,6 +14,12 @@ vi.mock('@/utils/debug', () => ({
   debugLog: vi.fn(),
 }))
 
+vi.mock('vue-sonner', () => ({
+  toast: {
+    error: vi.fn(),
+  },
+}))
+
 import { usePersonManagement } from '../usePersonManagement'
 import { schemas } from '@/api/generated/api'
 
@@ -43,38 +49,38 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
 
   it('returns empty string when no person is selected', () => {
     const { displayValue } = usePersonManagement()
-    expect(displayValue.get()).toBe('')
+    expect(displayValue.value).toBe('')
   })
 
   it('formats the selected person as "name - phone - email"', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson())
-    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100 - jane@example.com')
+    expect(displayValue.value).toBe('Jane Doe - +64 21 555 0100 - jane@example.com')
   })
 
   it('skips the phone segment when the person has no phone', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson({ phone: '' }))
-    expect(displayValue.get()).toBe('Jane Doe - jane@example.com')
+    expect(displayValue.value).toBe('Jane Doe - jane@example.com')
   })
 
   it('skips the email segment when the person has no email', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson({ person_email: null }))
-    expect(displayValue.get()).toBe('Jane Doe - +64 21 555 0100')
+    expect(displayValue.value).toBe('Jane Doe - +64 21 555 0100')
   })
 
   it('shows only the name when the person has neither phone nor email', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson({ phone: '', person_email: null }))
-    expect(displayValue.get()).toBe('Jane Doe')
+    expect(displayValue.value).toBe('Jane Doe')
   })
 
   it('set() splits "name - phone - email" into the selected person', () => {
     const { displayValue, setSelectedPerson, selectedPerson } = usePersonManagement()
     setSelectedPerson(buildPerson())
 
-    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
+    displayValue.value = 'Bob Smith - 09 555 1234 - bob@example.com'
 
     expect(selectedPerson.value).toMatchObject({
       person_name: 'Bob Smith',
@@ -86,7 +92,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
   it('set() populates the new-person form when nothing is selected', () => {
     const { displayValue, personForm } = usePersonManagement()
 
-    displayValue.set('Bob Smith - 09 555 1234 - bob@example.com')
+    displayValue.value = 'Bob Smith - 09 555 1234 - bob@example.com'
 
     expect(personForm.value).toMatchObject({
       name: 'Bob Smith',
@@ -98,7 +104,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
   it('set() with a blank value clears name, phone and email on the form', () => {
     const { displayValue, personForm } = usePersonManagement()
 
-    displayValue.set('')
+    displayValue.value = ''
 
     expect(personForm.value).toMatchObject({
       name: '',
diff --git a/frontend/src/composables/useJobHeaderAutosave.ts b/frontend/src/composables/useJobHeaderAutosave.ts
index 82bef185e..3300b75f7 100644
--- a/frontend/src/composables/useJobHeaderAutosave.ts
+++ b/frontend/src/composables/useJobHeaderAutosave.ts
@@ -48,6 +48,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
     if ('name' in patch) p.name = patch.name as string
     if ('company_id' in patch) p.company_id = patch.company_id as string | null
     if ('company_name' in patch) p.company_name = patch.company_name as string | null
+    if ('person_id' in patch) p.person_id = patch.person_id as string | null
+    if ('person_name' in patch) p.person_name = patch.person_name as string | null
     if ('job_status' in patch)
       p.status = (patch.job_status as JobStatusKey | undefined) ?? undefined
     if ('pricing_methodology' in patch)
@@ -64,7 +66,8 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
   /**
    * Applies a patch (based on "local" fields reflected from header) to the header snapshot.
-   * Accepts keys: name, company_id, company_name, job_status, pricing_methodology, quoted, fully_invoiced, paid.
+   * Accepts keys: name, company_id, company_name, person_id, person_name, job_status,
+   * pricing_methodology, quoted, fully_invoiced, paid.
    * Here we do the inverse mapping (local fields -> header).
    */
   const applyPatchToHeader = (base: JobHeaderResponse, patch: Partial<Job>): JobHeaderResponse => {
@@ -84,6 +87,14 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
         patch.company_name !== undefined
           ? ((patch.company_name as string | null) ?? null)
           : base.company_name,
+      person_id:
+        patch.person_id !== undefined
+          ? ((patch.person_id as string | null) ?? null)
+          : base.person_id,
+      person_name:
+        patch.person_name !== undefined
+          ? ((patch.person_name as string | null) ?? null)
+          : base.person_name,
       status,
       pricing_methodology:
         (patch.pricing_methodology as PricingMethodology | undefined) ?? base.pricing_methodology,
@@ -134,6 +145,9 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
             const allowedHeaderKeys = [
               'name',
               'company_id',
+              'company_name',
+              'person_id',
+              'person_name',
               'job_status',
               'pricing_methodology',
               'quoted',
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
index cb72a9e19..215066db0 100644
--- a/frontend/src/composables/usePersonManagement.ts
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -3,6 +3,7 @@ import { schemas } from '@/api/generated/api'
 import { api } from '@/api/client'
 import { z } from 'zod'
 import { debugLog } from '@/utils/debug'
+import { toast } from 'vue-sonner'
 
 // Schema-derived types (no custom interfaces)
 type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
@@ -54,7 +55,7 @@ export function usePersonManagement() {
 
   const hasPeople = computed(() => people.value.length > 0)
 
-  const displayValue = {
+  const displayValue = computed({
     get() {
       if (!selectedPerson.value) return ''
       const person = selectedPerson.value
@@ -82,7 +83,7 @@ export function usePersonManagement() {
         }
       }
     },
-  }
+  })
 
   /**
    * Opens the person selection modal for a specific company
@@ -135,6 +136,7 @@ export function usePersonManagement() {
       personForm.value.is_primary = people.value.length === 0
     } catch (error) {
       debugLog('Error loading people:', error)
+      toast.error('Failed to load people for this company')
       people.value = []
       personForm.value.is_primary = true
     } finally {
diff --git a/frontend/src/services/job.service.ts b/frontend/src/services/job.service.ts
index 9080bce2a..d36854848 100644
--- a/frontend/src/services/job.service.ts
+++ b/frontend/src/services/job.service.ts
@@ -30,7 +30,7 @@ async function updateJobHeaderPartial(
       'quote_acceptance_date',
       'price_cap',
       'default_xero_pay_item_id',
-      // include 'person_name' if ever present
+      'person_id',
       'person_name',
     ])
     const normalizeBefore = (k: string, v: unknown) => {
diff --git a/frontend/src/stores/__tests__/companyStore.test.ts b/frontend/src/stores/__tests__/companyStore.test.ts
new file mode 100644
index 000000000..dc2487749
--- /dev/null
+++ b/frontend/src/stores/__tests__/companyStore.test.ts
@@ -0,0 +1,65 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { api } from '@/api/client'
+import { useCompanyStore } from '@/stores/companyStore'
+
+vi.mock('@/api/client', () => ({
+  api: {
+    companies_person_links_list: vi.fn(),
+  },
+}))
+
+const mockedApi = vi.mocked(api)
+
+describe('company store people links', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+    vi.clearAllMocks()
+  })
+
+  it('fetchCompanyPersonLinks updates companyPeople as a side effect', async () => {
+    const store = useCompanyStore()
+    const previousCompanyPeople = store.companyPeople
+    const people = [
+      {
+        id: 'link-1',
+        company: 'company-1',
+        person: 'person-1',
+        person_name: 'Jane Doe',
+        person_email: 'jane@example.com',
+        xero_name: 'Jane Doe',
+        position: null,
+        is_primary: true,
+        notes: null,
+        is_active: true,
+        created_at: '2026-01-01T00:00:00+00:00',
+        updated_at: '2026-01-01T00:00:00+00:00',
+        phone: '+64 21 555 0100',
+      },
+    ]
+    mockedApi.companies_person_links_list.mockResolvedValueOnce(people)
+
+    const result = await store.fetchCompanyPersonLinks('company-1')
+
+    expect(result).toBeUndefined()
+    expect(store.companyPeople).not.toBe(previousCompanyPeople)
+    expect(store.companyPeople['company-1']).toEqual(people)
+  })
+
+  it('getCompanyPersonLinks uses cached state and otherwise fetches as a side effect', async () => {
+    const store = useCompanyStore()
+    mockedApi.companies_person_links_list.mockResolvedValueOnce([])
+
+    const result = await store.getCompanyPersonLinks('company-1')
+
+    expect(result).toBeUndefined()
+    expect(mockedApi.companies_person_links_list).toHaveBeenCalledWith({
+      queries: { company_id: 'company-1' },
+    })
+    expect(store.companyPeople['company-1']).toEqual([])
+
+    await store.getCompanyPersonLinks('company-1')
+
+    expect(mockedApi.companies_person_links_list).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/frontend/src/stores/__tests__/jobs.test.ts b/frontend/src/stores/__tests__/jobs.test.ts
index 0e961553c..63e50bbae 100644
--- a/frontend/src/stores/__tests__/jobs.test.ts
+++ b/frontend/src/stores/__tests__/jobs.test.ts
@@ -139,4 +139,34 @@ describe('jobs store kanban cache', () => {
 
     expect(store.kanbanColumnCache.in_progress).toBeUndefined()
   })
+
+  it('clears stale kanban person name when detailed job has no person', () => {
+    const store = useJobsStore()
+
+    store.setKanbanJob(buildKanbanJob({ id: 'job-1', person_name: 'Stale Person' }))
+    store.setDetailedJob({
+      job: {
+        id: 'job-1',
+        job_number: 9001,
+        name: 'Detailed Job',
+        job_status: 'in_progress',
+        company_name: 'Company',
+        company_id: null,
+        person_id: null,
+        person_name: null,
+        paid: false,
+        fully_invoiced: false,
+        quoted: false,
+        quote_acceptance_date: null,
+        pricing_methodology: 'time_materials',
+        price_cap: null,
+        default_xero_pay_item_id: null,
+        default_xero_pay_item_name: null,
+      },
+      events: [],
+      company_defaults: {},
+    })
+
+    expect(store.getKanbanJobById('job-1')?.person_name).toBe('')
+  })
 })
diff --git a/frontend/src/stores/companyStore.ts b/frontend/src/stores/companyStore.ts
index b13d61652..747ae4ba9 100644
--- a/frontend/src/stores/companyStore.ts
+++ b/frontend/src/stores/companyStore.ts
@@ -107,18 +107,23 @@ export const useCompanyStore = defineStore('companies', () => {
    * Fetch people for a specific company
    * @param companyId UUID of the company
    */
-  async function fetchCompanyPersonLinks(companyId: string) {
+  async function fetchCompanyPersonLinks(companyId: string): Promise<void> {
     isLoadingPeople.value = true
 
     try {
       const response = await api.companies_person_links_list({
         queries: { company_id: companyId },
       })
-      companyPeople.value[companyId] = response
-      return response
+      companyPeople.value = {
+        ...companyPeople.value,
+        [companyId]: response,
+      }
     } catch (error) {
       console.error('Failed to fetch company people:', error)
-      companyPeople.value[companyId] = []
+      companyPeople.value = {
+        ...companyPeople.value,
+        [companyId]: [],
+      }
       throw error
     } finally {
       isLoadingPeople.value = false
@@ -140,11 +145,11 @@ export const useCompanyStore = defineStore('companies', () => {
    * Get cached company people or fetch if not available
    * @param companyId UUID of the company
    */
-  async function getCompanyPersonLinks(companyId: string): Promise<CompanyPersonLink[]> {
+  async function getCompanyPersonLinks(companyId: string): Promise<void> {
     if (companyPeople.value[companyId]) {
-      return companyPeople.value[companyId]
+      return
     }
-    return await fetchCompanyPersonLinks(companyId)
+    await fetchCompanyPersonLinks(companyId)
   }
 
   /**
diff --git a/frontend/src/stores/jobs.ts b/frontend/src/stores/jobs.ts
index 087661e38..d8d4e686d 100644
--- a/frontend/src/stores/jobs.ts
+++ b/frontend/src/stores/jobs.ts
@@ -321,7 +321,7 @@ export const useJobsStore = defineStore('jobs', () => {
           name: detailedJob.job.name,
           status: detailedJob.job.job_status,
           company_name: detailedJob.job.company_name || '',
-          person_name: detailedJob.job.person_name || kanbanJob.person_name,
+          person_name: detailedJob.job.person_name ?? '',
           paid: detailedJob.job.paid || false,
         },
       }
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index a343b3449..c8980966c 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -836,22 +836,6 @@ apps/accounting/services/wip_service.py:0: error: Argument "key" to "sorted" has
 apps/accounting/services/wip_service.py:0: error: Incompatible return value type (got "object", expected "SupportsDunderLT[Any] | SupportsDunderGT[Any]")  [return-value]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Call to untyped function "_report_queryset" in typed context  [no-untyped-call]
-apps/workflow/management/commands/e2e_cleanup.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/quoting/services/ai_price_extraction.py:0: error: Incompatible default for parameter "model_name" (default has type "None", parameter has type "str")  [assignment]
 apps/quoting/services/ai_price_extraction.py:0: note: PEP 484 prohibits implicit Optional. Accordingly, mypy has changed its default to no_implicit_optional=True
 apps/quoting/services/ai_price_extraction.py:0: note: Use https://github.com/hauntsaninja/no_implicit_optional to automatically upgrade your codebase

From 7851827f10d68cb29a2022c032c9ff3abbde5518 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Fri, 10 Jul 2026 07:17:29 +1200
Subject: [PATCH 14/73] fix: type company person link serializer overrides

---
 apps/company/serializers.py | 6 ++++--
 mypy-baseline.txt           | 2 --
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 5ab6e7b70..40c3d3012 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -133,7 +133,7 @@ def to_internal_value(self, data: Any) -> Any:
 
         return super().to_internal_value(data)
 
-    def create(self, validated_data):
+    def create(self, validated_data: dict[str, Any]) -> CompanyPersonLink:
         raw_phone = validated_data.pop("phone", None)  # not a model field
         person_value = validated_data.pop("person", None)
         with transaction.atomic():
@@ -153,7 +153,9 @@ def create(self, validated_data):
             link = super().create(validated_data)
             return self._apply_phone(link, raw_phone)
 
-    def update(self, instance, validated_data):
+    def update(
+        self, instance: CompanyPersonLink, validated_data: dict[str, Any]
+    ) -> CompanyPersonLink:
         raw_phone = validated_data.pop("phone", None)  # not a model field
         person_data = validated_data.pop("person", None)
         with transaction.atomic():
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index c8980966c..5750b6c5b 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -666,9 +666,7 @@ apps/job/serializers/data_integrity_serializers.py:0: error: Missing type argume
 apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/job/serializers/data_integrity_serializers.py:0: error: Missing type arguments for generic type "Serializer"  [type-arg]
 apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/company/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
-apps/company/serializers.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
 apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]
 apps/company/serializers.py:0: error: Missing type arguments for generic type "ModelSerializer"  [type-arg]

From 57227b943256c89566370f89c3dda87f8d81e1c8 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Fri, 10 Jul 2026 07:33:08 +1200
Subject: [PATCH 15/73] fix: tighten company person serializer typing

---
 apps/company/__init__.py                      |  4 +++
 apps/company/serializers.py                   | 33 +++++++++++++++----
 ...028-type-annotations-are-data-contracts.md |  4 +--
 3 files changed, 32 insertions(+), 9 deletions(-)

diff --git a/apps/company/__init__.py b/apps/company/__init__.py
index ff7a64bd0..da7af1d09 100644
--- a/apps/company/__init__.py
+++ b/apps/company/__init__.py
@@ -29,6 +29,8 @@
             CompanyJobsResponseSerializer,
             CompanyListResponseSerializer,
             CompanyNameOnlySerializer,
+            CompanyPersonAttrs,
+            CompanyPersonLinkAttrs,
             CompanyPersonLinkSerializer,
             CompanySearchResponseSerializer,
             CompanySearchResultSerializer,
@@ -61,7 +63,9 @@
     "CompanyJobsResponseSerializer",
     "CompanyListResponseSerializer",
     "CompanyNameOnlySerializer",
+    "CompanyPersonAttrs",
     "CompanyPersonLink",
+    "CompanyPersonLinkAttrs",
     "CompanyPersonLinkSerializer",
     "CompanyQuerySet",
     "CompanySearchResponseSerializer",
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 40c3d3012..a6c71b72b 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, TypedDict
 
 from django.core.exceptions import ValidationError as DjangoValidationError
 from django.db import transaction
@@ -82,6 +82,26 @@ def set_primary_phone(owner: Company | Person, raw_value: str) -> None:
     transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
 
 
+class CompanyPersonAttrs(TypedDict, total=False):
+    """DRF-normalized nested attrs from person_name/person_email."""
+
+    name: str
+    email: str | None
+
+
+class CompanyPersonLinkAttrs(TypedDict, total=False):
+    """DRF-normalized writable attrs for CompanyPersonLinkSerializer."""
+
+    company: Company
+    person: CompanyPersonAttrs
+    xero_name: str | None
+    position: str | None
+    is_primary: bool
+    notes: str | None
+    is_active: bool
+    phone: str | None
+
+
 class CompanyPersonLinkSerializer(serializers.ModelSerializer):
     """Serializer for a person's relationship to a company."""
 
@@ -133,34 +153,33 @@ def to_internal_value(self, data: Any) -> Any:
 
         return super().to_internal_value(data)
 
-    def create(self, validated_data: dict[str, Any]) -> CompanyPersonLink:
+    def create(self, validated_data: CompanyPersonLinkAttrs) -> CompanyPersonLink:
         raw_phone = validated_data.pop("phone", None)  # not a model field
         person_value = validated_data.pop("person", None)
         with transaction.atomic():
-            if isinstance(person_value, dict):
+            if person_value is not None and "name" in person_value:
                 person = Person.objects.create(
                     name=person_value["name"],
                     email=person_value.get("email"),
                     is_active=validated_data.get("is_active", True),
                 )
-                validated_data["person"] = person
             else:
                 raise serializers.ValidationError(
                     {"person_name": "This field is required."}
                 )
             if validated_data.get("xero_name") is None:
                 validated_data["xero_name"] = person.name
-            link = super().create(validated_data)
+            link = super().create({**validated_data, "person": person})
             return self._apply_phone(link, raw_phone)
 
     def update(
-        self, instance: CompanyPersonLink, validated_data: dict[str, Any]
+        self, instance: CompanyPersonLink, validated_data: CompanyPersonLinkAttrs
     ) -> CompanyPersonLink:
         raw_phone = validated_data.pop("phone", None)  # not a model field
         person_data = validated_data.pop("person", None)
         with transaction.atomic():
             link = super().update(instance, validated_data)
-            if isinstance(person_data, dict):
+            if person_data is not None:
                 person_update_fields = ["updated_at"]
                 if "name" in person_data:
                     link.person.name = person_data["name"]
diff --git a/docs/adr/0028-type-annotations-are-data-contracts.md b/docs/adr/0028-type-annotations-are-data-contracts.md
index 895d7e910..8a1152352 100644
--- a/docs/adr/0028-type-annotations-are-data-contracts.md
+++ b/docs/adr/0028-type-annotations-are-data-contracts.md
@@ -8,7 +8,7 @@ The app relies on strict data contracts to stay bug-free. A type shortcut can we
 
 ## Decision
 
-When touching Python code, improve its mypy state by preserving or tightening the real contract. Do not add `Any`, broad `object`, fake optionality, broad unions, casts, or ignores to avoid local typing work. `Any` and `object` are allowed only at unavoidable external or dynamic boundaries, and must be immediately validated or converted into a typed shape. `T | None` is allowed only when `None` is genuinely valid and intentionally handled. If a type becomes complex enough to hide domain meaning, introduce a named type: dataclass for internal domain values, `TypedDict` for dict-shaped payloads, protocol for behaviour, or a simple alias for readable composition.
+When touching Python code, improve its mypy state by preserving or tightening the real contract. Do not add `Any`, containers of `Any`, broad `object`, fake optionality, broad unions, casts, or ignores to avoid local typing work. `Any` and `object` are allowed only at unavoidable external or dynamic boundaries, and must be immediately validated or converted into a typed shape. `T | None` is allowed only when `None` is genuinely valid and intentionally handled. If a type becomes complex enough to hide domain meaning, introduce a named type: dataclass for internal domain values, `TypedDict` for dict-shaped payloads, protocol for behaviour, or a simple alias for readable composition.
 
 Contract discipline applies to control flow as well as annotations. Fallback-style `dict.get()`, `hasattr()` probes, and happy-case-first branching are not banned, but they are smells in application code because they often mean the contract is unclear. Use them at genuine dynamic boundaries only, then validate or convert into a named shape. Once code indexes, mutates, or reads attributes from a value, give that value a real type. For required data, prefer direct access after validation so malformed input fails loudly instead of becoming a default.
 
@@ -18,7 +18,7 @@ Types are executable documentation for the data model. A helper typed as accepti
 
 Readable named types also make review possible. `dict[str, list[tuple[str, list[tuple[str, int, float]]]]]` forces readers to decode positional meaning. `OrdersByCustomer = dict[str, list[Order]]`, with `Order` and `OrderLine` named, states the model directly and gives mypy stable structure to enforce.
 
-Small code-shape choices carry the same signal. Use `payload["job_id"]` after serializer or schema validation instead of `payload.get("job_id", "")`. Introduce `JobPayload` as a `TypedDict` instead of passing `dict[str, object]` once callers read keys from it. Load the required annotation or relation before rendering instead of probing with `hasattr()`. Check `if missing_required_value: raise ...` before the main path instead of nesting the whole function under `if value:`.
+Small code-shape choices carry the same signal. Use `payload["job_id"]` after serializer or schema validation instead of `payload.get("job_id", "")`. Introduce `JobPayload` as a `TypedDict` instead of passing `dict[str, object]` or `dict[str, Any]` once callers read keys from it. Load the required annotation or relation before rendering instead of probing with `hasattr()`. Check `if missing_required_value: raise ...` before the main path instead of nesting the whole function under `if value:`.
 
 ## Alternatives considered
 

From 7bb5ff76b50a37db6c0a3bff6e28ba09b3311c1f Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Fri, 10 Jul 2026 07:48:23 +1200
Subject: [PATCH 16/73] fix: refine company person serializer attr contracts

---
 apps/company/__init__.py                   | 14 ++--
 apps/company/serializers.py                | 82 +++++++++++++++-------
 apps/company/tests/test_contact_methods.py | 38 ++++++++++
 3 files changed, 106 insertions(+), 28 deletions(-)

diff --git a/apps/company/__init__.py b/apps/company/__init__.py
index da7af1d09..b15721916 100644
--- a/apps/company/__init__.py
+++ b/apps/company/__init__.py
@@ -29,9 +29,12 @@
             CompanyJobsResponseSerializer,
             CompanyListResponseSerializer,
             CompanyNameOnlySerializer,
-            CompanyPersonAttrs,
-            CompanyPersonLinkAttrs,
+            CompanyPersonCreateAttrs,
+            CompanyPersonLinkCreateAttrs,
+            CompanyPersonLinkModelCreateAttrs,
             CompanyPersonLinkSerializer,
+            CompanyPersonLinkUpdateAttrs,
+            CompanyPersonUpdateAttrs,
             CompanySearchResponseSerializer,
             CompanySearchResultSerializer,
             CompanySerializer,
@@ -63,10 +66,13 @@
     "CompanyJobsResponseSerializer",
     "CompanyListResponseSerializer",
     "CompanyNameOnlySerializer",
-    "CompanyPersonAttrs",
+    "CompanyPersonCreateAttrs",
     "CompanyPersonLink",
-    "CompanyPersonLinkAttrs",
+    "CompanyPersonLinkCreateAttrs",
+    "CompanyPersonLinkModelCreateAttrs",
     "CompanyPersonLinkSerializer",
+    "CompanyPersonLinkUpdateAttrs",
+    "CompanyPersonUpdateAttrs",
     "CompanyQuerySet",
     "CompanySearchResponseSerializer",
     "CompanySearchResultSerializer",
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index a6c71b72b..3c37d3a8a 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -1,4 +1,4 @@
-from typing import Any, TypedDict
+from typing import Any, NotRequired, TypedDict
 
 from django.core.exceptions import ValidationError as DjangoValidationError
 from django.db import transaction
@@ -82,23 +82,52 @@ def set_primary_phone(owner: Company | Person, raw_value: str) -> None:
     transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
 
 
-class CompanyPersonAttrs(TypedDict, total=False):
-    """DRF-normalized nested attrs from person_name/person_email."""
+class CompanyPersonCreateAttrs(TypedDict):
+    """DRF-normalized person attrs required when creating a company link."""
+
+    name: str
+    email: NotRequired[str | None]
+
+
+class CompanyPersonUpdateAttrs(TypedDict, total=False):
+    """DRF-normalized person attrs accepted when updating a company link."""
 
     name: str
     email: str | None
 
 
-class CompanyPersonLinkAttrs(TypedDict, total=False):
-    """DRF-normalized writable attrs for CompanyPersonLinkSerializer."""
+class CompanyPersonLinkCreateAttrs(TypedDict):
+    """DRF-normalized writable attrs for CompanyPersonLinkSerializer.create."""
 
     company: Company
-    person: CompanyPersonAttrs
+    person: CompanyPersonCreateAttrs
+    xero_name: NotRequired[str | None]
+    position: NotRequired[str | None]
+    is_primary: NotRequired[bool]
+    notes: NotRequired[str | None]
+    phone: NotRequired[str | None]
+
+
+class CompanyPersonLinkModelCreateAttrs(TypedDict):
+    """Model attrs passed to DRF after the nested person attrs are persisted."""
+
+    company: Company
+    person: Person
+    xero_name: NotRequired[str | None]
+    position: NotRequired[str | None]
+    is_primary: NotRequired[bool]
+    notes: NotRequired[str | None]
+
+
+class CompanyPersonLinkUpdateAttrs(TypedDict, total=False):
+    """DRF-normalized writable attrs for CompanyPersonLinkSerializer.update."""
+
+    company: Company
+    person: CompanyPersonUpdateAttrs
     xero_name: str | None
     position: str | None
     is_primary: bool
     notes: str | None
-    is_active: bool
     phone: str | None
 
 
@@ -153,27 +182,32 @@ def to_internal_value(self, data: Any) -> Any:
 
         return super().to_internal_value(data)
 
-    def create(self, validated_data: CompanyPersonLinkAttrs) -> CompanyPersonLink:
-        raw_phone = validated_data.pop("phone", None)  # not a model field
-        person_value = validated_data.pop("person", None)
+    def create(self, validated_data: CompanyPersonLinkCreateAttrs) -> CompanyPersonLink:
+        raw_phone = validated_data.get("phone")  # not a model field
+        person_value = validated_data["person"]
         with transaction.atomic():
-            if person_value is not None and "name" in person_value:
-                person = Person.objects.create(
-                    name=person_value["name"],
-                    email=person_value.get("email"),
-                    is_active=validated_data.get("is_active", True),
-                )
-            else:
-                raise serializers.ValidationError(
-                    {"person_name": "This field is required."}
-                )
-            if validated_data.get("xero_name") is None:
-                validated_data["xero_name"] = person.name
-            link = super().create({**validated_data, "person": person})
+            person = Person.objects.create(
+                name=person_value["name"],
+                email=person_value.get("email"),
+                is_active=True,
+            )
+            xero_name = validated_data.get("xero_name")
+            link_data: CompanyPersonLinkModelCreateAttrs = {
+                "company": validated_data["company"],
+                "person": person,
+                "xero_name": xero_name if xero_name is not None else person.name,
+            }
+            if "position" in validated_data:
+                link_data["position"] = validated_data["position"]
+            if "is_primary" in validated_data:
+                link_data["is_primary"] = validated_data["is_primary"]
+            if "notes" in validated_data:
+                link_data["notes"] = validated_data["notes"]
+            link = super().create(link_data)
             return self._apply_phone(link, raw_phone)
 
     def update(
-        self, instance: CompanyPersonLink, validated_data: CompanyPersonLinkAttrs
+        self, instance: CompanyPersonLink, validated_data: CompanyPersonLinkUpdateAttrs
     ) -> CompanyPersonLink:
         raw_phone = validated_data.pop("phone", None)  # not a model field
         person_data = validated_data.pop("person", None)
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index 9f2419478..9a5a20e43 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -481,6 +481,44 @@ def test_create_contact_with_phone_creates_primary_method(self) -> None:
         self.assertTrue(method.is_primary)
         rematch.assert_called_once_with(["+6421222222"])
 
+    def test_create_contact_sets_person_fields_and_ignores_is_active(self) -> None:
+        response = self.client.post(
+            self.URL,
+            {
+                "company": str(self.job_client.id),
+                "person_name": "Bob Brown",
+                "person_email": "bob@example.com",
+                "is_active": False,
+            },
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 201)
+        link = CompanyPersonLink.objects.select_related("person").get(
+            pk=response.json()["id"]
+        )
+        self.assertEqual(link.person.name, "Bob Brown")
+        self.assertEqual(link.person.email, "bob@example.com")
+        self.assertTrue(link.person.is_active)
+        self.assertTrue(link.is_active)
+
+    def test_update_contact_updates_person_name_and_email(self) -> None:
+        contact = self._contact("Jane Smith")
+
+        response = self.client.patch(
+            f"{self.URL}{contact.id}/",
+            {
+                "person_name": "Jane Brown",
+                "person_email": "jane@example.com",
+            },
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 200)
+        contact.person.refresh_from_db()
+        self.assertEqual(contact.person.name, "Jane Brown")
+        self.assertEqual(contact.person.email, "jane@example.com")
+
     def test_update_phone_updates_existing_primary_method(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
         method = contact.person.contact_methods.get()

From 7c7e158289efa99ee7674fa59ddd90ef6259a4ff Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Fri, 10 Jul 2026 18:06:13 +1200
Subject: [PATCH 17/73] fix: finish KAN-278 terminology cleanup

---
 .../services/duplicate_phone_report.py        |  10 +-
 .../tests/test_company_merge_service.py       |   4 +-
 .../tests/test_duplicate_phone_report.py      |   6 +-
 apps/crm/tests/test_phone_call_service.py     |  17 ++-
 apps/crm/views/phone_call_views.py            |  20 +--
 ...6_rename_job_event_people_company_terms.py |  74 +++++++++
 apps/job/models/job.py                        |   4 +-
 apps/job/models/job_event.py                  |   4 +-
 .../data_quality_report_serializers.py        |   8 +-
 apps/job/services/kanban_service.py           |   2 +-
 apps/job/tests/test_duplicate_phones_view.py  |   2 +-
 .../test_job_event_terminology_migration.py   |  83 ++++++++++
 ..._search_telemetry_company_lookup_source.py |  27 ++++
 apps/workflow/tests/test_search_telemetry.py  |   2 +-
 .../tests/test_search_telemetry_migration.py  |  55 +++++++
 frontend/schema.yml                           |  18 +--
 frontend/src/api/generated/api.ts             |  12 +-
 frontend/src/components/CompanyLookup.vue     |   2 +-
 frontend/src/composables/useCompanyLookup.ts  |   2 +-
 .../crm/__tests__/calls.pagination.test.ts    |   4 +-
 frontend/src/pages/crm/calls.vue              |   8 +-
 .../reports/data-quality/duplicate-phones.vue |  10 +-
 scripts/analyze_client_contacts.py            | 132 ----------------
 scripts/analyze_company_people.py             | 143 ++++++++++++++++++
 24 files changed, 455 insertions(+), 194 deletions(-)
 create mode 100644 apps/job/migrations/0006_rename_job_event_people_company_terms.py
 create mode 100644 apps/job/tests/test_job_event_terminology_migration.py
 create mode 100644 apps/workflow/migrations/0008_rename_search_telemetry_company_lookup_source.py
 create mode 100644 apps/workflow/tests/test_search_telemetry_migration.py
 delete mode 100644 scripts/analyze_client_contacts.py
 create mode 100644 scripts/analyze_company_people.py

diff --git a/apps/company/services/duplicate_phone_report.py b/apps/company/services/duplicate_phone_report.py
index a806083b4..326d399ad 100644
--- a/apps/company/services/duplicate_phone_report.py
+++ b/apps/company/services/duplicate_phone_report.py
@@ -13,7 +13,7 @@ class DuplicatePhoneOwner(TypedDict):
     method_id: str
     owner_kind: str
     owner_name: str
-    effective_client_id: str | None
+    effective_company_id: str | None
 
 
 class DuplicatePhoneIssue(TypedDict):
@@ -24,7 +24,7 @@ class DuplicatePhoneIssue(TypedDict):
 
 
 class DuplicatePhoneSummary(TypedDict):
-    cross_client: int
+    cross_company: int
     internal_line: int
 
 
@@ -43,7 +43,7 @@ def get_report(self) -> DuplicatePhonesReport:
         return {
             "duplicate_phones": cross_company + internal_line,
             "summary": {
-                "cross_client": len(cross_company),
+                "cross_company": len(cross_company),
                 "internal_line": len(internal_line),
             },
             "checked_at": timezone.now(),
@@ -78,7 +78,7 @@ def _cross_company_conflicts(self) -> list[DuplicatePhoneIssue]:
         return [
             {
                 "normalized_value": number,
-                "issue": "cross_client",
+                "issue": "cross_company",
                 "endpoint_label": None,
                 "owners": owners,
             }
@@ -118,7 +118,7 @@ def _owner(method: ContactMethod) -> DuplicatePhoneOwner:
             "method_id": str(method.id),
             "owner_kind": "company" if method.company_id else "person",
             "owner_name": method.owner_display_name(),
-            "effective_client_id": (
+            "effective_company_id": (
                 str(effective_company_id) if effective_company_id else None
             ),
         }
diff --git a/apps/company/tests/test_company_merge_service.py b/apps/company/tests/test_company_merge_service.py
index a21be838f..b7c45c6b4 100644
--- a/apps/company/tests/test_company_merge_service.py
+++ b/apps/company/tests/test_company_merge_service.py
@@ -558,10 +558,10 @@ def test_job_reassignment_creates_company_changed_event(self) -> None:
         self.assertEqual(
             events_after,
             events_before + 1,
-            "Job reassignment should create a client_changed JobEvent",
+            "Job reassignment should create a company_changed JobEvent",
         )
         latest = JobEvent.objects.filter(job=job).latest("timestamp")
-        self.assertEqual(latest.event_type, "client_changed")
+        self.assertEqual(latest.event_type, "company_changed")
         self.assertEqual(latest.delta_after["company_id"], str(self.destination.id))
 
 
diff --git a/apps/company/tests/test_duplicate_phone_report.py b/apps/company/tests/test_duplicate_phone_report.py
index 1945afcf9..5918febd7 100644
--- a/apps/company/tests/test_duplicate_phone_report.py
+++ b/apps/company/tests/test_duplicate_phone_report.py
@@ -43,14 +43,14 @@ def test_detects_cross_company_number(self) -> None:
 
         report = DuplicatePhoneReportService().get_report()
 
-        cross = [i for i in report["duplicate_phones"] if i["issue"] == "cross_client"]
+        cross = [i for i in report["duplicate_phones"] if i["issue"] == "cross_company"]
         self.assertEqual(len(cross), 1)
         self.assertEqual(
             cross[0]["normalized_value"],
             ContactMethod.normalize_phone("021 111 111"),
         )
         self.assertEqual(len(cross[0]["owners"]), 2)
-        self.assertEqual(report["summary"]["cross_client"], 1)
+        self.assertEqual(report["summary"]["cross_company"], 1)
 
     def test_detects_internal_line_collision(self) -> None:
         company = self._company("Acme Ltd")
@@ -83,5 +83,5 @@ def test_clean_data_returns_empty(self) -> None:
         report = DuplicatePhoneReportService().get_report()
 
         self.assertEqual(report["duplicate_phones"], [])
-        self.assertEqual(report["summary"], {"cross_client": 0, "internal_line": 0})
+        self.assertEqual(report["summary"], {"cross_company": 0, "internal_line": 0})
         self.assertIn("checked_at", report)
diff --git a/apps/crm/tests/test_phone_call_service.py b/apps/crm/tests/test_phone_call_service.py
index 8741f73dc..e10b79cb8 100644
--- a/apps/crm/tests/test_phone_call_service.py
+++ b/apps/crm/tests/test_phone_call_service.py
@@ -182,7 +182,7 @@ def test_same_number_across_contacts_on_one_client_is_allowed(
         self.assertEqual(matched_company, company)
         self.assertIsNone(matched_contact)
 
-    def test_same_number_across_clients_is_rejected(self) -> None:
+    def test_same_number_across_companies_is_rejected(self) -> None:
         first = self._client("Acme Ltd")
         second = self._client("Beta Ltd")
         ContactMethod.objects.create(
@@ -614,11 +614,11 @@ def test_list_filters_unmatched_and_unlinked_calls(self) -> None:
 
         unmatched_response = self.api.get(
             "/api/crm/phone-calls/",
-            {"client_match": "unmatched"},
+            {"company_match": "unmatched"},
         )
         unlinked_response = self.api.get(
             "/api/crm/phone-calls/",
-            {"client_match": "matched", "job_link": "unlinked"},
+            {"company_match": "matched", "job_link": "unlinked"},
         )
 
         self.assertEqual(unmatched_response.status_code, 200)
@@ -632,6 +632,15 @@ def test_list_filters_unmatched_and_unlinked_calls(self) -> None:
             [str(unlinked.id)],
         )
 
+    def test_list_rejects_legacy_client_match_filter(self) -> None:
+        response = self.api.get(
+            "/api/crm/phone-calls/",
+            {"client_match": "matched"},
+        )
+
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(response.data["client_match"], ["Use company_match."])
+
     def test_list_filters_by_direction_recording_date_and_search(self) -> None:
         """Catches recent-call filters drifting from provider call fields."""
         PhoneEndpoint.objects.update_or_create(
@@ -819,7 +828,7 @@ def test_link_rejects_unmatched_call(self) -> None:
         self.assertEqual(response.status_code, 400)
         self.assertIn("assigned to a company", response.data["message"])
 
-    def test_link_rejects_cross_client_job(self) -> None:
+    def test_link_rejects_cross_company_job(self) -> None:
         response = self.api.post(
             f"/api/crm/phone-calls/{self.call.id}/job-link/",
             {"job": str(self.other_job.id)},
diff --git a/apps/crm/views/phone_call_views.py b/apps/crm/views/phone_call_views.py
index a088f5abf..ba1eb643b 100644
--- a/apps/crm/views/phone_call_views.py
+++ b/apps/crm/views/phone_call_views.py
@@ -117,13 +117,13 @@ def _query_date(value: str | None, field_name: str) -> date | None:
     return parsed
 
 
-def _apply_client_match_filter(
+def _apply_company_match_filter(
     queryset: QuerySet[PhoneCallRecord],
-    client_match: str,
+    company_match: str,
 ) -> QuerySet[PhoneCallRecord]:
-    if client_match == "matched":
+    if company_match == "matched":
         return queryset.filter(company_id__isnull=False)
-    if client_match == "unmatched":
+    if company_match == "unmatched":
         return queryset.filter(company_id__isnull=True)
     return queryset
 
@@ -207,9 +207,11 @@ def _filter_phone_call_queryset(
     queryset: QuerySet[PhoneCallRecord],
     request: Request,
 ) -> QuerySet[PhoneCallRecord]:
-    client_match = _query_choice(
-        request.query_params.get("client_match"),
-        "client_match",
+    if "client_match" in request.query_params:
+        raise ValidationError({"client_match": ["Use company_match."]})
+    company_match = _query_choice(
+        request.query_params.get("company_match"),
+        "company_match",
         {"all", "matched", "unmatched"},
     )
     job_link = _query_choice(
@@ -226,7 +228,7 @@ def _filter_phone_call_queryset(
         request.query_params.get("has_recording"), "has_recording"
     )
 
-    queryset = _apply_client_match_filter(queryset, client_match)
+    queryset = _apply_company_match_filter(queryset, company_match)
     queryset = _apply_job_link_filter(queryset, job_link)
     queryset = _apply_direction_filter(queryset, direction)
     queryset = _apply_recording_filter(queryset, has_recording)
@@ -250,7 +252,7 @@ class PhoneCallRecordViewSet(viewsets.ReadOnlyModelViewSet[PhoneCallRecord]):
             OpenApiParameter(
                 "destination_endpoint", OpenApiTypes.UUID, OpenApiParameter.QUERY
             ),
-            OpenApiParameter("client_match", OpenApiTypes.STR, OpenApiParameter.QUERY),
+            OpenApiParameter("company_match", OpenApiTypes.STR, OpenApiParameter.QUERY),
             OpenApiParameter("job_link", OpenApiTypes.STR, OpenApiParameter.QUERY),
             OpenApiParameter("direction", OpenApiTypes.STR, OpenApiParameter.QUERY),
             OpenApiParameter(
diff --git a/apps/job/migrations/0006_rename_job_event_people_company_terms.py b/apps/job/migrations/0006_rename_job_event_people_company_terms.py
new file mode 100644
index 000000000..b704c96c1
--- /dev/null
+++ b/apps/job/migrations/0006_rename_job_event_people_company_terms.py
@@ -0,0 +1,74 @@
+from typing import Any
+
+from django.db import migrations
+
+EVENT_TYPE_RENAMES = {
+    "client_changed": "company_changed",
+    "contact_changed": "person_changed",
+}
+EVENT_TYPE_REVERSES = {value: key for key, value in EVENT_TYPE_RENAMES.items()}
+DETAIL_LABEL_RENAMES = {
+    "Client": "Company",
+    "Contact": "Person",
+}
+DETAIL_LABEL_REVERSES = {value: key for key, value in DETAIL_LABEL_RENAMES.items()}
+
+
+def _rename_event_types(JobEvent: Any, mapping: dict[str, str]) -> None:
+    for old_value, new_value in mapping.items():
+        JobEvent.objects.filter(event_type=old_value).update(event_type=new_value)
+
+
+def _rename_detail_labels(JobEvent: Any, mapping: dict[str, str]) -> None:
+    queryset = JobEvent.objects.filter(
+        event_type__in=[
+            "client_changed",
+            "contact_changed",
+            "company_changed",
+            "person_changed",
+        ]
+    )
+    for event in queryset.iterator():
+        detail = event.detail or {}
+        changed = False
+
+        field_name = detail.get("field_name")
+        if field_name in mapping:
+            detail["field_name"] = mapping[field_name]
+            changed = True
+
+        changes = detail.get("changes")
+        if isinstance(changes, list):
+            for change in changes:
+                if not isinstance(change, dict):
+                    continue
+                change_field_name = change.get("field_name")
+                if change_field_name in mapping:
+                    change["field_name"] = mapping[change_field_name]
+                    changed = True
+
+        if changed:
+            event.detail = detail
+            event.save(update_fields=["detail"])
+
+
+def forwards(apps: Any, schema_editor: Any) -> None:
+    JobEvent = apps.get_model("job", "JobEvent")
+    _rename_detail_labels(JobEvent, DETAIL_LABEL_RENAMES)
+    _rename_event_types(JobEvent, EVENT_TYPE_RENAMES)
+
+
+def backwards(apps: Any, schema_editor: Any) -> None:
+    JobEvent = apps.get_model("job", "JobEvent")
+    _rename_detail_labels(JobEvent, DETAIL_LABEL_REVERSES)
+    _rename_event_types(JobEvent, EVENT_TYPE_REVERSES)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("job", "0005_remove_job_contact_alter_job_person"),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards, backwards),
+    ]
diff --git a/apps/job/models/job.py b/apps/job/models/job.py
index 4c22b6612..a0cd3ee6d 100644
--- a/apps/job/models/job.py
+++ b/apps/job/models/job.py
@@ -942,7 +942,7 @@ def _handle_company_change(self_job, old_company_id, new_company_id):
                 self_job.company.name if self_job.company else "Unknown Company"
             )
         return (
-            "client_changed",
+            "company_changed",
             {
                 "field_name": "Company",
                 "old_value": old_company,
@@ -964,7 +964,7 @@ def _handle_person_change(self_job, old_person_id, new_person_id):
         if new_person_id:
             new_person = self_job.person.name if self_job.person else "Unknown Person"
         return (
-            "contact_changed",
+            "person_changed",
             {
                 "field_name": "Person",
                 "old_value": old_person,
diff --git a/apps/job/models/job_event.py b/apps/job/models/job_event.py
index becca74e8..bcefae311 100644
--- a/apps/job/models/job_event.py
+++ b/apps/job/models/job_event.py
@@ -327,8 +327,8 @@ def _build_jsa_description(detail: dict) -> str:
         "job_created": _build_job_created_description.__func__,
         "status_changed": _build_status_changed_description.__func__,
         "job_updated": _build_changes_description.__func__,
-        "client_changed": _build_changes_description.__func__,
-        "contact_changed": _build_changes_description.__func__,
+        "company_changed": _build_changes_description.__func__,
+        "person_changed": _build_changes_description.__func__,
         "notes_updated": _build_changes_description.__func__,
         "delivery_date_changed": _build_changes_description.__func__,
         "quote_accepted": _build_changes_description.__func__,
diff --git a/apps/job/serializers/data_quality_report_serializers.py b/apps/job/serializers/data_quality_report_serializers.py
index c4729be92..b668e4d25 100644
--- a/apps/job/serializers/data_quality_report_serializers.py
+++ b/apps/job/serializers/data_quality_report_serializers.py
@@ -71,9 +71,9 @@ class DuplicatePhoneOwnerSerializer(serializers.Serializer[DuplicatePhoneOwner])
     """One owner of a mis-owned phone number."""
 
     method_id = serializers.CharField(help_text="Contact-method id")
-    owner_kind = serializers.CharField(help_text="'company' or 'contact'")
+    owner_kind = serializers.CharField(help_text="'company' or 'person'")
     owner_name = serializers.CharField(help_text="Human-readable owner")
-    effective_client_id = serializers.CharField(
+    effective_company_id = serializers.CharField(
         allow_null=True, help_text="Company the number resolves to"
     )
 
@@ -81,7 +81,7 @@ class DuplicatePhoneOwnerSerializer(serializers.Serializer[DuplicatePhoneOwner])
 class DuplicatePhoneSummarySerializer(serializers.Serializer[DuplicatePhoneSummary]):
     """Summary of duplicate-phone issues."""
 
-    cross_client = serializers.IntegerField(
+    cross_company = serializers.IntegerField(
         help_text="Numbers owned by more than one company"
     )
     internal_line = serializers.IntegerField(
@@ -93,7 +93,7 @@ class DuplicatePhoneIssueSerializer(serializers.Serializer[DuplicatePhoneIssue])
     """One problematic phone number and its owners."""
 
     normalized_value = serializers.CharField(help_text="Normalized phone number")
-    issue = serializers.CharField(help_text="'cross_client' or 'internal_line'")
+    issue = serializers.CharField(help_text="'cross_company' or 'internal_line'")
     endpoint_label = serializers.CharField(
         required=False,
         allow_null=True,
diff --git a/apps/job/services/kanban_service.py b/apps/job/services/kanban_service.py
index d11932455..1cd1c1d23 100644
--- a/apps/job/services/kanban_service.py
+++ b/apps/job/services/kanban_service.py
@@ -92,7 +92,7 @@ class KanbanService:
                 "company__name", Value(""), output_field=TextField()
             ),
             "score": SEARCH_SCORE_COMPANY_CONTAINS,
-            "reason": "client_contains",
+            "reason": "company_contains",
         },
         {
             "db_path": "person__name",
diff --git a/apps/job/tests/test_duplicate_phones_view.py b/apps/job/tests/test_duplicate_phones_view.py
index 87a385e1f..c1dc860b3 100644
--- a/apps/job/tests/test_duplicate_phones_view.py
+++ b/apps/job/tests/test_duplicate_phones_view.py
@@ -36,7 +36,7 @@ def test_returns_cross_company_conflict_to_office_staff(self) -> None:
         response = self.client.get(URL)
 
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.data["summary"]["cross_client"], 1)
+        self.assertEqual(response.data["summary"]["cross_company"], 1)
         self.assertEqual(len(response.data["duplicate_phones"]), 1)
         self.assertEqual(len(response.data["duplicate_phones"][0]["owners"]), 2)
 
diff --git a/apps/job/tests/test_job_event_terminology_migration.py b/apps/job/tests/test_job_event_terminology_migration.py
new file mode 100644
index 000000000..198cfaf41
--- /dev/null
+++ b/apps/job/tests/test_job_event_terminology_migration.py
@@ -0,0 +1,83 @@
+from typing import ClassVar
+
+from django.db import connection
+from django.db.migrations.executor import MigrationExecutor
+from django.test import TransactionTestCase
+
+
+class JobEventTerminologyMigrationTests(TransactionTestCase):
+    migrate_from: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("job", "0005_remove_job_contact_alter_job_person"),
+    )
+    migrate_to: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("job", "0006_rename_job_event_people_company_terms"),
+    )
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.executor = MigrationExecutor(connection)
+        self.executor.migrate(self.migrate_from)
+        self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
+
+    def tearDown(self) -> None:
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
+        super().tearDown()
+
+    def test_forward_and_reverse_rename_event_types_and_detail_labels(self) -> None:
+        Staff = self.old_apps.get_model("accounts", "Staff")
+        JobEvent = self.old_apps.get_model("job", "JobEvent")
+        staff = Staff.objects.create(
+            email="migration-staff@example.test",
+            password="not-used",
+            first_name="Migration",
+            last_name="Staff",
+            wage_rate=0,
+            base_wage_rate=0,
+        )
+        company_event = JobEvent.objects.create(
+            staff=staff,
+            event_type="client_changed",
+            detail={
+                "field_name": "Client",
+                "old_value": "Old Co",
+                "new_value": "New Co",
+            },
+        )
+        person_event = JobEvent.objects.create(
+            staff=staff,
+            event_type="contact_changed",
+            detail={
+                "changes": [
+                    {
+                        "field_name": "Contact",
+                        "old_value": "Old Person",
+                        "new_value": "New Person",
+                    }
+                ]
+            },
+        )
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_to)
+        new_apps = self.executor.loader.project_state(self.migrate_to).apps
+        JobEvent = new_apps.get_model("job", "JobEvent")
+
+        company_event = JobEvent.objects.get(pk=company_event.pk)
+        person_event = JobEvent.objects.get(pk=person_event.pk)
+        self.assertEqual(company_event.event_type, "company_changed")
+        self.assertEqual(company_event.detail["field_name"], "Company")
+        self.assertEqual(person_event.event_type, "person_changed")
+        self.assertEqual(person_event.detail["changes"][0]["field_name"], "Person")
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_from)
+        reversed_apps = self.executor.loader.project_state(self.migrate_from).apps
+        JobEvent = reversed_apps.get_model("job", "JobEvent")
+
+        company_event = JobEvent.objects.get(pk=company_event.pk)
+        person_event = JobEvent.objects.get(pk=person_event.pk)
+        self.assertEqual(company_event.event_type, "client_changed")
+        self.assertEqual(company_event.detail["field_name"], "Client")
+        self.assertEqual(person_event.event_type, "contact_changed")
+        self.assertEqual(person_event.detail["changes"][0]["field_name"], "Contact")
diff --git a/apps/workflow/migrations/0008_rename_search_telemetry_company_lookup_source.py b/apps/workflow/migrations/0008_rename_search_telemetry_company_lookup_source.py
new file mode 100644
index 000000000..e64991c61
--- /dev/null
+++ b/apps/workflow/migrations/0008_rename_search_telemetry_company_lookup_source.py
@@ -0,0 +1,27 @@
+from typing import Any
+
+from django.db import migrations
+
+
+def forwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    SearchTelemetryEvent.objects.filter(source="client_lookup").update(
+        source="company_lookup"
+    )
+
+
+def backwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    SearchTelemetryEvent.objects.filter(source="company_lookup").update(
+        source="client_lookup"
+    )
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("workflow", "0007_rename_search_telemetry_client_domain"),
+    ]
+
+    operations = [
+        migrations.RunPython(forwards, backwards),
+    ]
diff --git a/apps/workflow/tests/test_search_telemetry.py b/apps/workflow/tests/test_search_telemetry.py
index a43fce3f3..24c14aeae 100644
--- a/apps/workflow/tests/test_search_telemetry.py
+++ b/apps/workflow/tests/test_search_telemetry.py
@@ -29,7 +29,7 @@ def test_search_click_endpoint_records_generic_event(db):
             "selected_label": "Fumecare Ltd",
             "selected_rank": 1,
             "result_count": 7,
-            "source": "client_lookup",
+            "source": "company_lookup",
             "metadata": {"extra": "future-safe"},
         },
         format="json",
diff --git a/apps/workflow/tests/test_search_telemetry_migration.py b/apps/workflow/tests/test_search_telemetry_migration.py
new file mode 100644
index 000000000..24466c729
--- /dev/null
+++ b/apps/workflow/tests/test_search_telemetry_migration.py
@@ -0,0 +1,55 @@
+from typing import ClassVar
+
+from django.db import connection
+from django.db.migrations.executor import MigrationExecutor
+from django.test import TransactionTestCase
+
+
+class SearchTelemetryTerminologyMigrationTests(TransactionTestCase):
+    migrate_from: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("workflow", "0007_rename_search_telemetry_client_domain"),
+    )
+    migrate_to: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("workflow", "0008_rename_search_telemetry_company_lookup_source"),
+    )
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.executor = MigrationExecutor(connection)
+        self.executor.migrate(self.migrate_from)
+        self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
+
+    def tearDown(self) -> None:
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
+        super().tearDown()
+
+    def test_forward_and_reverse_rename_company_lookup_source(self) -> None:
+        SearchTelemetryEvent = self.old_apps.get_model(
+            "workflow", "SearchTelemetryEvent"
+        )
+        event = SearchTelemetryEvent.objects.create(
+            event_type="click",
+            domain="company",
+            source="client_lookup",
+            query="Acme",
+            normalized_query="acme",
+        )
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_to)
+        new_apps = self.executor.loader.project_state(self.migrate_to).apps
+        SearchTelemetryEvent = new_apps.get_model("workflow", "SearchTelemetryEvent")
+
+        event = SearchTelemetryEvent.objects.get(pk=event.pk)
+        self.assertEqual(event.source, "company_lookup")
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_from)
+        reversed_apps = self.executor.loader.project_state(self.migrate_from).apps
+        SearchTelemetryEvent = reversed_apps.get_model(
+            "workflow", "SearchTelemetryEvent"
+        )
+
+        event = SearchTelemetryEvent.objects.get(pk=event.pk)
+        self.assertEqual(event.source, "client_lookup")
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 49a23ce6a..57f57c61b 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -2574,14 +2574,14 @@ paths:
       operationId: crm_phone_calls_list
       parameters:
         - in: query
-          name: client_match
+          name: company
           schema:
             type: string
+            format: uuid
         - in: query
-          name: company
+          name: company_match
           schema:
             type: string
-            format: uuid
         - in: query
           name: destination_endpoint
           schema:
@@ -12221,7 +12221,7 @@ components:
           description: Normalized phone number
         issue:
           type: string
-          description: "'cross_client' or 'internal_line'"
+          description: "'cross_company' or 'internal_line'"
         endpoint_label:
           type: string
           nullable: true
@@ -12243,16 +12243,16 @@ components:
           description: Contact-method id
         owner_kind:
           type: string
-          description: "'company' or 'contact'"
+          description: "'company' or 'person'"
         owner_name:
           type: string
           description: Human-readable owner
-        effective_client_id:
+        effective_company_id:
           type: string
           nullable: true
           description: Company the number resolves to
       required:
-        - effective_client_id
+        - effective_company_id
         - method_id
         - owner_kind
         - owner_name
@@ -12260,14 +12260,14 @@ components:
       type: object
       description: Summary of duplicate-phone issues.
       properties:
-        cross_client:
+        cross_company:
           type: integer
           description: Numbers owned by more than one company
         internal_line:
           type: integer
           description: Company numbers that are actually internal company lines
       required:
-        - cross_client
+        - cross_company
         - internal_line
     DuplicatePhonesResponse:
       type: object
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index 0dd8ad41d..e23d436aa 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -1347,7 +1347,7 @@ const DuplicatePhoneOwner = z.object({
   method_id: z.string(),
   owner_kind: z.string(),
   owner_name: z.string(),
-  effective_client_id: z.string().nullable(),
+  effective_company_id: z.string().nullable(),
 })
 const DuplicatePhoneIssue = z.object({
   normalized_value: z.string(),
@@ -1356,7 +1356,7 @@ const DuplicatePhoneIssue = z.object({
   owners: z.array(DuplicatePhoneOwner),
 })
 const DuplicatePhoneSummary = z.object({
-  cross_client: z.number().int(),
+  cross_company: z.number().int(),
   internal_line: z.number().int(),
 })
 const DuplicatePhonesResponse = z.object({
@@ -5760,14 +5760,14 @@ DELETE: Clear a logo field and remove the file from disk.`,
     requestFormat: 'json',
     parameters: [
       {
-        name: 'client_match',
+        name: 'company',
         type: 'Query',
-        schema: z.string().optional(),
+        schema: z.string().uuid().optional(),
       },
       {
-        name: 'company',
+        name: 'company_match',
         type: 'Query',
-        schema: z.string().uuid().optional(),
+        schema: z.string().optional(),
       },
       {
         name: 'destination_endpoint',
diff --git a/frontend/src/components/CompanyLookup.vue b/frontend/src/components/CompanyLookup.vue
index 0bf5d3e5b..4523f80e4 100644
--- a/frontend/src/components/CompanyLookup.vue
+++ b/frontend/src/components/CompanyLookup.vue
@@ -212,7 +212,7 @@ const selectCompany = (company: Company, rank: number | null = null) => {
   const query = searchQuery.value
   preserveSelectedCompany()
   selectCompanyFromComposable(company)
-  logCompanySearchClick(company, query, rank, 'client_lookup')
+  logCompanySearchClick(company, query, rank, 'company_lookup')
   emit('update:modelValue', company.name)
   emit('update:selectedCompany', company)
   emit('update:selectedId', company.id)
diff --git a/frontend/src/composables/useCompanyLookup.ts b/frontend/src/composables/useCompanyLookup.ts
index 531f513a9..5823cd14e 100644
--- a/frontend/src/composables/useCompanyLookup.ts
+++ b/frontend/src/composables/useCompanyLookup.ts
@@ -18,7 +18,7 @@ export async function logCompanySearchClick(
   company: Company,
   query: string,
   rank: number | null,
-  source = 'client_lookup',
+  source = 'company_lookup',
 ) {
   const trimmedQuery = query.trim()
   if (trimmedQuery.length < 3) {
diff --git a/frontend/src/pages/crm/__tests__/calls.pagination.test.ts b/frontend/src/pages/crm/__tests__/calls.pagination.test.ts
index 20a238f30..aaf6dd0bc 100644
--- a/frontend/src/pages/crm/__tests__/calls.pagination.test.ts
+++ b/frontend/src/pages/crm/__tests__/calls.pagination.test.ts
@@ -66,7 +66,7 @@ describe('CRM calls pagination', () => {
     await flushPromises()
 
     expect(api.crm_phone_calls_list).toHaveBeenCalledWith({
-      queries: { page: 1, page_size: 50, client_match: 'all', job_link: 'all' },
+      queries: { page: 1, page_size: 50, company_match: 'all', job_link: 'all' },
     })
     expect(wrapper.text()).toContain('Showing 1 of 12')
     expect(wrapper.text()).toContain('Recent Calls')
@@ -84,7 +84,7 @@ describe('CRM calls pagination', () => {
     await flushPromises()
 
     expect(api.crm_phone_calls_list).toHaveBeenLastCalledWith({
-      queries: { page: 1, page_size: 50, client_match: 'unmatched' },
+      queries: { page: 1, page_size: 50, company_match: 'unmatched' },
     })
   })
 
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index 1906e1f37..13142a8ab 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -183,7 +183,7 @@ type DirectionFilter = 'all' | 'inbound' | 'outbound' | 'internal' | 'unknown'
 type PhoneCallQuery = {
   page: number
   page_size: number
-  client_match?: string
+  company_match?: string
   job_link?: string
   direction?: string
   has_recording?: boolean
@@ -240,12 +240,12 @@ const activeQueue = computed(() => QUEUE_META[activeTab.value])
 function queryForActiveTab(): PhoneCallQuery {
   const query: PhoneCallQuery = { page: 1, page_size: 50 }
   if (activeTab.value === 'unmatched') {
-    query.client_match = 'unmatched'
+    query.company_match = 'unmatched'
   } else if (activeTab.value === 'unlinked') {
-    query.client_match = 'matched'
+    query.company_match = 'matched'
     query.job_link = 'unlinked'
   } else {
-    query.client_match = 'all'
+    query.company_match = 'all'
     query.job_link = 'all'
   }
   if (directionFilter.value !== 'all') query.direction = directionFilter.value
diff --git a/frontend/src/pages/reports/data-quality/duplicate-phones.vue b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
index ff81641df..3a4ea182a 100644
--- a/frontend/src/pages/reports/data-quality/duplicate-phones.vue
+++ b/frontend/src/pages/reports/data-quality/duplicate-phones.vue
@@ -37,8 +37,8 @@
               <div class="flex items-center gap-3">
                 <Users class="w-5 h-5 text-amber-500" />
                 <div>
-                  <p class="text-sm text-slate-600">Cross-client</p>
-                  <p class="text-2xl font-bold text-amber-600">{{ summary.cross_client }}</p>
+                  <p class="text-sm text-slate-600">Cross-company</p>
+                  <p class="text-2xl font-bold text-amber-600">{{ summary.cross_company }}</p>
                 </div>
               </div>
             </div>
@@ -190,18 +190,18 @@ type DuplicatePhoneSummary = z.infer<typeof schemas.DuplicatePhoneSummary>
 const loading = ref(false)
 const error = ref<string | null>(null)
 const duplicates = ref<DuplicatePhone[]>([])
-const summary = ref<DuplicatePhoneSummary>({ cross_client: 0, internal_line: 0 })
+const summary = ref<DuplicatePhoneSummary>({ cross_company: 0, internal_line: 0 })
 const lastRunTime = ref<string>('Never')
 
 // Known issue/owner kinds get styled labels; unknown future kinds render the
 // raw value with neutral styling instead of being mislabeled.
 const ISSUE_LABELS: Record<string, string> = {
-  cross_client: 'Cross-client',
+  cross_company: 'Cross-company',
   internal_line: 'Internal line',
 }
 
 const ISSUE_CLASSES: Record<string, string> = {
-  cross_client: 'bg-amber-100 text-amber-800',
+  cross_company: 'bg-amber-100 text-amber-800',
   internal_line: 'bg-blue-100 text-blue-800',
 }
 
diff --git a/scripts/analyze_client_contacts.py b/scripts/analyze_client_contacts.py
deleted file mode 100644
index ec48db783..000000000
--- a/scripts/analyze_client_contacts.py
+++ /dev/null
@@ -1,132 +0,0 @@
-#!/usr/bin/env python
-"""
-Analyze ClientContact records for duplicates and empty names.
-
-Usage:
-    python scripts/analyze_client_contacts.py
-    python scripts/analyze_client_contacts.py --verbose
-"""
-
-import argparse
-import logging
-import os
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
-
-import django
-
-django.setup()
-
-from django.db.models import Count
-
-from apps.company.models import ClientContact, Company
-from apps.job.models import Job
-
-
-def analyze_empty_names(verbose: bool) -> None:
-    """Analyze ClientContact records with empty/whitespace names."""
-    logging.info("1. EMPTY NAME ANALYSIS")
-
-    empty_name_contacts = ClientContact.objects.filter(
-        name=""
-    ) | ClientContact.objects.filter(name__regex=r"^\s+$")
-    count = empty_name_contacts.count()
-
-    logging.info("Total contacts with empty/whitespace names: %d", count)
-
-    if count > 0 and verbose:
-        logging.info("Sample records (first 10):")
-        for contact in empty_name_contacts[:10]:
-            logging.info("  - ID: %s", contact.id)
-            logging.info("    Company: %s", contact.company.name)
-            logging.info("    Name: '%s' (length: %d)", contact.name, len(contact.name))
-            logging.info("    Email: %s", contact.email or "None")
-
-            job_count = Job.objects.filter(contact=contact).count()
-            if job_count > 0:
-                logging.warning("    Referenced by %d jobs", job_count)
-
-
-def analyze_duplicates(verbose: bool) -> None:
-    """Analyze duplicate ClientContact records (same company + name)."""
-    logging.info("2. DUPLICATE CONTACT ANALYSIS")
-
-    duplicates = (
-        ClientContact.objects.values("company", "name")
-        .annotate(count=Count("id"))
-        .filter(count__gt=1)
-        .order_by("-count")
-    )
-
-    total_duplicate_groups = duplicates.count()
-    logging.info(
-        "Total duplicate (company, name) combinations: %d", total_duplicate_groups
-    )
-
-    if total_duplicate_groups == 0:
-        logging.info("No duplicates found")
-        return
-
-    total_duplicate_records = sum(d["count"] - 1 for d in duplicates)
-    logging.info("Total duplicate records to be merged: %d", total_duplicate_records)
-
-    if verbose:
-        logging.info("Top 10 duplicate groups:")
-        for i, dup in enumerate(duplicates[:10], 1):
-            company = Company.objects.get(id=dup["company"])
-            logging.info(
-                "%d. Company: %s — Contact: '%s' — %d copies",
-                i,
-                company.name,
-                dup["name"],
-                dup["count"],
-            )
-
-            contacts = ClientContact.objects.filter(
-                company_id=dup["company"], name=dup["name"]
-            ).order_by("-created_at")
-
-            for contact in contacts[:5]:
-                job_count = Job.objects.filter(contact=contact).count()
-                jobs_str = f" ({job_count} jobs)" if job_count > 0 else ""
-                logging.info(
-                    "     ID: %s  Email: %s  Created: %s%s",
-                    contact.id,
-                    contact.email or "None",
-                    contact.created_at,
-                    jobs_str,
-                )
-
-    # Summary
-    empty_count = (
-        ClientContact.objects.filter(name="")
-        | ClientContact.objects.filter(name__regex=r"^\s+$")
-    ).count()
-
-    logging.info("--- SUMMARY ---")
-    logging.info("Empty/whitespace name contacts: %d", empty_count)
-    logging.info("Duplicate (company, name) combinations: %d", total_duplicate_groups)
-    logging.info("Total duplicate records to be removed: %d", total_duplicate_records)
-    logging.info(
-        "Total records after cleanup: %d",
-        ClientContact.objects.count() - empty_count - total_duplicate_records,
-    )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
-        "--verbose",
-        action="store_true",
-        help="Show detailed information about each duplicate group",
-    )
-    args = parser.parse_args()
-
-    logging.info("ClientContact State Analysis")
-    analyze_empty_names(args.verbose)
-    analyze_duplicates(args.verbose)
-
-
-if __name__ == "__main__":
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
-    main()
diff --git a/scripts/analyze_company_people.py b/scripts/analyze_company_people.py
new file mode 100644
index 000000000..ec784d86a
--- /dev/null
+++ b/scripts/analyze_company_people.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python
+"""
+Analyze company/person links for duplicate and empty person names.
+
+Usage:
+    python scripts/analyze_company_people.py
+    python scripts/analyze_company_people.py --verbose
+"""
+
+import argparse
+import logging
+import os
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from django.db.models import Count
+
+from apps.company.models import Company, CompanyPersonLink
+from apps.job.models import Job
+
+
+def analyze_empty_names(verbose: bool) -> int:
+    """Analyze linked Person records with empty/whitespace names."""
+    logging.info("1. EMPTY PERSON NAME ANALYSIS")
+
+    empty_name_links = CompanyPersonLink.objects.filter(
+        person__name=""
+    ) | CompanyPersonLink.objects.filter(person__name__regex=r"^\s+$")
+    count = empty_name_links.count()
+
+    logging.info("Total company/person links with empty person names: %d", count)
+
+    if count > 0 and verbose:
+        logging.info("Sample records (first 10):")
+        for link in empty_name_links.select_related("company", "person")[:10]:
+            logging.info("  - Link ID: %s", link.id)
+            logging.info("    Person ID: %s", link.person_id)
+            logging.info("    Company: %s", link.company.name)
+            logging.info(
+                "    Name: '%s' (length: %d)", link.person.name, len(link.person.name)
+            )
+            logging.info("    Email: %s", link.person.email or "None")
+
+            job_count = Job.objects.filter(
+                company=link.company,
+                person=link.person,
+            ).count()
+            if job_count > 0:
+                logging.warning("    Referenced by %d jobs at this company", job_count)
+
+    return count
+
+
+def analyze_duplicates(verbose: bool) -> int:
+    """Analyze duplicate person names linked to the same company."""
+    logging.info("2. DUPLICATE PERSON NAME ANALYSIS")
+
+    duplicates = (
+        CompanyPersonLink.objects.values("company", "person__name")
+        .annotate(count=Count("id"))
+        .filter(count__gt=1)
+        .order_by("-count")
+    )
+
+    total_duplicate_groups = duplicates.count()
+    logging.info(
+        "Total duplicate (company, person name) combinations: %d",
+        total_duplicate_groups,
+    )
+
+    if total_duplicate_groups == 0:
+        logging.info("No duplicates found")
+        return 0
+
+    total_duplicate_links = sum(duplicate["count"] - 1 for duplicate in duplicates)
+    logging.info("Total duplicate links to review: %d", total_duplicate_links)
+
+    if verbose:
+        logging.info("Top 10 duplicate groups:")
+        for index, duplicate in enumerate(duplicates[:10], 1):
+            company = Company.objects.get(id=duplicate["company"])
+            person_name = duplicate["person__name"]
+            logging.info(
+                "%d. Company: %s - Person: '%s' - %d links",
+                index,
+                company.name,
+                person_name,
+                duplicate["count"],
+            )
+
+            links = (
+                CompanyPersonLink.objects.select_related("person")
+                .filter(company_id=duplicate["company"], person__name=person_name)
+                .order_by("-created_at")
+            )
+
+            for link in links[:5]:
+                job_count = Job.objects.filter(
+                    company_id=duplicate["company"],
+                    person=link.person,
+                ).count()
+                jobs_text = f" ({job_count} jobs)" if job_count > 0 else ""
+                logging.info(
+                    "     Link ID: %s  Person ID: %s  Email: %s  Created: %s%s",
+                    link.id,
+                    link.person_id,
+                    link.person.email or "None",
+                    link.created_at,
+                    jobs_text,
+                )
+
+    return total_duplicate_links
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed information about each duplicate group",
+    )
+    args = parser.parse_args()
+
+    logging.info("Company/Person Link State Analysis")
+    empty_count = analyze_empty_names(args.verbose)
+    duplicate_count = analyze_duplicates(args.verbose)
+
+    logging.info("--- SUMMARY ---")
+    logging.info("Empty/whitespace person-name links: %d", empty_count)
+    logging.info("Duplicate company/person-name links to review: %d", duplicate_count)
+    logging.info(
+        "Total links after cleanup: %d",
+        CompanyPersonLink.objects.count() - empty_count - duplicate_count,
+    )
+
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+    main()

From 599377891c78cca2ca4363db393f2efb2f77bf56 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Sun, 12 Jul 2026 19:20:22 +1200
Subject: [PATCH 18/73] fix: address KAN-278 review feedback

---
 apps/workflow/tests/test_search_telemetry.py |  1 +
 scripts/analyze_company_people.py            | 37 +++++++++++++++++---
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/apps/workflow/tests/test_search_telemetry.py b/apps/workflow/tests/test_search_telemetry.py
index 24c14aeae..a08f07c6f 100644
--- a/apps/workflow/tests/test_search_telemetry.py
+++ b/apps/workflow/tests/test_search_telemetry.py
@@ -45,6 +45,7 @@ def test_search_click_endpoint_records_generic_event(db):
     assert event.selected_label == "Fumecare Ltd"
     assert event.selected_rank == 1
     assert event.result_count == 7
+    assert event.source == "company_lookup"
     assert event.metadata == {"extra": "future-safe"}
 
 
diff --git a/scripts/analyze_company_people.py b/scripts/analyze_company_people.py
index ec784d86a..903b6bda9 100644
--- a/scripts/analyze_company_people.py
+++ b/scripts/analyze_company_people.py
@@ -10,6 +10,7 @@
 import argparse
 import logging
 import os
+from uuid import UUID
 
 os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
 
@@ -17,7 +18,7 @@
 
 django.setup()
 
-from django.db.models import Count
+from django.db.models import Count, Q
 
 from apps.company.models import Company, CompanyPersonLink
 from apps.job.models import Job
@@ -28,8 +29,8 @@ def analyze_empty_names(verbose: bool) -> int:
     logging.info("1. EMPTY PERSON NAME ANALYSIS")
 
     empty_name_links = CompanyPersonLink.objects.filter(
-        person__name=""
-    ) | CompanyPersonLink.objects.filter(person__name__regex=r"^\s+$")
+        Q(person__name="") | Q(person__name__regex=r"^\s+$")
+    )
     count = empty_name_links.count()
 
     logging.info("Total company/person links with empty person names: %d", count)
@@ -55,6 +56,31 @@ def analyze_empty_names(verbose: bool) -> int:
     return count
 
 
+def flagged_link_ids() -> set[UUID]:
+    """Return company/person link IDs that need manual review."""
+    empty_name_ids = set(
+        CompanyPersonLink.objects.filter(
+            Q(person__name="") | Q(person__name__regex=r"^\s+$")
+        ).values_list("id", flat=True)
+    )
+
+    duplicate_groups = (
+        CompanyPersonLink.objects.values("company", "person__name")
+        .annotate(count=Count("id"))
+        .filter(count__gt=1)
+    )
+    duplicate_ids: set[UUID] = set()
+    for duplicate in duplicate_groups:
+        duplicate_ids.update(
+            CompanyPersonLink.objects.filter(
+                company_id=duplicate["company"],
+                person__name=duplicate["person__name"],
+            ).values_list("id", flat=True)
+        )
+
+    return empty_name_ids | duplicate_ids
+
+
 def analyze_duplicates(verbose: bool) -> int:
     """Analyze duplicate person names linked to the same company."""
     logging.info("2. DUPLICATE PERSON NAME ANALYSIS")
@@ -132,9 +158,10 @@ def main() -> None:
     logging.info("--- SUMMARY ---")
     logging.info("Empty/whitespace person-name links: %d", empty_count)
     logging.info("Duplicate company/person-name links to review: %d", duplicate_count)
+    logging.info("Total company/person links: %d", CompanyPersonLink.objects.count())
     logging.info(
-        "Total links after cleanup: %d",
-        CompanyPersonLink.objects.count() - empty_count - duplicate_count,
+        "Unique company/person links flagged for review: %d",
+        len(flagged_link_ids()),
     )
 
 

From 6141e5eb0f2e27d169b4c6a5082de436495c7610 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Sun, 12 Jul 2026 19:27:49 +1200
Subject: [PATCH 19/73] fix: batch company person analyzer queries

---
 scripts/analyze_company_people.py | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/scripts/analyze_company_people.py b/scripts/analyze_company_people.py
index 903b6bda9..ce143bfdb 100644
--- a/scripts/analyze_company_people.py
+++ b/scripts/analyze_company_people.py
@@ -23,14 +23,14 @@
 from apps.company.models import Company, CompanyPersonLink
 from apps.job.models import Job
 
+EMPTY_PERSON_NAME_Q = Q(person__name="") | Q(person__name__regex=r"^\s+$")
+
 
 def analyze_empty_names(verbose: bool) -> int:
     """Analyze linked Person records with empty/whitespace names."""
     logging.info("1. EMPTY PERSON NAME ANALYSIS")
 
-    empty_name_links = CompanyPersonLink.objects.filter(
-        Q(person__name="") | Q(person__name__regex=r"^\s+$")
-    )
+    empty_name_links = CompanyPersonLink.objects.filter(EMPTY_PERSON_NAME_Q)
     count = empty_name_links.count()
 
     logging.info("Total company/person links with empty person names: %d", count)
@@ -59,25 +59,30 @@ def analyze_empty_names(verbose: bool) -> int:
 def flagged_link_ids() -> set[UUID]:
     """Return company/person link IDs that need manual review."""
     empty_name_ids = set(
-        CompanyPersonLink.objects.filter(
-            Q(person__name="") | Q(person__name__regex=r"^\s+$")
-        ).values_list("id", flat=True)
+        CompanyPersonLink.objects.filter(EMPTY_PERSON_NAME_Q).values_list(
+            "id",
+            flat=True,
+        )
     )
 
-    duplicate_groups = (
+    duplicate_groups = list(
         CompanyPersonLink.objects.values("company", "person__name")
         .annotate(count=Count("id"))
         .filter(count__gt=1)
     )
-    duplicate_ids: set[UUID] = set()
+    if not duplicate_groups:
+        return empty_name_ids
+
+    duplicate_filter = Q()
     for duplicate in duplicate_groups:
-        duplicate_ids.update(
-            CompanyPersonLink.objects.filter(
-                company_id=duplicate["company"],
-                person__name=duplicate["person__name"],
-            ).values_list("id", flat=True)
+        duplicate_filter |= Q(
+            company_id=duplicate["company"],
+            person__name=duplicate["person__name"],
         )
 
+    duplicate_ids: set[UUID] = set(
+        CompanyPersonLink.objects.filter(duplicate_filter).values_list("id", flat=True)
+    )
     return empty_name_ids | duplicate_ids
 
 

From 75550fe739a3adee02c6ee4fe08d5896ef0f0556 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Sun, 12 Jul 2026 20:45:04 +1200
Subject: [PATCH 20/73] feat: add duplicate person merge tooling

---
 .../commands/cleanup_duplicate_people.py      | 220 ++++++++++++++
 .../migrations/0005_backfill_person.py        |  11 +
 .../0007_remove_xero_person_identity.py       |  36 +++
 apps/company/models.py                        |   7 -
 apps/company/serializers.py                   |   6 -
 apps/company/services/__init__.py             |  25 ++
 .../company/services/company_merge_service.py |  10 +-
 .../services/duplicate_person_report.py       | 284 ++++++++++++++++++
 .../services/duplicate_phone_report.py        |  29 +-
 apps/company/services/person_merge_service.py | 166 ++++++++++
 .../test_cleanup_duplicate_people_command.py  |  55 ++++
 .../tests/test_company_merge_service.py       |   1 -
 apps/company/tests/test_contact_methods.py    |   1 -
 .../tests/test_duplicate_person_report.py     |  74 +++++
 .../tests/test_duplicate_phone_report.py      |  14 +-
 apps/company/tests/test_job_contact_view.py   |   1 -
 .../tests/test_people_backfill_migration.py   |   2 +
 .../tests/test_person_cleanup_migration.py    | 105 +++++++
 .../tests/test_person_merge_service.py        | 142 +++++++++
 apps/crm/tests/test_phone_call_service.py     |   2 -
 apps/crm/tests/test_phone_endpoint_guard.py   |   1 -
 apps/job/serializers/__init__.py              |  14 +
 .../data_quality_report_serializers.py        |  75 +++++
 apps/job/tests/test_duplicate_people_view.py  |  36 +++
 apps/job/tests/test_kanban_search.py          |   1 -
 apps/job/tests/test_kanban_service.py         |   1 -
 apps/job/urls_rest.py                         |   6 +
 apps/job/views/__init__.py                    |   7 +-
 apps/job/views/data_quality_report_views.py   |  30 ++
 apps/workflow/api/xero/reprocess_xero.py      |  80 +----
 .../workflow/tests/test_data_versions_view.py |   1 -
 apps/workflow/tests/test_sync_clients.py      |  42 ++-
 ...30-first-class-people-and-company-links.md |   8 +-
 docs/urls/job.md                              |   1 +
 frontend/schema.yml                           | 246 +++++++++++++--
 frontend/src/api/generated/api.ts             |  91 +++++-
 .../__tests__/usePersonManagement.test.ts     |   1 -
 .../src/stores/__tests__/companyStore.test.ts |   1 -
 mypy-baseline.txt                             |   2 -
 39 files changed, 1678 insertions(+), 157 deletions(-)
 create mode 100644 apps/company/management/commands/cleanup_duplicate_people.py
 create mode 100644 apps/company/migrations/0007_remove_xero_person_identity.py
 create mode 100644 apps/company/services/duplicate_person_report.py
 create mode 100644 apps/company/services/person_merge_service.py
 create mode 100644 apps/company/tests/test_cleanup_duplicate_people_command.py
 create mode 100644 apps/company/tests/test_duplicate_person_report.py
 create mode 100644 apps/company/tests/test_person_cleanup_migration.py
 create mode 100644 apps/company/tests/test_person_merge_service.py
 create mode 100644 apps/job/tests/test_duplicate_people_view.py

diff --git a/apps/company/management/commands/cleanup_duplicate_people.py b/apps/company/management/commands/cleanup_duplicate_people.py
new file mode 100644
index 000000000..f513f7d95
--- /dev/null
+++ b/apps/company/management/commands/cleanup_duplicate_people.py
@@ -0,0 +1,220 @@
+"""Preview and apply reviewed duplicate-Person merges."""
+
+import csv
+from pathlib import Path
+from typing import Any
+from uuid import UUID
+
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+from django.utils.dateparse import parse_datetime
+
+from apps.accounts.models import Staff
+from apps.company.models import Person
+from apps.company.services.duplicate_person_report import (
+    DuplicatePersonCandidate,
+    DuplicatePersonReportService,
+    DuplicatePersonSummary,
+)
+from apps.company.services.person_merge_service import merge_people
+
+CSV_COLUMNS = [
+    "action",
+    "confidence",
+    "match_kinds",
+    "match_values",
+    "source_person_id",
+    "source_name",
+    "source_email",
+    "source_companies",
+    "source_jobs",
+    "source_calls",
+    "source_updated_at",
+    "destination_person_id",
+    "destination_name",
+    "destination_email",
+    "destination_companies",
+    "destination_jobs",
+    "destination_calls",
+    "destination_updated_at",
+]
+
+
+def _recommended_people(
+    candidate: DuplicatePersonCandidate,
+) -> tuple[DuplicatePersonSummary, DuplicatePersonSummary]:
+    people = [candidate["first_person"], candidate["second_person"]]
+    people.sort(
+        key=lambda person: (
+            not person["is_active"],
+            -(person["job_count"] + person["phone_call_count"]),
+            -(len(person["company_links"]) + len(person["contact_methods"])),
+            person["created_at"],
+            person["person_id"],
+        )
+    )
+    destination = people[0]
+    source = people[1]
+    return source, destination
+
+
+class Command(BaseCommand):
+    help = "Preview duplicate Person candidates or apply a reviewed merge CSV"
+
+    def add_arguments(self, parser: Any) -> None:
+        modes = parser.add_mutually_exclusive_group(required=True)
+        modes.add_argument("--preview", type=str, help="Write candidate CSV")
+        modes.add_argument("--apply", type=str, help="Apply reviewed candidate CSV")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        preview_path = options["preview"]
+        apply_path = options["apply"]
+        if preview_path is not None:
+            self._preview(Path(preview_path))
+        elif apply_path is not None:
+            self._apply(Path(apply_path))
+        else:
+            raise CommandError("Specify --preview or --apply")
+
+    def _preview(self, path: Path) -> None:
+        if not path.parent.exists():
+            raise CommandError(f"Output directory does not exist: {path.parent}")
+        report = DuplicatePersonReportService().get_report()
+        candidates = report["duplicate_people"]
+        candidate_degrees: dict[str, int] = {}
+        for candidate in candidates:
+            for person in (candidate["first_person"], candidate["second_person"]):
+                person_id = person["person_id"]
+                candidate_degrees[person_id] = candidate_degrees.get(person_id, 0) + 1
+
+        with path.open("w", newline="", encoding="utf-8") as output:
+            writer = csv.DictWriter(output, fieldnames=CSV_COLUMNS)
+            writer.writeheader()
+            for candidate in candidates:
+                source, destination = _recommended_people(candidate)
+                isolated_high = (
+                    candidate["confidence"] == "high"
+                    and candidate_degrees[source["person_id"]] == 1
+                    and candidate_degrees[destination["person_id"]] == 1
+                )
+                writer.writerow(
+                    {
+                        "action": "merge" if isolated_high else "",
+                        "confidence": candidate["confidence"],
+                        "match_kinds": ";".join(
+                            sorted({match["kind"] for match in candidate["matches"]})
+                        ),
+                        "match_values": ";".join(
+                            f"{match['kind']}={match['normalized_value']}"
+                            for match in candidate["matches"]
+                        ),
+                        **self._person_columns("source", source),
+                        **self._person_columns("destination", destination),
+                    }
+                )
+        self.stdout.write(
+            self.style.SUCCESS(
+                f"Wrote {len(candidates)} duplicate-Person candidates to {path}"
+            )
+        )
+
+    @staticmethod
+    def _person_columns(prefix: str, person: DuplicatePersonSummary) -> dict[str, Any]:
+        return {
+            f"{prefix}_person_id": person["person_id"],
+            f"{prefix}_name": person["name"],
+            f"{prefix}_email": person["email"] or "",
+            f"{prefix}_companies": ";".join(
+                link["company_name"] for link in person["company_links"]
+            ),
+            f"{prefix}_jobs": person["job_count"],
+            f"{prefix}_calls": person["phone_call_count"],
+            f"{prefix}_updated_at": person["updated_at"].isoformat(),
+        }
+
+    def _apply(self, path: Path) -> None:
+        if not path.is_file():
+            raise CommandError(f"CSV file not found: {path}")
+        with path.open(newline="", encoding="utf-8") as input_file:
+            reader = csv.DictReader(input_file)
+            if reader.fieldnames != CSV_COLUMNS:
+                raise CommandError("CSV columns do not match the preview contract")
+            selected_rows = [row for row in reader if row["action"].strip() == "merge"]
+        if not selected_rows:
+            raise CommandError("CSV contains no rows with action=merge")
+
+        report = DuplicatePersonReportService().get_report()
+        current_pairs = {
+            frozenset(
+                [
+                    candidate["first_person"]["person_id"],
+                    candidate["second_person"]["person_id"],
+                ]
+            )
+            for candidate in report["duplicate_people"]
+        }
+        merges: list[tuple[UUID, UUID]] = []
+        source_ids: set[UUID] = set()
+        destination_ids: set[UUID] = set()
+        for row_number, row in enumerate(selected_rows, 2):
+            source_id = self._uuid(row, "source_person_id", row_number)
+            destination_id = self._uuid(row, "destination_person_id", row_number)
+            if source_id == destination_id:
+                raise CommandError(f"Row {row_number}: source equals destination")
+            if source_id in source_ids:
+                raise CommandError(f"Row {row_number}: source appears more than once")
+            source_ids.add(source_id)
+            destination_ids.add(destination_id)
+            if frozenset([str(source_id), str(destination_id)]) not in current_pairs:
+                raise CommandError(
+                    f"Row {row_number}: pair is no longer a duplicate candidate"
+                )
+            self._validate_timestamp(
+                source_id, row["source_updated_at"], "source", row_number
+            )
+            self._validate_timestamp(
+                destination_id,
+                row["destination_updated_at"],
+                "destination",
+                row_number,
+            )
+            merges.append((source_id, destination_id))
+        chained_ids = source_ids & destination_ids
+        if chained_ids:
+            raise CommandError(
+                "A Person cannot be both source and destination in one batch: "
+                + ", ".join(
+                    str(person_id) for person_id in sorted(chained_ids, key=str)
+                )
+            )
+
+        staff = Staff.get_automation_user()
+        with transaction.atomic():
+            for source_id, destination_id in merges:
+                counts = merge_people(source_id, destination_id, staff)
+                self.stdout.write(f"Merged {source_id} -> {destination_id}: {counts}")
+        self.stdout.write(self.style.SUCCESS(f"Applied {len(merges)} Person merges"))
+
+    @staticmethod
+    def _uuid(row: dict[str, str], column: str, row_number: int) -> UUID:
+        try:
+            return UUID(row[column])
+        except (KeyError, ValueError) as exc:
+            raise CommandError(f"Row {row_number}: invalid {column}") from exc
+
+    @staticmethod
+    def _validate_timestamp(
+        person_id: UUID, raw_timestamp: str, role: str, row_number: int
+    ) -> None:
+        expected = parse_datetime(raw_timestamp)
+        if expected is None:
+            raise CommandError(f"Row {row_number}: invalid {role}_updated_at")
+        actual = (
+            Person.objects.filter(id=person_id)
+            .values_list("updated_at", flat=True)
+            .first()
+        )
+        if actual is None:
+            raise CommandError(f"Row {row_number}: {role} Person does not exist")
+        if actual != expected:
+            raise CommandError(f"Row {row_number}: {role} Person changed after preview")
diff --git a/apps/company/migrations/0005_backfill_person.py b/apps/company/migrations/0005_backfill_person.py
index 514eb0989..cb252e244 100644
--- a/apps/company/migrations/0005_backfill_person.py
+++ b/apps/company/migrations/0005_backfill_person.py
@@ -44,6 +44,7 @@ def forwards(apps: Any, schema_editor: Any) -> None:
 
 
 def backwards(apps: Any, schema_editor: Any) -> None:
+    Person = apps.get_model("company", "Person")
     CompanyPersonLink = apps.get_model("company", "CompanyPersonLink")
     ContactMethod = apps.get_model("company", "ContactMethod")
     Job = apps.get_model("job", "Job")
@@ -95,6 +96,11 @@ def link_id_for_person(
         method.person_id = None
         method.save(update_fields=["contact", "person", "updated_at"])
 
+    linked_person_ids = list(
+        CompanyPersonLink.objects.exclude(person__isnull=True).values_list(
+            "person_id", flat=True
+        )
+    )
     for link in CompanyPersonLink.objects.exclude(person__isnull=True).select_related(
         "person"
     ):
@@ -114,6 +120,11 @@ def link_id_for_person(
             ]
         )
 
+    # These Person rows were created by forwards(). Removing them makes a
+    # reverse/forward rehearsal return to the same row count instead of leaving
+    # one unreferenced duplicate for every legacy contact.
+    Person.objects.filter(id__in=linked_person_ids).delete()
+
 
 class Migration(migrations.Migration):
 
diff --git a/apps/company/migrations/0007_remove_xero_person_identity.py b/apps/company/migrations/0007_remove_xero_person_identity.py
new file mode 100644
index 000000000..096225f9b
--- /dev/null
+++ b/apps/company/migrations/0007_remove_xero_person_identity.py
@@ -0,0 +1,36 @@
+# Generated by Django 6.0.4 on 2026-07-12 08:32
+
+from typing import Any
+
+from django.db import migrations
+
+
+def delete_unreferenced_people(apps: Any, schema_editor: Any) -> None:
+    Person = apps.get_model("company", "Person")
+    Person.objects.filter(
+        company_links__isnull=True,
+        contact_methods__isnull=True,
+        jobs__isnull=True,
+        phone_calls__isnull=True,
+    ).delete()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0006_alter_companypersonlink_options_and_more"),
+        ("crm", "0006_remove_phonecallrecord_contact_and_more"),
+        ("job", "0006_rename_job_event_people_company_terms"),
+    ]
+
+    operations = [
+        migrations.RunPython(delete_unreferenced_people, migrations.RunPython.noop),
+        migrations.RemoveConstraint(
+            model_name="companypersonlink",
+            name="unique_company_person_link_xero_name",
+        ),
+        migrations.RemoveField(
+            model_name="companypersonlink",
+            name="xero_name",
+        ),
+    ]
diff --git a/apps/company/models.py b/apps/company/models.py
index 977069a26..ce8433e28 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -317,7 +317,6 @@ class CompanyPersonLink(models.Model):
         "id",
         "company",
         "person",
-        "xero_name",
         "position",
         "is_primary",
         "notes",
@@ -343,7 +342,6 @@ class CompanyPersonLink(models.Model):
         on_delete=models.CASCADE,
         related_name="company_links",
     )
-    xero_name = models.CharField(max_length=255, null=True, blank=True)
     position = models.CharField(
         max_length=255,
         null=True,
@@ -373,11 +371,6 @@ class Meta:
                 fields=["company", "person"],
                 name="unique_company_person_link",
             ),
-            models.UniqueConstraint(
-                fields=["company", "xero_name"],
-                condition=models.Q(xero_name__isnull=False),
-                name="unique_company_person_link_xero_name",
-            ),
         ]
 
     def __str__(self):
diff --git a/apps/company/serializers.py b/apps/company/serializers.py
index 3c37d3a8a..31cf1f281 100644
--- a/apps/company/serializers.py
+++ b/apps/company/serializers.py
@@ -101,7 +101,6 @@ class CompanyPersonLinkCreateAttrs(TypedDict):
 
     company: Company
     person: CompanyPersonCreateAttrs
-    xero_name: NotRequired[str | None]
     position: NotRequired[str | None]
     is_primary: NotRequired[bool]
     notes: NotRequired[str | None]
@@ -113,7 +112,6 @@ class CompanyPersonLinkModelCreateAttrs(TypedDict):
 
     company: Company
     person: Person
-    xero_name: NotRequired[str | None]
     position: NotRequired[str | None]
     is_primary: NotRequired[bool]
     notes: NotRequired[str | None]
@@ -124,7 +122,6 @@ class CompanyPersonLinkUpdateAttrs(TypedDict, total=False):
 
     company: Company
     person: CompanyPersonUpdateAttrs
-    xero_name: str | None
     position: str | None
     is_primary: bool
     notes: str | None
@@ -153,7 +150,6 @@ class Meta:
             "person",
             "person_name",
             "person_email",
-            "xero_name",
             "position",
             "is_primary",
             "notes",
@@ -191,11 +187,9 @@ def create(self, validated_data: CompanyPersonLinkCreateAttrs) -> CompanyPersonL
                 email=person_value.get("email"),
                 is_active=True,
             )
-            xero_name = validated_data.get("xero_name")
             link_data: CompanyPersonLinkModelCreateAttrs = {
                 "company": validated_data["company"],
                 "person": person,
-                "xero_name": xero_name if xero_name is not None else person.name,
             }
             if "position" in validated_data:
                 link_data["position"] = validated_data["position"]
diff --git a/apps/company/services/__init__.py b/apps/company/services/__init__.py
index 13c11d651..d45f7d263 100644
--- a/apps/company/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -7,6 +7,18 @@
     if apps.ready:
         from .company_merge_service import reassign_company_fk_records
         from .company_rest_service import CompanyPhoneAnnotations, CompanyRestService
+        from .duplicate_person_report import (
+            DuplicatePersonCandidate,
+            DuplicatePersonCompanyLink,
+            DuplicatePersonContactMethod,
+            DuplicatePersonMatch,
+            DuplicatePersonReport,
+            DuplicatePersonReportService,
+            DuplicatePersonReportSummary,
+            DuplicatePersonSummary,
+            normalize_person_email,
+            normalize_person_name,
+        )
         from .duplicate_phone_report import (
             DuplicatePhoneIssue,
             DuplicatePhoneOwner,
@@ -21,6 +33,7 @@
             geocode_address,
             get_api_key,
         )
+        from .person_merge_service import PersonMergeCounts, merge_people
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
     pass
@@ -28,6 +41,14 @@
 __all__ = [
     "CompanyPhoneAnnotations",
     "CompanyRestService",
+    "DuplicatePersonCandidate",
+    "DuplicatePersonCompanyLink",
+    "DuplicatePersonContactMethod",
+    "DuplicatePersonMatch",
+    "DuplicatePersonReport",
+    "DuplicatePersonReportService",
+    "DuplicatePersonReportSummary",
+    "DuplicatePersonSummary",
     "DuplicatePhoneIssue",
     "DuplicatePhoneOwner",
     "DuplicatePhoneReportService",
@@ -36,7 +57,11 @@
     "GeocodingError",
     "GeocodingNotConfiguredError",
     "GeocodingResult",
+    "PersonMergeCounts",
     "geocode_address",
     "get_api_key",
+    "merge_people",
+    "normalize_person_email",
+    "normalize_person_name",
     "reassign_company_fk_records",
 ]
diff --git a/apps/company/services/company_merge_service.py b/apps/company/services/company_merge_service.py
index 04c535421..3e75897f2 100644
--- a/apps/company/services/company_merge_service.py
+++ b/apps/company/services/company_merge_service.py
@@ -95,16 +95,8 @@ def _move_company_contacts_and_methods(
     for link in CompanyPersonLink.objects.filter(company=source).iterator():
         destination_link = destination_links_by_person.get(link.person_id)
         if destination_link is None:
-            if (
-                link.xero_name is not None
-                and CompanyPersonLink.objects.filter(
-                    company=destination,
-                    xero_name=link.xero_name,
-                ).exists()
-            ):
-                link.xero_name = None
             link.company = destination
-            link.save(update_fields=["company", "xero_name", "updated_at"])
+            link.save(update_fields=["company", "updated_at"])
             destination_links_by_person[link.person_id] = link
         else:
             counts["phone_calls"] += PhoneCallRecord.objects.filter(
diff --git a/apps/company/services/duplicate_person_report.py b/apps/company/services/duplicate_person_report.py
new file mode 100644
index 000000000..99a773fe3
--- /dev/null
+++ b/apps/company/services/duplicate_person_report.py
@@ -0,0 +1,284 @@
+"""Find distinct Person rows that share exact identity signals."""
+
+from collections import defaultdict
+from datetime import datetime
+from typing import Literal, TypedDict
+from uuid import UUID
+
+from django.db.models import Count
+from django.utils import timezone
+
+from apps.company.models import CompanyPersonLink, ContactMethod, Person
+
+MatchKind = Literal["name", "email", "phone"]
+Confidence = Literal["high", "medium", "low"]
+
+
+class DuplicatePersonCompanyLink(TypedDict):
+    link_id: str
+    company_id: str
+    company_name: str
+    position: str | None
+    is_primary: bool
+    is_active: bool
+
+
+class DuplicatePersonContactMethod(TypedDict):
+    method_id: str
+    method_type: str
+    value: str
+    normalized_value: str
+    contact_label: str
+    is_primary: bool
+
+
+class DuplicatePersonSummary(TypedDict):
+    person_id: str
+    name: str
+    email: str | None
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+    company_links: list[DuplicatePersonCompanyLink]
+    contact_methods: list[DuplicatePersonContactMethod]
+    job_count: int
+    phone_call_count: int
+
+
+class DuplicatePersonMatch(TypedDict):
+    kind: MatchKind
+    normalized_value: str
+
+
+class DuplicatePersonCandidate(TypedDict):
+    confidence: Confidence
+    matches: list[DuplicatePersonMatch]
+    shared_company_ids: list[str]
+    first_person: DuplicatePersonSummary
+    second_person: DuplicatePersonSummary
+
+
+class DuplicatePersonReportSummary(TypedDict):
+    candidate_pairs: int
+    people_flagged: int
+    high: int
+    medium: int
+    low: int
+
+
+class DuplicatePersonReport(TypedDict):
+    duplicate_people: list[DuplicatePersonCandidate]
+    summary: DuplicatePersonReportSummary
+    checked_at: datetime
+
+
+def normalize_person_name(value: str) -> str:
+    """Normalize an exact-name signal without introducing fuzzy matching."""
+    return " ".join(value.split()).casefold()
+
+
+def normalize_person_email(value: str | None) -> str:
+    return (value or "").strip().casefold()
+
+
+def _confidence(match_kinds: set[MatchKind]) -> Confidence:
+    if len(match_kinds) >= 2:
+        return "high"
+    if "phone" in match_kinds or "email" in match_kinds:
+        return "medium"
+    return "low"
+
+
+class DuplicatePersonReportService:
+    """Build exact-signal candidate pairs for operator review."""
+
+    def get_report(self) -> DuplicatePersonReport:
+        people = list(Person.objects.order_by("id"))
+        person_ids = [person.id for person in people]
+        links_by_person: dict[UUID, list[CompanyPersonLink]] = defaultdict(list)
+        for link in CompanyPersonLink.objects.filter(
+            person_id__in=person_ids
+        ).select_related("company"):
+            links_by_person[link.person_id].append(link)
+        methods_by_person: dict[UUID, list[ContactMethod]] = defaultdict(list)
+        for method in ContactMethod.objects.filter(person_id__in=person_ids):
+            if method.person_id is None:
+                raise RuntimeError(f"Person contact method {method.id} has no Person")
+            methods_by_person[method.person_id].append(method)
+        job_counts = self._job_counts(person_ids)
+        call_counts = self._call_counts(person_ids)
+        summaries = {
+            person.id: self._person_summary(
+                person,
+                links=links_by_person[person.id],
+                methods=methods_by_person[person.id],
+                job_count=job_counts.get(person.id, 0),
+                phone_call_count=call_counts.get(person.id, 0),
+            )
+            for person in people
+        }
+
+        signal_owners: dict[tuple[MatchKind, str], set[UUID]] = defaultdict(set)
+        for person in people:
+            name = normalize_person_name(person.name)
+            if name:
+                signal_owners[("name", name)].add(person.id)
+
+            email = normalize_person_email(person.email)
+            if email:
+                signal_owners[("email", email)].add(person.id)
+
+            for method in methods_by_person[person.id]:
+                if method.method_type == ContactMethod.MethodType.EMAIL:
+                    kind: MatchKind = "email"
+                elif method.method_type == ContactMethod.MethodType.PHONE:
+                    kind = "phone"
+                else:
+                    raise ValueError(
+                        f"Unknown contact method type {method.method_type!r}"
+                    )
+                if method.normalized_value:
+                    signal_owners[(kind, method.normalized_value)].add(person.id)
+
+        pair_matches: dict[tuple[UUID, UUID], dict[MatchKind, set[str]]] = defaultdict(
+            lambda: defaultdict(set)
+        )
+        for (kind, normalized_value), owners in signal_owners.items():
+            ordered_owners = sorted(owners, key=str)
+            for first_index, first_id in enumerate(ordered_owners):
+                for second_id in ordered_owners[first_index + 1 :]:
+                    pair_matches[(first_id, second_id)][kind].add(normalized_value)
+
+        candidates = [
+            self._candidate(pair, matches, summaries)
+            for pair, matches in pair_matches.items()
+        ]
+        confidence_order: dict[Confidence, int] = {"high": 0, "medium": 1, "low": 2}
+        candidates.sort(
+            key=lambda candidate: (
+                confidence_order[candidate["confidence"]],
+                candidate["first_person"]["name"].casefold(),
+                candidate["second_person"]["name"].casefold(),
+                candidate["first_person"]["person_id"],
+                candidate["second_person"]["person_id"],
+            )
+        )
+        flagged_ids = {
+            person["person_id"]
+            for candidate in candidates
+            for person in (candidate["first_person"], candidate["second_person"])
+        }
+        return {
+            "duplicate_people": candidates,
+            "summary": {
+                "candidate_pairs": len(candidates),
+                "people_flagged": len(flagged_ids),
+                "high": sum(c["confidence"] == "high" for c in candidates),
+                "medium": sum(c["confidence"] == "medium" for c in candidates),
+                "low": sum(c["confidence"] == "low" for c in candidates),
+            },
+            "checked_at": timezone.now(),
+        }
+
+    @staticmethod
+    def _job_counts(person_ids: list[UUID]) -> dict[UUID, int]:
+        from apps.job.models import Job
+
+        return {
+            person_id: count
+            for person_id, count in Job.objects.filter(person_id__in=person_ids)
+            .values_list("person_id")
+            .annotate(count=Count("id"))
+        }
+
+    @staticmethod
+    def _call_counts(person_ids: list[UUID]) -> dict[UUID, int]:
+        from apps.crm.models import PhoneCallRecord
+
+        return {
+            person_id: count
+            for person_id, count in PhoneCallRecord.objects.filter(
+                person_id__in=person_ids
+            )
+            .values_list("person_id")
+            .annotate(count=Count("id"))
+        }
+
+    @staticmethod
+    def _person_summary(
+        person: Person,
+        *,
+        links: list[CompanyPersonLink],
+        methods: list[ContactMethod],
+        job_count: int,
+        phone_call_count: int,
+    ) -> DuplicatePersonSummary:
+        link_summaries: list[DuplicatePersonCompanyLink] = [
+            {
+                "link_id": str(link.id),
+                "company_id": str(link.company_id),
+                "company_name": link.company.name,
+                "position": link.position,
+                "is_primary": link.is_primary,
+                "is_active": link.is_active,
+            }
+            for link in sorted(
+                links,
+                key=lambda item: (item.company.name.casefold(), str(item.id)),
+            )
+        ]
+        method_summaries: list[DuplicatePersonContactMethod] = [
+            {
+                "method_id": str(method.id),
+                "method_type": method.method_type,
+                "value": method.value,
+                "normalized_value": method.normalized_value,
+                "contact_label": method.label,
+                "is_primary": method.is_primary,
+            }
+            for method in sorted(
+                methods,
+                key=lambda item: (
+                    item.method_type,
+                    item.normalized_value,
+                    str(item.id),
+                ),
+            )
+        ]
+        return {
+            "person_id": str(person.id),
+            "name": person.name,
+            "email": person.email,
+            "is_active": person.is_active,
+            "created_at": person.created_at,
+            "updated_at": person.updated_at,
+            "company_links": link_summaries,
+            "contact_methods": method_summaries,
+            "job_count": job_count,
+            "phone_call_count": phone_call_count,
+        }
+
+    @staticmethod
+    def _candidate(
+        pair: tuple[UUID, UUID],
+        matches_by_kind: dict[MatchKind, set[str]],
+        summaries: dict[UUID, DuplicatePersonSummary],
+    ) -> DuplicatePersonCandidate:
+        first_id, second_id = pair
+        match_kind_order: tuple[MatchKind, ...] = ("name", "email", "phone")
+        matches: list[DuplicatePersonMatch] = [
+            {"kind": kind, "normalized_value": value}
+            for kind in match_kind_order
+            for value in sorted(matches_by_kind.get(kind, set()))
+        ]
+        first = summaries[first_id]
+        second = summaries[second_id]
+        first_companies = {link["company_id"] for link in first["company_links"]}
+        second_companies = {link["company_id"] for link in second["company_links"]}
+        return {
+            "confidence": _confidence(set(matches_by_kind)),
+            "matches": matches,
+            "shared_company_ids": sorted(first_companies & second_companies),
+            "first_person": first,
+            "second_person": second,
+        }
diff --git a/apps/company/services/duplicate_phone_report.py b/apps/company/services/duplicate_phone_report.py
index 326d399ad..d0f7fee0d 100644
--- a/apps/company/services/duplicate_phone_report.py
+++ b/apps/company/services/duplicate_phone_report.py
@@ -53,17 +53,26 @@ def _cross_company_conflicts(self) -> list[DuplicatePhoneIssue]:
         phones = ContactMethod.objects.filter(
             method_type=ContactMethod.MethodType.PHONE
         )
-        companies_by_number: dict[str, set[str]] = {}
+        companies_by_owner_by_number: dict[str, dict[tuple[str, str], set[str]]] = {}
         for method in phones.select_related("company", "person").prefetch_related(
             "person__company_links"
         ):
-            companies_by_number.setdefault(method.normalized_value, set()).update(
+            if method.person_id is not None:
+                owner_key = ("person", str(method.person_id))
+            elif method.company_id is not None:
+                owner_key = ("company", str(method.company_id))
+            else:
+                raise RuntimeError(f"Contact method {method.id} has no owner")
+            owners = companies_by_owner_by_number.setdefault(
+                method.normalized_value, {}
+            )
+            owners.setdefault(owner_key, set()).update(
                 str(company_id) for company_id in method.owner_company_ids()
             )
         conflict_numbers = [
             number
-            for number, company_ids in companies_by_number.items()
-            if len(company_ids) > 1
+            for number, owners in companies_by_owner_by_number.items()
+            if self._owners_have_no_common_company(owners)
         ]
         if not conflict_numbers:
             return []
@@ -85,6 +94,18 @@ def _cross_company_conflicts(self) -> list[DuplicatePhoneIssue]:
             for number, owners in grouped.items()
         ]
 
+    @staticmethod
+    def _owners_have_no_common_company(
+        companies_by_owner: dict[tuple[str, str], set[str]],
+    ) -> bool:
+        if len(companies_by_owner) < 2:
+            return False
+        owner_company_sets = iter(companies_by_owner.values())
+        common_companies = set(next(owner_company_sets))
+        for company_ids in owner_company_sets:
+            common_companies.intersection_update(company_ids)
+        return not common_companies
+
     def _internal_line_collisions(self) -> list[DuplicatePhoneIssue]:
         endpoint_labels = dict(
             PhoneEndpoint.objects.filter(is_active=True).values_list(
diff --git a/apps/company/services/person_merge_service.py b/apps/company/services/person_merge_service.py
new file mode 100644
index 000000000..da92bd911
--- /dev/null
+++ b/apps/company/services/person_merge_service.py
@@ -0,0 +1,166 @@
+"""Atomic reassignment of one duplicate Person into a canonical Person."""
+
+from typing import TypedDict
+from uuid import UUID
+
+from django.db import transaction
+from django.utils import timezone
+
+from apps.accounts.models import Staff
+from apps.company.models import CompanyPersonLink, ContactMethod, Person
+from apps.workflow.exceptions import AlreadyLoggedException
+from apps.workflow.services.error_persistence import persist_app_error
+
+
+class PersonMergeCounts(TypedDict):
+    jobs: int
+    phone_calls: int
+    links_moved: int
+    links_collapsed: int
+    contact_methods_moved: int
+    contact_methods_collapsed: int
+
+
+def _merge_links(source: Person, destination: Person) -> tuple[int, int]:
+    destination_links = {
+        link.company_id: link
+        for link in CompanyPersonLink.objects.filter(person=destination)
+    }
+    moved = 0
+    collapsed = 0
+    for source_link in CompanyPersonLink.objects.filter(person=source).order_by("id"):
+        destination_link = destination_links.get(source_link.company_id)
+        if destination_link is None:
+            source_link.person = destination
+            source_link.save(update_fields=["person", "updated_at"])
+            destination_links[source_link.company_id] = source_link
+            moved += 1
+            continue
+
+        update_fields = ["updated_at"]
+        if not destination_link.position and source_link.position:
+            destination_link.position = source_link.position
+            update_fields.append("position")
+        if not destination_link.notes and source_link.notes:
+            destination_link.notes = source_link.notes
+            update_fields.append("notes")
+        if source_link.is_active and not destination_link.is_active:
+            destination_link.is_active = True
+            update_fields.append("is_active")
+        if source_link.is_primary and not destination_link.is_primary:
+            destination_link.is_primary = True
+            update_fields.append("is_primary")
+        destination_link.save(update_fields=update_fields)
+        source_link.delete()
+        collapsed += 1
+    return moved, collapsed
+
+
+def _merge_contact_methods(source: Person, destination: Person) -> tuple[int, int]:
+    destination_methods = {
+        (method.method_type, method.normalized_value): method
+        for method in ContactMethod.objects.filter(person=destination)
+    }
+    destination_primary_types = set(
+        ContactMethod.objects.filter(person=destination, is_primary=True).values_list(
+            "method_type", flat=True
+        )
+    )
+    moved = 0
+    collapsed = 0
+    now = timezone.now()
+    for source_method in ContactMethod.objects.filter(person=source).order_by("id"):
+        key = (source_method.method_type, source_method.normalized_value)
+        destination_method = destination_methods.get(key)
+        if destination_method is not None:
+            update_fields = ["updated_at"]
+            if not destination_method.label and source_method.label:
+                destination_method.label = source_method.label
+                update_fields.append("label")
+            if (
+                source_method.is_primary
+                and source_method.method_type not in destination_primary_types
+            ):
+                destination_method.is_primary = True
+                destination_primary_types.add(source_method.method_type)
+                update_fields.append("is_primary")
+            destination_method.save(update_fields=update_fields)
+            source_method.delete()
+            collapsed += 1
+            continue
+
+        moving_primary = source_method.is_primary
+        if source_method.method_type in destination_primary_types:
+            moving_primary = False
+        elif moving_primary:
+            destination_primary_types.add(source_method.method_type)
+
+        # The ownership change is the repair itself. Bypass save()'s assignment
+        # guard so grandfathered phone data cannot prevent its documented remedy.
+        ContactMethod.objects.filter(pk=source_method.pk).update(
+            person=destination,
+            is_primary=moving_primary,
+            updated_at=now,
+        )
+        destination_methods[key] = source_method
+        moved += 1
+    return moved, collapsed
+
+
+def merge_people(
+    source_id: UUID,
+    destination_id: UUID,
+    staff: Staff,
+) -> PersonMergeCounts:
+    """Merge ``source_id`` into ``destination_id`` and delete the source row."""
+    if source_id == destination_id:
+        raise ValueError("Source and destination Person must be different")
+
+    from apps.crm.models import PhoneCallRecord
+    from apps.job.models import Job
+
+    try:
+        with transaction.atomic():
+            people = {
+                person.id: person
+                for person in Person.objects.select_for_update()
+                .filter(id__in=[source_id, destination_id])
+                .order_by("id")
+            }
+            source = people.get(source_id)
+            if source is None:
+                raise ValueError(f"Source Person {source_id} does not exist")
+            destination = people.get(destination_id)
+            if destination is None:
+                raise ValueError(f"Destination Person {destination_id} does not exist")
+
+            links_moved, links_collapsed = _merge_links(source, destination)
+            methods_moved, methods_collapsed = _merge_contact_methods(
+                source, destination
+            )
+
+            jobs_moved = 0
+            for job in Job.objects.filter(person=source).order_by("id"):
+                job.person = destination
+                job.save(staff=staff, update_fields=["person"])
+                jobs_moved += 1
+
+            calls_moved = PhoneCallRecord.objects.filter(person=source).update(
+                person=destination
+            )
+            source.delete()
+            return {
+                "jobs": jobs_moved,
+                "phone_calls": calls_moved,
+                "links_moved": links_moved,
+                "links_collapsed": links_collapsed,
+                "contact_methods_moved": methods_moved,
+                "contact_methods_collapsed": methods_collapsed,
+            }
+    except AlreadyLoggedException:
+        raise
+    except ValueError:
+        raise
+    except Exception as exc:
+        error = persist_app_error(exc)
+        raise AlreadyLoggedException(exc, error.id) from exc
diff --git a/apps/company/tests/test_cleanup_duplicate_people_command.py b/apps/company/tests/test_cleanup_duplicate_people_command.py
new file mode 100644
index 000000000..3d76c6c4b
--- /dev/null
+++ b/apps/company/tests/test_cleanup_duplicate_people_command.py
@@ -0,0 +1,55 @@
+import csv
+import tempfile
+from pathlib import Path
+
+from django.core.management import call_command
+from django.core.management.base import CommandError
+
+from apps.company.models import Person
+from apps.testing import BaseTestCase
+
+
+class CleanupDuplicatePeopleCommandTests(BaseTestCase):
+    """The cleanup CSV is a reviewed, stale-safe boundary around destructive merges."""
+
+    def _path(self) -> Path:
+        handle = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
+        handle.close()
+        return Path(handle.name)
+
+    def test_preview_prefills_only_isolated_high_confidence_pair(self) -> None:
+        Person.objects.create(name="Jane Smith", email="jane@example.com")
+        Person.objects.create(name="jane smith", email="JANE@example.com")
+        Person.objects.create(name="Accounts")
+        Person.objects.create(name=" accounts ")
+        path = self._path()
+
+        call_command("cleanup_duplicate_people", preview=str(path))
+
+        with path.open(newline="", encoding="utf-8") as input_file:
+            rows = list(csv.DictReader(input_file))
+        self.assertEqual(len(rows), 2)
+        actions_by_confidence = {row["confidence"]: row["action"] for row in rows}
+        self.assertEqual(actions_by_confidence["high"], "merge")
+        self.assertEqual(actions_by_confidence["low"], "")
+
+    def test_apply_merges_selected_rows(self) -> None:
+        first = Person.objects.create(name="Jane Smith", email="jane@example.com")
+        second = Person.objects.create(name="jane smith", email="JANE@example.com")
+        path = self._path()
+        call_command("cleanup_duplicate_people", preview=str(path))
+
+        call_command("cleanup_duplicate_people", apply=str(path))
+
+        self.assertEqual(Person.objects.filter(id__in=[first.id, second.id]).count(), 1)
+
+    def test_apply_rejects_stale_person(self) -> None:
+        Person.objects.create(name="Jane Smith", email="jane@example.com")
+        second = Person.objects.create(name="jane smith", email="JANE@example.com")
+        path = self._path()
+        call_command("cleanup_duplicate_people", preview=str(path))
+        second.name = "Jane Smith Updated"
+        second.save(update_fields=["name", "updated_at"])
+
+        with self.assertRaisesRegex(CommandError, "changed after preview"):
+            call_command("cleanup_duplicate_people", apply=str(path))
diff --git a/apps/company/tests/test_company_merge_service.py b/apps/company/tests/test_company_merge_service.py
index b7c45c6b4..ed7b74037 100644
--- a/apps/company/tests/test_company_merge_service.py
+++ b/apps/company/tests/test_company_merge_service.py
@@ -40,7 +40,6 @@ def make_link(company: Company, name: str) -> CompanyPersonLink:
     return CompanyPersonLink.objects.create(
         company=company,
         person=person,
-        xero_name=name,
     )
 
 
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index 9a5a20e43..04d3ad790 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -29,7 +29,6 @@ def _link(company: Company, name: str, email: str | None = None) -> CompanyPerso
     return CompanyPersonLink.objects.create(
         company=company,
         person=person,
-        xero_name=name,
     )
 
 
diff --git a/apps/company/tests/test_duplicate_person_report.py b/apps/company/tests/test_duplicate_person_report.py
new file mode 100644
index 000000000..e724f9189
--- /dev/null
+++ b/apps/company/tests/test_duplicate_person_report.py
@@ -0,0 +1,74 @@
+from django.test import TestCase
+from django.utils import timezone
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services.duplicate_person_report import DuplicatePersonReportService
+
+
+class DuplicatePersonReportTests(TestCase):
+    """Exact signals must find review candidates without splitting one Person."""
+
+    def _company(self, name: str) -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
+
+    def _link(self, person: Person, company: Company) -> None:
+        CompanyPersonLink.objects.create(person=person, company=company)
+
+    def _legacy_phone(self, person: Person, value: str) -> None:
+        method = ContactMethod(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value=value,
+            normalized_value=ContactMethod.normalize_phone(value),
+        )
+        ContactMethod.objects.bulk_create([method])
+
+    def test_combined_name_and_email_is_high_confidence(self) -> None:
+        """A report refactor must retain all evidence used for safe auto-selection."""
+        first = Person.objects.create(name=" Jane   Smith ", email="JANE@example.com")
+        second = Person.objects.create(name="jane smith", email="jane@example.com")
+        self._link(first, self._company("Acme"))
+        self._link(second, self._company("Beta"))
+
+        report = DuplicatePersonReportService().get_report()
+
+        self.assertEqual(len(report["duplicate_people"]), 1)
+        candidate = report["duplicate_people"][0]
+        self.assertEqual(candidate["confidence"], "high")
+        self.assertEqual(
+            {match["kind"] for match in candidate["matches"]}, {"name", "email"}
+        )
+        self.assertEqual(report["summary"]["people_flagged"], 2)
+
+    def test_phone_only_match_is_medium_confidence(self) -> None:
+        """Person-owned phones are useful candidates even when names differ."""
+        first = Person.objects.create(name="Jane Smith")
+        second = Person.objects.create(name="J Smith")
+        self._legacy_phone(first, "021 555 123")
+        self._legacy_phone(second, "+64 21 555 123")
+
+        candidate = DuplicatePersonReportService().get_report()["duplicate_people"][0]
+
+        self.assertEqual(candidate["confidence"], "medium")
+        self.assertEqual(candidate["matches"][0]["kind"], "phone")
+
+    def test_one_person_linked_to_multiple_companies_is_not_duplicate(self) -> None:
+        """The first-class model allows one human to have several company links."""
+        person = Person.objects.create(name="Jane Smith", email="jane@example.com")
+        self._link(person, self._company("Acme"))
+        self._link(person, self._company("Beta"))
+        self._legacy_phone(person, "021 555 123")
+
+        report = DuplicatePersonReportService().get_report()
+
+        self.assertEqual(report["duplicate_people"], [])
+        self.assertEqual(report["summary"]["candidate_pairs"], 0)
+
+    def test_name_only_match_is_low_confidence(self) -> None:
+        """Common exact names require review rather than automatic confidence."""
+        Person.objects.create(name="Accounts")
+        Person.objects.create(name=" accounts ")
+
+        candidate = DuplicatePersonReportService().get_report()["duplicate_people"][0]
+
+        self.assertEqual(candidate["confidence"], "low")
diff --git a/apps/company/tests/test_duplicate_phone_report.py b/apps/company/tests/test_duplicate_phone_report.py
index 5918febd7..7805a31b5 100644
--- a/apps/company/tests/test_duplicate_phone_report.py
+++ b/apps/company/tests/test_duplicate_phone_report.py
@@ -32,7 +32,6 @@ def _link(self, company: Company, name: str) -> CompanyPersonLink:
         return CompanyPersonLink.objects.create(
             company=company,
             person=person,
-            xero_name=name,
         )
 
     def test_detects_cross_company_number(self) -> None:
@@ -85,3 +84,16 @@ def test_clean_data_returns_empty(self) -> None:
         self.assertEqual(report["duplicate_phones"], [])
         self.assertEqual(report["summary"], {"cross_company": 0, "internal_line": 0})
         self.assertIn("checked_at", report)
+
+    def test_one_person_linked_to_two_companies_is_one_phone_owner(self) -> None:
+        """A Person may span companies; unioning their company ids caused a false alert."""
+        acme = self._company("Acme Ltd")
+        beta = self._company("Beta Ltd")
+        person = Person.objects.create(name="Jane Smith")
+        first_link = CompanyPersonLink.objects.create(company=acme, person=person)
+        CompanyPersonLink.objects.create(company=beta, person=person)
+        self._phone("021 111 111", contact=first_link)
+
+        report = DuplicatePhoneReportService().get_report()
+
+        self.assertEqual(report["duplicate_phones"], [])
diff --git a/apps/company/tests/test_job_contact_view.py b/apps/company/tests/test_job_contact_view.py
index 876405fdf..e4eb101e9 100644
--- a/apps/company/tests/test_job_contact_view.py
+++ b/apps/company/tests/test_job_contact_view.py
@@ -32,7 +32,6 @@ def _link(self, name: str) -> CompanyPersonLink:
         return CompanyPersonLink.objects.create(
             company=self.job_company,
             person=person,
-            xero_name=name,
         )
 
     def _job(self, link: CompanyPersonLink) -> Job:
diff --git a/apps/company/tests/test_people_backfill_migration.py b/apps/company/tests/test_people_backfill_migration.py
index d450d3394..abef1eec8 100644
--- a/apps/company/tests/test_people_backfill_migration.py
+++ b/apps/company/tests/test_people_backfill_migration.py
@@ -116,6 +116,7 @@ def test_backfill_and_reverse_restore_legacy_contact_ownership(self) -> None:
         self.executor.loader.build_graph()
         self.executor.migrate(self.migrate_from)
         reversed_apps = self.executor.loader.project_state(self.migrate_from).apps
+        Person = reversed_apps.get_model("company", "Person")
         CompanyPersonLink = reversed_apps.get_model("company", "CompanyPersonLink")
         ContactMethod = reversed_apps.get_model("company", "ContactMethod")
         Job = reversed_apps.get_model("job", "Job")
@@ -135,3 +136,4 @@ def test_backfill_and_reverse_restore_legacy_contact_ownership(self) -> None:
         self.assertIsNone(job.person_id)
         self.assertEqual(call.contact_id, link.pk)
         self.assertIsNone(call.person_id)
+        self.assertEqual(Person.objects.count(), 0)
diff --git a/apps/company/tests/test_person_cleanup_migration.py b/apps/company/tests/test_person_cleanup_migration.py
new file mode 100644
index 000000000..dd40a8f2a
--- /dev/null
+++ b/apps/company/tests/test_person_cleanup_migration.py
@@ -0,0 +1,105 @@
+import uuid
+from typing import ClassVar
+
+from django.db import connection, transaction
+from django.db.migrations.executor import MigrationExecutor
+from django.test import TransactionTestCase
+from django.utils import timezone
+
+
+class PersonCleanupMigrationTests(TransactionTestCase):
+    """The cleanup removes only rows with no remaining business references."""
+
+    migrate_from: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("company", "0006_alter_companypersonlink_options_and_more"),
+        ("crm", "0006_remove_phonecallrecord_contact_and_more"),
+        ("job", "0006_rename_job_event_people_company_terms"),
+    )
+    migrate_to: ClassVar[tuple[tuple[str, str], ...]] = (
+        ("company", "0007_remove_xero_person_identity"),
+    )
+
+    def setUp(self) -> None:
+        super().setUp()
+        self.executor = MigrationExecutor(connection)
+        self.executor.migrate(self.migrate_from)
+        self.old_apps = self.executor.loader.project_state(self.migrate_from).apps
+
+    def tearDown(self) -> None:
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.executor.loader.graph.leaf_nodes())
+        super().tearDown()
+
+    def test_removes_unreferenced_person_and_preserves_every_reference_kind(
+        self,
+    ) -> None:
+        Company = self.old_apps.get_model("company", "Company")
+        Person = self.old_apps.get_model("company", "Person")
+        CompanyPersonLink = self.old_apps.get_model("company", "CompanyPersonLink")
+        ContactMethod = self.old_apps.get_model("company", "ContactMethod")
+        Job = self.old_apps.get_model("job", "Job")
+        CostSet = self.old_apps.get_model("job", "CostSet")
+        PhoneCallRecord = self.old_apps.get_model("crm", "PhoneCallRecord")
+        XeroPayItem = self.old_apps.get_model("workflow", "XeroPayItem")
+
+        company = Company.objects.create(name="Acme", xero_last_modified=timezone.now())
+        unreferenced = Person.objects.create(name="Unreferenced")
+        linked = Person.objects.create(name="Linked")
+        method_owner = Person.objects.create(name="Method Owner")
+        job_person = Person.objects.create(name="Job Person")
+        call_person = Person.objects.create(name="Call Person")
+        CompanyPersonLink.objects.create(company=company, person=linked)
+        ContactMethod.objects.create(
+            person=method_owner,
+            method_type="email",
+            value="method@example.com",
+            normalized_value="method@example.com",
+        )
+        pay_item, _created = XeroPayItem.objects.get_or_create(
+            name="Ordinary Time",
+            uses_leave_api=False,
+            defaults={"multiplier": "1.00"},
+        )
+        estimate_id = uuid.uuid4()
+        quote_id = uuid.uuid4()
+        actual_id = uuid.uuid4()
+        with transaction.atomic():
+            with connection.cursor() as cursor:
+                cursor.execute("SET CONSTRAINTS ALL DEFERRED")
+            job = Job.objects.create(
+                company=company,
+                person=job_person,
+                name="Migration Job",
+                job_number=998101,
+                default_xero_pay_item=pay_item,
+                latest_estimate_id=estimate_id,
+                latest_quote_id=quote_id,
+                latest_actual_id=actual_id,
+            )
+            CostSet.objects.create(id=estimate_id, job=job, kind="estimate", rev=1)
+            CostSet.objects.create(id=quote_id, job=job, kind="quote", rev=1)
+            CostSet.objects.create(id=actual_id, job=job, kind="actual", rev=1)
+        now = timezone.now()
+        PhoneCallRecord.objects.create(
+            provider_call_id="person-cleanup-migration",
+            account_code="account",
+            call_datetime=now,
+            call_date=timezone.localdate(),
+            call_time=now.time(),
+            person=call_person,
+            raw_json={},
+        )
+
+        self.executor.loader.build_graph()
+        self.executor.migrate(self.migrate_to)
+        new_apps = self.executor.loader.project_state(self.migrate_to).apps
+        Person = new_apps.get_model("company", "Person")
+        CompanyPersonLink = new_apps.get_model("company", "CompanyPersonLink")
+
+        self.assertFalse(Person.objects.filter(id=unreferenced.id).exists())
+        for person in (linked, method_owner, job_person, call_person):
+            self.assertTrue(Person.objects.filter(id=person.id).exists())
+        self.assertNotIn(
+            "xero_name",
+            {field.name for field in CompanyPersonLink._meta.get_fields()},
+        )
diff --git a/apps/company/tests/test_person_merge_service.py b/apps/company/tests/test_person_merge_service.py
new file mode 100644
index 000000000..3e21034f4
--- /dev/null
+++ b/apps/company/tests/test_person_merge_service.py
@@ -0,0 +1,142 @@
+import uuid
+from unittest.mock import patch
+
+from django.utils import timezone
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services.person_merge_service import merge_people
+from apps.crm.models import PhoneCallRecord
+from apps.job.models import Job
+from apps.testing import BaseTestCase
+from apps.workflow.exceptions import AlreadyLoggedException
+from apps.workflow.models import AppError
+
+
+class PersonMergeServiceTests(BaseTestCase):
+    """Merging must preserve references while retaining uniqueness invariants."""
+
+    def _company(self, name: str) -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
+
+    def _call(self, person: Person) -> PhoneCallRecord:
+        now = timezone.now()
+        return PhoneCallRecord.objects.create(
+            provider_call_id=f"person-merge:{uuid.uuid4()}",
+            account_code="account",
+            call_datetime=now,
+            call_date=timezone.localdate(),
+            call_time=now.time(),
+            person=person,
+            raw_json={},
+        )
+
+    def _job(self, person: Person, company: Company) -> Job:
+        job = Job(
+            name="Merge Person Job",
+            job_number=998001,
+            company=company,
+            person=person,
+        )
+        job.save(staff=self.test_staff)
+        return job
+
+    def test_moves_cross_company_relationships_and_references(self) -> None:
+        source = Person.objects.create(name="J Smith", email="old@example.com")
+        destination = Person.objects.create(
+            name="Jane Smith", email="canonical@example.com"
+        )
+        source_company = self._company("Source Co")
+        destination_company = self._company("Destination Co")
+        CompanyPersonLink.objects.create(company=source_company, person=source)
+        CompanyPersonLink.objects.create(
+            company=destination_company, person=destination
+        )
+        method = ContactMethod.objects.create(
+            person=source,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 555 123",
+        )
+        job = self._job(source, source_company)
+        call = self._call(source)
+
+        counts = merge_people(source.id, destination.id, self.test_staff)
+
+        destination.refresh_from_db()
+        method.refresh_from_db()
+        job.refresh_from_db()
+        call.refresh_from_db()
+        self.assertFalse(Person.objects.filter(id=source.id).exists())
+        self.assertEqual(destination.name, "Jane Smith")
+        self.assertEqual(destination.email, "canonical@example.com")
+        self.assertEqual(destination.company_links.count(), 2)
+        self.assertEqual(method.person_id, destination.id)
+        self.assertEqual(job.person_id, destination.id)
+        self.assertEqual(call.person_id, destination.id)
+        self.assertEqual(counts["links_moved"], 1)
+        self.assertEqual(counts["jobs"], 1)
+        self.assertEqual(counts["phone_calls"], 1)
+
+    def test_collapses_same_company_link_and_exact_method(self) -> None:
+        source = Person.objects.create(name="J Smith")
+        destination = Person.objects.create(name="Jane Smith")
+        company = self._company("Acme")
+        source_link = CompanyPersonLink.objects.create(
+            company=company,
+            person=source,
+            position="Foreman",
+            notes="Source notes",
+            is_primary=True,
+        )
+        destination_link = CompanyPersonLink.objects.create(
+            company=company,
+            person=destination,
+        )
+        source_method = ContactMethod.objects.create(
+            person=source,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 555 123",
+            label="Mobile",
+            is_primary=True,
+        )
+        destination_method = ContactMethod.objects.create(
+            person=destination,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="+64 21 555 123",
+        )
+
+        counts = merge_people(source.id, destination.id, self.test_staff)
+
+        destination_link.refresh_from_db()
+        destination_method.refresh_from_db()
+        self.assertFalse(CompanyPersonLink.objects.filter(id=source_link.id).exists())
+        self.assertEqual(destination.company_links.count(), 1)
+        self.assertEqual(destination_link.position, "Foreman")
+        self.assertEqual(destination_link.notes, "Source notes")
+        self.assertTrue(destination_link.is_primary)
+        self.assertFalse(ContactMethod.objects.filter(id=source_method.id).exists())
+        self.assertEqual(destination.contact_methods.count(), 1)
+        self.assertEqual(destination_method.label, "Mobile")
+        self.assertTrue(destination_method.is_primary)
+        self.assertEqual(counts["links_collapsed"], 1)
+        self.assertEqual(counts["contact_methods_collapsed"], 1)
+
+    def test_unexpected_failure_rolls_back_and_persists_once(self) -> None:
+        """A mid-merge failure must not strand links or create duplicate AppErrors."""
+        source = Person.objects.create(name="J Smith")
+        destination = Person.objects.create(name="Jane Smith")
+        source_link = CompanyPersonLink.objects.create(
+            company=self._company("Acme"), person=source
+        )
+        before_errors = AppError.objects.count()
+
+        with patch(
+            "apps.company.services.person_merge_service._merge_contact_methods",
+            side_effect=RuntimeError("merge failed"),
+        ):
+            with self.assertRaises(AlreadyLoggedException):
+                merge_people(source.id, destination.id, self.test_staff)
+
+        source_link.refresh_from_db()
+        self.assertEqual(source_link.person_id, source.id)
+        self.assertTrue(Person.objects.filter(id=source.id).exists())
+        self.assertEqual(AppError.objects.count(), before_errors + 1)
diff --git a/apps/crm/tests/test_phone_call_service.py b/apps/crm/tests/test_phone_call_service.py
index e10b79cb8..ba3b06afb 100644
--- a/apps/crm/tests/test_phone_call_service.py
+++ b/apps/crm/tests/test_phone_call_service.py
@@ -94,7 +94,6 @@ def _link(self, company: Company, name: str) -> CompanyPersonLink:
         return CompanyPersonLink.objects.create(
             company=company,
             person=person,
-            xero_name=name,
         )
 
     def test_assign_phone_number_creates_primary_contact_method_and_matches_client(
@@ -797,7 +796,6 @@ def test_assign_number_cross_company_person_does_not_persist_app_error(
         CompanyPersonLink.objects.create(
             company=self.other_company,
             person=person,
-            xero_name=person.name,
         )
         before = AppError.objects.count()
 
diff --git a/apps/crm/tests/test_phone_endpoint_guard.py b/apps/crm/tests/test_phone_endpoint_guard.py
index eeac79478..11e0a8529 100644
--- a/apps/crm/tests/test_phone_endpoint_guard.py
+++ b/apps/crm/tests/test_phone_endpoint_guard.py
@@ -33,7 +33,6 @@ def _link(company: Company, name: str) -> CompanyPersonLink:
     return CompanyPersonLink.objects.create(
         company=company,
         person=person,
-        xero_name=name,
     )
 
 
diff --git a/apps/job/serializers/__init__.py b/apps/job/serializers/__init__.py
index 50b61ec00..e6dbf6022 100644
--- a/apps/job/serializers/__init__.py
+++ b/apps/job/serializers/__init__.py
@@ -30,6 +30,13 @@
             ArchivedJobIssueSerializer,
             ArchivedJobsComplianceResponseSerializer,
             ComplianceSummarySerializer,
+            DuplicatePeopleResponseSerializer,
+            DuplicatePersonCandidateSerializer,
+            DuplicatePersonCompanyLinkSerializer,
+            DuplicatePersonContactMethodSerializer,
+            DuplicatePersonMatchSerializer,
+            DuplicatePersonReportSummarySerializer,
+            DuplicatePersonSummarySerializer,
             DuplicatePhoneIssueSerializer,
             DuplicatePhoneOwnerSerializer,
             DuplicatePhoneSummarySerializer,
@@ -196,6 +203,13 @@
     "DataIntegritySummarySerializer",
     "DiffPreviewSerializer",
     "DraftLineSerializer",
+    "DuplicatePeopleResponseSerializer",
+    "DuplicatePersonCandidateSerializer",
+    "DuplicatePersonCompanyLinkSerializer",
+    "DuplicatePersonContactMethodSerializer",
+    "DuplicatePersonMatchSerializer",
+    "DuplicatePersonReportSummarySerializer",
+    "DuplicatePersonSummarySerializer",
     "DuplicatePhoneIssueSerializer",
     "DuplicatePhoneOwnerSerializer",
     "DuplicatePhoneSummarySerializer",
diff --git a/apps/job/serializers/data_quality_report_serializers.py b/apps/job/serializers/data_quality_report_serializers.py
index b668e4d25..020db55f3 100644
--- a/apps/job/serializers/data_quality_report_serializers.py
+++ b/apps/job/serializers/data_quality_report_serializers.py
@@ -2,6 +2,15 @@
 
 from rest_framework import serializers
 
+from apps.company.services.duplicate_person_report import (
+    DuplicatePersonCandidate,
+    DuplicatePersonCompanyLink,
+    DuplicatePersonContactMethod,
+    DuplicatePersonMatch,
+    DuplicatePersonReport,
+    DuplicatePersonReportSummary,
+    DuplicatePersonSummary,
+)
 from apps.company.services.duplicate_phone_report import (
     DuplicatePhoneIssue,
     DuplicatePhoneOwner,
@@ -111,3 +120,69 @@ class DuplicatePhonesResponseSerializer(serializers.Serializer[DuplicatePhonesRe
     )
     summary = DuplicatePhoneSummarySerializer(help_text="Summary of issues")
     checked_at = serializers.DateTimeField(help_text="When the check was performed")
+
+
+class DuplicatePersonCompanyLinkSerializer(
+    serializers.Serializer[DuplicatePersonCompanyLink]
+):
+    link_id = serializers.UUIDField()
+    company_id = serializers.UUIDField()
+    company_name = serializers.CharField()
+    position = serializers.CharField(allow_null=True)
+    is_primary = serializers.BooleanField()
+    is_active = serializers.BooleanField()
+
+
+class DuplicatePersonContactMethodSerializer(
+    serializers.Serializer[DuplicatePersonContactMethod]
+):
+    method_id = serializers.UUIDField()
+    method_type = serializers.ChoiceField(choices=["phone", "email"])
+    value = serializers.CharField()
+    normalized_value = serializers.CharField()
+    contact_label = serializers.CharField()
+    is_primary = serializers.BooleanField()
+
+
+class DuplicatePersonSummarySerializer(serializers.Serializer[DuplicatePersonSummary]):
+    person_id = serializers.UUIDField()
+    name = serializers.CharField()
+    email = serializers.EmailField(allow_null=True)
+    is_active = serializers.BooleanField()
+    created_at = serializers.DateTimeField()
+    updated_at = serializers.DateTimeField()
+    company_links = DuplicatePersonCompanyLinkSerializer(many=True)
+    contact_methods = DuplicatePersonContactMethodSerializer(many=True)
+    job_count = serializers.IntegerField()
+    phone_call_count = serializers.IntegerField()
+
+
+class DuplicatePersonMatchSerializer(serializers.Serializer[DuplicatePersonMatch]):
+    kind = serializers.ChoiceField(choices=["name", "email", "phone"])
+    normalized_value = serializers.CharField()
+
+
+class DuplicatePersonCandidateSerializer(
+    serializers.Serializer[DuplicatePersonCandidate]
+):
+    confidence = serializers.ChoiceField(choices=["high", "medium", "low"])
+    matches = DuplicatePersonMatchSerializer(many=True)
+    shared_company_ids = serializers.ListField(child=serializers.UUIDField())
+    first_person = DuplicatePersonSummarySerializer()
+    second_person = DuplicatePersonSummarySerializer()
+
+
+class DuplicatePersonReportSummarySerializer(
+    serializers.Serializer[DuplicatePersonReportSummary]
+):
+    candidate_pairs = serializers.IntegerField()
+    people_flagged = serializers.IntegerField()
+    high = serializers.IntegerField()
+    medium = serializers.IntegerField()
+    low = serializers.IntegerField()
+
+
+class DuplicatePeopleResponseSerializer(serializers.Serializer[DuplicatePersonReport]):
+    duplicate_people = DuplicatePersonCandidateSerializer(many=True)
+    summary = DuplicatePersonReportSummarySerializer()
+    checked_at = serializers.DateTimeField()
diff --git a/apps/job/tests/test_duplicate_people_view.py b/apps/job/tests/test_duplicate_people_view.py
new file mode 100644
index 000000000..542c64172
--- /dev/null
+++ b/apps/job/tests/test_duplicate_people_view.py
@@ -0,0 +1,36 @@
+from apps.accounts.models import Staff
+from apps.company.models import Person
+from apps.testing import BaseAPITestCase
+
+URL = "/api/job/data-quality/duplicate-people/"
+
+
+class DuplicatePeopleViewTests(BaseAPITestCase):
+    """The report contains identity data and must remain office-staff-only."""
+
+    def _office_staff(self) -> Staff:
+        return Staff.objects.create_user(
+            email="office-person-report@example.com",
+            password="testpass",
+            first_name="Office",
+            last_name="Staff",
+            is_office_staff=True,
+        )
+
+    def test_returns_duplicate_person_candidates_to_office_staff(self) -> None:
+        Person.objects.create(name="Jane Smith", email="jane@example.com")
+        Person.objects.create(name="jane smith", email="JANE@example.com")
+        self.client.force_authenticate(self._office_staff())
+
+        response = self.client.get(URL)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.data["summary"]["high"], 1)
+        self.assertEqual(len(response.data["duplicate_people"]), 1)
+
+    def test_forbidden_for_non_office_staff(self) -> None:
+        self.client.force_authenticate(self.test_staff)
+
+        response = self.client.get(URL)
+
+        self.assertEqual(response.status_code, 403)
diff --git a/apps/job/tests/test_kanban_search.py b/apps/job/tests/test_kanban_search.py
index f9cba47b2..ca10b5670 100644
--- a/apps/job/tests/test_kanban_search.py
+++ b/apps/job/tests/test_kanban_search.py
@@ -48,7 +48,6 @@ def _make_job(
             CompanyPersonLink.objects.create(
                 company=company,
                 person=person,
-                xero_name=person_name,
             )
 
         self.job_number += 1
diff --git a/apps/job/tests/test_kanban_service.py b/apps/job/tests/test_kanban_service.py
index 0afcb4f46..e91b78b6f 100644
--- a/apps/job/tests/test_kanban_service.py
+++ b/apps/job/tests/test_kanban_service.py
@@ -48,7 +48,6 @@ def _link(self, name: str) -> CompanyPersonLink:
         return CompanyPersonLink.objects.create(
             company=self.client_obj,
             person=person,
-            xero_name=name,
         )
 
     def test_over_budget_when_tm_actual_exceeds_price_cap(self):
diff --git a/apps/job/urls_rest.py b/apps/job/urls_rest.py
index 895ebf117..6dd5512ab 100644
--- a/apps/job/urls_rest.py
+++ b/apps/job/urls_rest.py
@@ -3,6 +3,7 @@
 from apps.job.views.data_integrity_views import DataIntegrityReportView
 from apps.job.views.data_quality_report_views import (
     ArchivedJobsComplianceView,
+    DuplicatePeopleView,
     DuplicatePhonesView,
 )
 from apps.job.views.delivery_docket_view import DeliveryDocketView
@@ -336,6 +337,11 @@
         DuplicatePhonesView.as_view(),
         name="data_quality_duplicate_phones",
     ),
+    path(
+        "data-quality/duplicate-people/",
+        DuplicatePeopleView.as_view(),
+        name="data_quality_duplicate_people",
+    ),
     path(
         "data-integrity/scan/",
         DataIntegrityReportView.as_view(),
diff --git a/apps/job/views/__init__.py b/apps/job/views/__init__.py
index f55f59eff..dbe6e0878 100644
--- a/apps/job/views/__init__.py
+++ b/apps/job/views/__init__.py
@@ -6,7 +6,11 @@
 )
 from .assign_job_view import JobAssignmentCreateView, JobAssignmentDeleteView
 from .data_integrity_views import DataIntegrityReportView
-from .data_quality_report_views import ArchivedJobsComplianceView, DuplicatePhonesView
+from .data_quality_report_views import (
+    ArchivedJobsComplianceView,
+    DuplicatePeopleView,
+    DuplicatePhonesView,
+)
 from .delivery_docket_view import DeliveryDocketView
 from .job_costing_views import JobCostSetView, JobQuoteRevisionView
 from .job_costline_views import (
@@ -109,6 +113,7 @@
     "CostLineUpdateView",
     "DataIntegrityReportView",
     "DeliveryDocketView",
+    "DuplicatePeopleView",
     "DuplicatePhonesView",
     "FetchAllJobsAPIView",
     "FetchJobsAPIView",
diff --git a/apps/job/views/data_quality_report_views.py b/apps/job/views/data_quality_report_views.py
index fd7570070..ff962b976 100644
--- a/apps/job/views/data_quality_report_views.py
+++ b/apps/job/views/data_quality_report_views.py
@@ -12,10 +12,12 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
+from apps.company.services.duplicate_person_report import DuplicatePersonReportService
 from apps.company.services.duplicate_phone_report import DuplicatePhoneReportService
 from apps.job.permissions import IsOfficeStaff
 from apps.job.serializers.data_quality_report_serializers import (
     ArchivedJobsComplianceResponseSerializer,
+    DuplicatePeopleResponseSerializer,
     DuplicatePhonesResponseSerializer,
 )
 from apps.job.services.data_quality_report import ArchivedJobsComplianceService
@@ -94,3 +96,31 @@ def get(self, request: Request) -> Response:
         except Exception as exc:
             err = persist_app_error(exc)
             raise AlreadyLoggedException(exc, err.id) from exc
+
+
+class DuplicatePeopleView(APIView):
+    """API view for exact-signal duplicate Person candidates."""
+
+    permission_classes = [IsAuthenticated, IsOfficeStaff]
+
+    @extend_schema(
+        operation_id="check_duplicate_people",
+        summary="Check for duplicate people",
+        description=(
+            "List pairs of distinct Person rows sharing exact normalized name, "
+            "email, or person-owned phone signals."
+        ),
+        responses={200: DuplicatePeopleResponseSerializer, 500: dict},
+        tags=["Data Quality"],
+    )
+    def get(self, request: Request) -> Response:
+        try:
+            result = DuplicatePersonReportService().get_report()
+            serializer = DuplicatePeopleResponseSerializer(data=result)
+            serializer.is_valid(raise_exception=True)
+            return Response(serializer.data, status=status.HTTP_200_OK)
+        except AlreadyLoggedException:
+            raise
+        except Exception as exc:
+            err = persist_app_error(exc)
+            raise AlreadyLoggedException(exc, err.id) from exc
diff --git a/apps/workflow/api/xero/reprocess_xero.py b/apps/workflow/api/xero/reprocess_xero.py
index f4d444835..935a58d5d 100644
--- a/apps/workflow/api/xero/reprocess_xero.py
+++ b/apps/workflow/api/xero/reprocess_xero.py
@@ -4,7 +4,7 @@
 from collections.abc import Mapping
 
 from django.core.exceptions import ValidationError
-from django.db import IntegrityError, transaction
+from django.db import transaction
 from django.utils import timezone
 from django.utils.dateparse import parse_datetime
 
@@ -18,16 +18,13 @@
 )
 from apps.company.models import (
     Company,
-    CompanyPersonLink,
     ContactMethod,
-    Person,
     SupplierPickupAddress,
 )
 from apps.crm.tasks import rematch_phone_calls_task
 from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.models import XeroAccount
 from apps.workflow.services.error_persistence import (
-    persist_and_raise,
     persist_app_error,
 )
 
@@ -370,81 +367,6 @@ def set_company_fields(company: Company, new_from_xero: bool = False) -> None:
         "_is_customer", company.is_account_customer
     )
 
-    contact_persons_payload = raw_json.get("_contact_persons")
-    if isinstance(contact_persons_payload, list):
-        contact_persons = contact_persons_payload
-    else:
-        contact_persons = []
-
-    for person_payload in contact_persons:
-        if not isinstance(person_payload, dict):
-            continue
-        first_name = person_payload.get("_first_name") or ""
-        last_name = person_payload.get("_last_name") or ""
-        xero_name = (first_name + (" " + last_name if last_name else "")).strip()
-        if not xero_name:
-            logger.debug("Skipping Xero contact person with empty name for %s", company)
-            continue
-        email = person_payload.get("_email_address") or None
-        try:
-            link = (
-                CompanyPersonLink.objects.filter(
-                    company=company,
-                    xero_name=xero_name,
-                )
-                .select_related("person")
-                .get()
-            )
-            if not link.is_active:
-                link.is_active = True
-                link.save(update_fields=["is_active", "updated_at"])
-            if link.person.email != email:
-                link.person.email = email
-                link.person.save(update_fields=["email", "updated_at"])
-        except CompanyPersonLink.DoesNotExist:
-            try:
-                with transaction.atomic():
-                    person = Person.objects.create(name=xero_name, email=email)
-                    CompanyPersonLink.objects.create(
-                        company=company,
-                        person=person,
-                        xero_name=xero_name,
-                        is_active=True,
-                    )
-            except IntegrityError as exc:
-                try:
-                    CompanyPersonLink.objects.filter(
-                        company=company,
-                        xero_name=xero_name,
-                    ).select_related("person").get()
-                except CompanyPersonLink.DoesNotExist:
-                    persist_and_raise(
-                        exc,
-                        additional_context={
-                            "operation": "set_company_fields_person_link_race",
-                            "client_id": str(company.id),
-                            "xero_name": xero_name,
-                        },
-                    )
-                except CompanyPersonLink.MultipleObjectsReturned:
-                    persist_and_raise(
-                        exc,
-                        additional_context={
-                            "operation": "set_company_fields_person_link_race",
-                            "client_id": str(company.id),
-                            "xero_name": xero_name,
-                        },
-                    )
-        except CompanyPersonLink.MultipleObjectsReturned as exc:
-            persist_and_raise(
-                exc,
-                additional_context={
-                    "operation": "set_company_fields_duplicate_person_link",
-                    "client_id": str(company.id),
-                    "xero_name": xero_name,
-                },
-            )
-
     # Handle xero_last_modified
     updated_date_utc_str = raw_json.get("_updated_date_utc")
     if updated_date_utc_str:
diff --git a/apps/workflow/tests/test_data_versions_view.py b/apps/workflow/tests/test_data_versions_view.py
index 366732e95..dfd1da864 100644
--- a/apps/workflow/tests/test_data_versions_view.py
+++ b/apps/workflow/tests/test_data_versions_view.py
@@ -206,7 +206,6 @@ def test_related_display_changes_change_kanban_version(
     CompanyPersonLink.objects.create(
         company=company,
         person=person,
-        xero_name=person.name,
     )
     _job(office_staff, company=company, person=person)
     before = auth_client.get("/api/data-versions/").json()["kanban"]
diff --git a/apps/workflow/tests/test_sync_clients.py b/apps/workflow/tests/test_sync_clients.py
index 1d0f8eceb..c223ca7d9 100644
--- a/apps/workflow/tests/test_sync_clients.py
+++ b/apps/workflow/tests/test_sync_clients.py
@@ -8,7 +8,7 @@
 from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
-from apps.company.models import Company, ContactMethod
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.crm.models import PhoneCallRecord
 from apps.crm.services.phone_call_service import rematch_calls_for_numbers
 from apps.workflow.api.xero.reprocess_xero import (
@@ -20,7 +20,12 @@
 from apps.workflow.models import AppError
 
 
-def _make_raw_json(contact_id, name, status="ACTIVE", merged_to=None):
+def _make_raw_json(
+    contact_id: str,
+    name: str,
+    status: str = "ACTIVE",
+    merged_to: str | None = None,
+) -> dict[str, object]:
     """Return raw_json shaped like real Xero contact data stored in the DB.
 
     Based on actual production records — includes the full set of underscore-
@@ -257,6 +262,39 @@ def test_archived_contact_with_existing_xero_id_updates_in_place(
         self.assertTrue(self.existing_client.xero_archived)
 
 
+class XeroPersonIdentityTests(TestCase):
+    def test_contact_person_payload_does_not_create_or_update_people(self) -> None:
+        """Xero reads must not undo DocketWorks-owned Person cleanup."""
+        raw_json = _make_raw_json("xero-company", "Acme")
+        raw_json["_contact_persons"] = [
+            {
+                "_first_name": "Jane",
+                "_last_name": "Smith",
+                "_email_address": "xero@example.com",
+            }
+        ]
+        company = Company.objects.create(
+            name="Acme",
+            xero_last_modified=timezone.now(),
+            raw_json=raw_json,
+        )
+        person = Person.objects.create(
+            name="Jane Smith", email="local@example.com", is_active=False
+        )
+        link = CompanyPersonLink.objects.create(
+            company=company, person=person, is_active=False
+        )
+
+        set_company_fields(company)
+
+        person.refresh_from_db()
+        link.refresh_from_db()
+        self.assertEqual(Person.objects.count(), 1)
+        self.assertEqual(person.email, "local@example.com")
+        self.assertFalse(person.is_active)
+        self.assertFalse(link.is_active)
+
+
 class XeroPhoneMethodSyncTests(TestCase):
     def _client_with_phone(
         self,
diff --git a/docs/adr/0030-first-class-people-and-company-links.md b/docs/adr/0030-first-class-people-and-company-links.md
index 6fc512422..0a8c44d85 100644
--- a/docs/adr/0030-first-class-people-and-company-links.md
+++ b/docs/adr/0030-first-class-people-and-company-links.md
@@ -16,8 +16,7 @@ Xero import key).
 ## Decision
 
 People are first-class records. `Person` owns human identity and person-owned
-contact methods. `CompanyPersonLink` owns relationship-at-company data and the
-stable `xero_name` key used to reconcile Xero contact persons for one company.
+contact methods. `CompanyPersonLink` owns relationship-at-company data.
 
 Jobs and phone call records point to `Person`. Company contact APIs expose link
 rows with embedded person identity fields. Contact methods are owned by exactly
@@ -32,8 +31,9 @@ because those are external Xero identifiers, not CRM people.
 
 - A person may have links to multiple companies; deduplicating equivalent people
   remains a separate data-quality task.
-- Xero may create or reactivate links keyed by `(company, xero_name)`, but
-  `Person.name` is user-owned after the initial seed.
+- DocketWorks owns Person identity. Xero company contact-person payloads do not
+  create, reactivate, or update Person rows, and Person identity is not written
+  back to Xero.
 - Company merge moves company-owned contact methods, company links, jobs, and
   call company ownership. It does not move person-owned contact methods.
 - API callers use `person_id` and `person_name` for jobs, calls, Kanban, and
diff --git a/docs/urls/job.md b/docs/urls/job.md
index b16eeb4f2..0bae5995a 100644
--- a/docs/urls/job.md
+++ b/docs/urls/job.md
@@ -23,6 +23,7 @@
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
 | `/data-quality/archived-jobs-compliance/` | `data_quality_report_views.ArchivedJobsComplianceView` | `jobs:data_quality_archived_jobs_compliance` | API view for checking archived jobs compliance. |
+| `/data-quality/duplicate-people/` | `data_quality_report_views.DuplicatePeopleView` | `jobs:data_quality_duplicate_people` | API view for exact-signal duplicate Person candidates. |
 | `/data-quality/duplicate-phones/` | `data_quality_report_views.DuplicatePhonesView` | `jobs:data_quality_duplicate_phones` | API view for the duplicate phones data-quality check. |
 
 ### Job Management
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 57f57c61b..dc5985d58 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -3144,6 +3144,30 @@ paths:
                 type: object
                 additionalProperties: {}
           description: ''
+  /api/job/data-quality/duplicate-people/:
+    get:
+      operationId: check_duplicate_people
+      description: List pairs of distinct Person rows sharing exact normalized name,
+        email, or person-owned phone signals.
+      summary: Check for duplicate people
+      tags:
+        - Data Quality
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DuplicatePeopleResponse'
+          description: ''
+        '500':
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: {}
+          description: ''
   /api/job/data-quality/duplicate-phones/:
     get:
       operationId: check_duplicate_phones
@@ -11153,10 +11177,6 @@ components:
           type: string
           format: email
           nullable: true
-        xero_name:
-          type: string
-          nullable: true
-          maxLength: 255
         position:
           type: string
           nullable: true
@@ -11209,10 +11229,6 @@ components:
           type: string
           format: email
           nullable: true
-        xero_name:
-          type: string
-          nullable: true
-          maxLength: 255
         position:
           type: string
           nullable: true
@@ -11379,6 +11395,16 @@ components:
         - not_cancelled
         - not_invoiced
         - not_paid
+    ConfidenceEnum:
+      enum:
+        - high
+        - medium
+        - low
+      type: string
+      description: |-
+        * `high` - high
+        * `medium` - medium
+        * `low` - low
     ContactMethod:
       type: object
       description: Serializer for canonical company/person phone and email methods.
@@ -11405,7 +11431,7 @@ components:
           type: string
           readOnly: true
         method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
         value:
           type: string
           maxLength: 255
@@ -11438,6 +11464,14 @@ components:
         - person_name
         - updated_at
         - value
+    ContactMethodMethodTypeEnum:
+      enum:
+        - phone
+        - email
+      type: string
+      description: |-
+        * `phone` - Phone
+        * `email` - Email
     ContactMethodRequest:
       type: object
       description: Serializer for canonical company/person phone and email methods.
@@ -11451,7 +11485,7 @@ components:
           format: uuid
           nullable: true
         method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
         value:
           type: string
           minLength: 1
@@ -12212,6 +12246,184 @@ components:
         - total_rev
         - unit_cost
         - unit_rev
+    DuplicatePeopleResponse:
+      type: object
+      properties:
+        duplicate_people:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonCandidate'
+        summary:
+          $ref: '#/components/schemas/DuplicatePersonReportSummary'
+        checked_at:
+          type: string
+          format: date-time
+      required:
+        - checked_at
+        - duplicate_people
+        - summary
+    DuplicatePersonCandidate:
+      type: object
+      properties:
+        confidence:
+          $ref: '#/components/schemas/ConfidenceEnum'
+        matches:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonMatch'
+        shared_company_ids:
+          type: array
+          items:
+            type: string
+            format: uuid
+        first_person:
+          $ref: '#/components/schemas/DuplicatePersonSummary'
+        second_person:
+          $ref: '#/components/schemas/DuplicatePersonSummary'
+      required:
+        - confidence
+        - first_person
+        - matches
+        - second_person
+        - shared_company_ids
+    DuplicatePersonCompanyLink:
+      type: object
+      properties:
+        link_id:
+          type: string
+          format: uuid
+        company_id:
+          type: string
+          format: uuid
+        company_name:
+          type: string
+        position:
+          type: string
+          nullable: true
+        is_primary:
+          type: boolean
+        is_active:
+          type: boolean
+      required:
+        - company_id
+        - company_name
+        - is_active
+        - is_primary
+        - link_id
+        - position
+    DuplicatePersonContactMethod:
+      type: object
+      properties:
+        method_id:
+          type: string
+          format: uuid
+        method_type:
+          $ref: '#/components/schemas/DuplicatePersonContactMethodMethodTypeEnum'
+        value:
+          type: string
+        normalized_value:
+          type: string
+        contact_label:
+          type: string
+        is_primary:
+          type: boolean
+      required:
+        - contact_label
+        - is_primary
+        - method_id
+        - method_type
+        - normalized_value
+        - value
+    DuplicatePersonContactMethodMethodTypeEnum:
+      enum:
+        - phone
+        - email
+      type: string
+      description: |-
+        * `phone` - phone
+        * `email` - email
+    DuplicatePersonMatch:
+      type: object
+      properties:
+        kind:
+          $ref: '#/components/schemas/DuplicatePersonMatchKindEnum'
+        normalized_value:
+          type: string
+      required:
+        - kind
+        - normalized_value
+    DuplicatePersonMatchKindEnum:
+      enum:
+        - name
+        - email
+        - phone
+      type: string
+      description: |-
+        * `name` - name
+        * `email` - email
+        * `phone` - phone
+    DuplicatePersonReportSummary:
+      type: object
+      properties:
+        candidate_pairs:
+          type: integer
+        people_flagged:
+          type: integer
+        high:
+          type: integer
+        medium:
+          type: integer
+        low:
+          type: integer
+      required:
+        - candidate_pairs
+        - high
+        - low
+        - medium
+        - people_flagged
+    DuplicatePersonSummary:
+      type: object
+      properties:
+        person_id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        email:
+          type: string
+          format: email
+          nullable: true
+        is_active:
+          type: boolean
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        company_links:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonCompanyLink'
+        contact_methods:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonContactMethod'
+        job_count:
+          type: integer
+        phone_call_count:
+          type: integer
+      required:
+        - company_links
+        - contact_methods
+        - created_at
+        - email
+        - is_active
+        - job_count
+        - name
+        - person_id
+        - phone_call_count
+        - updated_at
     DuplicatePhoneIssue:
       type: object
       description: One problematic phone number and its owners.
@@ -15523,14 +15735,6 @@ components:
         * `galvanized` - Galvanized
         * `unspecified` - Unspecified
         * `other` - Other
-    MethodTypeEnum:
-      enum:
-        - phone
-        - email
-      type: string
-      description: |-
-        * `phone` - Phone
-        * `email` - Email
     ModernStaff:
       type: object
       description: Serializer for staff in timesheet context
@@ -16479,10 +16683,6 @@ components:
           type: string
           format: email
           nullable: true
-        xero_name:
-          type: string
-          nullable: true
-          maxLength: 255
         position:
           type: string
           nullable: true
@@ -16532,7 +16732,7 @@ components:
           format: uuid
           nullable: true
         method_type:
-          $ref: '#/components/schemas/MethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
         value:
           type: string
           minLength: 1
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index e23d436aa..f4be2774b 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -705,7 +705,7 @@ const PatchedCompanyUpdateRequest = z
   })
   .partial()
 const CompanyNameOnly = z.object({ id: z.string().uuid(), name: z.string() })
-const MethodTypeEnum = z.enum(['phone', 'email'])
+const ContactMethodMethodTypeEnum = z.enum(['phone', 'email'])
 const ContactMethodSourceEnum = z.enum(['imported', 'local'])
 const ContactMethod = z.object({
   id: z.string().uuid(),
@@ -714,7 +714,7 @@ const ContactMethod = z.object({
   company_name: z.string(),
   person: z.string().uuid().nullish(),
   person_name: z.string(),
-  method_type: MethodTypeEnum,
+  method_type: ContactMethodMethodTypeEnum,
   value: z.string().max(255),
   normalized_value: z.string(),
   label: z.string().max(255).optional(),
@@ -733,7 +733,7 @@ const PaginatedContactMethodList = z.object({
 const ContactMethodRequest = z.object({
   company: z.string().uuid().nullish(),
   person: z.string().uuid().nullish(),
-  method_type: MethodTypeEnum,
+  method_type: ContactMethodMethodTypeEnum,
   value: z.string().min(1).max(255),
   label: z.string().max(255).optional(),
   is_primary: z.boolean().optional().default(false),
@@ -743,7 +743,7 @@ const PatchedContactMethodRequest = z
   .object({
     company: z.string().uuid().nullable(),
     person: z.string().uuid().nullable(),
-    method_type: MethodTypeEnum,
+    method_type: ContactMethodMethodTypeEnum,
     value: z.string().min(1).max(255),
     label: z.string().max(255),
     is_primary: z.boolean().default(false),
@@ -797,7 +797,6 @@ const CompanyPersonLink = z.object({
   person: z.string().uuid(),
   person_name: z.string(),
   person_email: z.string().email().nullish(),
-  xero_name: z.string().max(255).nullish(),
   position: z.string().max(255).nullish(),
   is_primary: z.boolean().optional(),
   notes: z.string().nullish(),
@@ -810,7 +809,6 @@ const CompanyPersonLinkRequest = z.object({
   company: z.string().uuid(),
   person_name: z.string().min(1),
   person_email: z.string().email().nullish(),
-  xero_name: z.string().max(255).nullish(),
   position: z.string().max(255).nullish(),
   is_primary: z.boolean().optional(),
   notes: z.string().nullish(),
@@ -821,7 +819,6 @@ const PatchedCompanyPersonLinkRequest = z
     company: z.string().uuid(),
     person_name: z.string().min(1),
     person_email: z.string().email().nullable(),
-    xero_name: z.string().max(255).nullable(),
     position: z.string().max(255).nullable(),
     is_primary: z.boolean(),
     notes: z.string().nullable(),
@@ -1343,6 +1340,60 @@ const ArchivedJobsComplianceResponse = z.object({
   summary: ComplianceSummary,
   checked_at: z.string().datetime({ offset: true }),
 })
+const ConfidenceEnum = z.enum(['high', 'medium', 'low'])
+const DuplicatePersonMatchKindEnum = z.enum(['name', 'email', 'phone'])
+const DuplicatePersonMatch = z.object({
+  kind: DuplicatePersonMatchKindEnum,
+  normalized_value: z.string(),
+})
+const DuplicatePersonCompanyLink = z.object({
+  link_id: z.string().uuid(),
+  company_id: z.string().uuid(),
+  company_name: z.string(),
+  position: z.string().nullable(),
+  is_primary: z.boolean(),
+  is_active: z.boolean(),
+})
+const DuplicatePersonContactMethodMethodTypeEnum = z.enum(['phone', 'email'])
+const DuplicatePersonContactMethod = z.object({
+  method_id: z.string().uuid(),
+  method_type: DuplicatePersonContactMethodMethodTypeEnum,
+  value: z.string(),
+  normalized_value: z.string(),
+  contact_label: z.string(),
+  is_primary: z.boolean(),
+})
+const DuplicatePersonSummary = z.object({
+  person_id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email().nullable(),
+  is_active: z.boolean(),
+  created_at: z.string().datetime({ offset: true }),
+  updated_at: z.string().datetime({ offset: true }),
+  company_links: z.array(DuplicatePersonCompanyLink),
+  contact_methods: z.array(DuplicatePersonContactMethod),
+  job_count: z.number().int(),
+  phone_call_count: z.number().int(),
+})
+const DuplicatePersonCandidate = z.object({
+  confidence: ConfidenceEnum,
+  matches: z.array(DuplicatePersonMatch),
+  shared_company_ids: z.array(z.string().uuid()),
+  first_person: DuplicatePersonSummary,
+  second_person: DuplicatePersonSummary,
+})
+const DuplicatePersonReportSummary = z.object({
+  candidate_pairs: z.number().int(),
+  people_flagged: z.number().int(),
+  high: z.number().int(),
+  medium: z.number().int(),
+  low: z.number().int(),
+})
+const DuplicatePeopleResponse = z.object({
+  duplicate_people: z.array(DuplicatePersonCandidate),
+  summary: DuplicatePersonReportSummary,
+  checked_at: z.string().datetime({ offset: true }),
+})
 const DuplicatePhoneOwner = z.object({
   method_id: z.string(),
   owner_kind: z.string(),
@@ -3599,7 +3650,7 @@ export const schemas = {
   CompanyUpdateResponse,
   PatchedCompanyUpdateRequest,
   CompanyNameOnly,
-  MethodTypeEnum,
+  ContactMethodMethodTypeEnum,
   ContactMethodSourceEnum,
   ContactMethod,
   PaginatedContactMethodList,
@@ -3653,6 +3704,16 @@ export const schemas = {
   ArchivedJobIssue,
   ComplianceSummary,
   ArchivedJobsComplianceResponse,
+  ConfidenceEnum,
+  DuplicatePersonMatchKindEnum,
+  DuplicatePersonMatch,
+  DuplicatePersonCompanyLink,
+  DuplicatePersonContactMethodMethodTypeEnum,
+  DuplicatePersonContactMethod,
+  DuplicatePersonSummary,
+  DuplicatePersonCandidate,
+  DuplicatePersonReportSummary,
+  DuplicatePeopleResponse,
   DuplicatePhoneOwner,
   DuplicatePhoneIssue,
   DuplicatePhoneSummary,
@@ -6144,6 +6205,20 @@ POST /job/rest/cost_lines/&lt;cost_line_id&gt;/approve`,
       },
     ],
   },
+  {
+    method: 'get',
+    path: '/api/job/data-quality/duplicate-people/',
+    alias: 'check_duplicate_people',
+    description: `List pairs of distinct Person rows sharing exact normalized name, email, or person-owned phone signals.`,
+    requestFormat: 'json',
+    response: DuplicatePeopleResponse,
+    errors: [
+      {
+        status: 500,
+        schema: z.object({}).partial().passthrough(),
+      },
+    ],
+  },
   {
     method: 'get',
     path: '/api/job/data-quality/duplicate-phones/',
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
index 49a425a73..5880efd5e 100644
--- a/frontend/src/composables/__tests__/usePersonManagement.test.ts
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -31,7 +31,6 @@ const buildPerson = (overrides: Partial<CompanyPersonLink> = {}): CompanyPersonL
   person: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0003',
   person_name: 'Jane Doe',
   person_email: 'jane@example.com',
-  xero_name: 'Jane Doe',
   position: null,
   is_primary: true,
   notes: null,
diff --git a/frontend/src/stores/__tests__/companyStore.test.ts b/frontend/src/stores/__tests__/companyStore.test.ts
index dc2487749..eb45e2a3e 100644
--- a/frontend/src/stores/__tests__/companyStore.test.ts
+++ b/frontend/src/stores/__tests__/companyStore.test.ts
@@ -27,7 +27,6 @@ describe('company store people links', () => {
         person: 'person-1',
         person_name: 'Jane Doe',
         person_email: 'jane@example.com',
-        xero_name: 'Jane Doe',
         position: null,
         is_primary: true,
         notes: null,
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index 5750b6c5b..0d212b9ef 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -3736,7 +3736,6 @@ apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type an
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: note: Use "-> None" if function does not return a value
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_raw_json" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
@@ -3745,7 +3744,6 @@ apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type an
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]
-apps/workflow/tests/test_sync_clients.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "_make_xero_contact" in typed context  [no-untyped-call]
 apps/workflow/tests/test_sync_clients.py:0: error: Module "apps.workflow.api.xero.sync" does not explicitly export attribute "sync_companies"  [attr-defined]
 apps/workflow/tests/test_sync_clients.py:0: error: Call to untyped function "sync_companies" in typed context  [no-untyped-call]

From c6c84a895075f76310eddc9cfc8d2fd2dc0af3f8 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Mon, 13 Jul 2026 20:50:41 +1200
Subject: [PATCH 21/73] feat: deduplicate company and person identities

---
 .../commands/cleanup_duplicate_identities.py  | 179 ++++
 .../commands/cleanup_duplicate_people.py      | 220 -----
 .../0008_apply_reviewed_duplicate_cleanup.py  |  22 +
 apps/company/services/__init__.py             |  36 +-
 .../company/services/company_merge_service.py |  79 +-
 .../services/duplicate_identity_report.py     | 919 ++++++++++++++++++
 .../services/duplicate_person_report.py       |  73 +-
 .../services/kan278_duplicate_cleanup.py      | 561 +++++++++++
 ...st_cleanup_duplicate_identities_command.py |  35 +
 .../test_cleanup_duplicate_people_command.py  |  55 --
 .../tests/test_company_merge_service.py       |  62 +-
 .../tests/test_duplicate_identity_report.py   |  89 ++
 .../tests/test_duplicate_person_report.py     |  36 +-
 .../tests/test_kan278_duplicate_cleanup.py    | 105 ++
 apps/job/serializers/__init__.py              |  20 +-
 .../data_quality_report_serializers.py        |  82 +-
 ...w.py => test_duplicate_identities_view.py} |  25 +-
 apps/job/urls_rest.py                         |   8 +-
 apps/job/views/__init__.py                    |   4 +-
 apps/job/views/data_quality_report_views.py   |  24 +-
 docs/urls/job.md                              |   2 +-
 frontend/router-auto-options.ts               |   1 +
 frontend/schema.yml                           | 247 +++--
 frontend/src/api/generated/api.ts             |  95 +-
 frontend/src/components/AppNavbar.vue         |  16 +
 .../data-quality/IdentityGroupCard.vue        | 198 ++++
 .../components/data-quality/SummaryCard.vue   |  25 +
 .../__tests__/duplicate-identities.test.ts    | 201 ++++
 .../data-quality/duplicate-identities.vue     | 234 +++++
 frontend/src/typed-router.d.ts                |  13 +
 poetry.lock                                   |  14 +-
 pyproject.toml                                |   1 +
 requirements.txt                              |   1 +
 33 files changed, 3228 insertions(+), 454 deletions(-)
 create mode 100644 apps/company/management/commands/cleanup_duplicate_identities.py
 delete mode 100644 apps/company/management/commands/cleanup_duplicate_people.py
 create mode 100644 apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
 create mode 100644 apps/company/services/duplicate_identity_report.py
 create mode 100644 apps/company/services/kan278_duplicate_cleanup.py
 create mode 100644 apps/company/tests/test_cleanup_duplicate_identities_command.py
 delete mode 100644 apps/company/tests/test_cleanup_duplicate_people_command.py
 create mode 100644 apps/company/tests/test_duplicate_identity_report.py
 create mode 100644 apps/company/tests/test_kan278_duplicate_cleanup.py
 rename apps/job/tests/{test_duplicate_people_view.py => test_duplicate_identities_view.py} (50%)
 create mode 100644 frontend/src/components/data-quality/IdentityGroupCard.vue
 create mode 100644 frontend/src/components/data-quality/SummaryCard.vue
 create mode 100644 frontend/src/pages/reports/data-quality/__tests__/duplicate-identities.test.ts
 create mode 100644 frontend/src/pages/reports/data-quality/duplicate-identities.vue

diff --git a/apps/company/management/commands/cleanup_duplicate_identities.py b/apps/company/management/commands/cleanup_duplicate_identities.py
new file mode 100644
index 000000000..c0ff2d7b4
--- /dev/null
+++ b/apps/company/management/commands/cleanup_duplicate_identities.py
@@ -0,0 +1,179 @@
+"""Preview and apply grouped Company and Person duplicate decisions."""
+
+import csv
+from pathlib import Path
+from typing import Any, Literal
+from uuid import UUID
+
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+
+from apps.accounts.models import Staff
+from apps.company.services.company_merge_service import merge_companies
+from apps.company.services.duplicate_identity_report import (
+    DuplicateCompanyGroup,
+    DuplicateIdentityReportService,
+    DuplicatePersonGroup,
+)
+from apps.company.services.person_merge_service import merge_people
+
+EntityKind = Literal["company", "person"]
+CSV_COLUMNS = [
+    "entity_kind",
+    "action",
+    "group_id",
+    "fingerprint",
+    "recommendation",
+    "canonical_id",
+    "members",
+    "reason_codes",
+    "evidence",
+]
+
+
+class Command(BaseCommand):
+    help = "Preview duplicate identity groups or apply a reviewed merge CSV"
+
+    def add_arguments(self, parser: Any) -> None:
+        modes = parser.add_mutually_exclusive_group(required=True)
+        modes.add_argument("--preview", type=str, help="Write grouped candidate CSV")
+        modes.add_argument("--apply", type=str, help="Apply reviewed grouped CSV")
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        preview_path = options["preview"]
+        apply_path = options["apply"]
+        if preview_path is not None:
+            self._preview(Path(preview_path))
+        elif apply_path is not None:
+            self._apply(Path(apply_path))
+        else:
+            raise CommandError("Specify --preview or --apply")
+
+    def _preview(self, path: Path) -> None:
+        if not path.parent.exists():
+            raise CommandError(f"Output directory does not exist: {path.parent}")
+        report = DuplicateIdentityReportService().get_report()
+        rows = [self._company_row(group) for group in report["company_groups"]] + [
+            self._person_row(group) for group in report["person_groups"]
+        ]
+        with path.open("w", newline="", encoding="utf-8") as output:
+            writer = csv.DictWriter(output, fieldnames=CSV_COLUMNS)
+            writer.writeheader()
+            writer.writerows(rows)
+        self.stdout.write(
+            self.style.SUCCESS(f"Wrote {len(rows)} duplicate identity groups to {path}")
+        )
+
+    @staticmethod
+    def _company_row(group: DuplicateCompanyGroup) -> dict[str, str]:
+        return {
+            "entity_kind": "company",
+            "action": "merge" if group["recommendation"] == "merge" else "",
+            "group_id": group["group_id"],
+            "fingerprint": group["fingerprint"],
+            "recommendation": group["recommendation"],
+            "canonical_id": group["canonical_id"] or "",
+            "members": "; ".join(
+                f"{member['company_id']}={member['name']}"
+                for member in group["members"]
+            ),
+            "reason_codes": ";".join(group["reason_codes"]),
+            "evidence": "; ".join(
+                f"{item['kind']}={item['normalized_value']}"
+                for item in group["evidence"]
+            ),
+        }
+
+    @staticmethod
+    def _person_row(group: DuplicatePersonGroup) -> dict[str, str]:
+        return {
+            "entity_kind": "person",
+            "action": "merge" if group["recommendation"] == "merge" else "",
+            "group_id": group["group_id"],
+            "fingerprint": group["fingerprint"],
+            "recommendation": group["recommendation"],
+            "canonical_id": group["canonical_id"] or "",
+            "members": "; ".join(
+                f"{member['person_id']}={member['name']}" for member in group["members"]
+            ),
+            "reason_codes": ";".join(group["reason_codes"]),
+            "evidence": "; ".join(
+                f"{item['kind']}={item['normalized_value']}"
+                for item in group["evidence"]
+            ),
+        }
+
+    def _apply(self, path: Path) -> None:
+        if not path.is_file():
+            raise CommandError(f"CSV file not found: {path}")
+        with path.open(newline="", encoding="utf-8") as input_file:
+            reader = csv.DictReader(input_file)
+            if reader.fieldnames != CSV_COLUMNS:
+                raise CommandError("CSV columns do not match the preview contract")
+            selected = [row for row in reader if row["action"].strip() == "merge"]
+        if not selected:
+            raise CommandError("CSV contains no rows with action=merge")
+
+        report = DuplicateIdentityReportService().get_report()
+        current_companies = {
+            ("company", group["group_id"]): group for group in report["company_groups"]
+        }
+        current_people = {
+            ("person", group["group_id"]): group for group in report["person_groups"]
+        }
+        decisions: list[tuple[EntityKind, UUID, list[UUID]]] = []
+        for row_number, row in enumerate(selected, 2):
+            entity_kind = row["entity_kind"]
+            canonical_id = self._uuid(row["canonical_id"], row_number)
+            if entity_kind == "company":
+                company_group = current_companies.get(("company", row["group_id"]))
+                if (
+                    company_group is None
+                    or company_group["fingerprint"] != row["fingerprint"]
+                ):
+                    raise CommandError(
+                        f"Row {row_number}: group is stale or no longer exists"
+                    )
+                member_ids = [
+                    UUID(member["company_id"]) for member in company_group["members"]
+                ]
+                decision_kind: EntityKind = "company"
+            elif entity_kind == "person":
+                person_group = current_people.get(("person", row["group_id"]))
+                if (
+                    person_group is None
+                    or person_group["fingerprint"] != row["fingerprint"]
+                ):
+                    raise CommandError(
+                        f"Row {row_number}: group is stale or no longer exists"
+                    )
+                member_ids = [
+                    UUID(member["person_id"]) for member in person_group["members"]
+                ]
+                decision_kind = "person"
+            else:
+                raise CommandError(f"Row {row_number}: invalid entity_kind")
+            if canonical_id not in member_ids:
+                raise CommandError(f"Row {row_number}: canonical_id is not a member")
+            decisions.append((decision_kind, canonical_id, member_ids))
+
+        staff = Staff.get_automation_user()
+        merge_count = 0
+        with transaction.atomic():
+            for entity_kind, canonical_id, member_ids in decisions:
+                for source_id in member_ids:
+                    if source_id == canonical_id:
+                        continue
+                    if entity_kind == "company":
+                        merge_companies(source_id, canonical_id, staff)
+                    else:
+                        merge_people(source_id, canonical_id, staff)
+                    merge_count += 1
+        self.stdout.write(self.style.SUCCESS(f"Applied {merge_count} identity merges"))
+
+    @staticmethod
+    def _uuid(raw_value: str, row_number: int) -> UUID:
+        try:
+            return UUID(raw_value)
+        except ValueError as exc:
+            raise CommandError(f"Row {row_number}: invalid canonical_id") from exc
diff --git a/apps/company/management/commands/cleanup_duplicate_people.py b/apps/company/management/commands/cleanup_duplicate_people.py
deleted file mode 100644
index f513f7d95..000000000
--- a/apps/company/management/commands/cleanup_duplicate_people.py
+++ /dev/null
@@ -1,220 +0,0 @@
-"""Preview and apply reviewed duplicate-Person merges."""
-
-import csv
-from pathlib import Path
-from typing import Any
-from uuid import UUID
-
-from django.core.management.base import BaseCommand, CommandError
-from django.db import transaction
-from django.utils.dateparse import parse_datetime
-
-from apps.accounts.models import Staff
-from apps.company.models import Person
-from apps.company.services.duplicate_person_report import (
-    DuplicatePersonCandidate,
-    DuplicatePersonReportService,
-    DuplicatePersonSummary,
-)
-from apps.company.services.person_merge_service import merge_people
-
-CSV_COLUMNS = [
-    "action",
-    "confidence",
-    "match_kinds",
-    "match_values",
-    "source_person_id",
-    "source_name",
-    "source_email",
-    "source_companies",
-    "source_jobs",
-    "source_calls",
-    "source_updated_at",
-    "destination_person_id",
-    "destination_name",
-    "destination_email",
-    "destination_companies",
-    "destination_jobs",
-    "destination_calls",
-    "destination_updated_at",
-]
-
-
-def _recommended_people(
-    candidate: DuplicatePersonCandidate,
-) -> tuple[DuplicatePersonSummary, DuplicatePersonSummary]:
-    people = [candidate["first_person"], candidate["second_person"]]
-    people.sort(
-        key=lambda person: (
-            not person["is_active"],
-            -(person["job_count"] + person["phone_call_count"]),
-            -(len(person["company_links"]) + len(person["contact_methods"])),
-            person["created_at"],
-            person["person_id"],
-        )
-    )
-    destination = people[0]
-    source = people[1]
-    return source, destination
-
-
-class Command(BaseCommand):
-    help = "Preview duplicate Person candidates or apply a reviewed merge CSV"
-
-    def add_arguments(self, parser: Any) -> None:
-        modes = parser.add_mutually_exclusive_group(required=True)
-        modes.add_argument("--preview", type=str, help="Write candidate CSV")
-        modes.add_argument("--apply", type=str, help="Apply reviewed candidate CSV")
-
-    def handle(self, *args: Any, **options: Any) -> None:
-        preview_path = options["preview"]
-        apply_path = options["apply"]
-        if preview_path is not None:
-            self._preview(Path(preview_path))
-        elif apply_path is not None:
-            self._apply(Path(apply_path))
-        else:
-            raise CommandError("Specify --preview or --apply")
-
-    def _preview(self, path: Path) -> None:
-        if not path.parent.exists():
-            raise CommandError(f"Output directory does not exist: {path.parent}")
-        report = DuplicatePersonReportService().get_report()
-        candidates = report["duplicate_people"]
-        candidate_degrees: dict[str, int] = {}
-        for candidate in candidates:
-            for person in (candidate["first_person"], candidate["second_person"]):
-                person_id = person["person_id"]
-                candidate_degrees[person_id] = candidate_degrees.get(person_id, 0) + 1
-
-        with path.open("w", newline="", encoding="utf-8") as output:
-            writer = csv.DictWriter(output, fieldnames=CSV_COLUMNS)
-            writer.writeheader()
-            for candidate in candidates:
-                source, destination = _recommended_people(candidate)
-                isolated_high = (
-                    candidate["confidence"] == "high"
-                    and candidate_degrees[source["person_id"]] == 1
-                    and candidate_degrees[destination["person_id"]] == 1
-                )
-                writer.writerow(
-                    {
-                        "action": "merge" if isolated_high else "",
-                        "confidence": candidate["confidence"],
-                        "match_kinds": ";".join(
-                            sorted({match["kind"] for match in candidate["matches"]})
-                        ),
-                        "match_values": ";".join(
-                            f"{match['kind']}={match['normalized_value']}"
-                            for match in candidate["matches"]
-                        ),
-                        **self._person_columns("source", source),
-                        **self._person_columns("destination", destination),
-                    }
-                )
-        self.stdout.write(
-            self.style.SUCCESS(
-                f"Wrote {len(candidates)} duplicate-Person candidates to {path}"
-            )
-        )
-
-    @staticmethod
-    def _person_columns(prefix: str, person: DuplicatePersonSummary) -> dict[str, Any]:
-        return {
-            f"{prefix}_person_id": person["person_id"],
-            f"{prefix}_name": person["name"],
-            f"{prefix}_email": person["email"] or "",
-            f"{prefix}_companies": ";".join(
-                link["company_name"] for link in person["company_links"]
-            ),
-            f"{prefix}_jobs": person["job_count"],
-            f"{prefix}_calls": person["phone_call_count"],
-            f"{prefix}_updated_at": person["updated_at"].isoformat(),
-        }
-
-    def _apply(self, path: Path) -> None:
-        if not path.is_file():
-            raise CommandError(f"CSV file not found: {path}")
-        with path.open(newline="", encoding="utf-8") as input_file:
-            reader = csv.DictReader(input_file)
-            if reader.fieldnames != CSV_COLUMNS:
-                raise CommandError("CSV columns do not match the preview contract")
-            selected_rows = [row for row in reader if row["action"].strip() == "merge"]
-        if not selected_rows:
-            raise CommandError("CSV contains no rows with action=merge")
-
-        report = DuplicatePersonReportService().get_report()
-        current_pairs = {
-            frozenset(
-                [
-                    candidate["first_person"]["person_id"],
-                    candidate["second_person"]["person_id"],
-                ]
-            )
-            for candidate in report["duplicate_people"]
-        }
-        merges: list[tuple[UUID, UUID]] = []
-        source_ids: set[UUID] = set()
-        destination_ids: set[UUID] = set()
-        for row_number, row in enumerate(selected_rows, 2):
-            source_id = self._uuid(row, "source_person_id", row_number)
-            destination_id = self._uuid(row, "destination_person_id", row_number)
-            if source_id == destination_id:
-                raise CommandError(f"Row {row_number}: source equals destination")
-            if source_id in source_ids:
-                raise CommandError(f"Row {row_number}: source appears more than once")
-            source_ids.add(source_id)
-            destination_ids.add(destination_id)
-            if frozenset([str(source_id), str(destination_id)]) not in current_pairs:
-                raise CommandError(
-                    f"Row {row_number}: pair is no longer a duplicate candidate"
-                )
-            self._validate_timestamp(
-                source_id, row["source_updated_at"], "source", row_number
-            )
-            self._validate_timestamp(
-                destination_id,
-                row["destination_updated_at"],
-                "destination",
-                row_number,
-            )
-            merges.append((source_id, destination_id))
-        chained_ids = source_ids & destination_ids
-        if chained_ids:
-            raise CommandError(
-                "A Person cannot be both source and destination in one batch: "
-                + ", ".join(
-                    str(person_id) for person_id in sorted(chained_ids, key=str)
-                )
-            )
-
-        staff = Staff.get_automation_user()
-        with transaction.atomic():
-            for source_id, destination_id in merges:
-                counts = merge_people(source_id, destination_id, staff)
-                self.stdout.write(f"Merged {source_id} -> {destination_id}: {counts}")
-        self.stdout.write(self.style.SUCCESS(f"Applied {len(merges)} Person merges"))
-
-    @staticmethod
-    def _uuid(row: dict[str, str], column: str, row_number: int) -> UUID:
-        try:
-            return UUID(row[column])
-        except (KeyError, ValueError) as exc:
-            raise CommandError(f"Row {row_number}: invalid {column}") from exc
-
-    @staticmethod
-    def _validate_timestamp(
-        person_id: UUID, raw_timestamp: str, role: str, row_number: int
-    ) -> None:
-        expected = parse_datetime(raw_timestamp)
-        if expected is None:
-            raise CommandError(f"Row {row_number}: invalid {role}_updated_at")
-        actual = (
-            Person.objects.filter(id=person_id)
-            .values_list("updated_at", flat=True)
-            .first()
-        )
-        if actual is None:
-            raise CommandError(f"Row {row_number}: {role} Person does not exist")
-        if actual != expected:
-            raise CommandError(f"Row {row_number}: {role} Person changed after preview")
diff --git a/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
new file mode 100644
index 000000000..0e1cccc36
--- /dev/null
+++ b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
@@ -0,0 +1,22 @@
+from django.db import migrations
+
+
+def apply_reviewed_cleanup(apps, schema_editor) -> None:
+    # This installation-specific cleanup intentionally uses the tested merge
+    # services so JobEvents and every cross-app Company FK remain consistent.
+    from apps.company.services.kan278_duplicate_cleanup import (
+        apply_reviewed_duplicate_cleanup,
+    )
+
+    apply_reviewed_duplicate_cleanup()
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("company", "0007_remove_xero_person_identity"),
+    ]
+
+    operations = [
+        migrations.RunPython(apply_reviewed_cleanup, migrations.RunPython.noop),
+    ]
diff --git a/apps/company/services/__init__.py b/apps/company/services/__init__.py
index d45f7d263..ed1efedeb 100644
--- a/apps/company/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -5,8 +5,25 @@
     from django.apps import apps
 
     if apps.ready:
-        from .company_merge_service import reassign_company_fk_records
+        from .company_merge_service import (
+            CompanyMergeCounts,
+            merge_companies,
+            reassign_company_fk_records,
+        )
         from .company_rest_service import CompanyPhoneAnnotations, CompanyRestService
+        from .duplicate_identity_report import (
+            DuplicateCompanyGroup,
+            DuplicateCompanyMember,
+            DuplicateIdentityEvidence,
+            DuplicateIdentityReport,
+            DuplicateIdentityReportService,
+            DuplicateIdentityReportSummary,
+            DuplicatePersonGroup,
+            DuplicatePersonMember,
+            normalize_company_address,
+            normalize_company_name,
+            person_names_strongly_compatible,
+        )
         from .duplicate_person_report import (
             DuplicatePersonCandidate,
             DuplicatePersonCompanyLink,
@@ -18,6 +35,7 @@
             DuplicatePersonSummary,
             normalize_person_email,
             normalize_person_name,
+            person_names_compatible,
         )
         from .duplicate_phone_report import (
             DuplicatePhoneIssue,
@@ -33,18 +51,28 @@
             geocode_address,
             get_api_key,
         )
+        from .kan278_duplicate_cleanup import apply_reviewed_duplicate_cleanup
         from .person_merge_service import PersonMergeCounts, merge_people
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
     pass
 
 __all__ = [
+    "CompanyMergeCounts",
     "CompanyPhoneAnnotations",
     "CompanyRestService",
+    "DuplicateCompanyGroup",
+    "DuplicateCompanyMember",
+    "DuplicateIdentityEvidence",
+    "DuplicateIdentityReport",
+    "DuplicateIdentityReportService",
+    "DuplicateIdentityReportSummary",
     "DuplicatePersonCandidate",
     "DuplicatePersonCompanyLink",
     "DuplicatePersonContactMethod",
+    "DuplicatePersonGroup",
     "DuplicatePersonMatch",
+    "DuplicatePersonMember",
     "DuplicatePersonReport",
     "DuplicatePersonReportService",
     "DuplicatePersonReportSummary",
@@ -58,10 +86,16 @@
     "GeocodingNotConfiguredError",
     "GeocodingResult",
     "PersonMergeCounts",
+    "apply_reviewed_duplicate_cleanup",
     "geocode_address",
     "get_api_key",
+    "merge_companies",
     "merge_people",
+    "normalize_company_address",
+    "normalize_company_name",
     "normalize_person_email",
     "normalize_person_name",
+    "person_names_compatible",
+    "person_names_strongly_compatible",
     "reassign_company_fk_records",
 ]
diff --git a/apps/company/services/company_merge_service.py b/apps/company/services/company_merge_service.py
index 3e75897f2..47835f47f 100644
--- a/apps/company/services/company_merge_service.py
+++ b/apps/company/services/company_merge_service.py
@@ -13,16 +13,34 @@
 """
 
 import logging
+from typing import TypedDict
+from uuid import UUID
 
 from django.db import transaction
 from django.utils import timezone
 
+from apps.accounts.models import Staff
 from apps.company.models import Company, CompanyPersonLink, ContactMethod
 from apps.workflow.services.error_persistence import persist_app_error
 
 logger = logging.getLogger("xero")
 
 
+class CompanyMergeCounts(TypedDict):
+    jobs: int
+    contacts: int
+    contact_methods: int
+    phone_calls: int
+    invoices: int
+    bills: int
+    credit_notes: int
+    quotes: int
+    purchase_orders: int
+    supplier_products: int
+    supplier_price_lists: int
+    scrape_jobs: int
+
+
 def _move_company_contact_methods(source: Company, destination: Company) -> int:
     """Move only company-owned methods during a company merge."""
 
@@ -118,10 +136,10 @@ def _move_company_contacts_and_methods(
 def reassign_company_fk_records(
     source: Company,
     destination: Company,
-    staff,
+    staff: Staff,
     *,
     logger_prefix: str = "",
-) -> dict[str, int]:
+) -> CompanyMergeCounts:
     """
     Move every company-referencing FK record from ``source`` to ``destination``.
 
@@ -160,7 +178,7 @@ def reassign_company_fk_records(
                 jobs_moved += 1
 
             crm_counts = _move_company_contacts_and_methods(source, destination)
-            counts = {
+            counts: CompanyMergeCounts = {
                 "jobs": jobs_moved,
                 "contacts": crm_counts["contacts"],
                 "contact_methods": crm_counts["contact_methods"],
@@ -217,3 +235,58 @@ def reassign_company_fk_records(
     except Exception as exc:
         persist_app_error(exc)
         raise
+
+
+def merge_companies(
+    source_id: UUID,
+    destination_id: UUID,
+    staff: Staff,
+) -> CompanyMergeCounts:
+    """Merge a Company while retaining its Xero-linked tombstone row."""
+    if source_id == destination_id:
+        raise ValueError("Source and destination Company must be different")
+
+    with transaction.atomic():
+        companies = {
+            company.id: company
+            for company in Company.objects.select_for_update()
+            .filter(id__in=[source_id, destination_id])
+            .order_by("id")
+        }
+        source = companies.get(source_id)
+        if source is None:
+            raise ValueError(f"Source Company {source_id} does not exist")
+        destination = companies.get(destination_id)
+        if destination is None:
+            raise ValueError(f"Destination Company {destination_id} does not exist")
+        if destination.merged_into_id is not None:
+            raise ValueError(f"Destination Company {destination_id} is already merged")
+        if source.merged_into_id not in (None, destination_id):
+            raise ValueError(
+                f"Source Company {source_id} is already merged into "
+                f"{source.merged_into_id}"
+            )
+
+        destination.is_account_customer = (
+            destination.is_account_customer or source.is_account_customer
+        )
+        destination.is_supplier = destination.is_supplier or source.is_supplier
+        destination.allow_jobs = destination.allow_jobs or source.allow_jobs
+        if not destination.email and source.email:
+            destination.email = source.email
+        if not destination.address and source.address:
+            destination.address = source.address
+        destination.save(
+            update_fields=[
+                "is_account_customer",
+                "is_supplier",
+                "allow_jobs",
+                "email",
+                "address",
+            ]
+        )
+
+        source.merged_into = destination
+        source.allow_jobs = False
+        source.save(update_fields=["merged_into", "allow_jobs"])
+        return reassign_company_fk_records(source, destination, staff)
diff --git a/apps/company/services/duplicate_identity_report.py b/apps/company/services/duplicate_identity_report.py
new file mode 100644
index 000000000..bb8d99cb6
--- /dev/null
+++ b/apps/company/services/duplicate_identity_report.py
@@ -0,0 +1,919 @@
+"""Group duplicate Company and Person records by corroborated identity evidence."""
+
+import re
+import unicodedata
+from collections import defaultdict
+from collections.abc import Iterable
+from datetime import datetime
+from hashlib import sha256
+from typing import Literal, TypedDict
+from uuid import UUID
+
+from django.db import models
+from django.utils import timezone
+from rapidfuzz import fuzz
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services.duplicate_person_report import (
+    DuplicatePersonSummary,
+    normalize_person_email,
+    normalize_person_name,
+    person_names_compatible,
+)
+
+EntityKind = Literal["company", "person"]
+Recommendation = Literal["merge", "review"]
+EvidenceKind = Literal[
+    "name",
+    "email",
+    "email_domain",
+    "phone",
+    "address",
+    "shared_person",
+]
+Pair = tuple[UUID, UUID]
+
+MAX_RARE_OWNERS = 3
+MAX_AUTO_GROUP_SIZE = 5
+COMPANY_NAME_SIMILARITY = 90
+PERSON_NAME_SIMILARITY = 85
+
+PUBLIC_EMAIL_DOMAINS = frozenset(
+    {
+        "gmail.com",
+        "hotmail.com",
+        "icloud.com",
+        "outlook.com",
+        "xtra.co.nz",
+        "yahoo.co.nz",
+        "yahoo.com",
+    }
+)
+GENERIC_EMAIL_LOCAL_PARTS = frozenset(
+    {
+        "accounts",
+        "admin",
+        "contact",
+        "enquiries",
+        "enquiry",
+        "info",
+        "office",
+        "reception",
+        "sales",
+    }
+)
+COMPANY_NAME_NOISE = frozenset(
+    {
+        "co",
+        "company",
+        "inc",
+        "incorporated",
+        "limited",
+        "ltd",
+        "llc",
+        "new",
+        "nz",
+        "zealand",
+    }
+)
+
+
+class DuplicateIdentityEvidence(TypedDict):
+    kind: EvidenceKind
+    normalized_value: str
+    owner_count: int
+
+
+class DuplicateCompanyMember(TypedDict):
+    company_id: str
+    name: str
+    email: str | None
+    address: str | None
+    allow_jobs: bool
+    is_account_customer: bool
+    is_supplier: bool
+    xero_archived: bool
+    job_count: int
+    contact_names: list[str]
+
+
+class DuplicatePersonMember(DuplicatePersonSummary):
+    pass
+
+
+class DuplicateCompanyGroup(TypedDict):
+    group_id: str
+    fingerprint: str
+    recommendation: Recommendation
+    reason_codes: list[str]
+    canonical_id: str | None
+    members: list[DuplicateCompanyMember]
+    evidence: list[DuplicateIdentityEvidence]
+
+
+class DuplicatePersonGroup(TypedDict):
+    group_id: str
+    fingerprint: str
+    recommendation: Recommendation
+    reason_codes: list[str]
+    canonical_id: str | None
+    members: list[DuplicatePersonMember]
+    evidence: list[DuplicateIdentityEvidence]
+
+
+class DuplicateIdentityReportSummary(TypedDict):
+    company_merge_groups: int
+    company_review_groups: int
+    person_merge_groups: int
+    person_review_groups: int
+
+
+class DuplicateIdentityReport(TypedDict):
+    company_groups: list[DuplicateCompanyGroup]
+    person_groups: list[DuplicatePersonGroup]
+    summary: DuplicateIdentityReportSummary
+    checked_at: datetime
+
+
+def _ordered_pair(first_id: UUID, second_id: UUID) -> Pair:
+    if str(first_id) < str(second_id):
+        return first_id, second_id
+    return second_id, first_id
+
+
+def _normalise_text(value: str | None) -> str:
+    folded = unicodedata.normalize("NFKC", value or "").casefold()
+    return " ".join(re.sub(r"[^\w]+", " ", folded).split())
+
+
+def normalize_company_name(value: str) -> str:
+    """Remove presentation/legal noise while retaining the business identity."""
+    normalized = _normalise_text(value.replace("&", " and ").replace("+", " plus "))
+    normalized = re.sub(r"^cash\s+sale\s+", "", normalized)
+    tokens = normalized.split()
+    while tokens and tokens[-1] in COMPANY_NAME_NOISE:
+        tokens.pop()
+    return " ".join(tokens)
+
+
+def normalize_company_address(value: str | None) -> str:
+    """Return only sufficiently specific addresses as identity evidence."""
+    normalized = _normalise_text(value)
+    if not re.search(r"\d", normalized):
+        return ""
+    if len(normalized.split()) < 3:
+        return ""
+    return normalized
+
+
+def _email_domain(value: str | None) -> str:
+    normalized = normalize_person_email(value)
+    if "@" not in normalized:
+        return ""
+    domain = normalized.rsplit("@", 1)[1]
+    if domain in PUBLIC_EMAIL_DOMAINS:
+        return ""
+    return domain
+
+
+def _generic_email(value: str) -> bool:
+    if "@" not in value:
+        return True
+    return value.split("@", 1)[0] in GENERIC_EMAIL_LOCAL_PARTS
+
+
+def person_names_strongly_compatible(first_name: str, second_name: str) -> bool:
+    """Match exact/nickname names and restrained one-token spelling variants."""
+    if person_names_compatible(first_name, second_name):
+        return True
+    first_tokens = normalize_person_name(first_name).split()
+    second_tokens = normalize_person_name(second_name).split()
+    if len(first_tokens) < 2 or len(second_tokens) < 2:
+        return False
+
+    first_given = first_tokens[0]
+    second_given = second_tokens[0]
+    first_surname = " ".join(first_tokens[1:])
+    second_surname = " ".join(second_tokens[1:])
+    given_exact = first_given == second_given
+    surname_exact = first_surname == second_surname
+    if not given_exact and not surname_exact:
+        return False
+    return (
+        fuzz.WRatio(
+            normalize_person_name(first_name),
+            normalize_person_name(second_name),
+        )
+        >= PERSON_NAME_SIMILARITY
+    )
+
+
+def _components(edges: Iterable[Pair]) -> list[set[UUID]]:
+    adjacency: dict[UUID, set[UUID]] = defaultdict(set)
+    for first_id, second_id in edges:
+        adjacency[first_id].add(second_id)
+        adjacency[second_id].add(first_id)
+    result: list[set[UUID]] = []
+    visited: set[UUID] = set()
+    for root_id in sorted(adjacency, key=str):
+        if root_id in visited:
+            continue
+        component: set[UUID] = set()
+        pending = [root_id]
+        while pending:
+            entity_id = pending.pop()
+            if entity_id in component:
+                continue
+            component.add(entity_id)
+            pending.extend(adjacency[entity_id])
+        visited.update(component)
+        result.append(component)
+    return result
+
+
+def _group_id(kind: EntityKind, member_ids: set[UUID]) -> str:
+    identity = f"{kind}:" + ":".join(sorted(str(member_id) for member_id in member_ids))
+    return sha256(identity.encode()).hexdigest()[:16]
+
+
+def _fingerprint(
+    kind: EntityKind,
+    member_ids: set[UUID],
+    evidence: list[DuplicateIdentityEvidence],
+) -> str:
+    evidence_values = [
+        f"{item['kind']}={item['normalized_value']}:{item['owner_count']}"
+        for item in evidence
+    ]
+    payload = "|".join(
+        [kind, *sorted(str(member_id) for member_id in member_ids), *evidence_values]
+    )
+    return sha256(payload.encode()).hexdigest()
+
+
+class DuplicateIdentityReportService:
+    """Detect actionable duplicate identities without emitting pairwise noise."""
+
+    def get_report(self) -> DuplicateIdentityReport:
+        companies = list(
+            Company.objects.filter(merged_into__isnull=True).order_by("id")
+        )
+        people = list(Person.objects.order_by("id"))
+        company_ids = [company.id for company in companies]
+        person_ids = [person.id for person in people]
+
+        links = list(
+            CompanyPersonLink.objects.filter(
+                company_id__in=company_ids,
+                person_id__in=person_ids,
+            ).select_related("company", "person")
+        )
+        methods = list(
+            ContactMethod.objects.filter(
+                models.Q(company_id__in=company_ids)
+                | models.Q(person_id__in=person_ids)
+            )
+        )
+
+        links_by_company: dict[UUID, list[CompanyPersonLink]] = defaultdict(list)
+        links_by_person: dict[UUID, list[CompanyPersonLink]] = defaultdict(list)
+        for link in links:
+            links_by_company[link.company_id].append(link)
+            links_by_person[link.person_id].append(link)
+
+        company_methods: dict[UUID, list[ContactMethod]] = defaultdict(list)
+        person_methods: dict[UUID, list[ContactMethod]] = defaultdict(list)
+        for method in methods:
+            if method.company_id is not None:
+                company_methods[method.company_id].append(method)
+            elif method.person_id is not None:
+                person_methods[method.person_id].append(method)
+            else:
+                raise RuntimeError(f"ContactMethod {method.id} has no owner")
+
+        person_pair_evidence, person_signal_owners = self._person_pair_evidence(
+            people,
+            person_methods,
+        )
+        provisional_people = self._provisional_person_edges(
+            people,
+            person_pair_evidence,
+            person_signal_owners,
+        )
+        company_pair_evidence = self._company_pair_evidence(
+            companies,
+            company_methods,
+            links_by_person,
+            provisional_people,
+        )
+        company_groups, effective_company = self._company_groups(
+            companies,
+            links_by_company,
+            company_pair_evidence,
+        )
+        person_groups = self._person_groups(
+            people,
+            links_by_person,
+            person_methods,
+            person_pair_evidence,
+            person_signal_owners,
+            effective_company,
+        )
+        return {
+            "company_groups": company_groups,
+            "person_groups": person_groups,
+            "summary": {
+                "company_merge_groups": sum(
+                    group["recommendation"] == "merge" for group in company_groups
+                ),
+                "company_review_groups": sum(
+                    group["recommendation"] == "review" for group in company_groups
+                ),
+                "person_merge_groups": sum(
+                    group["recommendation"] == "merge" for group in person_groups
+                ),
+                "person_review_groups": sum(
+                    group["recommendation"] == "review" for group in person_groups
+                ),
+            },
+            "checked_at": timezone.now(),
+        }
+
+    @staticmethod
+    def _person_pair_evidence(
+        people: list[Person],
+        methods_by_person: dict[UUID, list[ContactMethod]],
+    ) -> tuple[
+        dict[Pair, dict[EvidenceKind, set[str]]],
+        dict[tuple[EvidenceKind, str], set[UUID]],
+    ]:
+        signal_owners: dict[tuple[EvidenceKind, str], set[UUID]] = defaultdict(set)
+        for person in people:
+            name = normalize_person_name(person.name)
+            if name:
+                signal_owners[("name", name)].add(person.id)
+            email = normalize_person_email(person.email)
+            if email:
+                signal_owners[("email", email)].add(person.id)
+            for method in methods_by_person[person.id]:
+                kind: EvidenceKind
+                if method.method_type == ContactMethod.MethodType.EMAIL:
+                    kind = "email"
+                elif method.method_type == ContactMethod.MethodType.PHONE:
+                    kind = "phone"
+                else:
+                    raise ValueError(
+                        f"Unknown contact method type {method.method_type!r}"
+                    )
+                signal_owners[(kind, method.normalized_value)].add(person.id)
+
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]] = defaultdict(
+            lambda: defaultdict(set)
+        )
+        for (kind, value), owners in signal_owners.items():
+            if kind != "name" and len(owners) > MAX_RARE_OWNERS:
+                continue
+            ordered = sorted(owners, key=str)
+            for index, first_id in enumerate(ordered):
+                for second_id in ordered[index + 1 :]:
+                    pair_evidence[(first_id, second_id)][kind].add(value)
+        return pair_evidence, signal_owners
+
+    @staticmethod
+    def _provisional_person_edges(
+        people: list[Person],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+        signal_owners: dict[tuple[EvidenceKind, str], set[UUID]],
+    ) -> set[Pair]:
+        people_by_id = {person.id: person for person in people}
+        result: set[Pair] = set()
+        for pair, matches in pair_evidence.items():
+            first = people_by_id[pair[0]]
+            second = people_by_id[pair[1]]
+            compatible = person_names_strongly_compatible(first.name, second.name)
+            rare_email = any(
+                len(signal_owners[("email", value)]) <= MAX_RARE_OWNERS
+                and not _generic_email(value)
+                for value in matches.get("email", set())
+            )
+            rare_phone = any(
+                len(signal_owners[("phone", value)]) <= MAX_RARE_OWNERS
+                for value in matches.get("phone", set())
+            )
+            if compatible and (rare_email or rare_phone):
+                result.add(pair)
+        return result
+
+    @staticmethod
+    def _company_pair_evidence(
+        companies: list[Company],
+        methods_by_company: dict[UUID, list[ContactMethod]],
+        links_by_person: dict[UUID, list[CompanyPersonLink]],
+        strong_person_edges: set[Pair],
+    ) -> dict[Pair, dict[EvidenceKind, set[str]]]:
+        signal_owners: dict[tuple[EvidenceKind, str], set[UUID]] = defaultdict(set)
+        for company in companies:
+            name = normalize_company_name(company.name)
+            if name:
+                signal_owners[("name", name)].add(company.id)
+            address = normalize_company_address(company.address)
+            if address:
+                signal_owners[("address", address)].add(company.id)
+            email_values = {normalize_person_email(company.email)}
+            email_values.update(
+                method.normalized_value
+                for method in methods_by_company[company.id]
+                if method.method_type == ContactMethod.MethodType.EMAIL
+            )
+            for email in email_values - {""}:
+                signal_owners[("email", email)].add(company.id)
+                domain = _email_domain(email)
+                if domain:
+                    signal_owners[("email_domain", domain)].add(company.id)
+            for method in methods_by_company[company.id]:
+                if method.method_type == ContactMethod.MethodType.PHONE:
+                    signal_owners[("phone", method.normalized_value)].add(company.id)
+
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]] = defaultdict(
+            lambda: defaultdict(set)
+        )
+        for (kind, value), owners in signal_owners.items():
+            if kind != "name" and len(owners) > MAX_RARE_OWNERS:
+                continue
+            ordered = sorted(owners, key=str)
+            for index, first_id in enumerate(ordered):
+                for second_id in ordered[index + 1 :]:
+                    pair_evidence[(first_id, second_id)][kind].add(value)
+
+        for person_pair in strong_person_edges:
+            first_links = links_by_person[person_pair[0]]
+            second_links = links_by_person[person_pair[1]]
+            for first_link in first_links:
+                for second_link in second_links:
+                    if first_link.company_id == second_link.company_id:
+                        continue
+                    company_pair = _ordered_pair(
+                        first_link.company_id,
+                        second_link.company_id,
+                    )
+                    pair_evidence[company_pair]["shared_person"].add(
+                        f"{person_pair[0]}:{person_pair[1]}"
+                    )
+
+        return pair_evidence
+
+    def _company_groups(
+        self,
+        companies: list[Company],
+        links_by_company: dict[UUID, list[CompanyPersonLink]],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+    ) -> tuple[list[DuplicateCompanyGroup], dict[UUID, UUID]]:
+        companies_by_id = {company.id: company for company in companies}
+        auto_edges: set[Pair] = set()
+        review_edges: set[Pair] = set()
+        reasons_by_pair: dict[Pair, set[str]] = defaultdict(set)
+        for pair, matches in pair_evidence.items():
+            first = companies_by_id[pair[0]]
+            second = companies_by_id[pair[1]]
+            exact_name = bool(matches.get("name"))
+            name_similarity = fuzz.WRatio(
+                normalize_company_name(first.name),
+                normalize_company_name(second.name),
+            )
+            organisation_families = {
+                "email" if kind in {"email", "email_domain"} else kind
+                for kind in set(matches)
+                & {
+                    "email",
+                    "email_domain",
+                    "phone",
+                    "address",
+                }
+            }
+            shared_person_count = len(matches.get("shared_person", set()))
+            if exact_name:
+                reasons_by_pair[pair].add("exact_company_name")
+            if name_similarity >= COMPANY_NAME_SIMILARITY:
+                reasons_by_pair[pair].add("similar_company_name")
+            if organisation_families:
+                reasons_by_pair[pair].add("shared_organisation_identity")
+            if shared_person_count:
+                reasons_by_pair[pair].add("shared_person_identity")
+
+            strong = exact_name or (
+                name_similarity >= COMPANY_NAME_SIMILARITY
+                and bool(organisation_families or shared_person_count)
+            )
+            if strong:
+                auto_edges.add(pair)
+            elif shared_person_count or len(organisation_families) >= 2:
+                review_edges.add(pair)
+            else:
+                # A lone domain/email/phone/address is useful corroboration but
+                # not an actionable duplicate on its own. Related companies,
+                # branches, co-tenants, and shared office details are common
+                # enough that surfacing every such pair recreates the review
+                # explosion this report exists to prevent.
+                continue
+
+        auto_components = _components(auto_edges)
+        oversized_members = set().union(
+            *(
+                component
+                for component in auto_components
+                if len(component) > MAX_AUTO_GROUP_SIZE
+            ),
+            set(),
+        )
+        accepted_auto = [
+            component
+            for component in auto_components
+            if len(component) <= MAX_AUTO_GROUP_SIZE
+        ]
+        if oversized_members:
+            for pair in auto_edges:
+                if pair[0] in oversized_members or pair[1] in oversized_members:
+                    review_edges.add(pair)
+                    reasons_by_pair[pair].add("oversized_component")
+
+        effective_company: dict[UUID, UUID] = {
+            company.id: company.id for company in companies
+        }
+        for component in accepted_auto:
+            canonical = min(
+                (companies_by_id[company_id] for company_id in component),
+                key=lambda company: self._company_rank(
+                    company,
+                    links_by_company[company.id],
+                ),
+            )
+            for company_id in component:
+                effective_company[company_id] = canonical.id
+
+        review_edges = {
+            pair
+            for pair in review_edges
+            if effective_company[pair[0]] != effective_company[pair[1]]
+        }
+        review_components = _components(review_edges)
+        groups = [
+            self._company_group(
+                component,
+                "merge",
+                companies_by_id,
+                links_by_company,
+                pair_evidence,
+                reasons_by_pair,
+            )
+            for component in accepted_auto
+        ]
+        groups.extend(
+            self._company_group(
+                component,
+                "review",
+                companies_by_id,
+                links_by_company,
+                pair_evidence,
+                reasons_by_pair,
+            )
+            for component in review_components
+        )
+        groups.sort(
+            key=lambda group: (
+                group["recommendation"] != "merge",
+                group["members"][0]["name"].casefold(),
+                group["group_id"],
+            )
+        )
+        return groups, effective_company
+
+    @staticmethod
+    def _company_rank(
+        company: Company,
+        links: list[CompanyPersonLink],
+    ) -> tuple[bool, bool, bool, int, object, str]:
+        from apps.job.models import Job
+
+        return (
+            company.xero_archived,
+            not company.allow_jobs,
+            normalize_company_name(company.name) != _normalise_text(company.name),
+            -(Job.objects.filter(company=company).count() + len(links)),
+            company.django_created_at,
+            str(company.id),
+        )
+
+    def _company_group(
+        self,
+        member_ids: set[UUID],
+        recommendation: Recommendation,
+        companies_by_id: dict[UUID, Company],
+        links_by_company: dict[UUID, list[CompanyPersonLink]],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+        reasons_by_pair: dict[Pair, set[str]],
+    ) -> DuplicateCompanyGroup:
+        companies = [companies_by_id[company_id] for company_id in member_ids]
+        canonical = min(
+            companies,
+            key=lambda company: self._company_rank(
+                company,
+                links_by_company[company.id],
+            ),
+        )
+        evidence = self._evidence_for_members(member_ids, pair_evidence)
+        reason_codes = sorted(
+            {
+                reason
+                for pair, reasons in reasons_by_pair.items()
+                if set(pair) <= member_ids
+                for reason in reasons
+            }
+        )
+        if recommendation == "review" and reason_codes == ["shared_person_identity"]:
+            reason_codes = ["shared_person_only"]
+        return {
+            "group_id": _group_id("company", member_ids),
+            "fingerprint": _fingerprint("company", member_ids, evidence),
+            "recommendation": recommendation,
+            "reason_codes": reason_codes,
+            "canonical_id": str(canonical.id) if recommendation == "merge" else None,
+            "members": [
+                self._company_member(company, links_by_company[company.id])
+                for company in sorted(companies, key=lambda item: item.name.casefold())
+            ],
+            "evidence": evidence,
+        }
+
+    @staticmethod
+    def _company_member(
+        company: Company,
+        links: list[CompanyPersonLink],
+    ) -> DuplicateCompanyMember:
+        from apps.job.models import Job
+
+        return {
+            "company_id": str(company.id),
+            "name": company.name,
+            "email": company.email,
+            "address": company.address,
+            "allow_jobs": company.allow_jobs,
+            "is_account_customer": company.is_account_customer,
+            "is_supplier": company.is_supplier,
+            "xero_archived": company.xero_archived,
+            "job_count": Job.objects.filter(company=company).count(),
+            "contact_names": sorted(
+                {link.person.name for link in links},
+                key=str.casefold,
+            ),
+        }
+
+    def _person_groups(
+        self,
+        people: list[Person],
+        links_by_person: dict[UUID, list[CompanyPersonLink]],
+        methods_by_person: dict[UUID, list[ContactMethod]],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+        signal_owners: dict[tuple[EvidenceKind, str], set[UUID]],
+        effective_company: dict[UUID, UUID],
+    ) -> list[DuplicatePersonGroup]:
+        people_by_id = {person.id: person for person in people}
+        auto_edges: set[Pair] = set()
+        review_edges: set[Pair] = set()
+        reasons_by_pair: dict[Pair, set[str]] = defaultdict(set)
+        for pair, matches in pair_evidence.items():
+            first = people_by_id[pair[0]]
+            second = people_by_id[pair[1]]
+            first_companies = {
+                effective_company[link.company_id] for link in links_by_person[first.id]
+            }
+            second_companies = {
+                effective_company[link.company_id]
+                for link in links_by_person[second.id]
+            }
+            same_company = bool(first_companies & second_companies)
+            exact_name = bool(matches.get("name"))
+            compatible = person_names_strongly_compatible(first.name, second.name)
+            rare_email = any(
+                len(signal_owners[("email", value)]) <= MAX_RARE_OWNERS
+                and not _generic_email(value)
+                for value in matches.get("email", set())
+            )
+            rare_phone = any(
+                len(signal_owners[("phone", value)]) <= MAX_RARE_OWNERS
+                for value in matches.get("phone", set())
+            )
+            if same_company and exact_name:
+                auto_edges.add(pair)
+                reasons_by_pair[pair].add("same_company_exact_name")
+            elif compatible and (rare_email or rare_phone):
+                auto_edges.add(pair)
+                reasons_by_pair[pair].add("compatible_name_and_contact")
+            elif rare_email or rare_phone:
+                review_edges.add(pair)
+                reasons_by_pair[pair].add("conflicting_names_shared_contact")
+            else:
+                continue
+
+        auto_components = _components(auto_edges)
+        accepted_auto = [
+            component
+            for component in auto_components
+            if len(component) <= MAX_AUTO_GROUP_SIZE
+        ]
+        oversized = [
+            component
+            for component in auto_components
+            if len(component) > MAX_AUTO_GROUP_SIZE
+        ]
+        for component in oversized:
+            ordered = sorted(component, key=str)
+            for index, first_id in enumerate(ordered):
+                for second_id in ordered[index + 1 :]:
+                    review_edges.add((first_id, second_id))
+                    reasons_by_pair[(first_id, second_id)].add("oversized_component")
+
+        auto_owner: dict[UUID, UUID] = {}
+        for component in accepted_auto:
+            root = min(component, key=str)
+            for person_id in component:
+                auto_owner[person_id] = root
+        review_edges = {
+            pair
+            for pair in review_edges
+            if auto_owner.get(pair[0], pair[0]) != auto_owner.get(pair[1], pair[1])
+        }
+        review_components = _components(review_edges)
+        groups = [
+            self._person_group(
+                component,
+                "merge",
+                people_by_id,
+                links_by_person,
+                methods_by_person,
+                pair_evidence,
+                reasons_by_pair,
+            )
+            for component in accepted_auto
+        ]
+        groups.extend(
+            self._person_group(
+                component,
+                "review",
+                people_by_id,
+                links_by_person,
+                methods_by_person,
+                pair_evidence,
+                reasons_by_pair,
+            )
+            for component in review_components
+        )
+        groups.sort(
+            key=lambda group: (
+                group["recommendation"] != "merge",
+                group["members"][0]["name"].casefold(),
+                group["group_id"],
+            )
+        )
+        return groups
+
+    @staticmethod
+    def _person_rank(
+        person: Person,
+        links: list[CompanyPersonLink],
+        methods: list[ContactMethod],
+    ) -> tuple[bool, int, int, bool, object, str]:
+        from apps.crm.models import PhoneCallRecord
+        from apps.job.models import Job
+
+        activity = (
+            Job.objects.filter(person=person).count()
+            + PhoneCallRecord.objects.filter(person=person).count()
+        )
+        return (
+            not person.is_active,
+            -activity,
+            -(len(links) + len(methods)),
+            len(normalize_person_name(person.name).split()) < 2,
+            person.created_at,
+            str(person.id),
+        )
+
+    def _person_group(
+        self,
+        member_ids: set[UUID],
+        recommendation: Recommendation,
+        people_by_id: dict[UUID, Person],
+        links_by_person: dict[UUID, list[CompanyPersonLink]],
+        methods_by_person: dict[UUID, list[ContactMethod]],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+        reasons_by_pair: dict[Pair, set[str]],
+    ) -> DuplicatePersonGroup:
+        people = [people_by_id[person_id] for person_id in member_ids]
+        canonical = min(
+            people,
+            key=lambda person: self._person_rank(
+                person,
+                links_by_person[person.id],
+                methods_by_person[person.id],
+            ),
+        )
+        evidence = self._evidence_for_members(member_ids, pair_evidence)
+        return {
+            "group_id": _group_id("person", member_ids),
+            "fingerprint": _fingerprint("person", member_ids, evidence),
+            "recommendation": recommendation,
+            "reason_codes": sorted(
+                {
+                    reason
+                    for pair, reasons in reasons_by_pair.items()
+                    if set(pair) <= member_ids
+                    for reason in reasons
+                }
+            ),
+            "canonical_id": str(canonical.id) if recommendation == "merge" else None,
+            "members": [
+                self._person_member(
+                    person,
+                    links_by_person[person.id],
+                    methods_by_person[person.id],
+                )
+                for person in sorted(people, key=lambda item: item.name.casefold())
+            ],
+            "evidence": evidence,
+        }
+
+    @staticmethod
+    def _person_member(
+        person: Person,
+        links: list[CompanyPersonLink],
+        methods: list[ContactMethod],
+    ) -> DuplicatePersonMember:
+        from apps.crm.models import PhoneCallRecord
+        from apps.job.models import Job
+
+        return {
+            "person_id": str(person.id),
+            "name": person.name,
+            "email": person.email,
+            "is_active": person.is_active,
+            "created_at": person.created_at,
+            "updated_at": person.updated_at,
+            "company_links": [
+                {
+                    "link_id": str(link.id),
+                    "company_id": str(link.company_id),
+                    "company_name": link.company.name,
+                    "position": link.position,
+                    "is_primary": link.is_primary,
+                    "is_active": link.is_active,
+                }
+                for link in sorted(
+                    links,
+                    key=lambda item: (item.company.name.casefold(), str(item.id)),
+                )
+            ],
+            "contact_methods": [
+                {
+                    "method_id": str(method.id),
+                    "method_type": method.method_type,
+                    "value": method.value,
+                    "normalized_value": method.normalized_value,
+                    "contact_label": method.label,
+                    "is_primary": method.is_primary,
+                }
+                for method in sorted(
+                    methods,
+                    key=lambda item: (
+                        item.method_type,
+                        item.normalized_value,
+                        str(item.id),
+                    ),
+                )
+            ],
+            "job_count": Job.objects.filter(person=person).count(),
+            "phone_call_count": PhoneCallRecord.objects.filter(person=person).count(),
+        }
+
+    @staticmethod
+    def _evidence_for_members(
+        member_ids: set[UUID],
+        pair_evidence: dict[Pair, dict[EvidenceKind, set[str]]],
+    ) -> list[DuplicateIdentityEvidence]:
+        values: dict[tuple[EvidenceKind, str], set[UUID]] = defaultdict(set)
+        for pair, matches in pair_evidence.items():
+            if not set(pair) <= member_ids:
+                continue
+            for kind, normalized_values in matches.items():
+                for normalized_value in normalized_values:
+                    values[(kind, normalized_value)].update(pair)
+        return [
+            {
+                "kind": kind,
+                "normalized_value": normalized_value,
+                "owner_count": len(owners),
+            }
+            for (kind, normalized_value), owners in sorted(
+                values.items(),
+                key=lambda item: (item[0][0], item[0][1]),
+            )
+        ]
diff --git a/apps/company/services/duplicate_person_report.py b/apps/company/services/duplicate_person_report.py
index 99a773fe3..9239a61ca 100644
--- a/apps/company/services/duplicate_person_report.py
+++ b/apps/company/services/duplicate_person_report.py
@@ -1,12 +1,15 @@
 """Find distinct Person rows that share exact identity signals."""
 
+import re
 from collections import defaultdict
 from datetime import datetime
+from functools import lru_cache
 from typing import Literal, TypedDict
 from uuid import UUID
 
 from django.db.models import Count
 from django.utils import timezone
+from nicknames import name_triplets
 
 from apps.company.models import CompanyPersonLink, ContactMethod, Person
 
@@ -74,7 +77,7 @@ class DuplicatePersonReport(TypedDict):
 
 def normalize_person_name(value: str) -> str:
     """Normalize an exact-name signal without introducing fuzzy matching."""
-    return " ".join(value.split()).casefold()
+    return " ".join(re.sub(r"[^\w]+", " ", value.casefold()).split())
 
 
 def normalize_person_email(value: str | None) -> str:
@@ -82,13 +85,59 @@ def normalize_person_email(value: str | None) -> str:
 
 
 def _confidence(match_kinds: set[MatchKind]) -> Confidence:
-    if len(match_kinds) >= 2:
+    if "name" in match_kinds and match_kinds & {"email", "phone"}:
         return "high"
     if "phone" in match_kinds or "email" in match_kinds:
         return "medium"
     return "low"
 
 
+def _name_tokens(value: str) -> list[str]:
+    return normalize_person_name(value).split()
+
+
+@lru_cache(maxsize=1)
+def _alias_groups() -> dict[str, set[str]]:
+    groups: dict[str, set[str]] = defaultdict(set)
+    for triplet in name_triplets():
+        canonical = normalize_person_name(triplet.name1)
+        groups[canonical].add(canonical)
+        groups[canonical].add(normalize_person_name(triplet.name2))
+    return groups
+
+
+def person_names_compatible(
+    first_name: str,
+    second_name: str,
+    *,
+    alias_groups: dict[str, set[str]] | None = None,
+) -> bool:
+    """Return whether two names can support an exact contact-method match."""
+    first_tokens = _name_tokens(first_name)
+    second_tokens = _name_tokens(second_name)
+    if not first_tokens or not second_tokens:
+        return False
+    if first_tokens == second_tokens:
+        return True
+
+    groups = _alias_groups() if alias_groups is None else alias_groups
+    first_names_match = first_tokens[0] == second_tokens[0]
+    first_canonical = {
+        canonical for canonical, names in groups.items() if first_tokens[0] in names
+    }
+    second_canonical = {
+        canonical for canonical, names in groups.items() if second_tokens[0] in names
+    }
+    if not first_names_match and not first_canonical & second_canonical:
+        return False
+
+    first_surname = first_tokens[1:]
+    second_surname = second_tokens[1:]
+    if first_surname and second_surname:
+        return first_surname == second_surname
+    return True
+
+
 class DuplicatePersonReportService:
     """Build exact-signal candidate pairs for operator review."""
 
@@ -149,6 +198,26 @@ def get_report(self) -> DuplicatePersonReport:
                 for second_id in ordered_owners[first_index + 1 :]:
                     pair_matches[(first_id, second_id)][kind].add(normalized_value)
 
+        aliases = _alias_groups()
+        for pair, matches in pair_matches.items():
+            if "name" in matches:
+                continue
+            first_id, second_id = pair
+            if not matches.keys() & {"email", "phone"}:
+                continue
+            if person_names_compatible(
+                summaries[first_id]["name"],
+                summaries[second_id]["name"],
+                alias_groups=aliases,
+            ):
+                normalized_names = sorted(
+                    {
+                        normalize_person_name(summaries[first_id]["name"]),
+                        normalize_person_name(summaries[second_id]["name"]),
+                    }
+                )
+                matches["name"].add(" ~ ".join(normalized_names))
+
         candidates = [
             self._candidate(pair, matches, summaries)
             for pair, matches in pair_matches.items()
diff --git a/apps/company/services/kan278_duplicate_cleanup.py b/apps/company/services/kan278_duplicate_cleanup.py
new file mode 100644
index 000000000..9f24ab28b
--- /dev/null
+++ b/apps/company/services/kan278_duplicate_cleanup.py
@@ -0,0 +1,561 @@
+"""Reviewed one-time duplicate cleanup for the KAN-278 production dataset."""
+
+from collections import defaultdict
+from collections.abc import Iterable
+from uuid import UUID
+
+from apps.accounts.models import Staff
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services.company_merge_service import merge_companies
+from apps.company.services.duplicate_identity_report import (
+    DuplicateIdentityReportService,
+)
+from apps.company.services.person_merge_service import merge_people
+
+CompanyMerge = tuple[str, str]
+PersonLinkEdge = tuple[str, str]
+
+# source Company -> canonical Company. These UUIDs are stable across the
+# client->company relabel and the first-class Person migrations.
+REVIEWED_COMPANY_MERGES: tuple[CompanyMerge, ...] = (
+    (
+        "8a0a7c59-6b87-45d7-82f6-c543b74b37db",
+        "42341b19-8baf-434d-b2c9-fd0aed92a44b",
+    ),  # Northland Roofs
+    (
+        "99c01fb4-a14e-499c-bf4f-7dd1c139242b",
+        "9cca5c95-d4d1-4f7e-a781-eaea26873e06",
+    ),  # ELS NZ
+    (
+        "0aebb7a4-e7e3-443c-a329-6fa9bf4c07a7",
+        "c4fb5c65-278e-4790-9fce-acdd24a5012b",
+    ),  # Interior DB
+    (
+        "44fec154-e91e-41e8-a406-f913740c1258",
+        "94a26554-4758-4339-bfc0-f92067815d47",
+    ),  # Supercity
+    (
+        "59cd4324-98cb-4ea1-9825-dfe01bcc39d2",
+        "b52223eb-aa5d-4d94-9264-e4504baf4b38",
+    ),  # New Generation Operations
+    (
+        "8318321c-919a-440a-96ff-87e3c43e9551",
+        "b3bd1d4e-829f-47c7-a9f0-e77496835c21",
+    ),  # Timeworx
+    (
+        "039e1bc8-9068-464b-9998-a563a69fb6df",
+        "4cb5ef4e-2936-4f05-991f-cc41be8ad54d",
+    ),  # Viking Builders
+    (
+        "92e6e04e-f8e9-4fee-ac2f-5ca375468635",
+        "4d8e32e7-4e34-4e22-8169-91b9e1365579",
+    ),  # Penrose Motors
+    (
+        "d2059e47-da19-4bc1-bcc2-ead96368860b",
+        "c07dc252-d3ed-41c8-bf36-8e5d7e1da3b9",
+    ),  # Marsh Cooper
+    (
+        "6ac46b26-2d76-4cfe-ae85-f057fb98e169",
+        "15b27ab2-3b14-4eeb-bc70-a65c92a8b08a",
+    ),  # Point Maintenance
+    (
+        "c2eda802-c67f-471e-acd0-1d01e97c2162",
+        "15b27ab2-3b14-4eeb-bc70-a65c92a8b08a",
+    ),  # Point Maintenance
+    (
+        "f642cfe5-2a0d-42c1-a7de-24ff5b5ac521",
+        "0833cc79-f9a8-4537-8396-2a6b6040f9de",
+    ),  # Acryfab
+    (
+        "ae5d6422-f67d-463a-a0f9-5f6f1e9d0d99",
+        "67394ffd-13e5-4f1d-8af4-daf92d694e13",
+    ),  # AZ Panels
+    (
+        "588a8268-394c-41a4-aa39-cfcf3903f934",
+        "3fce4f6b-6211-4e18-9e26-5a64955afecf",
+    ),  # Custom Controls
+    (
+        "f29ec9b6-4c6d-46d6-937a-78f431276c1a",
+        "99568812-4f22-4f15-be24-715fb4458977",
+    ),  # Cushman & Wakefield
+    (
+        "581b0b1c-cda6-40f9-87b9-9d56b3902a6d",
+        "49bd07e9-25d1-4d33-b693-35eb2796fbdc",
+    ),  # Church St Panelbeaters
+    (
+        "1650248c-865c-463e-bef9-4374ca74b1de",
+        "1f667c71-3830-451e-96ad-90ec6f3177b2",
+    ),  # Elijah Haridas
+    (
+        "f7a53925-1099-4c8a-b55d-e25094df4bb8",
+        "0f61dc0c-c394-42d2-8d80-d4cdba9451ae",
+    ),  # Richard Pryde
+    (
+        "4bc54f5a-d7df-4e09-9898-4c6c2dd6f18a",
+        "8d35c1c1-2181-4979-8299-549a0556e48d",
+    ),  # Veronica Bartlett
+    (
+        "24ae90b5-4cf2-4958-b1de-287930733dd5",
+        "60b3f0e0-7da5-451d-9fe8-1c139f4fb826",
+    ),  # DGE
+    (
+        "82cdb03c-2590-4cd6-95d0-288aed62e7fb",
+        "245e1a32-dd55-49bd-899b-7f253774d774",
+    ),  # Rauland
+    (
+        "19744741-ad4a-49db-b52d-18ee91b6310a",
+        "d4fa0e82-8ea7-4cea-b755-0fd713f6b65e",
+    ),  # Pacific Bakery
+    (
+        "777b7d0d-2897-480c-a295-6e2e4a984f83",
+        "d4fa0e82-8ea7-4cea-b755-0fd713f6b65e",
+    ),  # Pacific Bakery
+    (
+        "3a189c4e-83f2-4364-b474-2da9403d3e19",
+        "76ec8dd0-20cf-44c0-bdb7-1bc446ce4366",
+    ),  # NZ Starch
+    (
+        "8e1baf74-a1c3-43be-b452-94d211e82401",
+        "7c2bdd26-7135-48a8-a5aa-1b8fbddbf8c5",
+    ),  # LT McGuinness
+    (
+        "511e3350-a2e2-4d9e-b971-5e02fe922dda",
+        "7050c890-8f6e-454f-be9d-d482d1f4270b",
+    ),  # IPL Maintenance
+    (
+        "226e9630-b770-4e99-93ea-9d4c3f4fa021",
+        "7317d696-5090-413b-a756-994c17b3c54e",
+    ),  # Eden Park Panel & Paint
+    (
+        "74deb0d4-5a75-4fd4-abd0-85c716abece2",
+        "75f7972e-4aa2-407a-b5bd-28304c67f6e8",
+    ),  # Garry Lawrence Roofing
+    (
+        "7abbce8d-5ff0-4fdd-8732-ca5ff258aa9e",
+        "a3fe8b47-2cca-4787-8e2d-9713f16703f8",
+    ),  # Gus Kanji
+    (
+        "eb7f98bc-06eb-47c9-99a0-b973e7fc6137",
+        "9c8adc9c-7593-4bac-bbbb-f4a5efe95c06",
+    ),  # Irving
+    (
+        "dea6f7dd-8c8f-47b4-b883-532a009ab11e",
+        "ca3f2cda-b146-4111-868a-893f6ba170ff",
+    ),  # Free Co Flooring
+    (
+        "a4b93d24-ca61-4278-8bf7-92ad4523107b",
+        "a7276a52-09d3-4143-8d7e-7f6f6e716954",
+    ),  # Jenny Stevens
+    (
+        "40e672c4-7332-4eb9-927f-813c20874d43",
+        "ada10565-b1ab-43e3-b0ac-79f2128ceea9",
+    ),  # Jerry Friar
+    (
+        "748550d5-4425-4853-b00b-b6e590e3403b",
+        "e556eab0-0621-4483-82f2-05f116597830",
+    ),  # Wakefield Metals
+    (
+        "0c82cbcc-2189-4869-8cb7-3e4168fe97b9",
+        "f3539c8f-c4eb-4730-bb9a-0e7e468be9a5",
+    ),  # High Mark Foods
+    (
+        "07063260-78ad-4e55-8aba-5854b0dc1e95",
+        "75511302-3ec3-4508-bc02-9f1eadf71fb8",
+    ),  # Jack Lum
+    (
+        "249670e0-27a2-4605-a68f-7eac229a6854",
+        "356b8de2-62be-419a-ac0b-a813c53b0244",
+    ),  # Nick Hansen
+    (
+        "34448f75-ed3e-4ba3-b948-7a2d768a1dad",
+        "cf57a6f9-53b8-4f5a-8eda-435b4d6fb81e",
+    ),  # Rem Wadeh
+    (
+        "7376ed99-6e39-44cc-af00-a785aef0f998",
+        "81475c76-3be9-4c9e-9f74-15e7d232506d",
+    ),  # Proclimb
+    (
+        "4178688e-3111-47f7-b155-e13409bb55e4",
+        "a7c282e9-da5a-46a8-900d-315a2e17557f",
+    ),  # Stephen Carr
+    (
+        "ac2b0365-3069-4c90-940b-2dd56fdbb6ac",
+        "a7c282e9-da5a-46a8-900d-315a2e17557f",
+    ),  # Stephen Carr
+    (
+        "6132ee9a-47fa-4755-93fb-28d054db2744",
+        "42d138e8-33fe-4a88-bc06-36cea6975385",
+    ),  # McAlpine Hussmann
+    (
+        "1628ea3b-72c4-4dfc-b5bd-ac5b57855cce",
+        "7ad6022b-0b09-49e4-92ee-8fa4124f86de",
+    ),  # Wolfgang
+    (
+        "f93353fb-be09-4b98-a2a1-7035017e5ba2",
+        "501c9415-1e34-444b-91a2-b722f28a6fdb",
+    ),  # Bronwyn Jackson
+    (
+        "1c95b84b-dae0-4ace-8ece-329209278264",
+        "730034a7-04f8-4c23-8c42-d8dd49408d1a",
+    ),  # Dave Booth
+    (
+        "b51bf289-cc6d-4137-87e3-0941166bd5a0",
+        "49954c00-0d80-4deb-845f-a52c69373fbe",
+    ),  # Davison Construction
+    (
+        "e747a5e0-746b-4f25-9f09-d70044f3c23f",
+        "82eb2fc3-3e80-4c92-90c5-6bfe92f4874a",
+    ),  # Mike Loomb
+    (
+        "f66dc794-fa95-442e-8475-f8667512bb81",
+        "1785e8e6-2e51-49d8-9c5d-2221359bc2d0",
+    ),  # Pete Pederson
+    (
+        "7c81c774-d986-4ee7-bab1-ca83025bee43",
+        "caed8f25-a71c-4053-878e-301cedb8179f",
+    ),  # Rick Van Swet
+    (
+        "dcdca54c-f588-4991-b3fd-a6317b3ba39b",
+        "c7332cbf-8e19-4bd6-8b72-00ecba0074b4",
+    ),  # Steve Kirby
+    (
+        "d7c2aec4-5dbb-4f84-a4a5-a7a5f5ef9843",
+        "d0868ba1-61a8-4299-ae72-5d36e5d3d6f9",
+    ),  # Lindsay Building Services
+    (
+        "161b2430-db80-4a58-a3d5-a7ffb62c887b",
+        "8ed26fa1-73fd-4c68-a63a-e6423afc3e3b",
+    ),  # PB Traffic
+    (
+        "d998e463-d3db-45d4-8a53-3fd08ab09c53",
+        "23f54e9d-bea3-4d14-bf8f-0dec2be589b8",
+    ),  # NZ Crane
+    (
+        "1a99b409-e72c-46c5-8ee9-fe7f279699ce",
+        "c7efc131-a29d-42e7-a6bd-cb00986d56d9",
+    ),  # Dunninghams
+    (
+        "3882c364-bae8-45cd-a658-85d691b6a108",
+        "e4af558d-b510-42af-b152-935cd426d4a9",
+    ),  # CGO Corporate
+    (
+        "9abdef63-da4c-4a2b-9cf0-4b7a4db91adc",
+        "6177173a-8499-45a3-8aec-03c707aa8ac5",
+    ),  # Watercone
+    (
+        "f9976610-8a0a-4ac1-8298-30c9f3f19254",
+        "b66ac775-90d5-45b3-9a0b-8d89590f59a5",
+    ),  # HTS Group
+)
+
+# Manually reviewed bridges not covered by exact/nickname name compatibility.
+# IDs are legacy contact IDs, retained as CompanyPersonLink IDs by migration 0005.
+REVIEWED_PERSON_LINK_EDGES: tuple[PersonLinkEdge, ...] = (
+    (
+        "90650519-eccd-4766-b869-c3b6e70855f6",
+        "df371ed0-43f3-43e1-af59-d5e400e01bed",
+    ),  # ?? / Michael Chee
+    (
+        "13546f44-681c-423d-9e02-abe933f5d8bb",
+        "9e50a9b9-8080-4975-a897-3aebc214ab8f",
+    ),  # Aaron / Aarron
+    (
+        "7e6cb791-a308-42ec-9156-889e62ebc52d",
+        "8d59aa42-0f30-4669-81b9-ef01753a357e",
+    ),  # Arno surname typo
+    (
+        "05816a5f-38d8-47fc-b3e5-95b3350b058e",
+        "79d8d9b2-5b1f-49a1-95ff-9c597ee6888f",
+    ),  # Aaron / Arron
+    (
+        "7e5b48fa-f9e9-46d2-847a-40b3b827f34a",
+        "bff2f883-853c-4e7e-b1f8-443a5c24bee4",
+    ),  # Bronwyn
+    (
+        "155c2987-ae6f-4175-9a37-d6ec5f9e3d3b",
+        "81f90c08-069b-41e0-9560-afbfc070b945",
+    ),  # Cushman Chris
+    (
+        "6bea2a11-081b-46c3-b3fa-a97e6569aebc",
+        "ec2907c6-f932-4b49-862c-e9f5278028cc",
+    ),  # Craig typo
+    (
+        "4663652a-11a9-4fdc-953b-713878be13a1",
+        "49b58609-8daa-414a-8654-a64bdacf2f20",
+    ),  # Cushman Nave
+    (
+        "49b58609-8daa-414a-8654-a64bdacf2f20",
+        "56172bb3-eb13-4065-8976-c2ef62a08ffe",
+    ),  # Cushman Nave job label
+    (
+        "347ad57f-21ed-405c-89f5-39dd4db6ad03",
+        "3598fc0b-da47-4090-8710-df8df78575ab",
+    ),  # Dave Yanala typo
+    (
+        "3c26bb57-3f52-435d-b075-636989e67735",
+        "ece95901-35d3-479f-bbad-76d5322dc29a",
+    ),  # Edwin typo
+    (
+        "cbe6808f-5cd5-4c8c-a741-ddc5fd435bd3",
+        "df32f23a-1acf-4ab3-bae3-19b034c84db4",
+    ),  # malformed Expac name / Rob
+    (
+        "1c25b5f3-132f-4a67-8b2b-3a9fbdf119ec",
+        "5f2f1c93-e0e3-48f6-80c1-6109105e7858",
+    ),  # Ian / Iain
+    (
+        "6d851c6e-6f1c-4966-aa7c-cbc8e495504d",
+        "f7a78661-4b9c-42b1-8f7e-39ce162d2848",
+    ),  # Joseph typo
+    (
+        "53a5c735-c00a-42bc-87b4-8cba3635aaa3",
+        "e5cc3937-ce4b-45c2-9233-17fe4b2d93cf",
+    ),  # John Laycock / Blacklock
+    (
+        "e782a08c-2e8f-4ff9-b055-3dd3df714ac3",
+        "fc30d89f-1038-4f01-9848-9172ce78b88c",
+    ),  # Lars typo
+    (
+        "268461ee-6d32-4a93-9561-d52496cd8492",
+        "99ef5e54-8cfb-45ec-ae97-7dcd6d4f37a6",
+    ),  # Lee / Jeanette malformed name
+    (
+        "6950a05e-2219-438d-9021-5203d3b5cb0f",
+        "766cf006-4679-4ceb-8971-5be5847aa1cd",
+    ),  # Madi
+    (
+        "13342c5e-225e-4b12-a4c7-8c37b37783a3",
+        "3354d901-f860-4411-a290-b34ee28ead3f",
+    ),  # Matthew surname typo
+    (
+        "36200504-e009-47d7-9dde-9db3cbb6f3dc",
+        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
+    ),  # Matt Green repair
+    (
+        "3a880441-9fdb-4979-b574-ad8e14e39e41",
+        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
+    ),  # Matt Green
+    (
+        "b13ee247-a890-44ae-8126-1781e78d2375",
+        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
+    ),  # Matt Green
+    (
+        "4663652a-11a9-4fdc-953b-713878be13a1",
+        "9418ddb0-28fd-4def-88d2-d933de154902",
+    ),  # Nave / Nav
+    (
+        "05a82448-d03c-437e-9f88-7bfd1f4d182b",
+        "c2f89cdb-109f-4440-bf61-888f927a4c16",
+    ),  # Onkar typo
+    (
+        "c2f89cdb-109f-4440-bf61-888f927a4c16",
+        "e19f00a9-2589-4465-a31f-2a2fe566af76",
+    ),  # Onkar company variant
+    (
+        "96241f46-590f-4f3a-a82d-ce3a1c31a260",
+        "e0a47879-41d3-48ef-8e68-ebd67c018711",
+    ),  # Pederson / Pedersen
+    (
+        "6913ce62-67e2-4dd1-a0a6-eca0c3cb35d8",
+        "8a2de35f-4828-4464-a9e0-44f94ee4e544",
+    ),  # Peter / Pieter Badenhorst
+    (
+        "3abf4238-63ba-4362-8a4d-d22dd6d77496",
+        "ec160e6f-7708-43f9-824b-3c219ca4d962",
+    ),  # Robbie / Robert Grant
+    (
+        "44e28e0a-3c70-4ce3-8cff-177f71efd468",
+        "c195f5e4-feb8-40ad-8a03-369830607f51",
+    ),  # Vimlesh surname typo
+)
+
+MATT_GREEN_LINK_ID = UUID("36200504-e009-47d7-9dde-9db3cbb6f3dc")
+MATT_WRONG_METHOD_VALUES = {"j.green@northlandroofs.com", "+64277003221"}
+
+
+def _components(edges: Iterable[tuple[UUID, UUID]]) -> list[set[UUID]]:
+    adjacency: dict[UUID, set[UUID]] = defaultdict(set)
+    for first_id, second_id in edges:
+        adjacency[first_id].add(second_id)
+        adjacency[second_id].add(first_id)
+
+    components: list[set[UUID]] = []
+    visited: set[UUID] = set()
+    for root_id in sorted(adjacency, key=str):
+        if root_id in visited:
+            continue
+        component: set[UUID] = set()
+        pending = [root_id]
+        while pending:
+            person_id = pending.pop()
+            if person_id in component:
+                continue
+            component.add(person_id)
+            pending.extend(adjacency[person_id])
+        visited.update(component)
+        components.append(component)
+    return components
+
+
+def _person_rank(person: Person) -> tuple[bool, int, int, object, str]:
+    from apps.crm.models import PhoneCallRecord
+    from apps.job.models import Job
+
+    activity = (
+        Job.objects.filter(person=person).count()
+        + PhoneCallRecord.objects.filter(person=person).count()
+    )
+    references = person.company_links.count() + person.contact_methods.count()
+    return (
+        not person.is_active,
+        -activity,
+        -references,
+        person.created_at,
+        str(person.id),
+    )
+
+
+def _merge_person_components(components: Iterable[set[UUID]], staff: Staff) -> int:
+    merge_count = 0
+    for component in components:
+        people = list(Person.objects.filter(id__in=component))
+        if len(people) < 2:
+            continue
+        destination = min(people, key=_person_rank)
+        for source in sorted(people, key=lambda person: str(person.id)):
+            if source.id == destination.id:
+                continue
+            merge_people(source.id, destination.id, staff)
+            merge_count += 1
+    return merge_count
+
+
+def _reviewed_person_components() -> list[set[UUID]]:
+    raw_edges = [
+        (UUID(first_id), UUID(second_id))
+        for first_id, second_id in REVIEWED_PERSON_LINK_EDGES
+    ]
+    link_ids = {link_id for edge in raw_edges for link_id in edge}
+    person_by_link = dict(
+        CompanyPersonLink.objects.filter(id__in=link_ids).values_list("id", "person_id")
+    )
+    active_edges: list[tuple[UUID, UUID]] = []
+    for first_link_id, second_link_id in raw_edges:
+        first_person_id = person_by_link.get(first_link_id)
+        second_person_id = person_by_link.get(second_link_id)
+        if first_person_id is None and second_person_id is None:
+            continue
+        if first_person_id is None or second_person_id is None:
+            raise RuntimeError(
+                "KAN-278 Person merge evidence is incomplete: "
+                f"{first_link_id}, {second_link_id}"
+            )
+        active_edges.append((first_person_id, second_person_id))
+    return _components(active_edges)
+
+
+def _merge_detected_company_groups(staff: Staff) -> int:
+    report = DuplicateIdentityReportService().get_report()
+    merge_count = 0
+    for group in report["company_groups"]:
+        if group["recommendation"] != "merge":
+            continue
+        canonical_id = group["canonical_id"]
+        if canonical_id is None:
+            raise RuntimeError(f"Merge group {group['group_id']} has no canonical")
+        destination_id = UUID(canonical_id)
+        for member in group["members"]:
+            source_id = UUID(member["company_id"])
+            if source_id == destination_id:
+                continue
+            merge_companies(source_id, destination_id, staff)
+            merge_count += 1
+    return merge_count
+
+
+def _merge_detected_person_groups(staff: Staff) -> int:
+    report = DuplicateIdentityReportService().get_report()
+    merge_count = 0
+    for group in report["person_groups"]:
+        if group["recommendation"] != "merge":
+            continue
+        canonical_id = group["canonical_id"]
+        if canonical_id is None:
+            raise RuntimeError(f"Merge group {group['group_id']} has no canonical")
+        destination_id = UUID(canonical_id)
+        for member in group["members"]:
+            source_id = UUID(member["person_id"])
+            if source_id == destination_id:
+                continue
+            merge_people(source_id, destination_id, staff)
+            merge_count += 1
+    return merge_count
+
+
+def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
+    """Apply the reviewed Company-first then Person cleanup plan."""
+    company_pairs = [
+        (UUID(source_id), UUID(destination_id))
+        for source_id, destination_id in REVIEWED_COMPANY_MERGES
+    ]
+    company_ids = {company_id for pair in company_pairs for company_id in pair}
+    existing_company_ids = set(
+        Company.objects.filter(id__in=company_ids).values_list("id", flat=True)
+    )
+    if not existing_company_ids:
+        return 0, 0
+
+    staff = Staff.get_automation_user()
+    existing_merges = list(
+        Company.objects.filter(
+            merged_into__isnull=False,
+            merged_into__merged_into__isnull=True,
+        ).values_list("id", "merged_into_id")
+    )
+    for source_id, destination_id in existing_merges:
+        if destination_id is None:
+            raise RuntimeError(f"Merged Company {source_id} has no destination")
+        merge_companies(source_id, destination_id, staff)
+
+    company_merge_count = 0
+    for source_id, destination_id in company_pairs:
+        source_exists = source_id in existing_company_ids
+        destination_exists = destination_id in existing_company_ids
+        if not source_exists and not destination_exists:
+            continue
+        if not source_exists or not destination_exists:
+            raise RuntimeError(
+                "KAN-278 Company merge evidence is incomplete: "
+                f"{source_id}, {destination_id}"
+            )
+        merge_companies(source_id, destination_id, staff)
+        company_merge_count += 1
+
+    matt_link = CompanyPersonLink.objects.filter(id=MATT_GREEN_LINK_ID).first()
+    if matt_link is not None:
+        ContactMethod.objects.filter(
+            person_id=matt_link.person_id,
+            normalized_value__in=MATT_WRONG_METHOD_VALUES,
+        ).delete()
+        Person.objects.filter(id=matt_link.person_id).update(email=None)
+
+    person_merge_count = _merge_person_components(_reviewed_person_components(), staff)
+    for _iteration in range(10):
+        detected_companies = _merge_detected_company_groups(staff)
+        detected_people = _merge_detected_person_groups(staff)
+        company_merge_count += detected_companies
+        person_merge_count += detected_people
+        if detected_companies == 0 and detected_people == 0:
+            break
+    else:
+        raise RuntimeError("KAN-278 cleanup did not converge after 10 iterations")
+
+    remaining = DuplicateIdentityReportService().get_report()["summary"]
+    remaining_automatic = (
+        remaining["company_merge_groups"] + remaining["person_merge_groups"]
+    )
+    if remaining_automatic:
+        raise RuntimeError(
+            f"KAN-278 cleanup left {remaining_automatic} automatic merge groups"
+        )
+    return company_merge_count, person_merge_count
diff --git a/apps/company/tests/test_cleanup_duplicate_identities_command.py b/apps/company/tests/test_cleanup_duplicate_identities_command.py
new file mode 100644
index 000000000..3932ccc05
--- /dev/null
+++ b/apps/company/tests/test_cleanup_duplicate_identities_command.py
@@ -0,0 +1,35 @@
+import csv
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from django.core.management import call_command
+from django.utils import timezone
+
+from apps.company.models import Company
+from apps.testing import BaseTestCase
+
+
+class CleanupDuplicateIdentitiesCommandTests(BaseTestCase):
+    def test_preview_and_apply_grouped_company_merge(self) -> None:
+        first = Company.objects.create(
+            name="Acme Ltd", xero_last_modified=timezone.now()
+        )
+        second = Company.objects.create(
+            name="CASH SALE - Acme Limited", xero_last_modified=timezone.now()
+        )
+        with TemporaryDirectory() as directory:
+            path = Path(directory) / "duplicates.csv"
+            call_command("cleanup_duplicate_identities", preview=str(path))
+
+            with path.open(newline="", encoding="utf-8") as input_file:
+                rows = list(csv.DictReader(input_file))
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(rows[0]["entity_kind"], "company")
+            self.assertEqual(rows[0]["action"], "merge")
+
+            call_command("cleanup_duplicate_identities", apply=str(path))
+
+        first.refresh_from_db()
+        second.refresh_from_db()
+        merged = [company for company in (first, second) if company.merged_into_id]
+        self.assertEqual(len(merged), 1)
diff --git a/apps/company/tests/test_cleanup_duplicate_people_command.py b/apps/company/tests/test_cleanup_duplicate_people_command.py
deleted file mode 100644
index 3d76c6c4b..000000000
--- a/apps/company/tests/test_cleanup_duplicate_people_command.py
+++ /dev/null
@@ -1,55 +0,0 @@
-import csv
-import tempfile
-from pathlib import Path
-
-from django.core.management import call_command
-from django.core.management.base import CommandError
-
-from apps.company.models import Person
-from apps.testing import BaseTestCase
-
-
-class CleanupDuplicatePeopleCommandTests(BaseTestCase):
-    """The cleanup CSV is a reviewed, stale-safe boundary around destructive merges."""
-
-    def _path(self) -> Path:
-        handle = tempfile.NamedTemporaryFile(suffix=".csv", delete=False)
-        handle.close()
-        return Path(handle.name)
-
-    def test_preview_prefills_only_isolated_high_confidence_pair(self) -> None:
-        Person.objects.create(name="Jane Smith", email="jane@example.com")
-        Person.objects.create(name="jane smith", email="JANE@example.com")
-        Person.objects.create(name="Accounts")
-        Person.objects.create(name=" accounts ")
-        path = self._path()
-
-        call_command("cleanup_duplicate_people", preview=str(path))
-
-        with path.open(newline="", encoding="utf-8") as input_file:
-            rows = list(csv.DictReader(input_file))
-        self.assertEqual(len(rows), 2)
-        actions_by_confidence = {row["confidence"]: row["action"] for row in rows}
-        self.assertEqual(actions_by_confidence["high"], "merge")
-        self.assertEqual(actions_by_confidence["low"], "")
-
-    def test_apply_merges_selected_rows(self) -> None:
-        first = Person.objects.create(name="Jane Smith", email="jane@example.com")
-        second = Person.objects.create(name="jane smith", email="JANE@example.com")
-        path = self._path()
-        call_command("cleanup_duplicate_people", preview=str(path))
-
-        call_command("cleanup_duplicate_people", apply=str(path))
-
-        self.assertEqual(Person.objects.filter(id__in=[first.id, second.id]).count(), 1)
-
-    def test_apply_rejects_stale_person(self) -> None:
-        Person.objects.create(name="Jane Smith", email="jane@example.com")
-        second = Person.objects.create(name="jane smith", email="JANE@example.com")
-        path = self._path()
-        call_command("cleanup_duplicate_people", preview=str(path))
-        second.name = "Jane Smith Updated"
-        second.save(update_fields=["name", "updated_at"])
-
-        with self.assertRaisesRegex(CommandError, "changed after preview"):
-            call_command("cleanup_duplicate_people", apply=str(path))
diff --git a/apps/company/tests/test_company_merge_service.py b/apps/company/tests/test_company_merge_service.py
index ed7b74037..4a098811c 100644
--- a/apps/company/tests/test_company_merge_service.py
+++ b/apps/company/tests/test_company_merge_service.py
@@ -16,7 +16,10 @@
 
 from apps.accounting.models import Bill, CreditNote, Invoice, Quote
 from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
-from apps.company.services.company_merge_service import reassign_company_fk_records
+from apps.company.services.company_merge_service import (
+    merge_companies,
+    reassign_company_fk_records,
+)
 from apps.crm.models import PhoneCallRecord
 from apps.job.models import Job, JobEvent
 from apps.purchasing.models import PurchaseOrder
@@ -689,3 +692,60 @@ def test_zero_records_returns_all_zero_counts(self) -> None:
                 "scrape_jobs": 0,
             },
         )
+
+
+class MergeCompaniesTests(ReassignFKBaseCase):
+    def test_preserves_source_classification_and_blank_destination_details(
+        self,
+    ) -> None:
+        self.source.is_account_customer = True
+        self.source.is_supplier = True
+        self.source.email = "accounts@example.com"
+        self.source.address = "1 Example Street"
+        self.source.save(
+            update_fields=["is_account_customer", "is_supplier", "email", "address"]
+        )
+
+        merge_companies(self.source.id, self.destination.id, self.test_staff)
+
+        self.destination.refresh_from_db()
+        self.assertTrue(self.destination.is_account_customer)
+        self.assertTrue(self.destination.is_supplier)
+        self.assertEqual(self.destination.email, "accounts@example.com")
+        self.assertEqual(self.destination.address, "1 Example Street")
+
+    def test_retains_disabled_xero_tombstone_and_moves_history(self) -> None:
+        self.source.xero_contact_id = "source-xero-id"
+        self.source.save(update_fields=["xero_contact_id"])
+        job = make_job(self.source, self.test_staff)
+
+        counts = merge_companies(
+            self.source.id,
+            self.destination.id,
+            self.test_staff,
+        )
+
+        self.source.refresh_from_db()
+        job.refresh_from_db()
+        self.assertEqual(self.source.merged_into_id, self.destination.id)
+        self.assertFalse(self.source.allow_jobs)
+        self.assertEqual(self.source.xero_contact_id, "source-xero-id")
+        self.assertEqual(job.company_id, self.destination.id)
+        self.assertEqual(counts["jobs"], 1)
+
+    def test_rolls_back_tombstone_when_reassignment_fails(self) -> None:
+        with patch(
+            "apps.company.services.company_merge_service."
+            "reassign_company_fk_records",
+            side_effect=RuntimeError("failed"),
+        ):
+            with self.assertRaisesRegex(RuntimeError, "failed"):
+                merge_companies(
+                    self.source.id,
+                    self.destination.id,
+                    self.test_staff,
+                )
+
+        self.source.refresh_from_db()
+        self.assertIsNone(self.source.merged_into_id)
+        self.assertTrue(self.source.allow_jobs)
diff --git a/apps/company/tests/test_duplicate_identity_report.py b/apps/company/tests/test_duplicate_identity_report.py
new file mode 100644
index 000000000..51b472d31
--- /dev/null
+++ b/apps/company/tests/test_duplicate_identity_report.py
@@ -0,0 +1,89 @@
+from django.utils import timezone
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services.duplicate_identity_report import (
+    DuplicateIdentityReportService,
+)
+from apps.testing import BaseTestCase
+
+
+class DuplicateIdentityReportTests(BaseTestCase):
+    def _company(self, name: str) -> Company:
+        return Company.objects.create(name=name, xero_last_modified=timezone.now())
+
+    def _method(self, owner: Company | Person, method_type: str, value: str) -> None:
+        normalized = (
+            value.strip().casefold()
+            if method_type == ContactMethod.MethodType.EMAIL
+            else ContactMethod.normalize_phone(value)
+        )
+        method = ContactMethod(
+            method_type=method_type,
+            value=value,
+            normalized_value=normalized,
+            company=owner if isinstance(owner, Company) else None,
+            person=owner if isinstance(owner, Person) else None,
+        )
+        ContactMethod.objects.bulk_create([method])
+
+    def test_exact_company_names_are_one_automatic_group(self) -> None:
+        self._company("Acme Limited")
+        self._company("CASH SALE - Acme Ltd")
+
+        report = DuplicateIdentityReportService().get_report()
+
+        self.assertEqual(report["summary"]["company_merge_groups"], 1)
+        group = report["company_groups"][0]
+        self.assertEqual(group["recommendation"], "merge")
+        self.assertEqual(len(group["members"]), 2)
+
+    def test_unrelated_company_names_with_shared_email_and_phone_need_review(
+        self,
+    ) -> None:
+        first = self._company("Acme Engineering")
+        second = self._company("Jane Smith")
+        for company in (first, second):
+            self._method(company, ContactMethod.MethodType.EMAIL, "jane@acme.test")
+            self._method(company, ContactMethod.MethodType.PHONE, "021 555 0101")
+
+        report = DuplicateIdentityReportService().get_report()
+
+        self.assertEqual(report["summary"]["company_merge_groups"], 0)
+        self.assertEqual(report["summary"]["company_review_groups"], 1)
+
+    def test_compatible_people_with_a_rare_phone_are_merged(self) -> None:
+        company = self._company("Acme")
+        first = Person.objects.create(name="Robert Jones")
+        second = Person.objects.create(name="Bob Jones")
+        CompanyPersonLink.objects.create(company=company, person=first)
+        CompanyPersonLink.objects.create(company=company, person=second)
+        self._method(first, ContactMethod.MethodType.PHONE, "021 555 0102")
+        self._method(second, ContactMethod.MethodType.PHONE, "021 555 0102")
+
+        report = DuplicateIdentityReportService().get_report()
+
+        self.assertEqual(report["summary"]["person_merge_groups"], 1)
+
+    def test_conflicting_person_names_with_shared_contacts_need_review(self) -> None:
+        first = Person.objects.create(name="Alice Smith")
+        second = Person.objects.create(name="Bob Jones")
+        for person in (first, second):
+            self._method(person, ContactMethod.MethodType.EMAIL, "office@acme.test")
+            self._method(person, ContactMethod.MethodType.PHONE, "021 555 0103")
+
+        report = DuplicateIdentityReportService().get_report()
+
+        self.assertEqual(report["summary"]["person_merge_groups"], 0)
+        self.assertEqual(report["summary"]["person_review_groups"], 1)
+
+    def test_cross_company_name_only_people_are_not_reported(self) -> None:
+        first_company = self._company("Acme")
+        second_company = self._company("Beta")
+        first = Person.objects.create(name="Chris Smith")
+        second = Person.objects.create(name="Chris Smith")
+        CompanyPersonLink.objects.create(company=first_company, person=first)
+        CompanyPersonLink.objects.create(company=second_company, person=second)
+
+        report = DuplicateIdentityReportService().get_report()
+
+        self.assertEqual(report["person_groups"], [])
diff --git a/apps/company/tests/test_duplicate_person_report.py b/apps/company/tests/test_duplicate_person_report.py
index e724f9189..e744fc6a8 100644
--- a/apps/company/tests/test_duplicate_person_report.py
+++ b/apps/company/tests/test_duplicate_person_report.py
@@ -2,7 +2,10 @@
 from django.utils import timezone
 
 from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
-from apps.company.services.duplicate_person_report import DuplicatePersonReportService
+from apps.company.services.duplicate_person_report import (
+    DuplicatePersonReportService,
+    person_names_compatible,
+)
 
 
 class DuplicatePersonReportTests(TestCase):
@@ -72,3 +75,34 @@ def test_name_only_match_is_low_confidence(self) -> None:
         candidate = DuplicatePersonReportService().get_report()["duplicate_people"][0]
 
         self.assertEqual(candidate["confidence"], "low")
+
+    def test_nickname_and_phone_is_high_confidence(self) -> None:
+        first = Person.objects.create(name="Christopher Watt")
+        second = Person.objects.create(name="Chris Watt")
+        self._legacy_phone(first, "021 555 123")
+        self._legacy_phone(second, "+64 21 555 123")
+
+        candidate = DuplicatePersonReportService().get_report()["duplicate_people"][0]
+
+        self.assertEqual(candidate["confidence"], "high")
+        self.assertEqual(
+            {match["kind"] for match in candidate["matches"]}, {"name", "phone"}
+        )
+
+    def test_two_contact_signals_with_incompatible_names_is_medium(self) -> None:
+        first = Person.objects.create(name="Brian")
+        second = Person.objects.create(name="Brent")
+        for person in (first, second):
+            ContactMethod.objects.create(
+                person=person,
+                method_type=ContactMethod.MethodType.EMAIL,
+                value="office@example.com",
+            )
+            self._legacy_phone(person, "021 555 123")
+
+        candidate = DuplicatePersonReportService().get_report()["duplicate_people"][0]
+
+        self.assertEqual(candidate["confidence"], "medium")
+
+    def test_nickname_does_not_override_conflicting_surnames(self) -> None:
+        self.assertFalse(person_names_compatible("Robert Grant", "Rob Smith"))
diff --git a/apps/company/tests/test_kan278_duplicate_cleanup.py b/apps/company/tests/test_kan278_duplicate_cleanup.py
new file mode 100644
index 000000000..eb6172199
--- /dev/null
+++ b/apps/company/tests/test_kan278_duplicate_cleanup.py
@@ -0,0 +1,105 @@
+from unittest.mock import patch
+
+from django.utils import timezone
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.services import kan278_duplicate_cleanup
+from apps.company.services.kan278_duplicate_cleanup import (
+    apply_reviewed_duplicate_cleanup,
+)
+from apps.job.models import Job
+from apps.testing import BaseTestCase
+
+
+class ReviewedDuplicateCleanupTests(BaseTestCase):
+    def test_applies_company_first_then_person_merge(self) -> None:
+        destination_company = Company.objects.create(
+            name="Northland Roofs NZ",
+            xero_last_modified=timezone.now(),
+        )
+        source_company = Company.objects.create(
+            name="CASH SALE - Northland Roofs NZ",
+            xero_contact_id="source-xero-id",
+            xero_last_modified=timezone.now(),
+        )
+        destination_person = Person.objects.create(
+            name="ACE PUNIA", email="ace@example.com"
+        )
+        source_person = Person.objects.create(name="Ace Punia", email="ACE@example.com")
+        destination_link = CompanyPersonLink.objects.create(
+            company=destination_company,
+            person=destination_person,
+        )
+        source_link = CompanyPersonLink.objects.create(
+            company=source_company,
+            person=source_person,
+        )
+        ContactMethod.objects.create(
+            person=source_person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 555 123",
+        )
+        job = Job(
+            company=source_company,
+            person=source_person,
+            name="Northland test",
+            job_number=998278,
+        )
+        job.save(staff=self.test_staff)
+
+        with (
+            patch.object(
+                kan278_duplicate_cleanup,
+                "REVIEWED_COMPANY_MERGES",
+                ((str(source_company.id), str(destination_company.id)),),
+            ),
+            patch.object(
+                kan278_duplicate_cleanup,
+                "REVIEWED_PERSON_LINK_EDGES",
+                ((str(source_link.id), str(destination_link.id)),),
+            ),
+            patch.object(
+                kan278_duplicate_cleanup,
+                "MATT_GREEN_LINK_ID",
+                source_link.id,
+            ),
+            patch.object(
+                kan278_duplicate_cleanup,
+                "MATT_WRONG_METHOD_VALUES",
+                set(),
+            ),
+        ):
+            company_count, person_count = apply_reviewed_duplicate_cleanup()
+
+        source_company.refresh_from_db()
+        job.refresh_from_db()
+        self.assertEqual(company_count, 1)
+        self.assertEqual(person_count, 1)
+        self.assertEqual(source_company.merged_into_id, destination_company.id)
+        self.assertFalse(source_company.allow_jobs)
+        self.assertEqual(source_company.xero_contact_id, "source-xero-id")
+        self.assertEqual(job.company_id, destination_company.id)
+        self.assertIn(job.person_id, {source_person.id, destination_person.id})
+        self.assertEqual(
+            Person.objects.filter(
+                id__in=[source_person.id, destination_person.id]
+            ).count(),
+            1,
+        )
+        self.assertEqual(
+            CompanyPersonLink.objects.filter(company=destination_company).count(), 1
+        )
+
+    def test_rejects_partially_present_company_evidence(self) -> None:
+        destination = Company.objects.create(
+            name="Destination",
+            xero_last_modified=timezone.now(),
+        )
+
+        with patch.object(
+            kan278_duplicate_cleanup,
+            "REVIEWED_COMPANY_MERGES",
+            (("00000000-0000-0000-0000-000000000278", str(destination.id)),),
+        ):
+            with self.assertRaisesRegex(RuntimeError, "Company merge evidence"):
+                apply_reviewed_duplicate_cleanup()
diff --git a/apps/job/serializers/__init__.py b/apps/job/serializers/__init__.py
index e6dbf6022..701c22210 100644
--- a/apps/job/serializers/__init__.py
+++ b/apps/job/serializers/__init__.py
@@ -30,12 +30,14 @@
             ArchivedJobIssueSerializer,
             ArchivedJobsComplianceResponseSerializer,
             ComplianceSummarySerializer,
-            DuplicatePeopleResponseSerializer,
-            DuplicatePersonCandidateSerializer,
+            DuplicateCompanyGroupSerializer,
+            DuplicateCompanyMemberSerializer,
+            DuplicateIdentitiesResponseSerializer,
+            DuplicateIdentityEvidenceSerializer,
+            DuplicateIdentityReportSummarySerializer,
             DuplicatePersonCompanyLinkSerializer,
             DuplicatePersonContactMethodSerializer,
-            DuplicatePersonMatchSerializer,
-            DuplicatePersonReportSummarySerializer,
+            DuplicatePersonGroupSerializer,
             DuplicatePersonSummarySerializer,
             DuplicatePhoneIssueSerializer,
             DuplicatePhoneOwnerSerializer,
@@ -203,12 +205,14 @@
     "DataIntegritySummarySerializer",
     "DiffPreviewSerializer",
     "DraftLineSerializer",
-    "DuplicatePeopleResponseSerializer",
-    "DuplicatePersonCandidateSerializer",
+    "DuplicateCompanyGroupSerializer",
+    "DuplicateCompanyMemberSerializer",
+    "DuplicateIdentitiesResponseSerializer",
+    "DuplicateIdentityEvidenceSerializer",
+    "DuplicateIdentityReportSummarySerializer",
     "DuplicatePersonCompanyLinkSerializer",
     "DuplicatePersonContactMethodSerializer",
-    "DuplicatePersonMatchSerializer",
-    "DuplicatePersonReportSummarySerializer",
+    "DuplicatePersonGroupSerializer",
     "DuplicatePersonSummarySerializer",
     "DuplicatePhoneIssueSerializer",
     "DuplicatePhoneOwnerSerializer",
diff --git a/apps/job/serializers/data_quality_report_serializers.py b/apps/job/serializers/data_quality_report_serializers.py
index 020db55f3..88d15a576 100644
--- a/apps/job/serializers/data_quality_report_serializers.py
+++ b/apps/job/serializers/data_quality_report_serializers.py
@@ -2,13 +2,17 @@
 
 from rest_framework import serializers
 
+from apps.company.services.duplicate_identity_report import (
+    DuplicateCompanyGroup,
+    DuplicateCompanyMember,
+    DuplicateIdentityEvidence,
+    DuplicateIdentityReport,
+    DuplicateIdentityReportSummary,
+    DuplicatePersonGroup,
+)
 from apps.company.services.duplicate_person_report import (
-    DuplicatePersonCandidate,
     DuplicatePersonCompanyLink,
     DuplicatePersonContactMethod,
-    DuplicatePersonMatch,
-    DuplicatePersonReport,
-    DuplicatePersonReportSummary,
     DuplicatePersonSummary,
 )
 from apps.company.services.duplicate_phone_report import (
@@ -157,32 +161,62 @@ class DuplicatePersonSummarySerializer(serializers.Serializer[DuplicatePersonSum
     phone_call_count = serializers.IntegerField()
 
 
-class DuplicatePersonMatchSerializer(serializers.Serializer[DuplicatePersonMatch]):
-    kind = serializers.ChoiceField(choices=["name", "email", "phone"])
+class DuplicateIdentityEvidenceSerializer(
+    serializers.Serializer[DuplicateIdentityEvidence]
+):
+    kind = serializers.ChoiceField(
+        choices=["name", "email", "email_domain", "phone", "address", "shared_person"]
+    )
     normalized_value = serializers.CharField()
+    owner_count = serializers.IntegerField()
 
 
-class DuplicatePersonCandidateSerializer(
-    serializers.Serializer[DuplicatePersonCandidate]
-):
-    confidence = serializers.ChoiceField(choices=["high", "medium", "low"])
-    matches = DuplicatePersonMatchSerializer(many=True)
-    shared_company_ids = serializers.ListField(child=serializers.UUIDField())
-    first_person = DuplicatePersonSummarySerializer()
-    second_person = DuplicatePersonSummarySerializer()
+class DuplicateCompanyMemberSerializer(serializers.Serializer[DuplicateCompanyMember]):
+    company_id = serializers.UUIDField()
+    name = serializers.CharField()
+    email = serializers.EmailField(allow_null=True)
+    address = serializers.CharField(allow_null=True)
+    allow_jobs = serializers.BooleanField()
+    is_account_customer = serializers.BooleanField()
+    is_supplier = serializers.BooleanField()
+    xero_archived = serializers.BooleanField()
+    job_count = serializers.IntegerField()
+    contact_names = serializers.ListField(child=serializers.CharField())
+
+
+class DuplicateCompanyGroupSerializer(serializers.Serializer[DuplicateCompanyGroup]):
+    group_id = serializers.CharField()
+    fingerprint = serializers.CharField()
+    recommendation = serializers.ChoiceField(choices=["merge", "review"])
+    reason_codes = serializers.ListField(child=serializers.CharField())
+    canonical_id = serializers.UUIDField(allow_null=True)
+    members = DuplicateCompanyMemberSerializer(many=True)
+    evidence = DuplicateIdentityEvidenceSerializer(many=True)
 
 
-class DuplicatePersonReportSummarySerializer(
-    serializers.Serializer[DuplicatePersonReportSummary]
+class DuplicatePersonGroupSerializer(serializers.Serializer[DuplicatePersonGroup]):
+    group_id = serializers.CharField()
+    fingerprint = serializers.CharField()
+    recommendation = serializers.ChoiceField(choices=["merge", "review"])
+    reason_codes = serializers.ListField(child=serializers.CharField())
+    canonical_id = serializers.UUIDField(allow_null=True)
+    members = DuplicatePersonSummarySerializer(many=True)
+    evidence = DuplicateIdentityEvidenceSerializer(many=True)
+
+
+class DuplicateIdentityReportSummarySerializer(
+    serializers.Serializer[DuplicateIdentityReportSummary]
 ):
-    candidate_pairs = serializers.IntegerField()
-    people_flagged = serializers.IntegerField()
-    high = serializers.IntegerField()
-    medium = serializers.IntegerField()
-    low = serializers.IntegerField()
+    company_merge_groups = serializers.IntegerField()
+    company_review_groups = serializers.IntegerField()
+    person_merge_groups = serializers.IntegerField()
+    person_review_groups = serializers.IntegerField()
 
 
-class DuplicatePeopleResponseSerializer(serializers.Serializer[DuplicatePersonReport]):
-    duplicate_people = DuplicatePersonCandidateSerializer(many=True)
-    summary = DuplicatePersonReportSummarySerializer()
+class DuplicateIdentitiesResponseSerializer(
+    serializers.Serializer[DuplicateIdentityReport]
+):
+    company_groups = DuplicateCompanyGroupSerializer(many=True)
+    person_groups = DuplicatePersonGroupSerializer(many=True)
+    summary = DuplicateIdentityReportSummarySerializer()
     checked_at = serializers.DateTimeField()
diff --git a/apps/job/tests/test_duplicate_people_view.py b/apps/job/tests/test_duplicate_identities_view.py
similarity index 50%
rename from apps/job/tests/test_duplicate_people_view.py
rename to apps/job/tests/test_duplicate_identities_view.py
index 542c64172..ab5c38bdf 100644
--- a/apps/job/tests/test_duplicate_people_view.py
+++ b/apps/job/tests/test_duplicate_identities_view.py
@@ -1,32 +1,35 @@
+from django.utils import timezone
+
 from apps.accounts.models import Staff
-from apps.company.models import Person
+from apps.company.models import Company
 from apps.testing import BaseAPITestCase
 
-URL = "/api/job/data-quality/duplicate-people/"
-
+URL = "/api/job/data-quality/duplicate-identities/"
 
-class DuplicatePeopleViewTests(BaseAPITestCase):
-    """The report contains identity data and must remain office-staff-only."""
 
+class DuplicateIdentitiesViewTests(BaseAPITestCase):
     def _office_staff(self) -> Staff:
         return Staff.objects.create_user(
-            email="office-person-report@example.com",
+            email="office@example.com",
             password="testpass",
             first_name="Office",
             last_name="Staff",
             is_office_staff=True,
         )
 
-    def test_returns_duplicate_person_candidates_to_office_staff(self) -> None:
-        Person.objects.create(name="Jane Smith", email="jane@example.com")
-        Person.objects.create(name="jane smith", email="JANE@example.com")
+    def test_returns_grouped_duplicates_to_office_staff(self) -> None:
+        Company.objects.create(name="Acme Ltd", xero_last_modified=timezone.now())
+        Company.objects.create(
+            name="CASH SALE - Acme Limited",
+            xero_last_modified=timezone.now(),
+        )
         self.client.force_authenticate(self._office_staff())
 
         response = self.client.get(URL)
 
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.data["summary"]["high"], 1)
-        self.assertEqual(len(response.data["duplicate_people"]), 1)
+        self.assertEqual(response.data["summary"]["company_merge_groups"], 1)
+        self.assertEqual(len(response.data["company_groups"]), 1)
 
     def test_forbidden_for_non_office_staff(self) -> None:
         self.client.force_authenticate(self.test_staff)
diff --git a/apps/job/urls_rest.py b/apps/job/urls_rest.py
index 6dd5512ab..b2a7a4e26 100644
--- a/apps/job/urls_rest.py
+++ b/apps/job/urls_rest.py
@@ -3,7 +3,7 @@
 from apps.job.views.data_integrity_views import DataIntegrityReportView
 from apps.job.views.data_quality_report_views import (
     ArchivedJobsComplianceView,
-    DuplicatePeopleView,
+    DuplicateIdentitiesView,
     DuplicatePhonesView,
 )
 from apps.job.views.delivery_docket_view import DeliveryDocketView
@@ -338,9 +338,9 @@
         name="data_quality_duplicate_phones",
     ),
     path(
-        "data-quality/duplicate-people/",
-        DuplicatePeopleView.as_view(),
-        name="data_quality_duplicate_people",
+        "data-quality/duplicate-identities/",
+        DuplicateIdentitiesView.as_view(),
+        name="data_quality_duplicate_identities",
     ),
     path(
         "data-integrity/scan/",
diff --git a/apps/job/views/__init__.py b/apps/job/views/__init__.py
index dbe6e0878..2fbcbf9a7 100644
--- a/apps/job/views/__init__.py
+++ b/apps/job/views/__init__.py
@@ -8,7 +8,7 @@
 from .data_integrity_views import DataIntegrityReportView
 from .data_quality_report_views import (
     ArchivedJobsComplianceView,
-    DuplicatePeopleView,
+    DuplicateIdentitiesView,
     DuplicatePhonesView,
 )
 from .delivery_docket_view import DeliveryDocketView
@@ -113,7 +113,7 @@
     "CostLineUpdateView",
     "DataIntegrityReportView",
     "DeliveryDocketView",
-    "DuplicatePeopleView",
+    "DuplicateIdentitiesView",
     "DuplicatePhonesView",
     "FetchAllJobsAPIView",
     "FetchJobsAPIView",
diff --git a/apps/job/views/data_quality_report_views.py b/apps/job/views/data_quality_report_views.py
index ff962b976..63c2d0607 100644
--- a/apps/job/views/data_quality_report_views.py
+++ b/apps/job/views/data_quality_report_views.py
@@ -12,12 +12,14 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
-from apps.company.services.duplicate_person_report import DuplicatePersonReportService
+from apps.company.services.duplicate_identity_report import (
+    DuplicateIdentityReportService,
+)
 from apps.company.services.duplicate_phone_report import DuplicatePhoneReportService
 from apps.job.permissions import IsOfficeStaff
 from apps.job.serializers.data_quality_report_serializers import (
     ArchivedJobsComplianceResponseSerializer,
-    DuplicatePeopleResponseSerializer,
+    DuplicateIdentitiesResponseSerializer,
     DuplicatePhonesResponseSerializer,
 )
 from apps.job.services.data_quality_report import ArchivedJobsComplianceService
@@ -98,25 +100,25 @@ def get(self, request: Request) -> Response:
             raise AlreadyLoggedException(exc, err.id) from exc
 
 
-class DuplicatePeopleView(APIView):
-    """API view for exact-signal duplicate Person candidates."""
+class DuplicateIdentitiesView(APIView):
+    """API view for grouped Company and Person duplicate exceptions."""
 
     permission_classes = [IsAuthenticated, IsOfficeStaff]
 
     @extend_schema(
-        operation_id="check_duplicate_people",
-        summary="Check for duplicate people",
+        operation_id="check_duplicate_identities",
+        summary="Check for duplicate companies and people",
         description=(
-            "List pairs of distinct Person rows sharing exact normalized name, "
-            "email, or person-owned phone signals."
+            "List compact groups of Company and Person identities that are safe "
+            "to merge automatically or require review."
         ),
-        responses={200: DuplicatePeopleResponseSerializer, 500: dict},
+        responses={200: DuplicateIdentitiesResponseSerializer, 500: dict},
         tags=["Data Quality"],
     )
     def get(self, request: Request) -> Response:
         try:
-            result = DuplicatePersonReportService().get_report()
-            serializer = DuplicatePeopleResponseSerializer(data=result)
+            result = DuplicateIdentityReportService().get_report()
+            serializer = DuplicateIdentitiesResponseSerializer(data=result)
             serializer.is_valid(raise_exception=True)
             return Response(serializer.data, status=status.HTTP_200_OK)
         except AlreadyLoggedException:
diff --git a/docs/urls/job.md b/docs/urls/job.md
index 0bae5995a..e7b9b6fdb 100644
--- a/docs/urls/job.md
+++ b/docs/urls/job.md
@@ -23,7 +23,7 @@
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
 | `/data-quality/archived-jobs-compliance/` | `data_quality_report_views.ArchivedJobsComplianceView` | `jobs:data_quality_archived_jobs_compliance` | API view for checking archived jobs compliance. |
-| `/data-quality/duplicate-people/` | `data_quality_report_views.DuplicatePeopleView` | `jobs:data_quality_duplicate_people` | API view for exact-signal duplicate Person candidates. |
+| `/data-quality/duplicate-identities/` | `data_quality_report_views.DuplicateIdentitiesView` | `jobs:data_quality_duplicate_identities` | API view for grouped Company and Person duplicate exceptions. |
 | `/data-quality/duplicate-phones/` | `data_quality_report_views.DuplicatePhonesView` | `jobs:data_quality_duplicate_phones` | API view for the duplicate phones data-quality check. |
 
 ### Job Management
diff --git a/frontend/router-auto-options.ts b/frontend/router-auto-options.ts
index 08905528f..07a696f92 100644
--- a/frontend/router-auto-options.ts
+++ b/frontend/router-auto-options.ts
@@ -35,6 +35,7 @@ const TITLES: Record<string, string> = {
   '/reports/profit-and-loss': 'Profit & Loss Report - DocketWorks',
   '/reports/job-movement': 'Job Movement Report - DocketWorks',
   '/reports/data-quality/archived-jobs': 'Archived Jobs Validation - DocketWorks',
+  '/reports/data-quality/duplicate-identities': 'Duplicate Identities - DocketWorks',
   '/reports/job-profitability': 'Job Profitability Report - DocketWorks',
   '/reports/rdti-spend': 'RDTI Spend Report - DocketWorks',
   '/reports/wip': 'WIP Report - DocketWorks',
diff --git a/frontend/schema.yml b/frontend/schema.yml
index dc5985d58..c8b779f0c 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -3144,12 +3144,12 @@ paths:
                 type: object
                 additionalProperties: {}
           description: ''
-  /api/job/data-quality/duplicate-people/:
+  /api/job/data-quality/duplicate-identities/:
     get:
-      operationId: check_duplicate_people
-      description: List pairs of distinct Person rows sharing exact normalized name,
-        email, or person-owned phone signals.
-      summary: Check for duplicate people
+      operationId: check_duplicate_identities
+      description: List compact groups of Company and Person identities that are safe
+        to merge automatically or require review.
+      summary: Check for duplicate companies and people
       tags:
         - Data Quality
       security:
@@ -3159,7 +3159,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/DuplicatePeopleResponse'
+                $ref: '#/components/schemas/DuplicateIdentitiesResponse'
           description: ''
         '500':
           content:
@@ -11395,16 +11395,6 @@ components:
         - not_cancelled
         - not_invoiced
         - not_paid
-    ConfidenceEnum:
-      enum:
-        - high
-        - medium
-        - low
-      type: string
-      description: |-
-        * `high` - high
-        * `medium` - medium
-        * `low` - low
     ContactMethod:
       type: object
       description: Serializer for canonical company/person phone and email methods.
@@ -12246,46 +12236,145 @@ components:
         - total_rev
         - unit_cost
         - unit_rev
-    DuplicatePeopleResponse:
+    DuplicateCompanyGroup:
       type: object
       properties:
-        duplicate_people:
+        group_id:
+          type: string
+        fingerprint:
+          type: string
+        recommendation:
+          $ref: '#/components/schemas/RecommendationEnum'
+        reason_codes:
           type: array
           items:
-            $ref: '#/components/schemas/DuplicatePersonCandidate'
+            type: string
+        canonical_id:
+          type: string
+          format: uuid
+          nullable: true
+        members:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicateCompanyMember'
+        evidence:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicateIdentityEvidence'
+      required:
+        - canonical_id
+        - evidence
+        - fingerprint
+        - group_id
+        - members
+        - reason_codes
+        - recommendation
+    DuplicateCompanyMember:
+      type: object
+      properties:
+        company_id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        email:
+          type: string
+          format: email
+          nullable: true
+        address:
+          type: string
+          nullable: true
+        allow_jobs:
+          type: boolean
+        is_account_customer:
+          type: boolean
+        is_supplier:
+          type: boolean
+        xero_archived:
+          type: boolean
+        job_count:
+          type: integer
+        contact_names:
+          type: array
+          items:
+            type: string
+      required:
+        - address
+        - allow_jobs
+        - company_id
+        - contact_names
+        - email
+        - is_account_customer
+        - is_supplier
+        - job_count
+        - name
+        - xero_archived
+    DuplicateIdentitiesResponse:
+      type: object
+      properties:
+        company_groups:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicateCompanyGroup'
+        person_groups:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonGroup'
         summary:
-          $ref: '#/components/schemas/DuplicatePersonReportSummary'
+          $ref: '#/components/schemas/DuplicateIdentityReportSummary'
         checked_at:
           type: string
           format: date-time
       required:
         - checked_at
-        - duplicate_people
+        - company_groups
+        - person_groups
         - summary
-    DuplicatePersonCandidate:
+    DuplicateIdentityEvidence:
       type: object
       properties:
-        confidence:
-          $ref: '#/components/schemas/ConfidenceEnum'
-        matches:
-          type: array
-          items:
-            $ref: '#/components/schemas/DuplicatePersonMatch'
-        shared_company_ids:
-          type: array
-          items:
-            type: string
-            format: uuid
-        first_person:
-          $ref: '#/components/schemas/DuplicatePersonSummary'
-        second_person:
-          $ref: '#/components/schemas/DuplicatePersonSummary'
-      required:
-        - confidence
-        - first_person
-        - matches
-        - second_person
-        - shared_company_ids
+        kind:
+          $ref: '#/components/schemas/DuplicateIdentityEvidenceKindEnum'
+        normalized_value:
+          type: string
+        owner_count:
+          type: integer
+      required:
+        - kind
+        - normalized_value
+        - owner_count
+    DuplicateIdentityEvidenceKindEnum:
+      enum:
+        - name
+        - email
+        - email_domain
+        - phone
+        - address
+        - shared_person
+      type: string
+      description: |-
+        * `name` - name
+        * `email` - email
+        * `email_domain` - email_domain
+        * `phone` - phone
+        * `address` - address
+        * `shared_person` - shared_person
+    DuplicateIdentityReportSummary:
+      type: object
+      properties:
+        company_merge_groups:
+          type: integer
+        company_review_groups:
+          type: integer
+        person_merge_groups:
+          type: integer
+        person_review_groups:
+          type: integer
+      required:
+        - company_merge_groups
+        - company_review_groups
+        - person_merge_groups
+        - person_review_groups
     DuplicatePersonCompanyLink:
       type: object
       properties:
@@ -12342,45 +12431,39 @@ components:
       description: |-
         * `phone` - phone
         * `email` - email
-    DuplicatePersonMatch:
+    DuplicatePersonGroup:
       type: object
       properties:
-        kind:
-          $ref: '#/components/schemas/DuplicatePersonMatchKindEnum'
-        normalized_value:
+        group_id:
           type: string
+        fingerprint:
+          type: string
+        recommendation:
+          $ref: '#/components/schemas/RecommendationEnum'
+        reason_codes:
+          type: array
+          items:
+            type: string
+        canonical_id:
+          type: string
+          format: uuid
+          nullable: true
+        members:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicatePersonSummary'
+        evidence:
+          type: array
+          items:
+            $ref: '#/components/schemas/DuplicateIdentityEvidence'
       required:
-        - kind
-        - normalized_value
-    DuplicatePersonMatchKindEnum:
-      enum:
-        - name
-        - email
-        - phone
-      type: string
-      description: |-
-        * `name` - name
-        * `email` - email
-        * `phone` - phone
-    DuplicatePersonReportSummary:
-      type: object
-      properties:
-        candidate_pairs:
-          type: integer
-        people_flagged:
-          type: integer
-        high:
-          type: integer
-        medium:
-          type: integer
-        low:
-          type: integer
-      required:
-        - candidate_pairs
-        - high
-        - low
-        - medium
-        - people_flagged
+        - canonical_id
+        - evidence
+        - fingerprint
+        - group_id
+        - members
+        - reason_codes
+        - recommendation
     DuplicatePersonSummary:
       type: object
       properties:
@@ -19490,6 +19573,14 @@ components:
         * `non_rd` - Non-R&D
         * `core_rd` - Core R&D
         * `supporting_rd` - Supporting R&D
+    RecommendationEnum:
+      enum:
+        - merge
+        - review
+      type: string
+      description: |-
+        * `merge` - merge
+        * `review` - review
     RoleEnum:
       enum:
         - user
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index f4be2774b..d9d4748c4 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -1340,11 +1340,40 @@ const ArchivedJobsComplianceResponse = z.object({
   summary: ComplianceSummary,
   checked_at: z.string().datetime({ offset: true }),
 })
-const ConfidenceEnum = z.enum(['high', 'medium', 'low'])
-const DuplicatePersonMatchKindEnum = z.enum(['name', 'email', 'phone'])
-const DuplicatePersonMatch = z.object({
-  kind: DuplicatePersonMatchKindEnum,
+const RecommendationEnum = z.enum(['merge', 'review'])
+const DuplicateCompanyMember = z.object({
+  company_id: z.string().uuid(),
+  name: z.string(),
+  email: z.string().email().nullable(),
+  address: z.string().nullable(),
+  allow_jobs: z.boolean(),
+  is_account_customer: z.boolean(),
+  is_supplier: z.boolean(),
+  xero_archived: z.boolean(),
+  job_count: z.number().int(),
+  contact_names: z.array(z.string()),
+})
+const DuplicateIdentityEvidenceKindEnum = z.enum([
+  'name',
+  'email',
+  'email_domain',
+  'phone',
+  'address',
+  'shared_person',
+])
+const DuplicateIdentityEvidence = z.object({
+  kind: DuplicateIdentityEvidenceKindEnum,
   normalized_value: z.string(),
+  owner_count: z.number().int(),
+})
+const DuplicateCompanyGroup = z.object({
+  group_id: z.string(),
+  fingerprint: z.string(),
+  recommendation: RecommendationEnum,
+  reason_codes: z.array(z.string()),
+  canonical_id: z.string().uuid().nullable(),
+  members: z.array(DuplicateCompanyMember),
+  evidence: z.array(DuplicateIdentityEvidence),
 })
 const DuplicatePersonCompanyLink = z.object({
   link_id: z.string().uuid(),
@@ -1375,23 +1404,25 @@ const DuplicatePersonSummary = z.object({
   job_count: z.number().int(),
   phone_call_count: z.number().int(),
 })
-const DuplicatePersonCandidate = z.object({
-  confidence: ConfidenceEnum,
-  matches: z.array(DuplicatePersonMatch),
-  shared_company_ids: z.array(z.string().uuid()),
-  first_person: DuplicatePersonSummary,
-  second_person: DuplicatePersonSummary,
-})
-const DuplicatePersonReportSummary = z.object({
-  candidate_pairs: z.number().int(),
-  people_flagged: z.number().int(),
-  high: z.number().int(),
-  medium: z.number().int(),
-  low: z.number().int(),
-})
-const DuplicatePeopleResponse = z.object({
-  duplicate_people: z.array(DuplicatePersonCandidate),
-  summary: DuplicatePersonReportSummary,
+const DuplicatePersonGroup = z.object({
+  group_id: z.string(),
+  fingerprint: z.string(),
+  recommendation: RecommendationEnum,
+  reason_codes: z.array(z.string()),
+  canonical_id: z.string().uuid().nullable(),
+  members: z.array(DuplicatePersonSummary),
+  evidence: z.array(DuplicateIdentityEvidence),
+})
+const DuplicateIdentityReportSummary = z.object({
+  company_merge_groups: z.number().int(),
+  company_review_groups: z.number().int(),
+  person_merge_groups: z.number().int(),
+  person_review_groups: z.number().int(),
+})
+const DuplicateIdentitiesResponse = z.object({
+  company_groups: z.array(DuplicateCompanyGroup),
+  person_groups: z.array(DuplicatePersonGroup),
+  summary: DuplicateIdentityReportSummary,
   checked_at: z.string().datetime({ offset: true }),
 })
 const DuplicatePhoneOwner = z.object({
@@ -3704,16 +3735,18 @@ export const schemas = {
   ArchivedJobIssue,
   ComplianceSummary,
   ArchivedJobsComplianceResponse,
-  ConfidenceEnum,
-  DuplicatePersonMatchKindEnum,
-  DuplicatePersonMatch,
+  RecommendationEnum,
+  DuplicateCompanyMember,
+  DuplicateIdentityEvidenceKindEnum,
+  DuplicateIdentityEvidence,
+  DuplicateCompanyGroup,
   DuplicatePersonCompanyLink,
   DuplicatePersonContactMethodMethodTypeEnum,
   DuplicatePersonContactMethod,
   DuplicatePersonSummary,
-  DuplicatePersonCandidate,
-  DuplicatePersonReportSummary,
-  DuplicatePeopleResponse,
+  DuplicatePersonGroup,
+  DuplicateIdentityReportSummary,
+  DuplicateIdentitiesResponse,
   DuplicatePhoneOwner,
   DuplicatePhoneIssue,
   DuplicatePhoneSummary,
@@ -6207,11 +6240,11 @@ POST /job/rest/cost_lines/&lt;cost_line_id&gt;/approve`,
   },
   {
     method: 'get',
-    path: '/api/job/data-quality/duplicate-people/',
-    alias: 'check_duplicate_people',
-    description: `List pairs of distinct Person rows sharing exact normalized name, email, or person-owned phone signals.`,
+    path: '/api/job/data-quality/duplicate-identities/',
+    alias: 'check_duplicate_identities',
+    description: `List compact groups of Company and Person identities that are safe to merge automatically or require review.`,
     requestFormat: 'json',
-    response: DuplicatePeopleResponse,
+    response: DuplicateIdentitiesResponse,
     errors: [
       {
         status: 500,
diff --git a/frontend/src/components/AppNavbar.vue b/frontend/src/components/AppNavbar.vue
index c64e4af4d..4afa5dc11 100644
--- a/frontend/src/components/AppNavbar.vue
+++ b/frontend/src/components/AppNavbar.vue
@@ -355,6 +355,13 @@
                 >
                   <PhoneCall class="w-4 h-4 mr-2" /> Duplicate Phones
                 </router-link>
+                <router-link
+                  to="/reports/data-quality/duplicate-identities"
+                  class="flex items-center px-4 py-2 text-sm text-gray-700 hover:text-blue-600 hover:bg-blue-50 font-medium transition-all"
+                  data-automation-id="AppNavbar-duplicate-identities"
+                >
+                  <Fingerprint class="w-4 h-4 mr-2" /> Duplicate Identities
+                </router-link>
               </div>
             </Transition>
           </div>
@@ -886,6 +893,14 @@
                       >
                         <PhoneCall class="w-4 h-4 mr-2" /> Duplicate Phones
                       </router-link>
+                      <router-link
+                        to="/reports/data-quality/duplicate-identities"
+                        class="flex items-center px-2 py-1.5 text-sm text-gray-600 hover:text-blue-600 hover:bg-blue-50 rounded transition-all"
+                        data-automation-id="AppNavbar-duplicate-identities-mobile"
+                        @click="closeMobileMenu"
+                      >
+                        <Fingerprint class="w-4 h-4 mr-2" /> Duplicate Identities
+                      </router-link>
                     </div>
                   </div>
                 </Transition>
@@ -987,6 +1002,7 @@ import {
   FlaskConical,
   Activity,
   PhoneCall,
+  Fingerprint,
 } from 'lucide-vue-next'
 import { useAppLayout } from '@/composables/useAppLayout'
 import { adminPages, adminExternalLinks } from '@/config/adminPages'
diff --git a/frontend/src/components/data-quality/IdentityGroupCard.vue b/frontend/src/components/data-quality/IdentityGroupCard.vue
new file mode 100644
index 000000000..5792f5cfd
--- /dev/null
+++ b/frontend/src/components/data-quality/IdentityGroupCard.vue
@@ -0,0 +1,198 @@
+<template>
+  <details
+    class="group rounded-lg border bg-white shadow-sm"
+    :class="groupData.recommendation === 'review' ? 'border-amber-300' : 'border-red-300'"
+    :data-automation-id="`duplicate-${entityKind}-group-${groupData.group_id}`"
+  >
+    <summary
+      class="flex cursor-pointer list-none flex-col gap-3 p-4 hover:bg-slate-50 sm:flex-row sm:items-center sm:justify-between"
+    >
+      <div class="min-w-0">
+        <div class="flex flex-wrap items-center gap-2">
+          <span
+            class="rounded-full px-2 py-0.5 text-xs font-semibold uppercase tracking-wide"
+            :class="
+              groupData.recommendation === 'review'
+                ? 'bg-amber-100 text-amber-900'
+                : 'bg-red-100 text-red-900'
+            "
+          >
+            {{ groupData.recommendation }}
+          </span>
+          <span class="rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-700">
+            {{ entityLabel }}
+          </span>
+          <span class="text-sm text-slate-500">{{ groupData.members.length }} records</span>
+        </div>
+        <p class="mt-2 truncate font-semibold text-slate-900">{{ memberNames }}</p>
+        <p class="mt-1 text-sm text-slate-600">{{ reasonSummary }}</p>
+      </div>
+      <ChevronDown
+        class="h-5 w-5 shrink-0 text-slate-500 transition-transform group-open:rotate-180"
+      />
+    </summary>
+
+    <div class="space-y-5 border-t border-slate-200 p-4">
+      <div>
+        <h3 class="text-xs font-semibold uppercase tracking-wide text-slate-500">Evidence</h3>
+        <div class="mt-2 flex flex-wrap gap-2">
+          <span
+            v-for="item in groupData.evidence"
+            :key="`${item.kind}-${item.normalized_value}`"
+            class="rounded-md bg-indigo-50 px-2 py-1 text-xs text-indigo-900"
+          >
+            {{ evidenceKindLabel(item.kind) }}: {{ item.normalized_value }}
+            <span class="text-indigo-600">({{ item.owner_count }})</span>
+          </span>
+          <span v-if="groupData.evidence.length === 0" class="text-sm text-slate-500">
+            No shared contact detail recorded.
+          </span>
+        </div>
+      </div>
+
+      <div class="grid gap-3 lg:grid-cols-2">
+        <article
+          v-for="member in groupData.members"
+          :key="memberId(member)"
+          class="rounded-md border p-3"
+          :class="isCanonical(member) ? 'border-indigo-300 bg-indigo-50/40' : 'border-slate-200'"
+        >
+          <div class="flex flex-wrap items-center justify-between gap-2">
+            <h3 class="font-semibold text-slate-900">{{ member.name }}</h3>
+            <span
+              v-if="isCanonical(member)"
+              class="rounded-full bg-indigo-100 px-2 py-0.5 text-xs font-semibold text-indigo-800"
+            >
+              Canonical
+            </span>
+          </div>
+
+          <template v-if="entityKind === 'company'">
+            <dl class="mt-3 grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-sm">
+              <dt class="text-slate-500">Email</dt>
+              <dd class="break-all text-slate-800">{{ companyMember(member).email ?? '—' }}</dd>
+              <dt class="text-slate-500">Address</dt>
+              <dd class="text-slate-800">{{ companyMember(member).address ?? '—' }}</dd>
+              <dt class="text-slate-500">Jobs</dt>
+              <dd class="text-slate-800">{{ companyMember(member).job_count }}</dd>
+              <dt class="text-slate-500">Contacts</dt>
+              <dd class="text-slate-800">
+                {{ companyMember(member).contact_names.join(', ') || '—' }}
+              </dd>
+              <dt class="text-slate-500">Roles</dt>
+              <dd class="flex flex-wrap gap-1">
+                <span v-if="companyMember(member).is_account_customer">Customer</span>
+                <span v-if="companyMember(member).is_supplier">Supplier</span>
+                <span v-if="companyMember(member).allow_jobs">Jobs enabled</span>
+                <span v-if="companyMember(member).xero_archived">Xero archived</span>
+                <span v-if="companyRoles(member).length === 0">—</span>
+              </dd>
+            </dl>
+          </template>
+
+          <template v-else>
+            <dl class="mt-3 grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-sm">
+              <dt class="text-slate-500">Email</dt>
+              <dd class="break-all text-slate-800">{{ personMember(member).email ?? '—' }}</dd>
+              <dt class="text-slate-500">Companies</dt>
+              <dd class="text-slate-800">{{ companyNames(member) }}</dd>
+              <dt class="text-slate-500">Contacts</dt>
+              <dd class="text-slate-800">{{ personContacts(member) }}</dd>
+              <dt class="text-slate-500">Activity</dt>
+              <dd class="text-slate-800">
+                {{ personMember(member).job_count }} jobs,
+                {{ personMember(member).phone_call_count }} calls
+              </dd>
+              <dt class="text-slate-500">Status</dt>
+              <dd class="text-slate-800">
+                {{ personMember(member).is_active ? 'Active' : 'Inactive' }}
+              </dd>
+            </dl>
+          </template>
+        </article>
+      </div>
+
+      <p class="text-xs text-slate-400">Group {{ groupData.group_id }}</p>
+    </div>
+  </details>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { z } from 'zod'
+import { ChevronDown } from 'lucide-vue-next'
+
+import { schemas } from '@/api/generated/api'
+
+type CompanyGroup = z.infer<typeof schemas.DuplicateCompanyGroup>
+type PersonGroup = z.infer<typeof schemas.DuplicatePersonGroup>
+type CompanyMember = z.infer<typeof schemas.DuplicateCompanyMember>
+type PersonMember = z.infer<typeof schemas.DuplicatePersonSummary>
+type Group = CompanyGroup | PersonGroup
+type Member = CompanyMember | PersonMember
+
+const props = defineProps<{
+  entityKind: 'company' | 'person'
+  group: Group
+}>()
+
+const groupData = computed(() => props.group)
+const entityLabel = computed(() => (props.entityKind === 'company' ? 'Company' : 'Person'))
+const memberNames = computed(() => props.group.members.map((member) => member.name).join(' · '))
+const reasonSummary = computed(() =>
+  props.group.reason_codes.map((reason) => reason.replaceAll('_', ' ')).join(' · '),
+)
+
+const EVIDENCE_LABELS: Record<string, string> = {
+  name: 'Name',
+  email: 'Email',
+  email_domain: 'Email domain',
+  phone: 'Phone',
+  address: 'Address',
+  shared_person: 'Shared person',
+}
+
+function evidenceKindLabel(kind: string): string {
+  return EVIDENCE_LABELS[kind] ?? kind.replaceAll('_', ' ')
+}
+
+function companyMember(member: Member): CompanyMember {
+  if (!('company_id' in member)) throw new Error('Expected a company member')
+  return member
+}
+
+function personMember(member: Member): PersonMember {
+  if (!('person_id' in member)) throw new Error('Expected a person member')
+  return member
+}
+
+function memberId(member: Member): string {
+  return 'company_id' in member ? member.company_id : member.person_id
+}
+
+function isCanonical(member: Member): boolean {
+  return memberId(member) === props.group.canonical_id
+}
+
+function companyRoles(member: Member): string[] {
+  const company = companyMember(member)
+  return [
+    company.is_account_customer ? 'customer' : null,
+    company.is_supplier ? 'supplier' : null,
+    company.allow_jobs ? 'jobs' : null,
+    company.xero_archived ? 'archived' : null,
+  ].filter((role): role is string => role !== null)
+}
+
+function companyNames(member: Member): string {
+  const names = personMember(member).company_links.map((link) => link.company_name)
+  return names.join(', ') || '—'
+}
+
+function personContacts(member: Member): string {
+  const methods = personMember(member).contact_methods.map(
+    (method) => `${method.contact_label}: ${method.value}`,
+  )
+  return methods.join(', ') || '—'
+}
+</script>
diff --git a/frontend/src/components/data-quality/SummaryCard.vue b/frontend/src/components/data-quality/SummaryCard.vue
new file mode 100644
index 000000000..5c8f3a0ea
--- /dev/null
+++ b/frontend/src/components/data-quality/SummaryCard.vue
@@ -0,0 +1,25 @@
+<template>
+  <div class="rounded-lg border border-slate-200 bg-white p-4 shadow-sm">
+    <p class="text-sm text-slate-600">{{ label }}</p>
+    <p class="mt-1 text-2xl font-bold" :class="toneClass">{{ value }}</p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{
+  label: string
+  value: number
+  tone: 'amber' | 'green' | 'red'
+}>()
+
+const toneClass = computed(
+  () =>
+    ({
+      amber: 'text-amber-700',
+      green: 'text-green-700',
+      red: 'text-red-700',
+    })[props.tone],
+)
+</script>
diff --git a/frontend/src/pages/reports/data-quality/__tests__/duplicate-identities.test.ts b/frontend/src/pages/reports/data-quality/__tests__/duplicate-identities.test.ts
new file mode 100644
index 000000000..6ca4cf1d0
--- /dev/null
+++ b/frontend/src/pages/reports/data-quality/__tests__/duplicate-identities.test.ts
@@ -0,0 +1,201 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/api/client', () => ({
+  api: {
+    check_duplicate_identities: vi.fn(),
+  },
+}))
+
+vi.mock('@/components/AppLayout.vue', () => ({
+  default: { template: '<div><slot /></div>' },
+}))
+
+vi.mock('vue-sonner', () => ({
+  toast: {
+    error: vi.fn(),
+    info: vi.fn(),
+    success: vi.fn(),
+    warning: vi.fn(),
+  },
+}))
+
+import { api } from '@/api/client'
+import DuplicateIdentitiesPage from '@/pages/reports/data-quality/duplicate-identities.vue'
+
+const REVIEW_PERSON_GROUP = {
+  group_id: 'person-review-1',
+  fingerprint: 'fingerprint-1',
+  recommendation: 'review' as const,
+  reason_codes: ['cross_company_contact_conflict'],
+  canonical_id: null,
+  members: [
+    {
+      person_id: '11111111-1111-4111-8111-111111111111',
+      name: 'Alex Smith',
+      email: 'alex@example.com',
+      is_active: true,
+      created_at: '2026-07-13T00:00:00Z',
+      updated_at: '2026-07-13T00:00:00Z',
+      company_links: [
+        {
+          link_id: '22222222-2222-4222-8222-222222222222',
+          company_id: '33333333-3333-4333-8333-333333333333',
+          company_name: 'Alpha Limited',
+          position: null,
+          is_primary: true,
+          is_active: true,
+        },
+      ],
+      contact_methods: [],
+      job_count: 1,
+      phone_call_count: 2,
+    },
+    {
+      person_id: '44444444-4444-4444-8444-444444444444',
+      name: 'Alex Smith',
+      email: 'alex@example.com',
+      is_active: true,
+      created_at: '2026-07-13T00:00:00Z',
+      updated_at: '2026-07-13T00:00:00Z',
+      company_links: [
+        {
+          link_id: '55555555-5555-4555-8555-555555555555',
+          company_id: '66666666-6666-4666-8666-666666666666',
+          company_name: 'Beta Limited',
+          position: null,
+          is_primary: true,
+          is_active: true,
+        },
+      ],
+      contact_methods: [],
+      job_count: 0,
+      phone_call_count: 0,
+    },
+  ],
+  evidence: [{ kind: 'email' as const, normalized_value: 'alex@example.com', owner_count: 2 }],
+}
+
+const EMPTY_RESPONSE = {
+  company_groups: [],
+  person_groups: [],
+  summary: {
+    company_merge_groups: 0,
+    company_review_groups: 0,
+    person_merge_groups: 0,
+    person_review_groups: 0,
+  },
+  checked_at: '2026-07-13T01:00:00Z',
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('duplicate identities report', () => {
+  it('emphasizes grouped exceptions after automatic cleanup is clear', async () => {
+    vi.mocked(api.check_duplicate_identities).mockResolvedValue({
+      ...EMPTY_RESPONSE,
+      person_groups: [REVIEW_PERSON_GROUP],
+      summary: { ...EMPTY_RESPONSE.summary, person_review_groups: 1 },
+    })
+
+    const wrapper = mount(DuplicateIdentitiesPage)
+    await flushPromises()
+
+    expect(api.check_duplicate_identities).toHaveBeenCalledOnce()
+    expect(wrapper.find('[data-automation-id="duplicate-identities-auto-clear"]').exists()).toBe(
+      true,
+    )
+    expect(wrapper.text()).toContain('Needs review')
+    expect(wrapper.text()).toContain('Alex Smith')
+    expect(wrapper.text()).toContain('Alpha Limited')
+    expect(wrapper.findAll('details')).toHaveLength(1)
+  })
+
+  it('warns when an automatic group remains', async () => {
+    vi.mocked(api.check_duplicate_identities).mockResolvedValue({
+      ...EMPTY_RESPONSE,
+      company_groups: [
+        {
+          group_id: 'company-merge-1',
+          fingerprint: 'fingerprint-2',
+          recommendation: 'merge',
+          reason_codes: ['exact_name'],
+          canonical_id: '77777777-7777-4777-8777-777777777777',
+          members: [
+            {
+              company_id: '77777777-7777-4777-8777-777777777777',
+              name: 'Acme Limited',
+              email: 'office@acme.example',
+              address: '1 Test Street',
+              allow_jobs: true,
+              is_account_customer: true,
+              is_supplier: false,
+              xero_archived: false,
+              job_count: 2,
+              contact_names: [],
+            },
+            {
+              company_id: '88888888-8888-4888-8888-888888888888',
+              name: 'Acme Ltd',
+              email: 'office@acme.example',
+              address: '1 Test Street',
+              allow_jobs: true,
+              is_account_customer: true,
+              is_supplier: false,
+              xero_archived: false,
+              job_count: 0,
+              contact_names: [],
+            },
+          ],
+          evidence: [{ kind: 'email', normalized_value: 'office@acme.example', owner_count: 2 }],
+        },
+      ],
+      summary: { ...EMPTY_RESPONSE.summary, company_merge_groups: 1 },
+    })
+
+    const wrapper = mount(DuplicateIdentitiesPage)
+    await flushPromises()
+
+    expect(wrapper.find('[data-automation-id="duplicate-identities-auto-warning"]').exists()).toBe(
+      true,
+    )
+    expect(wrapper.text()).toContain('1 automatic group remains')
+    expect(wrapper.text()).toContain('Automatic matches')
+    expect(wrapper.text()).toContain('Canonical')
+  })
+
+  it('shows the fully clear state when no grouped matches remain', async () => {
+    vi.mocked(api.check_duplicate_identities).mockResolvedValue(EMPTY_RESPONSE)
+
+    const wrapper = mount(DuplicateIdentitiesPage)
+    await flushPromises()
+
+    expect(wrapper.find('[data-automation-id="duplicate-identities-all-clear"]').exists()).toBe(
+      true,
+    )
+    expect(wrapper.text()).toContain('No duplicate company or person groups remain')
+  })
+
+  it('clears stale groups when refreshing fails', async () => {
+    vi.mocked(api.check_duplicate_identities).mockResolvedValueOnce({
+      ...EMPTY_RESPONSE,
+      person_groups: [REVIEW_PERSON_GROUP],
+      summary: { ...EMPTY_RESPONSE.summary, person_review_groups: 1 },
+    })
+
+    const wrapper = mount(DuplicateIdentitiesPage)
+    await flushPromises()
+    expect(wrapper.findAll('details')).toHaveLength(1)
+
+    vi.mocked(api.check_duplicate_identities).mockRejectedValueOnce(new Error('Report failed'))
+    await wrapper.find('[data-automation-id="duplicate-identities-refresh"]').trigger('click')
+    await flushPromises()
+
+    expect(wrapper.findAll('details')).toHaveLength(0)
+    expect(wrapper.find('[data-automation-id="duplicate-identities-error"]').text()).toContain(
+      'Report failed',
+    )
+  })
+})
diff --git a/frontend/src/pages/reports/data-quality/duplicate-identities.vue b/frontend/src/pages/reports/data-quality/duplicate-identities.vue
new file mode 100644
index 000000000..4f3717cfa
--- /dev/null
+++ b/frontend/src/pages/reports/data-quality/duplicate-identities.vue
@@ -0,0 +1,234 @@
+<template>
+  <AppLayout>
+    <div class="h-full w-full overflow-y-auto">
+      <main class="mx-auto flex max-w-7xl flex-col gap-6 px-3 py-8 md:px-8">
+        <header class="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+          <div>
+            <h1 class="flex items-center gap-3 text-3xl font-extrabold text-indigo-700">
+              <Fingerprint class="h-8 w-8 text-amber-500" />
+              Duplicate Identities
+            </h1>
+            <p class="mt-2 text-sm text-slate-600">
+              Compact company and person groups, with automatic matches separated from genuine
+              exceptions.
+            </p>
+          </div>
+          <Button
+            variant="outline"
+            class="self-start text-sm"
+            :disabled="loading"
+            data-automation-id="duplicate-identities-refresh"
+            @click="refreshData"
+          >
+            <RefreshCw class="mr-2 h-4 w-4" :class="{ 'animate-spin': loading }" />
+            Refresh
+          </Button>
+        </header>
+
+        <section class="grid grid-cols-2 gap-3 lg:grid-cols-5" aria-label="Report summary">
+          <SummaryCard label="Company review" :value="summary.company_review_groups" tone="amber" />
+          <SummaryCard label="Person review" :value="summary.person_review_groups" tone="amber" />
+          <SummaryCard
+            label="Company auto"
+            :value="summary.company_merge_groups"
+            :tone="summary.company_merge_groups === 0 ? 'green' : 'red'"
+          />
+          <SummaryCard
+            label="Person auto"
+            :value="summary.person_merge_groups"
+            :tone="summary.person_merge_groups === 0 ? 'green' : 'red'"
+          />
+          <div
+            class="col-span-2 rounded-lg border border-slate-200 bg-white p-4 shadow-sm lg:col-span-1"
+          >
+            <p class="text-sm text-slate-600">Last run</p>
+            <p class="mt-1 text-sm font-semibold text-slate-900">{{ lastRunTime }}</p>
+          </div>
+        </section>
+
+        <div
+          v-if="loading"
+          class="flex min-h-64 items-center justify-center text-xl text-slate-400"
+          data-automation-id="duplicate-identities-loading"
+        >
+          <RefreshCw class="mr-2 h-7 w-7 animate-spin" />
+          Loading duplicate identities…
+        </div>
+
+        <div
+          v-else-if="error"
+          class="flex min-h-64 items-center justify-center text-xl text-red-600"
+          data-automation-id="duplicate-identities-error"
+        >
+          <AlertCircle class="mr-2 h-7 w-7" />
+          {{ error }}
+        </div>
+
+        <template v-else>
+          <div
+            v-if="automaticGroups.length > 0"
+            class="rounded-lg border border-red-300 bg-red-50 p-4 text-red-900"
+            data-automation-id="duplicate-identities-auto-warning"
+          >
+            <div class="flex items-start gap-3">
+              <ShieldAlert class="mt-0.5 h-5 w-5 shrink-0" />
+              <div>
+                <p class="font-semibold">
+                  {{ automaticGroups.length }} automatic
+                  {{ automaticGroups.length === 1 ? 'group remains' : 'groups remain' }}
+                </p>
+                <p class="mt-1 text-sm">
+                  These groups meet the automatic merge rules and should normally be cleared by the
+                  cleanup process. They are shown below for diagnosis, not manual assessment.
+                </p>
+              </div>
+            </div>
+          </div>
+
+          <div
+            v-else
+            class="rounded-lg border border-green-300 bg-green-50 p-4 text-green-900"
+            data-automation-id="duplicate-identities-auto-clear"
+          >
+            <div class="flex items-center gap-3">
+              <CheckCircle2 class="h-5 w-5 shrink-0" />
+              <div>
+                <p class="font-semibold">Automatic duplicates are clear</p>
+                <p class="text-sm">Only genuine exceptions needing a decision appear below.</p>
+              </div>
+            </div>
+          </div>
+
+          <section v-if="reviewGroups.length > 0" class="space-y-3">
+            <div class="flex items-end justify-between gap-4">
+              <div>
+                <h2 class="text-xl font-bold text-slate-900">Needs review</h2>
+                <p class="text-sm text-slate-600">
+                  Shared details conflict or may represent a person legitimately linked to multiple
+                  companies.
+                </p>
+              </div>
+              <span
+                class="rounded-full bg-amber-100 px-3 py-1 text-sm font-semibold text-amber-900"
+              >
+                {{ reviewGroups.length }} groups
+              </span>
+            </div>
+            <IdentityGroupCard
+              v-for="group in reviewGroups"
+              :key="`${group.entityKind}-${group.group.group_id}`"
+              :entity-kind="group.entityKind"
+              :group="group.group"
+            />
+          </section>
+
+          <section v-if="automaticGroups.length > 0" class="space-y-3">
+            <div>
+              <h2 class="text-xl font-bold text-slate-900">Automatic matches</h2>
+              <p class="text-sm text-slate-600">Strong matches awaiting automatic cleanup.</p>
+            </div>
+            <IdentityGroupCard
+              v-for="group in automaticGroups"
+              :key="`${group.entityKind}-${group.group.group_id}`"
+              :entity-kind="group.entityKind"
+              :group="group.group"
+            />
+          </section>
+
+          <div
+            v-if="reviewGroups.length === 0 && automaticGroups.length === 0"
+            class="flex min-h-64 items-center justify-center"
+            data-automation-id="duplicate-identities-all-clear"
+          >
+            <div class="text-center">
+              <CheckCircle2 class="mx-auto mb-4 h-16 w-16 text-green-500" />
+              <h2 class="mb-2 text-2xl font-semibold text-slate-800">All clear</h2>
+              <p class="text-slate-600">No duplicate company or person groups remain.</p>
+            </div>
+          </div>
+        </template>
+      </main>
+    </div>
+  </AppLayout>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import type { z } from 'zod'
+import { AlertCircle, CheckCircle2, Fingerprint, RefreshCw, ShieldAlert } from 'lucide-vue-next'
+import { toast } from 'vue-sonner'
+
+import { api } from '@/api/client'
+import { schemas } from '@/api/generated/api'
+import AppLayout from '@/components/AppLayout.vue'
+import IdentityGroupCard from '@/components/data-quality/IdentityGroupCard.vue'
+import SummaryCard from '@/components/data-quality/SummaryCard.vue'
+import Button from '@/components/ui/button/Button.vue'
+import { formatDateTime } from '@/utils/string-formatting'
+
+type CompanyGroup = z.infer<typeof schemas.DuplicateCompanyGroup>
+type PersonGroup = z.infer<typeof schemas.DuplicatePersonGroup>
+type Summary = z.infer<typeof schemas.DuplicateIdentityReportSummary>
+
+type GroupItem =
+  | { entityKind: 'company'; group: CompanyGroup }
+  | { entityKind: 'person'; group: PersonGroup }
+
+const EMPTY_SUMMARY: Summary = {
+  company_merge_groups: 0,
+  company_review_groups: 0,
+  person_merge_groups: 0,
+  person_review_groups: 0,
+}
+
+const loading = ref(false)
+const error = ref<string | null>(null)
+const companyGroups = ref<CompanyGroup[]>([])
+const personGroups = ref<PersonGroup[]>([])
+const summary = ref<Summary>(EMPTY_SUMMARY)
+const lastRunTime = ref('Never')
+
+const allGroups = computed<GroupItem[]>(() => [
+  ...companyGroups.value.map((group) => ({ entityKind: 'company' as const, group })),
+  ...personGroups.value.map((group) => ({ entityKind: 'person' as const, group })),
+])
+
+const reviewGroups = computed(() =>
+  allGroups.value.filter(({ group }) => group.recommendation === 'review'),
+)
+
+const automaticGroups = computed(() =>
+  allGroups.value.filter(({ group }) => group.recommendation === 'merge'),
+)
+
+async function refreshData(): Promise<void> {
+  loading.value = true
+  error.value = null
+
+  try {
+    const data = await api.check_duplicate_identities()
+    companyGroups.value = data.company_groups
+    personGroups.value = data.person_groups
+    summary.value = data.summary
+    lastRunTime.value = formatDateTime(data.checked_at)
+
+    if (automaticGroups.value.length > 0) {
+      toast.warning(`Found ${automaticGroups.value.length} automatic duplicate groups`)
+    } else if (reviewGroups.value.length > 0) {
+      toast.info(`${reviewGroups.value.length} duplicate identity groups need review`)
+    } else {
+      toast.success('No duplicate identities found')
+    }
+  } catch (err) {
+    companyGroups.value = []
+    personGroups.value = []
+    summary.value = EMPTY_SUMMARY
+    error.value = err instanceof Error ? err.message : 'Failed to load duplicate identities report'
+    toast.error('Failed to load duplicate identities report')
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(refreshData)
+</script>
diff --git a/frontend/src/typed-router.d.ts b/frontend/src/typed-router.d.ts
index 3e9350a41..b4ee8c8fe 100644
--- a/frontend/src/typed-router.d.ts
+++ b/frontend/src/typed-router.d.ts
@@ -157,6 +157,13 @@ declare module 'vue-router/auto-routes' {
       Record<never, never>,
       | never
     >,
+    '/reports/data-quality/duplicate-identities': RouteRecordInfo<
+      '/reports/data-quality/duplicate-identities',
+      '/reports/data-quality/duplicate-identities',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
     '/reports/data-quality/duplicate-phones': RouteRecordInfo<
       '/reports/data-quality/duplicate-phones',
       '/reports/data-quality/duplicate-phones',
@@ -411,6 +418,12 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/reports/data-quality/duplicate-identities.vue': {
+      routes:
+        | '/reports/data-quality/duplicate-identities'
+      views:
+        | never
+    }
     'src/pages/reports/data-quality/duplicate-phones.vue': {
       routes:
         | '/reports/data-quality/duplicate-phones'
diff --git a/poetry.lock b/poetry.lock
index 21a1cb72d..352f88b2d 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -4040,6 +4040,18 @@ files = [
     {file = "mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558"},
 ]
 
+[[package]]
+name = "nicknames"
+version = "1.0.1"
+description = "Hand-curated dataset of English names and nicknames."
+optional = false
+python-versions = ">=3.8"
+groups = ["main"]
+files = [
+    {file = "nicknames-1.0.1-py3-none-any.whl", hash = "sha256:30608a6a50086bb508e6d5f4fb618ef4f988d5604f73ec1ebcccbc92952f9de9"},
+    {file = "nicknames-1.0.1.tar.gz", hash = "sha256:0b599c1ebf6844c5a65659d46d024c46e9c2cf66b3046e119107e82a14598e6a"},
+]
+
 [[package]]
 name = "nodeenv"
 version = "1.10.0"
@@ -7271,4 +7283,4 @@ type = ["pytest-mypy"]
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.12"
-content-hash = "416dcd10b5d9cee885f6079892220488b7e97bd0e31fc3451b4d0fdac6b60d94"
+content-hash = "3ffb13f7b3b981d3048908a0251d65e480083d72adadb91c69623928263a245d"
diff --git a/pyproject.toml b/pyproject.toml
index 873f6af27..1922521e7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -61,6 +61,7 @@ python-stdnum = "^2.1"
 pylint-django = "^2.7.0"
 django-solo = "^2.5.1"
 celery = "^5.5.0"
+nicknames = "^1.0.1"
 
 [tool.poetry.scripts]
 post-install = "scripts.post_install:install_system_deps"  # Script to install system dependencies like poppler-utils
diff --git a/requirements.txt b/requirements.txt
index 728d13cb4..48ef4377f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -121,6 +121,7 @@ multidict==6.7.1 ; python_version >= "3.12" and python_version < "3.14"
 mypy-baseline==0.7.4 ; python_version >= "3.12" and python_version < "4.0"
 mypy-extensions==1.1.0 ; python_version >= "3.12" and python_version < "4.0"
 mypy==2.1.0 ; python_version >= "3.12" and python_version < "4.0"
+nicknames==1.0.1 ; python_version >= "3.12" and python_version < "4.0"
 nodeenv==1.10.0 ; python_version >= "3.12" and python_version < "4.0"
 nplus1==1.1.5 ; python_version >= "3.12" and python_version < "4.0"
 numpy==2.4.4 ; python_version >= "3.12" and python_version < "4.0"

From a8522a464abcca285c9a6ca4f4992f0da09e273d Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 10:42:29 +1200
Subject: [PATCH 22/73] fix: complete KAN-278 production deduplication

---
 .../0008_apply_reviewed_duplicate_cleanup.py  |    1 +
 apps/company/services/__init__.py             |   14 +-
 .../services/kan278_duplicate_cleanup.py      | 3520 ++++++++++++++---
 apps/company/services/person_merge_service.py |    9 +
 .../tests/test_kan278_duplicate_cleanup.py    |   93 +-
 .../tests/test_person_merge_service.py        |   14 +
 6 files changed, 3104 insertions(+), 547 deletions(-)

diff --git a/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
index 0e1cccc36..4baa226e5 100644
--- a/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
+++ b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
@@ -15,6 +15,7 @@ class Migration(migrations.Migration):
 
     dependencies = [
         ("company", "0007_remove_xero_person_identity"),
+        ("accounting", "0003_rename_client_company"),
     ]
 
     operations = [
diff --git a/apps/company/services/__init__.py b/apps/company/services/__init__.py
index ed1efedeb..f268f073e 100644
--- a/apps/company/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -51,7 +51,14 @@
             geocode_address,
             get_api_key,
         )
-        from .kan278_duplicate_cleanup import apply_reviewed_duplicate_cleanup
+        from .kan278_duplicate_cleanup import (
+            CompanyMergeDecision,
+            InvalidLinkDecision,
+            PersonMergeDecision,
+            PersonSelector,
+            RetainedDecision,
+            apply_reviewed_duplicate_cleanup,
+        )
         from .person_merge_service import PersonMergeCounts, merge_people
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
@@ -59,6 +66,7 @@
 
 __all__ = [
     "CompanyMergeCounts",
+    "CompanyMergeDecision",
     "CompanyPhoneAnnotations",
     "CompanyRestService",
     "DuplicateCompanyGroup",
@@ -85,7 +93,11 @@
     "GeocodingError",
     "GeocodingNotConfiguredError",
     "GeocodingResult",
+    "InvalidLinkDecision",
     "PersonMergeCounts",
+    "PersonMergeDecision",
+    "PersonSelector",
+    "RetainedDecision",
     "apply_reviewed_duplicate_cleanup",
     "geocode_address",
     "get_api_key",
diff --git a/apps/company/services/kan278_duplicate_cleanup.py b/apps/company/services/kan278_duplicate_cleanup.py
index 9f24ab28b..b9be6905b 100644
--- a/apps/company/services/kan278_duplicate_cleanup.py
+++ b/apps/company/services/kan278_duplicate_cleanup.py
@@ -1,8 +1,15 @@
-"""Reviewed one-time duplicate cleanup for the KAN-278 production dataset."""
+"""Finite, human-reviewed KAN-278 cleanup for the production dataset.
 
-from collections import defaultdict
-from collections.abc import Iterable
-from uuid import UUID
+The decisions below are data, not matching rules.  Every production candidate was
+reviewed and is either in a named merge decision or in a named retained decision.
+No database identity is embedded here: database IDs are resolved only after the
+human-readable evidence has been checked against the database.
+"""
+
+from dataclasses import dataclass
+
+from django.db import transaction
+from django.db.models import Q
 
 from apps.accounts.models import Staff
 from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
@@ -12,550 +19,3029 @@
 )
 from apps.company.services.person_merge_service import merge_people
 
-CompanyMerge = tuple[str, str]
-PersonLinkEdge = tuple[str, str]
-
-# source Company -> canonical Company. These UUIDs are stable across the
-# client->company relabel and the first-class Person migrations.
-REVIEWED_COMPANY_MERGES: tuple[CompanyMerge, ...] = (
-    (
-        "8a0a7c59-6b87-45d7-82f6-c543b74b37db",
-        "42341b19-8baf-434d-b2c9-fd0aed92a44b",
-    ),  # Northland Roofs
-    (
-        "99c01fb4-a14e-499c-bf4f-7dd1c139242b",
-        "9cca5c95-d4d1-4f7e-a781-eaea26873e06",
-    ),  # ELS NZ
-    (
-        "0aebb7a4-e7e3-443c-a329-6fa9bf4c07a7",
-        "c4fb5c65-278e-4790-9fce-acdd24a5012b",
-    ),  # Interior DB
-    (
-        "44fec154-e91e-41e8-a406-f913740c1258",
-        "94a26554-4758-4339-bfc0-f92067815d47",
-    ),  # Supercity
-    (
-        "59cd4324-98cb-4ea1-9825-dfe01bcc39d2",
-        "b52223eb-aa5d-4d94-9264-e4504baf4b38",
-    ),  # New Generation Operations
-    (
-        "8318321c-919a-440a-96ff-87e3c43e9551",
-        "b3bd1d4e-829f-47c7-a9f0-e77496835c21",
-    ),  # Timeworx
-    (
-        "039e1bc8-9068-464b-9998-a563a69fb6df",
-        "4cb5ef4e-2936-4f05-991f-cc41be8ad54d",
-    ),  # Viking Builders
-    (
-        "92e6e04e-f8e9-4fee-ac2f-5ca375468635",
-        "4d8e32e7-4e34-4e22-8169-91b9e1365579",
-    ),  # Penrose Motors
-    (
-        "d2059e47-da19-4bc1-bcc2-ead96368860b",
-        "c07dc252-d3ed-41c8-bf36-8e5d7e1da3b9",
-    ),  # Marsh Cooper
-    (
-        "6ac46b26-2d76-4cfe-ae85-f057fb98e169",
-        "15b27ab2-3b14-4eeb-bc70-a65c92a8b08a",
-    ),  # Point Maintenance
-    (
-        "c2eda802-c67f-471e-acd0-1d01e97c2162",
-        "15b27ab2-3b14-4eeb-bc70-a65c92a8b08a",
-    ),  # Point Maintenance
-    (
-        "f642cfe5-2a0d-42c1-a7de-24ff5b5ac521",
-        "0833cc79-f9a8-4537-8396-2a6b6040f9de",
-    ),  # Acryfab
-    (
-        "ae5d6422-f67d-463a-a0f9-5f6f1e9d0d99",
-        "67394ffd-13e5-4f1d-8af4-daf92d694e13",
-    ),  # AZ Panels
-    (
-        "588a8268-394c-41a4-aa39-cfcf3903f934",
-        "3fce4f6b-6211-4e18-9e26-5a64955afecf",
-    ),  # Custom Controls
-    (
-        "f29ec9b6-4c6d-46d6-937a-78f431276c1a",
-        "99568812-4f22-4f15-be24-715fb4458977",
-    ),  # Cushman & Wakefield
-    (
-        "581b0b1c-cda6-40f9-87b9-9d56b3902a6d",
-        "49bd07e9-25d1-4d33-b693-35eb2796fbdc",
-    ),  # Church St Panelbeaters
-    (
-        "1650248c-865c-463e-bef9-4374ca74b1de",
-        "1f667c71-3830-451e-96ad-90ec6f3177b2",
-    ),  # Elijah Haridas
-    (
-        "f7a53925-1099-4c8a-b55d-e25094df4bb8",
-        "0f61dc0c-c394-42d2-8d80-d4cdba9451ae",
-    ),  # Richard Pryde
-    (
-        "4bc54f5a-d7df-4e09-9898-4c6c2dd6f18a",
-        "8d35c1c1-2181-4979-8299-549a0556e48d",
-    ),  # Veronica Bartlett
-    (
-        "24ae90b5-4cf2-4958-b1de-287930733dd5",
-        "60b3f0e0-7da5-451d-9fe8-1c139f4fb826",
-    ),  # DGE
-    (
-        "82cdb03c-2590-4cd6-95d0-288aed62e7fb",
-        "245e1a32-dd55-49bd-899b-7f253774d774",
-    ),  # Rauland
-    (
-        "19744741-ad4a-49db-b52d-18ee91b6310a",
-        "d4fa0e82-8ea7-4cea-b755-0fd713f6b65e",
-    ),  # Pacific Bakery
-    (
-        "777b7d0d-2897-480c-a295-6e2e4a984f83",
-        "d4fa0e82-8ea7-4cea-b755-0fd713f6b65e",
-    ),  # Pacific Bakery
-    (
-        "3a189c4e-83f2-4364-b474-2da9403d3e19",
-        "76ec8dd0-20cf-44c0-bdb7-1bc446ce4366",
-    ),  # NZ Starch
-    (
-        "8e1baf74-a1c3-43be-b452-94d211e82401",
-        "7c2bdd26-7135-48a8-a5aa-1b8fbddbf8c5",
-    ),  # LT McGuinness
-    (
-        "511e3350-a2e2-4d9e-b971-5e02fe922dda",
-        "7050c890-8f6e-454f-be9d-d482d1f4270b",
-    ),  # IPL Maintenance
-    (
-        "226e9630-b770-4e99-93ea-9d4c3f4fa021",
-        "7317d696-5090-413b-a756-994c17b3c54e",
-    ),  # Eden Park Panel & Paint
-    (
-        "74deb0d4-5a75-4fd4-abd0-85c716abece2",
-        "75f7972e-4aa2-407a-b5bd-28304c67f6e8",
-    ),  # Garry Lawrence Roofing
-    (
-        "7abbce8d-5ff0-4fdd-8732-ca5ff258aa9e",
-        "a3fe8b47-2cca-4787-8e2d-9713f16703f8",
-    ),  # Gus Kanji
-    (
-        "eb7f98bc-06eb-47c9-99a0-b973e7fc6137",
-        "9c8adc9c-7593-4bac-bbbb-f4a5efe95c06",
-    ),  # Irving
-    (
-        "dea6f7dd-8c8f-47b4-b883-532a009ab11e",
-        "ca3f2cda-b146-4111-868a-893f6ba170ff",
-    ),  # Free Co Flooring
-    (
-        "a4b93d24-ca61-4278-8bf7-92ad4523107b",
-        "a7276a52-09d3-4143-8d7e-7f6f6e716954",
-    ),  # Jenny Stevens
-    (
-        "40e672c4-7332-4eb9-927f-813c20874d43",
-        "ada10565-b1ab-43e3-b0ac-79f2128ceea9",
-    ),  # Jerry Friar
-    (
-        "748550d5-4425-4853-b00b-b6e590e3403b",
-        "e556eab0-0621-4483-82f2-05f116597830",
-    ),  # Wakefield Metals
-    (
-        "0c82cbcc-2189-4869-8cb7-3e4168fe97b9",
-        "f3539c8f-c4eb-4730-bb9a-0e7e468be9a5",
-    ),  # High Mark Foods
-    (
-        "07063260-78ad-4e55-8aba-5854b0dc1e95",
-        "75511302-3ec3-4508-bc02-9f1eadf71fb8",
-    ),  # Jack Lum
-    (
-        "249670e0-27a2-4605-a68f-7eac229a6854",
-        "356b8de2-62be-419a-ac0b-a813c53b0244",
-    ),  # Nick Hansen
-    (
-        "34448f75-ed3e-4ba3-b948-7a2d768a1dad",
-        "cf57a6f9-53b8-4f5a-8eda-435b4d6fb81e",
-    ),  # Rem Wadeh
-    (
-        "7376ed99-6e39-44cc-af00-a785aef0f998",
-        "81475c76-3be9-4c9e-9f74-15e7d232506d",
-    ),  # Proclimb
-    (
-        "4178688e-3111-47f7-b155-e13409bb55e4",
-        "a7c282e9-da5a-46a8-900d-315a2e17557f",
-    ),  # Stephen Carr
-    (
-        "ac2b0365-3069-4c90-940b-2dd56fdbb6ac",
-        "a7c282e9-da5a-46a8-900d-315a2e17557f",
-    ),  # Stephen Carr
-    (
-        "6132ee9a-47fa-4755-93fb-28d054db2744",
-        "42d138e8-33fe-4a88-bc06-36cea6975385",
-    ),  # McAlpine Hussmann
-    (
-        "1628ea3b-72c4-4dfc-b5bd-ac5b57855cce",
-        "7ad6022b-0b09-49e4-92ee-8fa4124f86de",
-    ),  # Wolfgang
-    (
-        "f93353fb-be09-4b98-a2a1-7035017e5ba2",
-        "501c9415-1e34-444b-91a2-b722f28a6fdb",
-    ),  # Bronwyn Jackson
-    (
-        "1c95b84b-dae0-4ace-8ece-329209278264",
-        "730034a7-04f8-4c23-8c42-d8dd49408d1a",
-    ),  # Dave Booth
-    (
-        "b51bf289-cc6d-4137-87e3-0941166bd5a0",
-        "49954c00-0d80-4deb-845f-a52c69373fbe",
-    ),  # Davison Construction
-    (
-        "e747a5e0-746b-4f25-9f09-d70044f3c23f",
-        "82eb2fc3-3e80-4c92-90c5-6bfe92f4874a",
-    ),  # Mike Loomb
-    (
-        "f66dc794-fa95-442e-8475-f8667512bb81",
-        "1785e8e6-2e51-49d8-9c5d-2221359bc2d0",
-    ),  # Pete Pederson
-    (
-        "7c81c774-d986-4ee7-bab1-ca83025bee43",
-        "caed8f25-a71c-4053-878e-301cedb8179f",
-    ),  # Rick Van Swet
-    (
-        "dcdca54c-f588-4991-b3fd-a6317b3ba39b",
-        "c7332cbf-8e19-4bd6-8b72-00ecba0074b4",
-    ),  # Steve Kirby
-    (
-        "d7c2aec4-5dbb-4f84-a4a5-a7a5f5ef9843",
-        "d0868ba1-61a8-4299-ae72-5d36e5d3d6f9",
-    ),  # Lindsay Building Services
-    (
-        "161b2430-db80-4a58-a3d5-a7ffb62c887b",
-        "8ed26fa1-73fd-4c68-a63a-e6423afc3e3b",
-    ),  # PB Traffic
-    (
-        "d998e463-d3db-45d4-8a53-3fd08ab09c53",
-        "23f54e9d-bea3-4d14-bf8f-0dec2be589b8",
-    ),  # NZ Crane
-    (
-        "1a99b409-e72c-46c5-8ee9-fe7f279699ce",
-        "c7efc131-a29d-42e7-a6bd-cb00986d56d9",
-    ),  # Dunninghams
-    (
-        "3882c364-bae8-45cd-a658-85d691b6a108",
-        "e4af558d-b510-42af-b152-935cd426d4a9",
-    ),  # CGO Corporate
-    (
-        "9abdef63-da4c-4a2b-9cf0-4b7a4db91adc",
-        "6177173a-8499-45a3-8aec-03c707aa8ac5",
-    ),  # Watercone
-    (
-        "f9976610-8a0a-4ac1-8298-30c9f3f19254",
-        "b66ac775-90d5-45b3-9a0b-8d89590f59a5",
-    ),  # HTS Group
+
+@dataclass(frozen=True)
+class CompanyMergeDecision:
+    canonical_name: str
+    names: tuple[str, ...]
+    expected_rows: int
+    evidence: str
+
+
+@dataclass(frozen=True)
+class PersonSelector:
+    name: str
+    email: str | None
+    company_name: str | None
+
+
+@dataclass(frozen=True)
+class PersonMergeDecision:
+    canonical: PersonSelector
+    members: tuple[PersonSelector, ...]
+    expected_people: int
+    evidence: str
+
+
+@dataclass(frozen=True)
+class RetainedDecision:
+    names: tuple[str, ...]
+    evidence: str
+
+
+@dataclass(frozen=True)
+class InvalidLinkDecision:
+    company_name: str
+    person_name: str
+    person_email: str | None
+    evidence: str
+
+
+REVIEWED_COMPANY_MERGES: tuple[CompanyMergeDecision, ...] = (
+    CompanyMergeDecision(
+        canonical_name="2Talk Limited",
+        names=("2Talk", "2Talk Limited"),
+        expected_rows=2,
+        evidence="production jobs 2Talk=0, 2Talk Limited=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="acryfab",
+        names=("acryfab", "CASH SALE - BLAYNE NEWTON"),
+        expected_rows=2,
+        evidence="production jobs acryfab=1, CASH SALE - BLAYNE NEWTON=1; shared contact blayne newton; shared email blayne@acryfab.co.nz; shared email domain acryfab.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Actual Building Services",
+        names=("Actual Building Services", "CASH SALE - SHANE ANNISS"),
+        expected_rows=2,
+        evidence="production jobs Actual Building Services=0, CASH SALE - SHANE ANNISS=1; shared email shane.anniss@xtra.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Aesthetix",
+        names=("Aesthetix", "Priel Segev"),
+        expected_rows=2,
+        evidence="production jobs Aesthetix=3, Priel Segev=0; shared email domain aesthetix.co.nz; shared email priel@aesthetix.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Archer Hospitality",
+        names=("Archer Hospitality", "Lionel Don"),
+        expected_rows=2,
+        evidence="production jobs Archer Hospitality=0, Lionel Don=1; shared email domain archerconcepts.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Assa Abloy - Entrance Systems Ltd",
+        names=("Assa Abloy - Entrance Systems Ltd", "Davis"),
+        expected_rows=2,
+        evidence="production jobs Assa Abloy - Entrance Systems Ltd=0, Davis=0; shared email domain assaabloy.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="B C Hastings",
+        names=("B C Hastings", "Brian Hastings", "CASH - SALE - BRIAN HASTINGS"),
+        expected_rows=3,
+        evidence="production jobs B C Hastings=0, Brian Hastings=1, CASH - SALE - BRIAN HASTINGS=0; shared email billieh@xtra.co.nz; shared phone +64221770482",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Bad Girl Creek Production",
+        names=("Bad Girl Creek Production", "Manu One Limited - account closed"),
+        expected_rows=2,
+        evidence="production jobs Bad Girl Creek Production=0, Manu One Limited - account closed=0; shared email gmills989@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Bikaner Foods",
+        names=("Bikaner Foods", "CASH SALE - ASHOKA SHARMA"),
+        expected_rows=2,
+        evidence="production jobs Bikaner Foods=0, CASH SALE - ASHOKA SHARMA=1; shared email ashoknz@yahoo.com; shared email domain yahoo.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Blackstone Project Management",
+        names=("Blackstone Project Management", "Bobby Prajito"),
+        expected_rows=2,
+        evidence="production jobs Blackstone Project Management=3, Bobby Prajito=0; shared email bobby@blackstonepm.co.nz; shared email domain blackstonepm.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="C V Compton Ltd",
+        names=("C V Compton Ltd", "Onsite Mechanics NZ Ltd"),
+        expected_rows=2,
+        evidence="production jobs C V Compton Ltd=1, Onsite Mechanics NZ Ltd=1; shared email domain cvcompton.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Camson Hoist Hire Limited",
+        names=("Camson Hoist Hire Limited", "CASH SALE - Lift truck"),
+        expected_rows=2,
+        evidence="production jobs Camson Hoist Hire Limited=0, CASH SALE - Lift truck=1; shared email domain liftrucks.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - Alex McCormick",
+        names=("CASH SALE - Alex McC", "CASH SALE - Alex McCormick"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Alex McC=0, CASH SALE - Alex McCormick=0; shared phone +64226160300",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - ASSET FORCE",
+        names=("CASH SALE - ASSET FORCE", "CASH SALE - ONE STOP CUTTING SHOP"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - ASSET FORCE=2, CASH SALE - ONE STOP CUTTING SHOP=1; shared email domain assetforce.co.nz; shared email jonas@assetforce.co.nz; shared phone +64277562134",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - AZ PANELS REPAIRS",
+        names=("Azam 021677855", "CASH SALE - AZ PANELS REPAIRS"),
+        expected_rows=2,
+        evidence="production jobs Azam 021677855=1, CASH SALE - AZ PANELS REPAIRS=1; shared phone +6421677855",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - BRONWYN JACKSON",
+        names=("Bronnie 02102255430", "CASH SALE - BRONWYN JACKSON"),
+        expected_rows=2,
+        evidence="production jobs Bronnie 02102255430=1, CASH SALE - BRONWYN JACKSON=2; shared phone +642102255430",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - Church Street Panelbeaters",
+        names=(
+            "CASH SALE - Church St Motors",
+            "CASH SALE - CHURCH ST PANELBEATERS",
+            "CASH SALE - Church Street Panelbeaters",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Church St Motors=3, CASH SALE - CHURCH ST PANELBEATERS=0, CASH SALE - Church Street Panelbeaters=1; shared contact onkar goundar; shared email church.st.panelbeaters@gmail.com; shared phone +64275670142",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - DAVID BOOTH",
+        names=("CASH SALE - Dave Booth", "CASH SALE - DAVID BOOTH"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Dave Booth=1, CASH SALE - DAVID BOOTH=1; shared email carpenterdavebooth@gmail.com; shared phone +642102631588",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - DOT DESIGN SAM GOODRIDGE",
+        names=(
+            "CASH SALE - DOT DEISIGN DAM GOODRIDGE",
+            "CASH SALE - DOT DESIGN SAM GOODRIDGE",
+        ),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - DOT DEISIGN DAM GOODRIDGE=0, CASH SALE - DOT DESIGN SAM GOODRIDGE=1; shared phone +610420355724",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - ELIJAH HARIDAS",
+        names=("CASH SALE - ELIJAH HARIDAS",),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - ELIJAH HARIDAS=0, CASH SALE - ELIJAH HARIDAS=1; shared contact elijah haridas; shared email elijahraulharidas@gmail.com; shared phone +642904302129",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - LIAM GREENWAY",
+        names=("CASH - SALE - Liam Greenway", "CASH SALE - LIAM GREENWAY"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - Liam Greenway=1, CASH SALE - LIAM GREENWAY=1; shared email lbgreenway@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - MARCUS SHELLEY",
+        names=("CASH SALE - MARCUS SHELLEY", "CASH SALE - MARCUS SHELLY"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MARCUS SHELLEY=1, CASH SALE - MARCUS SHELLY=0; shared email theshelleysnz@gmail.com; shared phone +6421979629",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - MARSH COOPER",
+        names=("CASH SALE - MARSH COOPER", "Marsh"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MARSH COOPER=1, Marsh=1; shared phone +6421920315",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - NEW GENERATION OPERATIONS",
+        names=(
+            "Ariki Gate and Cross Stock Depo",
+            "CASH SALE - NEW GENERATION OPERATIONS",
+            "Ian Matthew",
+        ),
+        expected_rows=3,
+        evidence="production jobs Ariki Gate and Cross Stock Depo=0, CASH SALE - NEW GENERATION OPERATIONS=1, Ian Matthew=1; shared email annettematthew1970@gmail.com; shared phone +64274754864",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - ONEHUNGA AUTOMOTIVE NZ LTD",
+        names=(
+            "CASH SALE - ONEHUNGA AUTOMOTIVE NZ LTD",
+            "CASH SALE - ONEHUNGA AUTOMOTIVE NZ LTD - JABIL",
+        ),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - ONEHUNGA AUTOMOTIVE NZ LTD=0, CASH SALE - ONEHUNGA AUTOMOTIVE NZ LTD - JABIL=1; shared email oanz202@gmail.com; shared phone +6421803134",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - REM WADEH",
+        names=("CASH - SALE - RERM WADEH", "CASH SALE - REM WADEH"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - RERM WADEH=0, CASH SALE - REM WADEH=2; shared contact rem wadeh; shared email rem_wadeh@hotmail.com; shared phone +64211523239",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - RICHARD MATHIESON",
+        names=("CASH SALE - REICHARD MATHIESON", "CASH SALE - RICHARD MATHIESON"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - REICHARD MATHIESON=0, CASH SALE - RICHARD MATHIESON=1; shared phone +64272787383",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - Richard Pryde",
+        names=("CASH SALE - Richard Pryde",),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Richard Pryde=1, CASH SALE - Richard Pryde=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - Rick Van Swet",
+        names=("CASH SALE - Rick Van Swet", "Rick vanderset"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Rick Van Swet=1, Rick vanderset=1; shared phone +6421400711",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - Seran",
+        names=("CASH SALE - Seran", "CASH SALE Seran"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Seran=1, CASH SALE Seran=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - SUPERCITY COMMERCIAL INTERIORS LTD",
+        names=(
+            "CASH SALE - Glen Barratt",
+            "CASH SALE - SUPERCITY COMMERCIAL INTERIORS LTD",
+        ),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Glen Barratt=1, CASH SALE - SUPERCITY COMMERCIAL INTERIORS LTD=1; shared phone +64274888111",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - VERONICA BARTLETT",
+        names=("CASH SALE - VERONICA BARTLETT",),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - VERONICA BARTLETT=0, CASH SALE - VERONICA BARTLETT=1",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE - VIKING BUILDERS LTD - PHIL",
+        names=("CASH SALE - Phil", "CASH SALE - VIKING BUILDERS LTD - PHIL", "Phil"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Phil=1, CASH SALE - VIKING BUILDERS LTD - PHIL=1, Phil=2; shared contact phil; shared phone +642108568997",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE- Penrose motors",
+        names=("CASH SALE - STUART WATTS", "CASH SALE- Penrose motors"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - STUART WATTS=1, CASH SALE- Penrose motors=1; shared contact stuart watts; shared phone +64278172546",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CASH SALE. Dema Grant",
+        names=("CASH - SALE - Dee", "CASH SALE. Dema Grant"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - Dee=1, CASH SALE. Dema Grant=1; shared phone +64279186461",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Cassidy Construction Limited",
+        names=("CASH SALE - PETROS PAN", "Cassidy Construction Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - PETROS PAN=1, Cassidy Construction Limited=3; shared email domain cassidy.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CGO Corporate Ltd",
+        names=(
+            "CASH SALE - Mammoth Brands",
+            "CGO (Corporate) Limited",
+            "CGO Corporate Ltd",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Mammoth Brands=0, CGO (Corporate) Limited=0, CGO Corporate Ltd=7; shared contact sarah newman; shared email accsupport@mammothbrands.nz; shared email domain mammothbrands.nz; shared email sarah@mammothbrands.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Classic Buildings Limited",
+        names=("Classic Buildings Limited", "Solarwind"),
+        expected_rows=2,
+        evidence="production jobs Classic Buildings Limited=0, Solarwind=0; shared email david@lm3.co.nz; shared email domain lm3.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Co-Mac (PN) Limited",
+        names=("Co-Mac (PN) Limited", "comac"),
+        expected_rows=2,
+        evidence="production jobs Co-Mac (PN) Limited=0, comac=0; shared email domain comac.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="CSP Pacific",
+        names=("CSP Pacific", "Martin Swart"),
+        expected_rows=2,
+        evidence="production jobs CSP Pacific=0, Martin Swart=0; shared email domain csp.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Cushman and Wakefield New Zealand Limited",
+        names=(
+            "cash sale - ROBERT - CUSHMAN WAKEFIELD",
+            "Cushman and Wakefield New Zealand Limited",
+            "Rusty Tagicakibau",
+        ),
+        expected_rows=3,
+        evidence="production jobs cash sale - ROBERT - CUSHMAN WAKEFIELD=2, Cushman and Wakefield New Zealand Limited=143, Rusty Tagicakibau=1; shared contact robert; shared email domain cushwake.com; shared email rusty.tagicakibau@cushwake.com; shared phone +64212450109",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Custom Controls Ltd",
+        names=("CASH SALE - MARK SEARS", "Custom Controls Ltd"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MARK SEARS=0, Custom Controls Ltd=4; shared contact mark sears; shared email domain customcontrols.co.nz; shared email msears@customcontrols.co.nz; shared phone +6421758031",
+    ),
+    CompanyMergeDecision(
+        canonical_name="D M Dunningham Limited",
+        names=("D M Dunningham Limited", "Dion - Dunninghams"),
+        expected_rows=2,
+        evidence="production jobs D M Dunningham Limited=3, Dion - Dunninghams=0; shared contact dion smit; shared email dion.smit@dunninghams.co.nz; shared email domain dunninghams.co.nz; shared phone +64275556091",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Dave Chown",
+        names=("Dave Chown", "David Chown"),
+        expected_rows=2,
+        evidence="production jobs Dave Chown=0, David Chown=0; shared email tkkid1939@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Davison Construction",
+        names=("CASH SALE - LARS DAVISON", "Davison Construction"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - LARS DAVISON=2, Davison Construction=5; shared email domain davison.kiwi; shared email lars@davison.kiwi; shared phone +64274052692",
+    ),
+    CompanyMergeDecision(
+        canonical_name="DGE Ltd",
+        names=("CASH SALE - Tony Dickson", "DGE Ltd"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Tony Dickson=1, DGE Ltd=0, DGE Ltd=36; shared email domain dge.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Diesel Works",
+        names=("Diesel Works", "Paul Harvey"),
+        expected_rows=2,
+        evidence="production jobs Diesel Works=2, Paul Harvey=0; shared email domain dieselworks.co.nz; shared email paul@dieselworks.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Dormakaba NZ Limited",
+        names=("Brian Pates", "Dormakaba NZ Limited"),
+        expected_rows=2,
+        evidence="production jobs Brian Pates=0, Dormakaba NZ Limited=0; shared email domain dormakaba.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Eden park panel and paint",
+        names=("CASH SALE#edenpark panel and paint", "Eden park panel and paint"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE#edenpark panel and paint=1, Eden park panel and paint=0; shared contact ernesto; shared phone +6421629559",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Electrical Importing Company",
+        names=("Alan", "CASH SALE - Alan", "Electrical Importing Company"),
+        expected_rows=3,
+        evidence="production jobs Alan=0, CASH SALE - Alan=0, Electrical Importing Company=5; shared contact alan kelway; shared email domain eic.nz; shared phone +6496342978",
+    ),
+    CompanyMergeDecision(
+        canonical_name="ELS New Zealand Limited",
+        names=(
+            "CASH SALE - Econic Laundry Solutions",
+            "CASH SALE - ELS New Zealand",
+            "ELS New Zealand Limited",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Econic Laundry Solutions=1, CASH SALE - ELS New Zealand=1, ELS New Zealand Limited=0; shared contact bob lopesi; shared email domain elsnz.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Evans European Limited",
+        names=("Evans European Limited", "Onehunga Car Painters"),
+        expected_rows=2,
+        evidence="production jobs Evans European Limited=0, Onehunga Car Painters=0; shared email domain evans-euro.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Expac Engineering Ltd (new account)",
+        names=(
+            "Expac Engineering Ltd (new account)",
+            "Expac Engineering Services Old account",
+        ),
+        expected_rows=2,
+        evidence="production jobs Expac Engineering Ltd (new account)=0, Expac Engineering Services Old account=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Expol Packaging",
+        names=("Chris Agius", "Expol Packaging"),
+        expected_rows=2,
+        evidence="production jobs Chris Agius=0, Expol Packaging=0; shared email domain expol.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Fab Works Limited",
+        names=("CASH SALE - MOHAMMED KHAN", "Fab Works Limited", "Mohammed Khan"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - MOHAMMED KHAN=0, Fab Works Limited=1, Mohammed Khan=0; shared phone +64212654413",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Field Services",
+        names=("CASH SALE - Field Services", "Field Services"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Field Services=1, Field Services=0; shared email domain fieldservices.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Fieldline NZ Limited",
+        names=("Fieldline - old account not in use", "Fieldline NZ Limited"),
+        expected_rows=2,
+        evidence="production jobs Fieldline - old account not in use=0, Fieldline NZ Limited=0; shared email domain fieldline.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Free Co Flooring",
+        names=("CASH SALE - Jason Hu", "Free Co Flooring"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Jason Hu=0, Free Co Flooring=5; shared contact jason hu; shared email domain freecoflooring.co.nz; shared email jason@freecoflooring.co.nz; shared phone +642108588883",
+    ),
+    CompanyMergeDecision(
+        canonical_name="FUZED LTD T/A GAST AUTOMOTIVE",
+        names=("CASH SALE - Gaast Automotive", "FUZED LTD T/A GAST AUTOMOTIVE"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Gaast Automotive=1, FUZED LTD T/A GAST AUTOMOTIVE=0; shared email domain gast.co.nz; shared email gareth@gast.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Garry Lawrence Roofing",
+        names=("CASH SALE - GARY LAWRENCE", "Garry Lawrence Roofing"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - GARY LAWRENCE=1, Garry Lawrence Roofing=1; shared contact gary lawrence; shared phone +6421969601",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Gilmours Mt Roskill",
+        names=("Gilmours Mt Roskill", "Greg Martin"),
+        expected_rows=2,
+        evidence="production jobs Gilmours Mt Roskill=0, Greg Martin=0; shared email domain gilmours.co.nz; shared email gregory.martin@gilmours.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Gordon & Ryan (2022) Ltd",
+        names=("CASH SALE - SALIM SHAIKH", "Gordon & Ryan (2022) Ltd"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - SALIM SHAIKH=2, Gordon & Ryan (2022) Ltd=0; shared email domain gordonandryan.co.nz; shared email salim@gordonandryan.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Grace International",
+        names=("Grace International", "Vidak Druskovich"),
+        expected_rows=2,
+        evidence="production jobs Grace International=0, Vidak Druskovich=1; shared email vidakdruskovich@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Graphic Packaging International NZ Ltd",
+        names=(
+            "CASH SALE - Graphic Packaging",
+            "Graphic Packaging International NZ Ltd",
+        ),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Graphic Packaging=1, Graphic Packaging International NZ Ltd=0; shared email domain graphicpkg.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Groundtest Equipment",
+        names=("Groundtest Equipment", "Seite-Last Engineering"),
+        expected_rows=2,
+        evidence="production jobs Groundtest Equipment=1, Seite-Last Engineering=1; shared email domain groundtest.co.nz; shared email richard@groundtest.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Gus Kanji",
+        names=("CASH SALE - GUS KANJI", "Gus Kanji"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - GUS KANJI=4, Gus Kanji=5; shared contact gus kanji; shared email domain icloud.com; shared email guskanji@icloud.com; shared phone +64274500727",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Health Pak Limited",
+        names=("Aaron Wilson", "Health Pak Limited"),
+        expected_rows=2,
+        evidence="production jobs Aaron Wilson=1, Health Pak Limited=1; shared phone +64210640540",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Hercules Crane and Rigging",
+        names=("Hercules Crane and Rigging", "Hercules Cranes and Rigging"),
+        expected_rows=2,
+        evidence="production jobs Hercules Crane and Rigging=2, Hercules Cranes and Rigging=0; shared phone +64272398572",
+    ),
+    CompanyMergeDecision(
+        canonical_name="High Mark Foods",
+        names=("CASH SALE - MICHAEL CHEE", "High Mark Foods"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MICHAEL CHEE=2, High Mark Foods=3; shared contact michael chee; shared phone +6421673290",
+    ),
+    CompanyMergeDecision(
+        canonical_name="HTS Group Ltd",
+        names=("Ed Macdonald", "HTS Group Ltd", "HTS Group LTD - Ed Macdonald"),
+        expected_rows=3,
+        evidence="production jobs Ed Macdonald=0, HTS Group Ltd=0, HTS Group LTD - Ed Macdonald=3; shared contact ed macdonald; shared email domain htsgroup.co.nz; shared email emacdonald@htsgroup.co.nz; shared phone +64272412956",
+    ),
+    CompanyMergeDecision(
+        canonical_name="HV Power Measurements and Protection Ltd",
+        names=("HV Power Measurements and Protection Ltd", "Wim Van Den Berg"),
+        expected_rows=2,
+        evidence="production jobs HV Power Measurements and Protection Ltd=15, Wim Van Den Berg=0; shared email domain hvpowerautomation.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Hynds Pipe Systems Limited",
+        names=("CASH - SALE - HYNDS - Kayleen Currie", "Hynds Pipe Systems Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - HYNDS - Kayleen Currie=2, Hynds Pipe Systems Limited=18; shared email domain hynds.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Insurance Resources - PSC Connect NZ Ltd",
+        names=("Insurance Resources - PSC Connect NZ Ltd", "rick"),
+        expected_rows=2,
+        evidence="production jobs Insurance Resources - PSC Connect NZ Ltd=0, rick=0; shared email domain insuranceresources.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="INTERIOR DB LIMITED",
+        names=("CASH SALE - CHRISTOPHER WATT", "INTERIOR DB LIMITED"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - CHRISTOPHER WATT=0, INTERIOR DB LIMITED=3; shared email christopher@interiordb.co.nz; shared email domain interiordb.co.nz; shared phone +64275382037",
+    ),
+    CompanyMergeDecision(
+        canonical_name="IPL Maintenance",
+        names=("CASH SALE - IPL maintenance", "IPL Maintenance"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - IPL maintenance=0, IPL Maintenance=7; shared contact dave allan; shared email domain yahoo.com; shared email iplmaintenance@yahoo.com; shared phone +64274884866",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Irving",
+        names=("CASH SALE - IRVING", "CASH SALE -Irving", "Irving"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - IRVING=2, CASH SALE -Irving=1, Irving=0; shared contact irving; shared email herbpatch20@gmail.com; shared phone +6421378335",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Jack Lum and Co Limited",
+        names=(
+            "CASH SALE - Jack Lum and Co.",
+            "CASH SALE - Mike Lum",
+            "Jack Lum and Co Limited",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Jack Lum and Co.=1, CASH SALE - Mike Lum=0, Jack Lum and Co Limited=0; shared contact mike lum; shared email domain email.com; shared email mikelum@email.com; shared phone +6421301188",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Jenny Stevens",
+        names=("CASH SALE - Jenny stevens", "Jenny Stevens"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Jenny stevens=1, Jenny Stevens=1; shared contact jenny stevens; shared email jennifersteven@gmail.com; shared phone +64210583499",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Jerry Friar",
+        names=("CASH SALE - Jerry Friar", "Jerry Friar"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Jerry Friar=2, Jerry Friar=1; shared contact jerry friar; shared phone +6421563894",
+    ),
+    CompanyMergeDecision(
+        canonical_name="JJ Wafer Biscuits Limited",
+        names=("arshay@wafers.co.nz", "JJ Wafer Biscuits Limited"),
+        expected_rows=2,
+        evidence="production jobs arshay@wafers.co.nz=0, JJ Wafer Biscuits Limited=0; shared email domain wafers.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Jocelyn Croad",
+        names=("CASH - SALE - Jocelyn Croad", "Jocelyn Croad"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - Jocelyn Croad=1, Jocelyn Croad=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="John",
+        names=("CASH SALE - JOHN", "John"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - JOHN=0, John=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Joseph Haydock",
+        names=("Joesph Haydock", "Joseph Haydock"),
+        expected_rows=2,
+        evidence="production jobs Joesph Haydock=1, Joseph Haydock=1; shared phone +642040142511",
+    ),
+    CompanyMergeDecision(
+        canonical_name="K & V Properties Ltd",
+        names=("K & V Properties Ltd", "Vladimir"),
+        expected_rows=2,
+        evidence="production jobs K & V Properties Ltd=0, Vladimir=0; shared email brico191441@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Keith Adams Plumbing",
+        names=("Cougar Trust", "Keith Adams Plumbing"),
+        expected_rows=2,
+        evidence="production jobs Cougar Trust=0, Keith Adams Plumbing=0; shared email plumber.keith@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="KTS Roofing and Spouting",
+        names=("CASH SALE - KIWI TRADE SERVICES", "KTS Roofing and Spouting"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - KIWI TRADE SERVICES=1, KTS Roofing and Spouting=0; shared email domain kts.kiwi",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Lakeland Consulting",
+        names=("Corrin Lakeland", "Lakeland Consulting"),
+        expected_rows=2,
+        evidence="production jobs Corrin Lakeland=2, Lakeland Consulting=0; shared email lakeland@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Laurie Miller",
+        names=("CASH SALE - Laurie Miller", "Laurie Miller"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Laurie Miller=1, Laurie Miller=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Leap Innovation NZ",
+        names=("Ben King", "Leap Innovation NZ"),
+        expected_rows=2,
+        evidence="production jobs Ben King=1, Leap Innovation NZ=1; shared email ben@leapinnovation.nz; shared email domain leapinnovation.nz; shared phone +64275259552",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Lindsay Building Services",
+        names=(
+            "CASH SALE - Lindsay Building Services",
+            "Lindsay Building Services",
+            "Mike Lindsay",
+            "tony m",
+        ),
+        expected_rows=4,
+        evidence="production jobs CASH SALE - Lindsay Building Services=2, Lindsay Building Services=1, Mike Lindsay=0, tony m=1; shared email domain lindsaybuildingservices.co.nz; shared email mike@lindsaybuildingservices.co.nz; shared phone +64212216699",
+    ),
+    CompanyMergeDecision(
+        canonical_name="LT McGuinness Auckland Limited",
+        names=(
+            "CASH SALE - LT MCGUINESS",
+            "CASH SALE - LT MCGUINNESS",
+            "LT McGuinness Auckland Limited",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - LT MCGUINESS=0, CASH SALE - LT MCGUINNESS=0, LT McGuinness Auckland Limited=5; shared email byronc@mcguinness.co.nz; shared email domain mcguinness.co.nz; shared phone +6421527295",
+    ),
+    CompanyMergeDecision(
+        canonical_name="MAG Assembly",
+        names=("CASH SALE - Philip Officer", "MAG Assembly"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Philip Officer=1, MAG Assembly=11; shared email domain magassembly.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Maraia",
+        names=("CASH SALE - Maraia", "Maraia"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Maraia=0, Maraia=0; shared phone +64210341340; shared phone +64341340",
+    ),
+    CompanyMergeDecision(
+        canonical_name="MATERIAL HANDLING SOLUTIONS",
+        names=("Handro", "MATERIAL HANDLING SOLUTIONS"),
+        expected_rows=2,
+        evidence="production jobs Handro=1, MATERIAL HANDLING SOLUTIONS=1; shared phone +64212892852",
+    ),
+    CompanyMergeDecision(
+        canonical_name="MC ALPINE HUSSMANN",
+        names=("CASH SALE - MCALPINE HUSSMANN", "MC ALPINE HUSSMANN"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MCALPINE HUSSMANN=0, MC ALPINE HUSSMANN=5; shared email domain hussmann.com; shared email tim.moore@hussmann.com; shared phone +64272240844",
+    ),
+    CompanyMergeDecision(
+        canonical_name="McConnell Dowell Constructors Limited",
+        names=("CASH SALE - MIKE BONNETTE", "McConnell Dowell Constructors Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MIKE BONNETTE=1, McConnell Dowell Constructors Limited=0; shared email domain mcdgroup.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="McDonald Vague Limited",
+        names=("CASH SALE - McDonald Vague", "McDonald Vague Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - McDonald Vague=1, McDonald Vague Limited=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Mehmet Doker",
+        names=("CASH SALE - MEHMET DOKER", "Mehmet Doker"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - MEHMET DOKER=2, Mehmet Doker=0; shared email mehmetdoker@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Michael Mackinven",
+        names=("CASH SALE - Michael Mackinven", "Michael Mackinven"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Michael Mackinven=4, Michael Mackinven=0; shared email mackinven@hotmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Mike (Michael) Loomb",
+        names=("CASH SALE - Mike Loomb", "Mike (Michael) Loomb"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Mike Loomb=2, Mike (Michael) Loomb=1; shared email michaelloomb@hotmail.com; shared phone +64211951166",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Miles Motor Group",
+        names=("Miles Motor Group", "Paul Curin"),
+        expected_rows=2,
+        evidence="production jobs Miles Motor Group=0, Paul Curin=0; shared email domain miles.co.nz; shared email pcurin@miles.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Motul New Zealand",
+        names=("CASH SALE - CHRIS", "Chris", "Motul New Zealand"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - CHRIS=2, Chris=0, Motul New Zealand=0; shared email domain motul.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="NEP Broadcast Services New Zealand Limited",
+        names=("CASH SALE - Nick Haines", "NEP Broadcast Services New Zealand Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Nick Haines=0, NEP Broadcast Services New Zealand Limited=4; shared contact nick haines",
+    ),
+    CompanyMergeDecision(
+        canonical_name="NEW ZEALAND STARCH",
+        names=("NEW ZEALAND STARCH", "NZ STARCH"),
+        expected_rows=2,
+        evidence="production jobs NEW ZEALAND STARCH=1, NZ STARCH=1; shared contact brett johnson; shared email brett.johnson@nzstarch.co.nz; shared email domain nzstarch.co.nz; shared phone +64273005151",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Nick Hansen",
+        names=("CASH SALE Nick Hansen", "Nick Hansen"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE Nick Hansen=3, Nick Hansen=1; shared contact nick hansen; shared email domain hotmail.co.nz; shared email nickhprogresse@hotmail.co.nz; shared phone +64272968753",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Nordson Australia Pty Limited",
+        names=("Nordson Australia Pty Limited", "Rodney Lambert"),
+        expected_rows=2,
+        evidence="production jobs Nordson Australia Pty Limited=3, Rodney Lambert=0; shared email domain nordson.com; shared email rodney.lambert@nordson.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Northland Roofs NZ",
+        names=("CASH SALE - Northland Roofs NZ", "Northland Roofs NZ"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Northland Roofs NZ=17, Northland Roofs NZ=11; shared contact ace punia; shared email ace.p@northlandroofs.com; shared email domain northlandroofs.com; shared email parisa.m@northlandroofs.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="NZ Crane Hire Limited",
+        names=("Danny - NZ Crane", "NZ Crane Hire Limited", "Scott Sandford"),
+        expected_rows=3,
+        evidence="production jobs Danny - NZ Crane=1, NZ Crane Hire Limited=14, Scott Sandford=0; shared contact danny newberry; shared email domain cranehire.co.nz; shared phone +6421747065",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Oji Fibre Solutions - Penrose Mill",
+        names=("Mark Bendikson", "Oji Fibre Solutions - Penrose Mill"),
+        expected_rows=2,
+        evidence="production jobs Mark Bendikson=0, Oji Fibre Solutions - Penrose Mill=0; shared email domain ojifs.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Omaha Beach Golf Club",
+        names=("Geoff Smith 0274985382", "Omaha Beach Golf Club"),
+        expected_rows=2,
+        evidence="production jobs Geoff Smith 0274985382=1, Omaha Beach Golf Club=0; shared email geoffsmith08@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Onehunga Auto Electric Ltd",
+        names=("CASH SALE-Rob Wedding", "Onehunga Auto Electric Ltd"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE-Rob Wedding=2, Onehunga Auto Electric Ltd=0; shared email onehungaae@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Onsite Team",
+        names=("Onsite Engineering Ltd", "Onsite Team"),
+        expected_rows=2,
+        evidence="production jobs Onsite Engineering Ltd=0, Onsite Team=21; shared contact gary mcnabb; shared email domain onsiteteam.co.nz; shared email gary@onsiteteam.co.nz; shared phone +6421848568",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Owen Dwyer",
+        names=("CASH SALE - Owen Dwyer", "Owen Dwyer"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Owen Dwyer=2, Owen Dwyer=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="pacific bakery Mangere",
+        names=(
+            "CASH SALE-pacific bakery Mangere",
+            "Mangere town bakery",
+            "pacific bakery Mangere",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE-pacific bakery Mangere=2, Mangere town bakery=1, pacific bakery Mangere=3; shared contact andrew winston; shared email domain yahoo.com; shared email pacbakery@yahoo.com; shared phone +64220308090",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Paul De Blois",
+        names=("CASH SALE - PAUL DE BLOIS", "Paul De Blois"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - PAUL DE BLOIS=0, Paul De Blois=1; shared email domain hotmail.co.nz; shared email rsmk1paul@hotmail.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="PB Traffic",
+        names=("PB Traffic", "PB traffic solutions"),
+        expected_rows=2,
+        evidence="production jobs PB Traffic=51, PB traffic solutions=0; shared contact akshay; shared contact emilio rueda; shared phone +64211462453; shared phone +64272097842",
+    ),
+    CompanyMergeDecision(
+        canonical_name="pcs painting",
+        names=("CASH SALE - PCS PAINTING", "pcs painting"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - PCS PAINTING=2, pcs painting=1; shared email pcspainting@xtra.co.nz; shared phone +6421723969",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Penrose Paper Engineering",
+        names=(
+            "CASH SALE - MATT GREEN",
+            "CASH SALE MATT GREEN",
+            "CASH SALE-Kidantics",
+            "Matt Green",
+            "Penrose Paper Engineering",
+        ),
+        expected_rows=5,
+        evidence="production jobs CASH SALE - MATT GREEN=1, CASH SALE MATT GREEN=0, CASH SALE-Kidantics=1, Matt Green=1, Penrose Paper Engineering=2; shared contact matt green; shared email domain kidantics.co.nz; shared email matt@kidantics.co.nz; shared email penrosepaper@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Performance Cleaners",
+        names=("Performance Cleaners", "Peter Barron"),
+        expected_rows=2,
+        evidence="production jobs Performance Cleaners=0, Peter Barron=0; shared email pcebarron@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Pete Pederson",
+        names=("CASH SALE - Pete Pederson", "CASH SALE#Pete Pederson", "Pete Pederson"),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Pete Pederson=1, CASH SALE#Pete Pederson=1, Pete Pederson=0; shared phone +64274300224",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Peter Champion",
+        names=("Peter Champion", "Peter Chapman"),
+        expected_rows=2,
+        evidence="production jobs Peter Champion=0, Peter Chapman=0; shared email ezycall@xtra.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Playhouse Theatre",
+        names=("Playhouse Theatre", "Tony Morrow"),
+        expected_rows=2,
+        evidence="production jobs Playhouse Theatre=0, Tony Morrow=0; shared email mdoherty.pjones@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Point Maintenance",
+        names=("cash sale phillip", "Phillip Whitham", "Point Maintenance"),
+        expected_rows=3,
+        evidence="production jobs cash sale phillip=1, Phillip Whitham=1, Point Maintenance=4; shared contact philip; shared email phil.point@outlook.com; shared phone +64277033500",
+    ),
+    CompanyMergeDecision(
+        canonical_name="PPG Industrial Coatings NZ",
+        names=("BDM - Commercial Transport", "PPG Industrial Coatings NZ"),
+        expected_rows=2,
+        evidence="production jobs BDM - Commercial Transport=0, PPG Industrial Coatings NZ=10; shared email domain ppg.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Proclimb",
+        names=("CASH SALE - SIMON ROSE", "Proclimb"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - SIMON ROSE=1, Proclimb=1; shared contact simon rose; shared email domain proclimb.co.nz; shared email simon.rose@proclimb.co.nz; shared phone +64276642307",
+    ),
+    CompanyMergeDecision(
+        canonical_name="QC Projects",
+        names=("John Williams", "John Williams -", "QC Projects"),
+        expected_rows=3,
+        evidence="production jobs John Williams=0, John Williams -=0, QC Projects=0; shared email domain qcprojects.co.nz; shared email john@qcprojects.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Rauland NZ Limited",
+        names=("CASH SALE - Rauland", "Rauland NZ Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Rauland=3, Rauland NZ Limited=1; shared contact alvin bonita; shared email alvinbonita@rauland.co.nz; shared email domain rauland.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Reece Taituha",
+        names=("CASH SALE - REECE TAITUHA", "Reece Taituha"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - REECE TAITUHA=1, Reece Taituha=0; shared email reecetaituha@live.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="REMUERA PROPERTY SERVICES",
+        names=(
+            "CASH SALE - REMUERA PROPERTY SERVICES",
+            "REMUERA PROPERTY SERVICES",
+            "Terry Brailford",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - REMUERA PROPERTY SERVICES=0, REMUERA PROPERTY SERVICES=2, Terry Brailford=1; shared email rpsltd@xtra.co.nz; shared phone +64274958816",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Rexmark Developments",
+        names=("Rex Sellars", "Rexmark Developments"),
+        expected_rows=2,
+        evidence="production jobs Rex Sellars=0, Rexmark Developments=0; shared email domain sellar.nz; shared email rex@sellar.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Ripout NZ Ltd",
+        names=("CASH SALE - Mark Homan", "Ripout NZ Ltd"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Mark Homan=0, Ripout NZ Ltd=5; shared contact mark homan; shared phone +6421744827",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Robert Grant",
+        names=("Robbie Grant", "Robert Grant"),
+        expected_rows=2,
+        evidence="production jobs Robbie Grant=1, Robert Grant=1; shared phone +6421502802",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Rocket Lab NZ Ltd",
+        names=("CASH SALE - KRISH RUPAN", "Rocket Lab NZ Ltd"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - KRISH RUPAN=1, Rocket Lab NZ Ltd=1; shared email domain rocketlab.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Ron - Landform",
+        names=("Ron - Landform", "Ron Grosse"),
+        expected_rows=2,
+        evidence="production jobs Ron - Landform=0, Ron Grosse=0; shared email landformnz@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="ROOTS R US Ltd - Balli",
+        names=("CASH SALE - BALLI (ROOTS R US LTD)", "ROOTS R US Ltd - Balli"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - BALLI (ROOTS R US LTD)=2, ROOTS R US Ltd - Balli=1; shared phone +64204336699",
+    ),
+    CompanyMergeDecision(
+        canonical_name="SD Aluminium LTD",
+        names=("SD Aluminium", "SD Aluminium LTD"),
+        expected_rows=2,
+        evidence="production jobs SD Aluminium=0, SD Aluminium LTD=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Secair - Compressed Air Solutions",
+        names=("CASH - SALE - Earl Warne", "Secair - Compressed Air Solutions"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - Earl Warne=1, Secair - Compressed Air Solutions=0; shared email domain secair.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Signbiz",
+        names=("CASH - SALE - SIGNBIZ", "Signbiz"),
+        expected_rows=2,
+        evidence="production jobs CASH - SALE - SIGNBIZ=1, Signbiz=0; shared email domain signbiz.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Silent Generator Company",
+        names=("Aaron Thorpe", "Silent Generator Company"),
+        expected_rows=2,
+        evidence="production jobs Aaron Thorpe=0, Silent Generator Company=1; shared email silentgeneratorcompany@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Simon",
+        names=("CASH SALE - Simon", "Simon"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Simon=0, Simon=1",
+    ),
+    CompanyMergeDecision(
+        canonical_name="SMG Ltd",
+        names=("SMG", "SMG Ltd"),
+        expected_rows=2,
+        evidence="production jobs SMG=0, SMG Ltd=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Snowdon Consulting",
+        names=("Snowden", "Snowdon Consulting"),
+        expected_rows=2,
+        evidence="production jobs Snowden=1, Snowdon Consulting=12; shared contact charlie thomlinson; shared phone +642108658458",
+    ),
+    CompanyMergeDecision(
+        canonical_name="St David's Church",
+        names=("David Brown", "St David's Church"),
+        expected_rows=2,
+        evidence="production jobs David Brown=0, St David's Church=0; shared email david-empireroad@hotmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Stainless Products Limited",
+        names=("Blair Tribe", "Stainless Products Limited"),
+        expected_rows=2,
+        evidence="production jobs Blair Tribe=0, Stainless Products Limited=0; shared email domain stainlessproducts.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Steam Brewing Limited",
+        names=("CASH SALE - Steam Brewing Steve Kermode", "Steam Brewing Limited"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Steam Brewing Steve Kermode=1, Steam Brewing Limited=0; shared email domain steambrewing.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Stebbing Recording Centre Ltd",
+        names=("Robert Stebbing", "Stebbing Recording Centre Ltd"),
+        expected_rows=2,
+        evidence="production jobs Robert Stebbing=0, Stebbing Recording Centre Ltd=0; shared email domain stebbing.co.nz; shared email robert@stebbing.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Steel Windows and Doors",
+        names=("Steel Profiles", "Steel Windows and Doors"),
+        expected_rows=2,
+        evidence="production jobs Steel Profiles=0, Steel Windows and Doors=0; shared email domain steelwindowsanddoors.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Stephen (Steve) Carr",
+        names=(
+            "CASH SALE - STEPHEN CARR",
+            "CASH SALE - Steve Carr",
+            "Stephen (Steve) Carr",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - STEPHEN CARR=1, CASH SALE - Steve Carr=2, Stephen (Steve) Carr=2; shared contact stephen carr; shared email daimlersteve@gmail.com; shared phone +64275120443",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Steve Kirby",
+        names=("CASH SALE - Steve Kirby", "Steve Kirby"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Steve Kirby=0, Steve Kirby=2; shared email kirby.nz@gmail.com; shared phone +6421354532",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Straightline Builders",
+        names=("Bryson Rangi", "Straightline Builders"),
+        expected_rows=2,
+        evidence="production jobs Bryson Rangi=0, Straightline Builders=0; shared email bryson@slb.co.nz; shared email domain slb.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Testing client name 3",
+        names=("Testing client name 3", "Testing Corrin 3"),
+        expected_rows=2,
+        evidence="production jobs Testing client name 3=0, Testing Corrin 3=0; shared email lakeland+testing3@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Textile Products 1971 Limited",
+        names=(
+            "CASH SALE - Matt O'Connor",
+            "Kevin Sanderson",
+            "Textile Products 1971 Limited",
+        ),
+        expected_rows=3,
+        evidence="production jobs CASH SALE - Matt O'Connor=1, Kevin Sanderson=0, Textile Products 1971 Limited=6; shared email domain textile.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="The Learning Wave",
+        names=("The Learning Wave", "Yellowjelly Limited"),
+        expected_rows=2,
+        evidence="production jobs The Learning Wave=0, Yellowjelly Limited=0; shared email domain thelearningwave.com; shared email richardm@thelearningwave.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Tim Cooper",
+        names=("CASH SALE - TIM COOPER", "Tim Cooper"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - TIM COOPER=1, Tim Cooper=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Timeworx",
+        names=(
+            "CASH SALE - PAUL O'BRIEN",
+            "Da Vinci Trust",
+            "Paul O'Brien",
+            "Timeworx",
+        ),
+        expected_rows=4,
+        evidence="production jobs CASH SALE - PAUL O'BRIEN=3, Da Vinci Trust=0, Paul O'Brien=0, Timeworx=2; shared contact paul o brien; shared email domain timeworx.co.nz; shared email paul@timeworx.co.nz; shared email paulobrien575@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="TNJ and S A Morris",
+        names=("GLEN MARINE TRUST", "TNJ and S A Morris"),
+        expected_rows=2,
+        evidence="production jobs GLEN MARINE TRUST=0, TNJ and S A Morris=0; shared email tomshirl10@gmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="tom c",
+        names=("thomas", "tom .c", "tom c"),
+        expected_rows=3,
+        evidence="production jobs thomas=1, tom .c=0, tom c=0; shared phone +64220446045",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Total Home Renovation",
+        names=("Ross Collins", "Total Home Renovation"),
+        expected_rows=2,
+        evidence="production jobs Ross Collins=0, Total Home Renovation=0; shared email domain thr.nz; shared email ross@thr.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="TR Group Ltd",
+        names=("Sam Davies", "TR Group Ltd"),
+        expected_rows=2,
+        evidence="production jobs Sam Davies=0, TR Group Ltd=0; shared email domain trgroup.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Twist Prop 1 Limited",
+        names=("Mark Boucher 021922804", "Twist Prop 1 Limited"),
+        expected_rows=2,
+        evidence="production jobs Mark Boucher 021922804=0, Twist Prop 1 Limited=0; shared email boucher@actrix.co.nz; shared email domain actrix.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Ultralon Foam International",
+        names=("Peter Manhire", "Ultralon Foam International"),
+        expected_rows=2,
+        evidence="production jobs Peter Manhire=1, Ultralon Foam International=1; shared contact peter manhire; shared phone +6421642273",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Vat Cleaning Services",
+        names=("Kevin Gardiner", "Vat Cleaning Services"),
+        expected_rows=2,
+        evidence="production jobs Kevin Gardiner=0, Vat Cleaning Services=0; shared email kevin.vatclean@xtra.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Vern Patel",
+        names=("CASH SALE - Vern Patel", "Vern Patel"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - Vern Patel=1, Vern Patel=0; shared email vern.patel@hotmail.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Vulcan Steel Limited",
+        names=(
+            "Vulcan Steel Limited",
+            "Vulcan Ullrich Aluminium - do not use 2763789 onehunga",
+        ),
+        expected_rows=2,
+        evidence="production jobs Vulcan Steel Limited=0, Vulcan Ullrich Aluminium - do not use 2763789 onehunga=0; shared email accounts.nzl@vulcan.co; shared email domain vulcan.co",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Wakefield Metals",
+        names=("CASH SALE - WAKEFIELDS METALS", "Wakefield Metals"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - WAKEFIELDS METALS=0, Wakefield Metals=2; shared email domain wmetals.co.nz; shared email matthew.macdonald@wmetals.co.nz; shared phone +64212426732",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Wallace Investments Ltd",
+        names=("Cedric/Wallace Investments", "Wallace Investments Ltd"),
+        expected_rows=2,
+        evidence="production jobs Cedric/Wallace Investments=0, Wallace Investments Ltd=0; shared email domain wil.stevedores.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Walter and Wild Limited",
+        names=("Nick Pretscherer", "Nicklaus Pretscherer", "Walter and Wild Limited"),
+        expected_rows=3,
+        evidence="production jobs Nick Pretscherer=0, Nicklaus Pretscherer=0, Walter and Wild Limited=3; shared email domain walterandwild.com; shared email nicklausp@walterandwild.com",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Watercone ltd (Neville)",
+        names=("The water cone", "Watercone ltd (Neville)"),
+        expected_rows=2,
+        evidence="production jobs The water cone=1, Watercone ltd (Neville)=2; shared contact neville; shared phone +6421922819",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Wolfgang Schenk",
+        names=("CASH SALE - WOLFGANG", "Wolfgang Schenk"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - WOLFGANG=2, Wolfgang Schenk=1; shared contact wolfgang; shared phone +64211253754",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Wright Panel and Paint",
+        names=("CASH SALE - WRIGHT PANEL AND PAINT", "Wright Panel and Paint"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - WRIGHT PANEL AND PAINT=1, Wright Panel and Paint=0; shared email wcpp@xtra.co.nz",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Xero (NZ) Limited",
+        names=("Xero (NZ) Limited", "Xero NZ"),
+        expected_rows=2,
+        evidence="production jobs Xero (NZ) Limited=0, Xero NZ=0",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Yoshiki Fujimoto",
+        names=("CASH SALE - YOSHIKI FUJIMOTO", "Yoshiki Fujimoto"),
+        expected_rows=2,
+        evidence="production jobs CASH SALE - YOSHIKI FUJIMOTO=0, Yoshiki Fujimoto=2",
+    ),
+)
+
+REVIEWED_PERSON_MERGES: tuple[PersonMergeDecision, ...] = (
+    PersonMergeDecision(
+        canonical=PersonSelector("Aaron Williams", "aaron.w@dge.nz", "DGE Ltd"),
+        members=(
+            PersonSelector("Aaron Williams", None, "Auckland Airport Limited"),
+            PersonSelector("Aaron Williams", "aaron.w@dge.nz", "DGE Ltd"),
+            PersonSelector("Aarron Williams", None, "DGE Ltd"),
+        ),
+        expected_people=3,
+        evidence="production jobs Aaron Williams=1, Aaron Williams=24, Aarron Williams=1; shared phone +64274783139",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "ACE PUNIA", "ace.p@northlandroofs.com", "CASH SALE - Northland Roofs NZ"
+        ),
+        members=(
+            PersonSelector(
+                "ACE PUNIA", "ace.p@northlandroofs.com", "Northland Roofs NZ"
+            ),
+            PersonSelector(
+                "ACE PUNIA",
+                "ace.p@northlandroofs.com",
+                "CASH SALE - Northland Roofs NZ",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs ACE PUNIA=1, ACE PUNIA=7; shared email ace.p@northlandroofs.com; shared phone +642108225902",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Akshay", None, "PB Traffic"),
+        members=(
+            PersonSelector("Akshay", None, "PB Traffic"),
+            PersonSelector("Akshay", None, "PB traffic solutions"),
+            PersonSelector("AKSHAY GUPTE", "akshay@pbtraffic.co.nz", "PB Traffic"),
+        ),
+        expected_people=3,
+        evidence="production jobs Akshay=22, Akshay=1, AKSHAY GUPTE=17; shared phone +64211462453",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Alan Kelway", None, "Electrical Importing Company"),
+        members=(
+            PersonSelector("Alan Kelway", None, "Electrical Importing Company"),
+            PersonSelector("Alan Kelway", "alan@eicnz.com", "CASH SALE - Alan"),
+        ),
+        expected_people=2,
+        evidence="production jobs Alan Kelway=4, Alan Kelway=0",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Alvin Bonita", "AlvinBonita@rauland.co.nz", "CASH SALE - Rauland"
+        ),
+        members=(
+            PersonSelector(
+                "Alvin Bonita", "AlvinBonita@rauland.co.nz", "CASH SALE - Rauland"
+            ),
+            PersonSelector(
+                "Alvin Bonita", "AlvinBonita@rauland.co.nz", "Rauland NZ Limited"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Alvin Bonita=3, Alvin Bonita=0; shared email alvinbonita@rauland.co.nz",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Andrew Winston", "pacbakery@yahoo.com", "pacific bakery Mangere"
+        ),
+        members=(
+            PersonSelector("Andrew", None, "Mangere town bakery"),
+            PersonSelector(
+                "Andrew Winston", "pacbakery@yahoo.com", "pacific bakery Mangere"
+            ),
+            PersonSelector(
+                "Andrew Winston",
+                "pacbakery@yahoo.com",
+                "CASH SALE-pacific bakery Mangere",
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs Andrew=1, Andrew Winston=3, Andrew Winston=1; shared email pacbakery@yahoo.com; shared phone +64220308090",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Angela", "Angela.Malden@hynds.co.nz", "Hynds Pipe Systems Limited"
+        ),
+        members=(
+            PersonSelector(
+                "Angela", "Angela.Malden@hynds.co.nz", "Hynds Pipe Systems Limited"
+            ),
+            PersonSelector(
+                "Angela Madden",
+                "Angela.Malden@hynds.co.nz",
+                "Hynds Pipe Systems Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Angela=1, Angela Madden=0; shared email angela.malden@hynds.co.nz",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Arno Eramus", None, "HV Power Measurements and Protection Ltd"
+        ),
+        members=(
+            PersonSelector(
+                "Arno Eramus", None, "HV Power Measurements and Protection Ltd"
+            ),
+            PersonSelector(
+                "Arno Erasmus",
+                "arnoe@hvpowerautomation.com",
+                "HV Power Measurements and Protection Ltd",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Arno Eramus=2, Arno Erasmus=1; shared phone +64212429114",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Arron Brown", "Arron@solutionzelectrical.co.nz", "CASH SALE - Arron Brown"
+        ),
+        members=(
+            PersonSelector(
+                "Aaron Brown",
+                "aaron@solutionzelectrical.co.nz",
+                "CASH SALE - Arron Brown",
+            ),
+            PersonSelector(
+                "Arron Brown",
+                "Arron@solutionzelectrical.co.nz",
+                "CASH SALE - Arron Brown",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Aaron Brown=0, Arron Brown=1; shared phone +6421572121",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "AZAM SHAH", "azampanelbeater@hotmail.copm", "CASH SALE - AZ PANELS REPAIRS"
+        ),
+        members=(
+            PersonSelector("AZAM", "azampanelbeater@hotmail.com", "Azam 021677855"),
+            PersonSelector(
+                "AZAM SHAH",
+                "azampanelbeater@hotmail.copm",
+                "CASH SALE - AZ PANELS REPAIRS",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs AZAM=1, AZAM SHAH=1; shared phone +6421677855",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Ben King", None, "Snowdon Consulting"),
+        members=(
+            PersonSelector("Ben King", None, "Snowdon Consulting"),
+            PersonSelector("Ben King", "ben@leapinnovation.nz", "Ben King"),
+        ),
+        expected_people=2,
+        evidence="production jobs Ben King=1, Ben King=1; shared phone +64275259552",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Blayne Newton", None, "acryfab"),
+        members=(
+            PersonSelector("Blayne Newton", None, "acryfab"),
+            PersonSelector(
+                "BLAYNE NEWTON", "BLAYNE@ACRYFAB.CO.NZ", "CASH SALE - BLAYNE NEWTON"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Blayne Newton=1, BLAYNE NEWTON=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Bob Lopesi", "spares@elsnz.co.nz", "CASH SALE - ELS New Zealand"
+        ),
+        members=(
+            PersonSelector(
+                "Bob Lopesi", "Bob.Lopesi@elsnz.co.nz", "ELS New Zealand Limited"
+            ),
+            PersonSelector(
+                "Bob Lopesi", "Bob@elsnz.co.nz", "CASH SALE - Econic Laundry Solutions"
+            ),
+            PersonSelector(
+                "Bob Lopesi", "spares@elsnz.co.nz", "CASH SALE - ELS New Zealand"
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs Bob Lopesi=0, Bob Lopesi=1, Bob Lopesi=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Bobby", None, "Blackstone Project Management"),
+        members=(
+            PersonSelector("Bobby", None, "Blackstone Project Management"),
+            PersonSelector("Bobby", None, "MSM (Shop)"),
+            PersonSelector("Bobby prajitno", None, "Blackstone Project Management"),
+        ),
+        expected_people=3,
+        evidence="production jobs Bobby=2, Bobby=1, Bobby prajitno=1; shared phone +642108817930",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "BRETT JOHNSON", "brett.johnson@nzstarch.co.nz", "NZ STARCH"
+        ),
+        members=(
+            PersonSelector(
+                "BRETT JOHNSON", "brett.johnson@nzstarch.co.nz", "NZ STARCH"
+            ),
+            PersonSelector(
+                "BRETT JOHNSON", "brett@nzstarch.co.nz", "NEW ZEALAND STARCH"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs BRETT JOHNSON=1, BRETT JOHNSON=1; shared phone +64273005151",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "BRONNY JACKSON",
+            "bronwyn.jackson@xtra.co.nz",
+            "CASH SALE - BRONWYN JACKSON",
+        ),
+        members=(
+            PersonSelector("Bronnie", None, "Bronnie 02102255430"),
+            PersonSelector(
+                "BRONNY JACKSON",
+                "bronwyn.jackson@xtra.co.nz",
+                "CASH SALE - BRONWYN JACKSON",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Bronnie=1, BRONNY JACKSON=2; shared phone +642102255430",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "BYRON CRAWFORD",
+            "ByronC@mcguinness.co.nz",
+            "LT McGuinness Auckland Limited",
+        ),
+        members=(
+            PersonSelector(
+                "BYRON", "ByronC@mcguinness.co.nz", "CASH SALE - LT MCGUINESS"
+            ),
+            PersonSelector(
+                "BYRON CRAWFORD",
+                "ByronC@mcguinness.co.nz",
+                "LT McGuinness Auckland Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs BYRON=0, BYRON CRAWFORD=4; shared email byronc@mcguinness.co.nz; shared phone +6421527295",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Charlie Thomlinson", None, "Snowdon Consulting"),
+        members=(
+            PersonSelector("Charlie", None, "Snowdon Consulting"),
+            PersonSelector("Charlie Thomlinson", None, "Snowdon Consulting"),
+            PersonSelector("Charlie Thomlinson", None, "Snowden"),
+        ),
+        expected_people=3,
+        evidence="production jobs Charlie=1, Charlie Thomlinson=6, Charlie Thomlinson=1; shared phone +642108658458",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Chris Baybut",
+            "Chris.Baybut@cushwake.com",
+            "Cushman and Wakefield New Zealand Limited",
+        ),
+        members=(
+            PersonSelector("CHRIS", None, "Cushman and Wakefield New Zealand Limited"),
+            PersonSelector(
+                "Chris Baybut",
+                "Chris.Baybut@cushwake.com",
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+            PersonSelector(
+                "Cushman wakefield Chris",
+                None,
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs CHRIS=1, Chris Baybut=6, Cushman wakefield Chris=1; shared phone +64274558373",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "CHRISTOPHER WATT", "christopher@interiordb.co.nz", "INTERIOR DB LIMITED"
+        ),
+        members=(
+            PersonSelector(
+                "Chris Watt",
+                "christopher@interiordb.co.nz",
+                "CASH SALE - CHRISTOPHER WATT",
+            ),
+            PersonSelector(
+                "CHRISTOPHER WATT",
+                "christopher@interiordb.co.nz",
+                "INTERIOR DB LIMITED",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Chris Watt=0, CHRISTOPHER WATT=3; shared email christopher@interiordb.co.nz; shared phone +64275382037",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "CRAIG BOYD", "dexterdut@gmail.com", "CASH SALE - CRAIG BOYD"
+        ),
+        members=(
+            PersonSelector(
+                "CRAIG BOYD", "dexterdut@gmail.com", "CASH SALE - CRAIG BOYD"
+            ),
+            PersonSelector(
+                "CRAIR BOYD", "dexterdut@gmail.com", "CASH SALE - CRAIG BOYD"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs CRAIG BOYD=0, CRAIR BOYD=1; shared email dexterdut@gmail.com",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Dane Charman", None, "Direct Control"),
+        members=(
+            PersonSelector("DANE CHARMAN", None, "Direct Control"),
+            PersonSelector("Dane Charman", None, "Direct Control"),
+        ),
+        expected_people=2,
+        evidence="production jobs DANE CHARMAN=0, Dane Charman=2",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Danny Newberry", "djnewberry1@gmail.com", "NZ Crane Hire Limited"
+        ),
+        members=(
+            PersonSelector(
+                "Danny Newberry", "djnewberry1@gmail.com", "NZ Crane Hire Limited"
+            ),
+            PersonSelector(
+                "DANNY NEWBERRY", "djnewberry1@gmail.com", "Danny - NZ Crane"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Danny Newberry=3, DANNY NEWBERRY=1; shared phone +6421747065",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Dave", None, "CASH SALE - Dave Booth"),
+        members=(
+            PersonSelector("Dave", None, "CASH SALE - Dave Booth"),
+            PersonSelector(
+                "DAVID BOOTH", "CARPENTERDAVEBOOTH@GMAIL.COM", "CASH SALE - DAVID BOOTH"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Dave=1, DAVID BOOTH=1; shared phone +642102631588",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Dave", None, "Guardsman Security Services Limited"),
+        members=(
+            PersonSelector("Dave", None, "Guardsman Security Services Limited"),
+            PersonSelector("DAVE YANALA", None, "Kiwi Alarms Ltd"),
+            PersonSelector("DEV YANDA", None, "Guardsman Security Services Limited"),
+        ),
+        expected_people=3,
+        evidence="production jobs Dave=9, DAVE YANALA=0, DEV YANDA=1; shared phone +64225084642",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Dave Allan", "iplmaintenance@yahoo.com", "IPL Maintenance"
+        ),
+        members=(
+            PersonSelector(
+                "Dave Allan", "iplmaintenance@yahoo.com", "CASH SALE - IPL maintenance"
+            ),
+            PersonSelector("Dave Allan", "iplmaintenance@yahoo.com", "IPL Maintenance"),
+        ),
+        expected_people=2,
+        evidence="production jobs Dave Allan=1, Dave Allan=6; shared email iplmaintenance@yahoo.com; shared phone +64274884866",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "David White", "David.White@fisherpaykel.com", "Fisher and Paykel"
+        ),
+        members=(
+            PersonSelector(
+                "david white", "David.White@fisherpaykel.com", "Fisher and Paykel"
+            ),
+            PersonSelector(
+                "David White", "David.White@fisherpaykel.com", "Fisher and Paykel"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs david white=0, David White=13; shared email david.white@fisherpaykel.com",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Dion smit .", "dion.smit@dunninghams.co.nz", "D M Dunningham Limited"
+        ),
+        members=(
+            PersonSelector(
+                "DION SMIT", "dion.smit@dunninghams.co.nz", "Dion - Dunninghams"
+            ),
+            PersonSelector(
+                "Dion smit .", "dion.smit@dunninghams.co.nz", "D M Dunningham Limited"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs DION SMIT=0, Dion smit .=2; shared email dion.smit@dunninghams.co.nz; shared phone +64275556091",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "ED MACDONALD", "EMacDonald@htsgroup.co.nz", "HTS Group LTD - Ed Macdonald"
+        ),
+        members=(
+            PersonSelector(
+                "ED MACDONALD",
+                "EMacDonald@htsgroup.co.nz",
+                "HTS Group LTD - Ed Macdonald",
+            ),
+            PersonSelector(
+                "Ed Macdonald", "emacdonald@htsgroup.co.nz", "HTS Group Ltd"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs ED MACDONALD=1, Ed Macdonald=0; shared email emacdonald@htsgroup.co.nz; shared phone +64272412956",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Edwin Rysenberry", "erysenbry@mac.com", "CASH SALE - Edwin Rysenberry"
+        ),
+        members=(
+            PersonSelector(
+                "Edin Rysenberry", "erysenbry@mac.com", "CASH SALE - Edwin Rysenberry"
+            ),
+            PersonSelector(
+                "Edwin Rysenberry", "erysenbry@mac.com", "CASH SALE - Edwin Rysenberry"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Edin Rysenberry=0, Edwin Rysenberry=1; shared email erysenbry@mac.com; shared phone +6421731454",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "ELIJAH HARIDAS",
+            "ELIJAHRAULHARIDAS@GMAIL.COM",
+            "CASH SALE - ELIJAH HARIDAS",
+        ),
+        members=(
+            PersonSelector(
+                "ELIJAH HARIDAS",
+                "ELIJAHRAULHARIDAS@GMAIL.COM",
+                "CASH SALE - ELIJAH HARIDAS",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs ELIJAH HARIDAS=0, ELIJAH HARIDAS=1; shared email elijahraulharidas@gmail.com; shared phone +642904302129",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("EMILIO RUEDA", None, "PB Traffic"),
+        members=(
+            PersonSelector("EMILIO RUEDA", None, "PB Traffic"),
+            PersonSelector("EMILIO RUEDA", None, "PB traffic solutions"),
+        ),
+        expected_people=2,
+        evidence="production jobs EMILIO RUEDA=1, EMILIO RUEDA=0; shared phone +64272097842",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Ernesto", None, "CASH SALE#edenpark panel and paint"),
+        members=(
+            PersonSelector("Ernesto", None, "CASH SALE#edenpark panel and paint"),
+            PersonSelector("Ernesto", None, "Eden park panel and paint"),
+        ),
+        expected_people=2,
+        evidence="production jobs Ernesto=1, Ernesto=0; shared phone +6421629559",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Gareth Taripo", "gareth@gast.co.nz", "CASH SALE - Gaast Automotive"
+        ),
+        members=(
+            PersonSelector("Gareth", None, "CASH SALE - Gaast Automotive"),
+            PersonSelector(
+                "Gareth Taripo", "gareth@gast.co.nz", "CASH SALE - Gaast Automotive"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Gareth=0, Gareth Taripo=1; shared phone +64212616893",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Gary Lawrence", None, "CASH SALE - GARY LAWRENCE"),
+        members=(
+            PersonSelector("Gary Lawrence", None, "CASH SALE - GARY LAWRENCE"),
+            PersonSelector("Gary Lawrence", None, "Garry Lawrence Roofing"),
+        ),
+        expected_people=2,
+        evidence="production jobs Gary Lawrence=1, Gary Lawrence=1; shared phone +6421969601",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Gary McNabb", "gary@onsiteteam.co.nz", "Onsite Team"),
+        members=(
+            PersonSelector(
+                "Gary Mcnabb", "gary@onsiteteam.co.nz", "Onsite Engineering Ltd"
+            ),
+            PersonSelector("Gary McNabb", "gary@onsiteteam.co.nz", "Onsite Team"),
+        ),
+        expected_people=2,
+        evidence="production jobs Gary Mcnabb=0, Gary McNabb=18; shared email gary@onsiteteam.co.nz; shared phone +6421848568",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Geoff", None, "Geoff Bates"),
+        members=(
+            PersonSelector("Geoff", None, "Geoff Bates"),
+            PersonSelector("Geoff Bates", None, "Geoff Bates"),
+        ),
+        expected_people=2,
+        evidence="production jobs Geoff=1, Geoff Bates=1; shared phone +64204762687",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "GINA GASCOIGNE",
+            "gina.gascoigne@aucklandcouncil.govt.nz",
+            "Auckland Council",
+        ),
+        members=(
+            PersonSelector(
+                "GINA GASCOIGNE",
+                "gina.gascoigne@aucklandcouncil.govt.nz",
+                "Auckland Council",
+            ),
+            PersonSelector(
+                "Gina Gascoigne",
+                "gina.gascoigne@aucklandcouncil.govt.nz",
+                "Auckland Council",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs GINA GASCOIGNE=1, Gina Gascoigne=0; shared email gina.gascoigne@aucklandcouncil.govt.nz",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Glen Barratt", "fury@xtra.co.nz", "CASH SALE - Glen Barratt"
+        ),
+        members=(
+            PersonSelector(
+                "Glen Barratt", "fury@xtra.co.nz", "CASH SALE - Glen Barratt"
+            ),
+            PersonSelector(
+                "GLENN BARRATT",
+                "fury@xtra.co.nz",
+                "CASH SALE - SUPERCITY COMMERCIAL INTERIORS LTD",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Glen Barratt=1, GLENN BARRATT=1; shared phone +64274888111",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Graeme", "onehungacarclinic@xtra.co.nz", "Onehunga Car Services Limited"
+        ),
+        members=(
+            PersonSelector(
+                "Graeme",
+                "onehungacarclinic@xtra.co.nz",
+                "Onehunga Car Services Limited",
+            ),
+            PersonSelector(
+                "Graeme Mills",
+                "onehunga.carclinic@xtra.co.nz",
+                "Onehunga Car Services Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Graeme=3, Graeme Mills=2; shared phone +6496342207",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "GUS KANJI", "guskanji@icloud.com", "CASH SALE - GUS KANJI"
+        ),
+        members=(
+            PersonSelector("GUS KANJI", "guskanji@icloud.com", "CASH SALE - GUS KANJI"),
+            PersonSelector("Gus Kanji", "guskanji@icloud.com", "Gus Kanji"),
+        ),
+        expected_people=2,
+        evidence="production jobs GUS KANJI=4, Gus Kanji=2; shared email guskanji@icloud.com; shared phone +64274500727",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "HANDRO BIEWENGA", None, "MATERIAL HANDLING SOLUTIONS"
+        ),
+        members=(
+            PersonSelector("Handro", None, "Handro"),
+            PersonSelector("HANDRO BIEWENGA", None, "MATERIAL HANDLING SOLUTIONS"),
+        ),
+        expected_people=2,
+        evidence="production jobs Handro=1, HANDRO BIEWENGA=1; shared phone +64212892852",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("HARSH", None, "Kiwi Alarms Ltd"),
+        members=(
+            PersonSelector("HARSH", None, "Kiwi Alarms Ltd"),
+            PersonSelector("HARSH", None, "Guardsman Security Services Limited"),
+        ),
+        expected_people=2,
+        evidence="production jobs HARSH=0, HARSH=0",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Henry", None, "Orams Marine Ltd"),
+        members=(
+            PersonSelector("Henry", None, "Orams Marine Ltd"),
+            PersonSelector("Henry.", None, "Orams Marine Ltd"),
+        ),
+        expected_people=2,
+        evidence="production jobs Henry=3, Henry.=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "IAIN MATTHEW",
+            "ANNETTEMATTHEW1970@GMAIL.COM",
+            "CASH SALE - NEW GENERATION OPERATIONS",
+        ),
+        members=(
+            PersonSelector(
+                "IAIN MATTHEW",
+                "ANNETTEMATTHEW1970@GMAIL.COM",
+                "CASH SALE - NEW GENERATION OPERATIONS",
+            ),
+            PersonSelector(
+                "IAN MATTHEW", "annettematthew1970@gmail.com", "Ian Matthew"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs IAIN MATTHEW=1, IAN MATTHEW=1; shared phone +64274754864",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("IRVING", None, "CASH SALE - IRVING"),
+        members=(
+            PersonSelector("IRVING", None, "CASH SALE - IRVING"),
+            PersonSelector("Irving", None, "CASH SALE -Irving"),
+        ),
+        expected_people=2,
+        evidence="production jobs IRVING=2, Irving=1; shared phone +6421378335",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Jason Hu", None, "Free Co Flooring"),
+        members=(
+            PersonSelector("Jason Hu", None, "Free Co Flooring"),
+            PersonSelector(
+                "jason Hu", "jason@freecoflooring.co.nz", "CASH SALE - Jason Hu"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Jason Hu=4, jason Hu=0; shared phone +642108588883",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Jenny Stevens", None, "Jenny Stevens"),
+        members=(
+            PersonSelector("Jenny Stevens", None, "Jenny Stevens"),
+            PersonSelector(
+                "Jenny Stevens", "jennifersteven@gmail.com", "CASH SALE - Jenny stevens"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Jenny Stevens=1, Jenny Stevens=1; shared phone +64210583499",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Jerry Friar", None, "Jerry Friar"),
+        members=(
+            PersonSelector("Jerry Friar", None, "Jerry Friar"),
+            PersonSelector(
+                "JERRY FRIAR",
+                "jerry.friar@jameshardie.co.nz",
+                "CASH SALE - Jerry Friar",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Jerry Friar=1, JERRY FRIAR=1; shared phone +6421563894",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "John Blacklock", "john@originbuild.co.nz", "Origin Build"
+        ),
+        members=(
+            PersonSelector("John Blacklock", "john@originbuild.co.nz", "Origin Build"),
+            PersonSelector("John Laycock", None, "Origin Build"),
+        ),
+        expected_people=2,
+        evidence="production jobs John Blacklock=2, John Laycock=1; shared phone +64212461388",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Joseph Haydock", None, "Joseph Haydock"),
+        members=(
+            PersonSelector("Joesph Haydock", None, "Joesph Haydock"),
+            PersonSelector("Joseph Haydock", None, "Joseph Haydock"),
+        ),
+        expected_people=2,
+        evidence="production jobs Joesph Haydock=1, Joseph Haydock=1; shared phone +642040142511",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Josh Loughnan", "josh@wekatravel.com", "CASH SALE WEKA TRAVEL"
+        ),
+        members=(
+            PersonSelector(
+                "Josh Loughnan", "josh@wekatravel.com", "CASH SALE WEKA TRAVEL"
+            ),
+            PersonSelector(
+                "Josh Loughnan", "josh@wekatravel.com", "Loughnan Construction"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Josh Loughnan=1, Josh Loughnan=1; shared email josh@wekatravel.com; shared phone +64220966480",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Lars", None, "Davison Construction"),
+        members=(
+            PersonSelector("Lard", None, "Davison Construction"),
+            PersonSelector("Lars", None, "Davison Construction"),
+            PersonSelector(
+                "LARS DAVISON", "lars@davison.kiwi", "CASH SALE - LARS DAVISON"
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs Lard=1, Lars=3, LARS DAVISON=2; shared phone +64274052692",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Lee / Jeanette", None, "Lee & Jeanette Sutton"),
+        members=(
+            PersonSelector("Lee / Jeanette", None, "Lee & Jeanette Sutton"),
+            PersonSelector(
+                "Lee and Jeanette,cut mild steel plate with holes",
+                None,
+                "Lee and Jeanette Sutton",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Lee / Jeanette=1, Lee and Jeanette,cut mild steel plate with holes=1; shared phone +6421904199",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Madi Johns", "MADIJ@WATERFORD.CO.NZ", "Waterford Security Limited"
+        ),
+        members=(
+            PersonSelector("MADI 2", None, "Waterford Security Limited"),
+            PersonSelector(
+                "Madi Johns", "MADIJ@WATERFORD.CO.NZ", "Waterford Security Limited"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs MADI 2=0, Madi Johns=4; shared phone +64211901935",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Mark Homan", "markhoman41@gmail.com", "Ripout NZ Ltd"
+        ),
+        members=(
+            PersonSelector("Mark Homan", None, "CASH SALE - Mark Homan"),
+            PersonSelector("Mark Homan", "markhoman41@gmail.com", "Ripout NZ Ltd"),
+        ),
+        expected_people=2,
+        evidence="production jobs Mark Homan=0, Mark Homan=4; shared phone +6421744827",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Mark Langdon", "mark@langdon.nz", "Mark Langdon"),
+        members=(
+            PersonSelector("MARK LANGDON", "mark@langdon.nz", "Mark Langdon"),
+            PersonSelector("Mark Langdon", "mark@langdon.nz", "Mark Langdon"),
+        ),
+        expected_people=2,
+        evidence="production jobs MARK LANGDON=1, Mark Langdon=1; shared phone +6421726479",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "MARK SEARS", "msears@customcontrols.co.nz", "Custom Controls Ltd"
+        ),
+        members=(
+            PersonSelector(
+                "MARK SEARS", "msears@customcontrols.co.nz", "Custom Controls Ltd"
+            ),
+            PersonSelector(
+                "MARK SEARS", "msears@customcontrols.co.nz", "CASH SALE - MARK SEARS"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs MARK SEARS=1, MARK SEARS=0; shared email msears@customcontrols.co.nz; shared phone +6421758031",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("MARSH COOPER", None, "CASH SALE - MARSH COOPER"),
+        members=(
+            PersonSelector("Marsh", None, "Marsh"),
+            PersonSelector("MARSH COOPER", None, "CASH SALE - MARSH COOPER"),
+        ),
+        expected_people=2,
+        evidence="production jobs Marsh=1, MARSH COOPER=1; shared phone +6421920315",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Matt green", None, "Penrose Paper Engineering"),
+        members=(
+            PersonSelector(
+                "Matt -Kindactics", "matt@kidantics.co.nz", "CASH SALE - Kindactics"
+            ),
+            PersonSelector("Matt green", None, "Penrose Paper Engineering"),
+            PersonSelector("Matt Green", "matt@kidantics.co.nz", "Matt Green"),
+        ),
+        expected_people=3,
+        evidence="production jobs Matt -Kindactics=1, Matt green=1, Matt Green=1; shared email matt@kidantics.co.nz; shared phone +64212242900",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "MATTHEW MACDONALD", "Matthew.Macdonald@wmetals.co.nz", "Wakefield Metals"
+        ),
+        members=(
+            PersonSelector(
+                "MATHEW MCDONALD",
+                "matthew.macdonald@wmetals.co.nz",
+                "CASH SALE - WAKEFIELDS METALS",
+            ),
+            PersonSelector(
+                "MATTHEW MACDONALD",
+                "Matthew.Macdonald@wmetals.co.nz",
+                "Wakefield Metals",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs MATHEW MCDONALD=0, MATTHEW MACDONALD=1; shared email matthew.macdonald@wmetals.co.nz; shared phone +64212426732",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Michael Chee", "Michael@highmark.co.nz", "High Mark Foods"
+        ),
+        members=(
+            PersonSelector("??", "Michael@highmark.co.nz", "High Mark Foods"),
+            PersonSelector("Michael Chee", "Michael@highmark.co.nz", "High Mark Foods"),
+            PersonSelector(
+                "MICHAEL CHEE", "michael@highmark.co.nz", "CASH SALE - MICHAEL CHEE"
+            ),
+            PersonSelector("Mike", None, "High Mark Foods"),
+        ),
+        expected_people=4,
+        evidence="production jobs ??=0, Michael Chee=3, MICHAEL CHEE=2, Mike=0; shared email michael@highmark.co.nz; shared phone +6421673290",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Mike", None, "Mike (Michael) Loomb"),
+        members=(
+            PersonSelector("Mike", None, "Mike (Michael) Loomb"),
+            PersonSelector("Mike Loomb", None, "CASH SALE - Mike Loomb"),
+        ),
+        expected_people=2,
+        evidence="production jobs Mike=1, Mike Loomb=0; shared phone +64211951166",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Mike Lum", "mikelum@email.com", "CASH SALE - Jack Lum and Co."
+        ),
+        members=(
+            PersonSelector("Mike Lum", "mikelum@email.com", "Jack Lum and Co Limited"),
+            PersonSelector(
+                "Mike Lum", "mikelum@email.com", "CASH SALE - Jack Lum and Co."
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Mike Lum=0, Mike Lum=1; shared email mikelum@email.com; shared phone +6421301188",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Nav",
+            "navneet.singh1@cushwake.com",
+            "Cushman and Wakefield New Zealand Limited",
+        ),
+        members=(
+            PersonSelector(
+                "Cushman Wakefield ,Nave",
+                None,
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+            PersonSelector(
+                "Nav",
+                "navneet.singh1@cushwake.com",
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+            PersonSelector("Nave", None, "Cushman and Wakefield New Zealand Limited"),
+            PersonSelector(
+                "Nave - Botany Woolworths",
+                None,
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+        ),
+        expected_people=4,
+        evidence="production jobs Cushman Wakefield ,Nave=3, Nav=9, Nave=1, Nave - Botany Woolworths=1; shared phone +64212434604",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Neville", None, "Watercone ltd (Neville)"),
+        members=(
+            PersonSelector("Neville", None, "The water cone"),
+            PersonSelector("Neville", None, "Watercone ltd (Neville)"),
+        ),
+        expected_people=2,
+        evidence="production jobs Neville=1, Neville=2; shared phone +6421922819",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "NICK DUFFY", "nick@hunkineng.co.nz", "Hunkin Engineering"
+        ),
+        members=(
+            PersonSelector("Nick Duffy", "nick@hunkineng.co.nz", "Hunkin Engineering"),
+            PersonSelector("NICK DUFFY", "nick@hunkineng.co.nz", "Hunkin Engineering"),
+        ),
+        expected_people=2,
+        evidence="production jobs Nick Duffy=0, NICK DUFFY=4; shared email nick@hunkineng.co.nz",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Nick Haines",
+            "nhaines@nepgroup.com",
+            "NEP Broadcast Services New Zealand Limited",
+        ),
+        members=(
+            PersonSelector("Nick Haines", None, "CASH SALE - Nick Haines"),
+            PersonSelector(
+                "Nick Haines",
+                "nhaines@nepgroup.com",
+                "NEP Broadcast Services New Zealand Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Nick Haines=0, Nick Haines=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Nick Hansen", "nickhprogresse@hotmail.co.nz", "CASH SALE Nick Hansen"
+        ),
+        members=(
+            PersonSelector("Nick Hansen", None, "Nick Hansen"),
+            PersonSelector(
+                "Nick Hansen", "nickhprogresse@hotmail.co.nz", "CASH SALE Nick Hansen"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Nick Hansen=1, Nick Hansen=3; shared phone +64272968753",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Nigel", None, "MSM (Shop)"),
+        members=(
+            PersonSelector("Nigel", None, "MSM (Shop)"),
+            PersonSelector("Nigel", None, "MSM"),
+        ),
+        expected_people=2,
+        evidence="production jobs Nigel=3, Nigel=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Onker Goundar",
+            "church.st.panelbeaters@gmail.com",
+            "CASH SALE - Church St Motors",
+        ),
+        members=(
+            PersonSelector(
+                "ONKAR GOUNDAR",
+                "church.st.panelbeaters@gmail.com",
+                "CASH SALE - CHURCH ST PANELBEATERS",
+            ),
+            PersonSelector(
+                "onkar goundar",
+                "church.st.panelbeaters@gmail.com",
+                "CASH SALE - Church Street Panelbeaters",
+            ),
+            PersonSelector(
+                "Onker Goundar",
+                "church.st.panelbeaters@gmail.com",
+                "CASH SALE - Church St Motors",
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs ONKAR GOUNDAR=0, onkar goundar=1, Onker Goundar=3; shared email church.st.panelbeaters@gmail.com; shared phone +64275670142",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Paul O'Brien", "paulobrien575@gmail.com", "CASH SALE - PAUL O'BRIEN"
+        ),
+        members=(
+            PersonSelector("PAUL O'BRIEN", "paul@timeworx.co.nz", "Timeworx"),
+            PersonSelector(
+                "Paul O'Brien", "paulobrien575@gmail.com", "CASH SALE - PAUL O'BRIEN"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs PAUL O'BRIEN=2, Paul O'Brien=3; shared phone +64212837447",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Pete Pedersen", None, "CASH SALE#Pete Pederson"),
+        members=(
+            PersonSelector("Pete Pedersen", None, "CASH SALE#Pete Pederson"),
+            PersonSelector(
+                "Pete Pederson", "prodognz@gmail.com", "CASH SALE - Pete Pederson"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Pete Pedersen=1, Pete Pederson=1; shared phone +64274300224",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Peter", None, "Cushman and Wakefield New Zealand Limited"
+        ),
+        members=(
+            PersonSelector("Peter", None, "Cushman and Wakefield New Zealand Limited"),
+            PersonSelector(
+                "Pieter Badenhorst",
+                "pieter.badenhorst@cushwake.com",
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Peter=5, Pieter Badenhorst=3; shared phone +6421466755",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "PETER MANHIRE", "peter.manhire@skellerupgroup.com", "Peter Manhire"
+        ),
+        members=(
+            PersonSelector("Peter Manhire", None, "Ultralon Foam International"),
+            PersonSelector(
+                "PETER MANHIRE", "peter.manhire@skellerupgroup.com", "Peter Manhire"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Peter Manhire=1, PETER MANHIRE=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Phil", None, "Phil"),
+        members=(
+            PersonSelector("Phil", None, "Phil"),
+            PersonSelector("Phil", None, "CASH SALE - VIKING BUILDERS LTD - PHIL"),
+            PersonSelector("Phil", None, "CASH SALE - Phil"),
+            PersonSelector("Philip", None, "Phil"),
+        ),
+        expected_people=4,
+        evidence="production jobs Phil=1, Phil=1, Phil=0, Philip=1; shared phone +642108568997",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Philip Whitam", "phil.point@outlook.com", "Point Maintenance"
+        ),
+        members=(
+            PersonSelector("Philip", None, "cash sale phillip"),
+            PersonSelector("Philip", "phil.point@outlook.com", "Phillip Whitham"),
+            PersonSelector(
+                "Philip Whitam", "phil.point@outlook.com", "Point Maintenance"
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs Philip=1, Philip=1, Philip Whitam=4; shared email phil.point@outlook.com; shared phone +64277033500",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Ray Zhang", "ray.zhang@hellofresh.co.nz", "Hello Fresh New Zealand"
+        ),
+        members=(
+            PersonSelector(
+                "Ray Zhang", "ray.zhang@hellofresh.co.nz", "Hello Fresh New Zealand"
+            ),
+            PersonSelector(
+                "RAY ZHANG", "ray.zhang@hellofresh.co.nz", "Hello Fresh New Zealand"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Ray Zhang=9, RAY ZHANG=0; shared email ray.zhang@hellofresh.co.nz",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "REM WADEH", "REM.WADEH@HOTMAIL.COM", "CASH SALE - REM WADEH"
+        ),
+        members=(
+            PersonSelector(
+                "REM WADEH", "REM.WADEH@HOTMAIL.COM", "CASH SALE - REM WADEH"
+            ),
+            PersonSelector(
+                "REM WADEH", "rem_wadeh@hotmail.com", "CASH - SALE - RERM WADEH"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs REM WADEH=2, REM WADEH=0; shared phone +64211523239",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Richard Mills", None, "Cushman and Wakefield New Zealand Limited"
+        ),
+        members=(
+            PersonSelector(
+                "Richard Mills", None, "Cushman and Wakefield New Zealand Limited"
+            ),
+            PersonSelector(
+                "Richard Mills",
+                "graememills15@gmail.com",
+                "Onehunga Car Services Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Richard Mills=10, Richard Mills=1",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Rick Van Swet", "rickvanswet@gmail.com", "CASH SALE - Rick Van Swet"
+        ),
+        members=(
+            PersonSelector("Rick", None, "Rick vanderset"),
+            PersonSelector(
+                "Rick Van Swet", "rickvanswet@gmail.com", "CASH SALE - Rick Van Swet"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Rick=1, Rick Van Swet=1; shared phone +6421400711",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Rob", None, "Expac Machining Centre 2024 Ltd"),
+        members=(
+            PersonSelector(
+                "Expac   cut and fold brackets as per drawing",
+                None,
+                "Expac Machining Centre 2024 Ltd",
+            ),
+            PersonSelector("Rob", None, "Expac Machining Centre 2024 Ltd"),
+        ),
+        expected_people=2,
+        evidence="production jobs Expac   cut and fold brackets as per drawing=1, Rob=5; shared phone +64274448238",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Robbie", None, "Robbie Grant"),
+        members=(
+            PersonSelector("Robbie", None, "Robbie Grant"),
+            PersonSelector("Robert Grant", None, "Robert Grant"),
+        ),
+        expected_people=2,
+        evidence="production jobs Robbie=1, Robert Grant=1; shared phone +6421502802",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Robert", None, "Cushman and Wakefield New Zealand Limited"
+        ),
+        members=(
+            PersonSelector("Robert", None, "Cushman and Wakefield New Zealand Limited"),
+            PersonSelector("ROBERT", None, "cash sale - ROBERT - CUSHMAN WAKEFIELD"),
+        ),
+        expected_people=2,
+        evidence="production jobs Robert=15, ROBERT=2; shared phone +64212450109",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Rusty Tagicakibau",
+            "Rusty.Tagicakibau@cushwake.com",
+            "Cushman and Wakefield New Zealand Limited",
+        ),
+        members=(
+            PersonSelector("Rusty", None, "Rusty Tagicakibau"),
+            PersonSelector(
+                "Rusty Tagicakibau",
+                "Rusty.Tagicakibau@cushwake.com",
+                "Cushman and Wakefield New Zealand Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Rusty=1, Rusty Tagicakibau=6; shared phone +64274050629",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Sam Loughnan", "sam@loughnanconstruction.co.nz", "Loughnan Construction"
+        ),
+        members=(
+            PersonSelector("Sam", None, "Loughnan Construction"),
+            PersonSelector(
+                "Sam Loughnan",
+                "sam@loughnanconstruction.co.nz",
+                "Loughnan Construction",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Sam=4, Sam Loughnan=5; shared phone +6421782110",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Sarah newman", None, "CGO (Corporate) Limited"),
+        members=(
+            PersonSelector("Sarah newman", None, "CGO (Corporate) Limited"),
+            PersonSelector(
+                "Sarah Newman", "accounts@mammothbrands.nz", "CGO Corporate Ltd"
+            ),
+            PersonSelector(
+                "Sarah Newman", "sarah@mammothbrands.nz", "CASH SALE - Mammoth Brands"
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs Sarah newman=4, Sarah Newman=1, Sarah Newman=0; shared phone +64212727246",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Simon", None, "Simon Cope"),
+        members=(
+            PersonSelector("Simon", None, "Simon Cope"),
+            PersonSelector("Simon Cope", None, "Simon Cope"),
+        ),
+        expected_people=2,
+        evidence="production jobs Simon=1, Simon Cope=1; shared phone +6421968103",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Simon Rose", "simon.rose@proclimb.co.nz", "Proclimb"),
+        members=(
+            PersonSelector("Simon Rose", "simon.rose@proclimb.co.nz", "Proclimb"),
+            PersonSelector(
+                "SIMON ROSE", "simon.rose@proclimb.co.nz", "CASH SALE - SIMON ROSE"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Simon Rose=1, SIMON ROSE=1; shared email simon.rose@proclimb.co.nz; shared phone +64276642307",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "STEPHEN CARR", "daimlersteve@gmail.com", "CASH SALE - STEPHEN CARR"
+        ),
+        members=(
+            PersonSelector(
+                "STEPHEN CARR", "daimlersteve@gmail.com", "Stephen (Steve) Carr"
+            ),
+            PersonSelector(
+                "STEPHEN CARR", "daimlersteve@gmail.com", "CASH SALE - STEPHEN CARR"
+            ),
+            PersonSelector(
+                "Steve Carr", "daimlersteve@gmail.com", "CASH SALE - Steve Carr"
+            ),
+        ),
+        expected_people=3,
+        evidence="production jobs STEPHEN CARR=1, STEPHEN CARR=1, Steve Carr=1; shared email daimlersteve@gmail.com; shared phone +64275120443",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Steve Kirby", "kirby.nz@gmail.com", "CASH SALE - Steve Kirby"
+        ),
+        members=(
+            PersonSelector("Steve", "Kirby.nz@gmail.com", "Steve Kirby"),
+            PersonSelector(
+                "Steve Kirby", "kirby.nz@gmail.com", "CASH SALE - Steve Kirby"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Steve=1, Steve Kirby=1; shared email kirby.nz@gmail.com",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Stuart Watts", "stuartwatts07@gmail.com", "CASH SALE- Penrose motors"
+        ),
+        members=(
+            PersonSelector(
+                "Stuart Watts", "stuartwatts07@gmail.com", "CASH SALE- Penrose motors"
+            ),
+            PersonSelector(
+                "STUART WATTS", "stuartwatts07@gmail.com", "CASH SALE - STUART WATTS"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Stuart Watts=1, STUART WATTS=1; shared phone +64278172546",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "SUZANNE PENTECOST",
+            "spentecost@adinahotels.co.nz",
+            "CASH SALE - ADINA APARTMENT HOTEL AUCKLAND BRITOMART",
+        ),
+        members=(
+            PersonSelector(
+                "SUZANNE PENTECOST",
+                "spentecost@adinahotels.co.nz",
+                "Dominion Constructors Limited",
+            ),
+            PersonSelector(
+                "SUZANNE PENTECOST",
+                "spentecost@adinahotels.co.nz",
+                "CASH SALE - ADINA APARTMENT HOTEL AUCKLAND BRITOMART",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs SUZANNE PENTECOST=0, SUZANNE PENTECOST=2; shared email spentecost@adinahotels.co.nz; shared phone +6493938200",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("Thomas", "redhawk@xtra.co.nz", "thomas"),
+        members=(
+            PersonSelector("Thomas", "redhawk@xtra.co.nz", "thomas"),
+            PersonSelector("tom", "redhawk@xtra.co", "thomas"),
+        ),
+        expected_people=2,
+        evidence="production jobs Thomas=1, tom=0; shared phone +64220446045",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Timothy Moore", "tim.moore@hussmann.com", "MC ALPINE HUSSMANN"
+        ),
+        members=(
+            PersonSelector(
+                "TIM MOORE", "tim.moore@hussmann.com", "CASH SALE - MCALPINE HUSSMANN"
+            ),
+            PersonSelector(
+                "Timothy Moore", "tim.moore@hussmann.com", "MC ALPINE HUSSMANN"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs TIM MOORE=2, Timothy Moore=2; shared email tim.moore@hussmann.com; shared phone +64272240844",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Toby Andrews", "tobias.andrews@ventia.com", "Ventia NZ Limited"
+        ),
+        members=(
+            PersonSelector(
+                "Tobias Andrews", "tobias.andrews@ventia.com", "Ventia NZ Limited"
+            ),
+            PersonSelector(
+                "Toby Andrews", "tobias.andrews@ventia.com", "Ventia NZ Limited"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Tobias Andrews=1, Toby Andrews=6; shared phone +64273594960",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Vanya Kroon", "Vanyakroon@gmail.com", "CASH SALE - Vanya Kroon"
+        ),
+        members=(
+            PersonSelector(
+                "VANYA KROON", "VANYAKROON@GMIAL.COM", "CASH SALE - Vanya Kroon"
+            ),
+            PersonSelector(
+                "Vanya Kroon", "Vanyakroon@gmail.com", "CASH SALE - Vanya Kroon"
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs VANYA KROON=1, Vanya Kroon=3; shared phone +64212046863",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "Vimlesh Prasad",
+            "Vimlesh.Prasad@fultonhogan.com",
+            "Fulton Hogan Auckland Limited",
+        ),
+        members=(
+            PersonSelector(
+                "Vimlesh Prasad",
+                "Vimlesh.Prasad@fultonhogan.com",
+                "Fulton Hogan Auckland Limited",
+            ),
+            PersonSelector(
+                "Vimlesh Prasadd",
+                "vimlesh.prasad@fultonhogan.com",
+                "Fulton Hogan Auckland Limited",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs Vimlesh Prasad=17, Vimlesh Prasadd=1; shared email vimlesh.prasad@fultonhogan.com; shared phone +64278365351",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector("WOLFGANG", None, "CASH SALE - WOLFGANG"),
+        members=(
+            PersonSelector("Wolfgang", None, "Wolfgang Schenk"),
+            PersonSelector("WOLFGANG", None, "CASH SALE - WOLFGANG"),
+        ),
+        expected_people=2,
+        evidence="production jobs Wolfgang=1, WOLFGANG=2; shared phone +64211253754",
+    ),
+    PersonMergeDecision(
+        canonical=PersonSelector(
+            "ZACH LINDSAY",
+            "mike@lindsaybuildingservices.co.nz",
+            "CASH SALE - Lindsay Building Services",
+        ),
+        members=(
+            PersonSelector(
+                "ZACH",
+                "ZACH@LINDSAYBUILDINGSERVICES.CO.NZ",
+                "Lindsay Building Services",
+            ),
+            PersonSelector(
+                "ZACH LINDSAY",
+                "mike@lindsaybuildingservices.co.nz",
+                "CASH SALE - Lindsay Building Services",
+            ),
+        ),
+        expected_people=2,
+        evidence="production jobs ZACH=1, ZACH LINDSAY=1; shared phone +64212216699",
+    ),
+)
+
+
+# These are genuine separate businesses despite a weak shared signal.  This is
+# the complete defence ledger for the broad production candidate review.
+USER_APPROVED_RETAINED_COMPANY_DECISIONS: tuple[RetainedDecision, ...] = ()
+
+AGENT_RETAINED_COMPANY_DECISIONS: tuple[RetainedDecision, ...] = (
+    RetainedDecision(
+        ("Auckland Airport Limited", "DGE Ltd"),
+        "Aaron Williams has real jobs recorded for both organisations; one Person is linked to both.",
+    ),
+    RetainedDecision(
+        (
+            "Auckland Bead Blasting Services",
+            "Westgate Welding Limited",
+            "Galvanising Services 2018 Limited",
+        ),
+        "Only a Vodafone-hosted email domain is shared; the names and job histories are unrelated.",
+    ),
+    RetainedDecision(
+        ("Auckland Council", "CASH SALE - Renee Bevan", "Kim Sinclair", "Mike Munley"),
+        "Only the public me.com email domain is shared.",
+    ),
+    RetainedDecision(
+        ("Body Corporate 322257", "Crockers Body Corp BC 312605"),
+        "The legal body-corporate numbers are different.",
+    ),
+    RetainedDecision(
+        ("Carter Holt Harvey - Infotech", "Carter Holt Harvey Paperbag"),
+        "Named operating divisions with separate purchasing histories.",
+    ),
+    RetainedDecision(
+        ("Carters Panmure", "Carters Onehunga - account 3079980"),
+        "Named branches; branch identity is required for delivery and billing.",
+    ),
+    RetainedDecision(
+        ("CASH SALE - FRESH CHOICE ONEHUNGA", "Fresh Choice Mangere Bridge"),
+        "Different supermarket branches.",
+    ),
+    RetainedDecision(
+        ("CASH SALE - New World Orakei", "New World Green Bay", "New World New Lynn"),
+        "Different supermarket branches.",
+    ),
+    RetainedDecision(
+        (
+            "CASH SALE - Rana Property Maintenance",
+            "CASH SALE - Matt Heywood",
+            "Garry Lawrence Roofing",
+            "Reece Taituha",
+            "Super Cheap Tyres",
+        ),
+        "Only the public live.com email domain is shared.",
+    ),
+    RetainedDecision(
+        ("Corrin Lakeland (corrin.lakeland@cmeconnect.com)", "Gerry Westenberg"),
+        "Two named coworkers using the CME corporate domain.",
+    ),
+    RetainedDecision(
+        (
+            "Craig Burrowes",
+            "Electrical Importing Company",
+            "Tom Morris",
+            "Watchman Developments Ltd",
+        ),
+        "Only the legacy ihug ISP domain is shared.",
+    ),
+    RetainedDecision(
+        ("Expac Engineering Ltd (new account)", "Expac Machining Centre 2024 Ltd"),
+        "Separate incorporated machining business: seven machining jobs for Rob and Steve.  Only the old Expac contact details overlap.",
+    ),
+    RetainedDecision(
+        ("Galeeco Automotive", "CASH SALE - MULTISERVE"),
+        "Different businesses and named contacts; a family/office phone is shared.",
+    ),
+    RetainedDecision(
+        ("George Western Foods Limited - Tip Top Bread Auckland", "Mauri"),
+        "Separate operating divisions sharing accounts-payable infrastructure.",
+    ),
+    RetainedDecision(
+        ("Global Fire Limited", "Global Linings Ltd"),
+        "Sister legal companies with shared administration.",
+    ),
+    RetainedDecision(
+        (
+            "CASH SALE - IDEAL ELECTRICAL ROSEDALE BRANCH",
+            "Ideal Electrical (Penrose) - Cash sale purchases",
+        ),
+        "Different electrical-supply branches.",
+    ),
+    RetainedDecision(
+        ("Kinect Holdings Ltd", "Brickell Technology"),
+        "Only the ieee.org membership domain is shared.",
+    ),
+    RetainedDecision(
+        ("KSG Food Packers Ltd", "Green Valley Foods"),
+        "Related but separately named and billed food businesses.",
+    ),
+    RetainedDecision(
+        ("Leap Innovation NZ", "Snowdon Consulting"),
+        "Ben has genuine job history at both companies.",
+    ),
+    RetainedDecision(
+        (
+            "Liquorland Onehunga",
+            "Liquorland Stonefield",
+            "Premium Liquor - Liquorland Onehunga",
+        ),
+        "Different retail branches/accounts.",
+    ),
+    RetainedDecision(
+        ("CASH SALE WEKA TRAVEL", "Loughnan Construction"),
+        "Josh Loughnan has genuine jobs at both; the companies have unrelated work histories.",
+    ),
+    RetainedDecision(
+        (
+            "Bloomin Luvley",
+            "Mike Gillard Family Trust",
+            "Onehunga Auto and Marine Upholstery",
+            "Tony Warren Engineering",
+        ),
+        "Only the legacy Orcon ISP domain is shared.",
+    ),
+    RetainedDecision(
+        ("MSM (Billable - Customer TBD)", "Cash Sales"),
+        "Deliberate internal workflow accounts with different accounting purposes.",
+    ),
+    RetainedDecision(
+        (
+            "MSM (Shop)",
+            "MSM (Billable - Customer TBD)",
+            "ABC Carpet Cleaning TEST IGNORE",
+            "Lakeland Consulting",
+        ),
+        "Deliberate internal/test accounts; the abc/lakeland address is test data, not customer identity.",
+    ),
+    RetainedDecision(
+        (
+            "Oji Fibre Solutions - Packaging NZ",
+            "Oji Fibre Solutions - Paper Bag",
+            "Oji Fibre Solutions - Penrose Mill",
+            "Penrose Paper Engineering",
+        ),
+        "Named Oji divisions are separate; Penrose Paper Engineering is a different current business despite Matt's obsolete Oji address.",
+    ),
+    RetainedDecision(
+        ("Onehunga Car Services Limited", "Cushman and Wakefield New Zealand Limited"),
+        "Richard Mills has real jobs under both companies and is represented by one Person linked to both.",
+    ),
+    RetainedDecision(
+        ("Pauanui Menzshed", "Timeworx"),
+        "Paul O'Brien's personal Gmail is the only overlap; the organisations are unrelated.",
+    ),
+    RetainedDecision(
+        ("Peter Diamond", "Impact Tints"), "Only the public mail.com domain is shared."
+    ),
+    RetainedDecision(
+        ("Ray Baker", "The Dunollie Group"),
+        "Only the legacy Slingshot ISP domain is shared.",
+    ),
+    RetainedDecision(
+        ("Regan Marshall (WWB)", "Richard Pryde - Winstones"),
+        "Different GIB coworkers represented by person-labelled records.",
+    ),
+    RetainedDecision(
+        ("Ripout NZ Ltd", "Workdek"),
+        "Raw values are '0800 RIPOUT' and '0800nofall'; both were incorrectly normalised to +64800.",
+    ),
+    RetainedDecision(
+        ("Road Science", "Downer Group"),
+        "Subsidiary and parent are separately billed legal entities.",
+    ),
+    RetainedDecision(
+        ("Ultralon Foam International", "Nexus Performance Foams Limited"),
+        "Separate Skellerup subsidiaries; Peter's group contact is shared.",
+    ),
+    RetainedDecision(
+        ("University of Auckland - Support Services", "Total Works Ltd"),
+        "Separate organisations; only an aucklanduni contact address overlaps.",
+    ),
+    RetainedDecision(
+        (
+            "Valmont Coatings/CSP Galvanising",
+            "Locker Group Limited/Webforge Locker (Valmont)",
+            "Webforge (NZ) Ltd",
+        ),
+        "Separate operating divisions with distinct work histories.",
+    ),
+    RetainedDecision(
+        ("Work Investment Ltd T/A Epic Beer", "Dominion Constructors Limited"),
+        "Simon Mowday is a construction contact for Epic; the legal companies are unrelated.",
+    ),
+    RetainedDecision(
+        ("Yellow Bites LImited", "JJ Wafer Biscuits Limited"),
+        "Separate Limited billing entities under shared group accounts; Yellow Bites alone has eleven jobs.",
+    ),
+)
+
+
+# Shared office numbers identify coworkers, not duplicate People.  The two
+# cross-company entries are also supported by real job history at both firms.
+USER_APPROVED_RETAINED_PERSON_DECISIONS: tuple[RetainedDecision, ...] = ()
+
+AGENT_RETAINED_PERSON_DECISIONS: tuple[RetainedDecision, ...] = (
+    RetainedDecision(
+        ("BRENT", "Brian", "Nathan"),
+        "Three Stainless Welding people share the office number; Brent has 94 jobs and Nathan has two.",
+    ),
+    RetainedDecision(
+        ("David", "Mike"),
+        "Equipment Engineering coworkers with different corporate emails and seven/six jobs.",
+    ),
+    RetainedDecision(
+        ("Graeme", "Richard Mills"),
+        "Different Onehunga Car Services people sharing the office number.",
+    ),
+    RetainedDecision(
+        ("Hamish Taylor", "TOM TAULA"),
+        "Matassa coworkers with different corporate emails and two jobs each.",
+    ),
+    RetainedDecision(
+        ("JENNINE MARSHALL", "TYLER BROWN"),
+        "GFL coworkers with different corporate emails and one job each.",
+    ),
+    RetainedDecision(
+        ("Josh N.", "Raj"), "Different companies; abc@gmail.com is placeholder data."
+    ),
+    RetainedDecision(
+        ("Keith Kariyawasam", "SURANGA KARIYAWASAM"),
+        "Different Galeeco/Multiserve people sharing a family or office phone.",
+    ),
+    RetainedDecision(
+        ("Mike", "Raj"),
+        "Different Boss Motorbodies/AI Technology contacts sharing an office number.",
+    ),
+    RetainedDecision(
+        ("Tamara Gogava", "Varinder Kumar"),
+        "HV coworkers with different corporate emails and jobs.",
+    ),
+    RetainedDecision(
+        ("tony", "ZACH LINDSAY"),
+        "Different Lindsay Building Services contacts sharing the company number.",
+    ),
 )
 
-# Manually reviewed bridges not covered by exact/nickname name compatibility.
-# IDs are legacy contact IDs, retained as CompanyPersonLink IDs by migration 0005.
-REVIEWED_PERSON_LINK_EDGES: tuple[PersonLinkEdge, ...] = (
-    (
-        "90650519-eccd-4766-b869-c3b6e70855f6",
-        "df371ed0-43f3-43e1-af59-d5e400e01bed",
-    ),  # ?? / Michael Chee
-    (
-        "13546f44-681c-423d-9e02-abe933f5d8bb",
-        "9e50a9b9-8080-4975-a897-3aebc214ab8f",
-    ),  # Aaron / Aarron
-    (
-        "7e6cb791-a308-42ec-9156-889e62ebc52d",
-        "8d59aa42-0f30-4669-81b9-ef01753a357e",
-    ),  # Arno surname typo
-    (
-        "05816a5f-38d8-47fc-b3e5-95b3350b058e",
-        "79d8d9b2-5b1f-49a1-95ff-9c597ee6888f",
-    ),  # Aaron / Arron
-    (
-        "7e5b48fa-f9e9-46d2-847a-40b3b827f34a",
-        "bff2f883-853c-4e7e-b1f8-443a5c24bee4",
-    ),  # Bronwyn
-    (
-        "155c2987-ae6f-4175-9a37-d6ec5f9e3d3b",
-        "81f90c08-069b-41e0-9560-afbfc070b945",
-    ),  # Cushman Chris
-    (
-        "6bea2a11-081b-46c3-b3fa-a97e6569aebc",
-        "ec2907c6-f932-4b49-862c-e9f5278028cc",
-    ),  # Craig typo
-    (
-        "4663652a-11a9-4fdc-953b-713878be13a1",
-        "49b58609-8daa-414a-8654-a64bdacf2f20",
-    ),  # Cushman Nave
-    (
-        "49b58609-8daa-414a-8654-a64bdacf2f20",
-        "56172bb3-eb13-4065-8976-c2ef62a08ffe",
-    ),  # Cushman Nave job label
-    (
-        "347ad57f-21ed-405c-89f5-39dd4db6ad03",
-        "3598fc0b-da47-4090-8710-df8df78575ab",
-    ),  # Dave Yanala typo
-    (
-        "3c26bb57-3f52-435d-b075-636989e67735",
-        "ece95901-35d3-479f-bbad-76d5322dc29a",
-    ),  # Edwin typo
-    (
-        "cbe6808f-5cd5-4c8c-a741-ddc5fd435bd3",
-        "df32f23a-1acf-4ab3-bae3-19b034c84db4",
-    ),  # malformed Expac name / Rob
-    (
-        "1c25b5f3-132f-4a67-8b2b-3a9fbdf119ec",
-        "5f2f1c93-e0e3-48f6-80c1-6109105e7858",
-    ),  # Ian / Iain
-    (
-        "6d851c6e-6f1c-4966-aa7c-cbc8e495504d",
-        "f7a78661-4b9c-42b1-8f7e-39ce162d2848",
-    ),  # Joseph typo
-    (
-        "53a5c735-c00a-42bc-87b4-8cba3635aaa3",
-        "e5cc3937-ce4b-45c2-9233-17fe4b2d93cf",
-    ),  # John Laycock / Blacklock
-    (
-        "e782a08c-2e8f-4ff9-b055-3dd3df714ac3",
-        "fc30d89f-1038-4f01-9848-9172ce78b88c",
-    ),  # Lars typo
-    (
-        "268461ee-6d32-4a93-9561-d52496cd8492",
-        "99ef5e54-8cfb-45ec-ae97-7dcd6d4f37a6",
-    ),  # Lee / Jeanette malformed name
-    (
-        "6950a05e-2219-438d-9021-5203d3b5cb0f",
-        "766cf006-4679-4ceb-8971-5be5847aa1cd",
-    ),  # Madi
-    (
-        "13342c5e-225e-4b12-a4c7-8c37b37783a3",
-        "3354d901-f860-4411-a290-b34ee28ead3f",
-    ),  # Matthew surname typo
-    (
-        "36200504-e009-47d7-9dde-9db3cbb6f3dc",
-        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
-    ),  # Matt Green repair
-    (
-        "3a880441-9fdb-4979-b574-ad8e14e39e41",
-        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
-    ),  # Matt Green
-    (
-        "b13ee247-a890-44ae-8126-1781e78d2375",
-        "b64f3614-69fd-4c0a-bb9e-333a6ce35feb",
-    ),  # Matt Green
-    (
-        "4663652a-11a9-4fdc-953b-713878be13a1",
-        "9418ddb0-28fd-4def-88d2-d933de154902",
-    ),  # Nave / Nav
-    (
-        "05a82448-d03c-437e-9f88-7bfd1f4d182b",
-        "c2f89cdb-109f-4440-bf61-888f927a4c16",
-    ),  # Onkar typo
-    (
-        "c2f89cdb-109f-4440-bf61-888f927a4c16",
-        "e19f00a9-2589-4465-a31f-2a2fe566af76",
-    ),  # Onkar company variant
-    (
-        "96241f46-590f-4f3a-a82d-ce3a1c31a260",
-        "e0a47879-41d3-48ef-8e68-ebd67c018711",
-    ),  # Pederson / Pedersen
-    (
-        "6913ce62-67e2-4dd1-a0a6-eca0c3cb35d8",
-        "8a2de35f-4828-4464-a9e0-44f94ee4e544",
-    ),  # Peter / Pieter Badenhorst
-    (
-        "3abf4238-63ba-4362-8a4d-d22dd6d77496",
-        "ec160e6f-7708-43f9-824b-3c219ca4d962",
-    ),  # Robbie / Robert Grant
-    (
-        "44e28e0a-3c70-4ce3-8cff-177f71efd468",
-        "c195f5e4-feb8-40ad-8a03-369830607f51",
-    ),  # Vimlesh surname typo
+
+INVALID_LINKS: tuple[InvalidLinkDecision, ...] = (
+    InvalidLinkDecision(
+        "MSM (Shop)",
+        "Bobby",
+        None,
+        "Bobby's real Blackstone history proves the MSM Shop association is erroneous.",
+    ),
+    InvalidLinkDecision(
+        "Dominion Constructors Limited",
+        "SUZANNE PENTECOST",
+        "spentecost@adinahotels.co.nz",
+        "Suzanne is Adina's contact; Dominion has no supporting job history for this link.",
+    ),
 )
 
-MATT_GREEN_LINK_ID = UUID("36200504-e009-47d7-9dde-9db3cbb6f3dc")
+MATT_GREEN_REPAIR = PersonSelector(
+    "Matthew Green", "j.green@northlandroofs.com", "CASH SALE-Kidantics"
+)
 MATT_WRONG_METHOD_VALUES = {"j.green@northlandroofs.com", "+64277003221"}
 
 
-def _components(edges: Iterable[tuple[UUID, UUID]]) -> list[set[UUID]]:
-    adjacency: dict[UUID, set[UUID]] = defaultdict(set)
-    for first_id, second_id in edges:
-        adjacency[first_id].add(second_id)
-        adjacency[second_id].add(first_id)
-
-    components: list[set[UUID]] = []
-    visited: set[UUID] = set()
-    for root_id in sorted(adjacency, key=str):
-        if root_id in visited:
-            continue
-        component: set[UUID] = set()
-        pending = [root_id]
-        while pending:
-            person_id = pending.pop()
-            if person_id in component:
-                continue
-            component.add(person_id)
-            pending.extend(adjacency[person_id])
-        visited.update(component)
-        components.append(component)
-    return components
-
-
-def _person_rank(person: Person) -> tuple[bool, int, int, object, str]:
+def _company_activity(company: Company) -> int:
+    from apps.accounting.models import Bill, CreditNote, Invoice, Quote
+    from apps.job.models import Job
+    from apps.purchasing.models import PurchaseOrder
+
+    return (
+        Job.objects.filter(company=company).count()
+        + Invoice.objects.filter(company=company).count()
+        + Bill.objects.filter(company=company).count()
+        + CreditNote.objects.filter(company=company).count()
+        + Quote.objects.filter(company=company).count()
+        + PurchaseOrder.objects.filter(supplier=company).count()
+        + company.contacts.count()
+        + company.contact_methods.count()
+    )
+
+
+def _person_activity(person: Person) -> int:
     from apps.crm.models import PhoneCallRecord
     from apps.job.models import Job
 
-    activity = (
+    return (
         Job.objects.filter(person=person).count()
         + PhoneCallRecord.objects.filter(person=person).count()
-    )
-    references = person.company_links.count() + person.contact_methods.count()
-    return (
-        not person.is_active,
-        -activity,
-        -references,
-        person.created_at,
-        str(person.id),
+        + person.company_links.count()
+        + person.contact_methods.count()
     )
 
 
-def _merge_person_components(components: Iterable[set[UUID]], staff: Staff) -> int:
-    merge_count = 0
-    for component in components:
-        people = list(Person.objects.filter(id__in=component))
-        if len(people) < 2:
-            continue
-        destination = min(people, key=_person_rank)
-        for source in sorted(people, key=lambda person: str(person.id)):
-            if source.id == destination.id:
-                continue
-            merge_people(source.id, destination.id, staff)
-            merge_count += 1
-    return merge_count
-
-
-def _reviewed_person_components() -> list[set[UUID]]:
-    raw_edges = [
-        (UUID(first_id), UUID(second_id))
-        for first_id, second_id in REVIEWED_PERSON_LINK_EDGES
-    ]
-    link_ids = {link_id for edge in raw_edges for link_id in edge}
-    person_by_link = dict(
-        CompanyPersonLink.objects.filter(id__in=link_ids).values_list("id", "person_id")
-    )
-    active_edges: list[tuple[UUID, UUID]] = []
-    for first_link_id, second_link_id in raw_edges:
-        first_person_id = person_by_link.get(first_link_id)
-        second_person_id = person_by_link.get(second_link_id)
-        if first_person_id is None and second_person_id is None:
-            continue
-        if first_person_id is None or second_person_id is None:
+def _resolve_company_decisions() -> list[tuple[Company, list[Company]]]:
+    resolved: list[tuple[Company, list[Company]]] = []
+    used_ids: set[str] = set()
+    for decision in REVIEWED_COMPANY_MERGES:
+        companies = list(Company.objects.filter(name__in=decision.names))
+        if len(companies) != decision.expected_rows:
+            raise RuntimeError(
+                f"KAN-278 Company evidence changed for {decision.names}: "
+                f"expected {decision.expected_rows}, found {len(companies)}"
+            )
+        canonical_candidates = [
+            company for company in companies if company.name == decision.canonical_name
+        ]
+        if not canonical_candidates:
+            raise RuntimeError(
+                f"KAN-278 canonical Company is missing: {decision.canonical_name}"
+            )
+        canonical = max(canonical_candidates, key=_company_activity)
+        sources = [company for company in companies if company.id != canonical.id]
+        company_ids = {str(company.id) for company in companies}
+        overlap = used_ids.intersection(company_ids)
+        if overlap:
+            raise RuntimeError(f"KAN-278 Company decisions overlap: {decision.names}")
+        used_ids.update(company_ids)
+        resolved.append((canonical, sources))
+    return resolved
+
+
+def _person_query(selector: PersonSelector) -> Q:
+    query = Q(name=selector.name)
+    if selector.email is None:
+        query &= Q(email__isnull=True)
+    else:
+        query &= Q(email__iexact=selector.email)
+    if selector.company_name is None:
+        query &= Q(company_links__isnull=True)
+    else:
+        query &= Q(company_links__company__name=selector.company_name)
+    return query
+
+
+def _people_for_selector(selector: PersonSelector) -> list[Person]:
+    return list(Person.objects.filter(_person_query(selector)).distinct())
+
+
+def _resolve_person_decisions() -> list[tuple[Person, list[Person]]]:
+    resolved: list[tuple[Person, list[Person]]] = []
+    used_ids: set[str] = set()
+    for decision in REVIEWED_PERSON_MERGES:
+        people_by_id = {
+            person.id: person
+            for selector in decision.members
+            for person in _people_for_selector(selector)
+        }
+        people = list(people_by_id.values())
+        if len(people) != decision.expected_people:
+            raise RuntimeError(
+                f"KAN-278 Person evidence changed for {decision.members}: "
+                f"expected {decision.expected_people}, found {len(people)}"
+            )
+        canonical_candidates = _people_for_selector(decision.canonical)
+        canonical_candidates = [
+            person for person in canonical_candidates if person.id in people_by_id
+        ]
+        if not canonical_candidates:
+            raise RuntimeError(
+                f"KAN-278 canonical Person is missing: {decision.canonical}"
+            )
+        canonical = max(canonical_candidates, key=_person_activity)
+        sources = [person for person in people if person.id != canonical.id]
+        person_ids = {str(person.id) for person in people}
+        overlap = used_ids.intersection(person_ids)
+        if overlap:
+            raise RuntimeError(f"KAN-278 Person decisions overlap: {decision.members}")
+        used_ids.update(person_ids)
+        resolved.append((canonical, sources))
+    return resolved
+
+
+def _resolve_invalid_links() -> list[CompanyPersonLink]:
+    links: list[CompanyPersonLink] = []
+    for decision in INVALID_LINKS:
+        queryset = CompanyPersonLink.objects.filter(
+            company__name=decision.company_name,
+            person__name=decision.person_name,
+        )
+        if decision.person_email is None:
+            queryset = queryset.filter(person__email__isnull=True)
+        else:
+            queryset = queryset.filter(person__email__iexact=decision.person_email)
+        matches = list(queryset)
+        if len(matches) != 1:
             raise RuntimeError(
-                "KAN-278 Person merge evidence is incomplete: "
-                f"{first_link_id}, {second_link_id}"
+                f"KAN-278 invalid-link evidence changed for {decision}: "
+                f"found {len(matches)}"
             )
-        active_edges.append((first_person_id, second_person_id))
-    return _components(active_edges)
+        links.append(matches[0])
+    return links
+
+
+def _repair_matt_green() -> None:
+    matches = _people_for_selector(MATT_GREEN_REPAIR)
+    if len(matches) != 1:
+        raise RuntimeError(f"KAN-278 Matt Green evidence changed: found {len(matches)}")
+    person = matches[0]
+    ContactMethod.objects.filter(
+        person=person,
+        normalized_value__in=MATT_WRONG_METHOD_VALUES,
+    ).delete()
+    person.email = None
+    person.save(update_fields=["email", "updated_at"])
+
+
+def _normalised_names(names: list[str]) -> frozenset[str]:
+    return frozenset(" ".join(name.casefold().split()) for name in names)
 
 
-def _merge_detected_company_groups(staff: Staff) -> int:
+def _assert_residuals_are_defended() -> None:
     report = DuplicateIdentityReportService().get_report()
-    merge_count = 0
+    automatic = [
+        group
+        for group in report["company_groups"] + report["person_groups"]
+        if group["recommendation"] == "merge"
+    ]
+    if automatic:
+        raise RuntimeError(
+            f"KAN-278 cleanup left {len(automatic)} unmerged duplicate groups"
+        )
+
+    retained_companies = {
+        _normalised_names(list(decision.names))
+        for decision in (
+            USER_APPROVED_RETAINED_COMPANY_DECISIONS + AGENT_RETAINED_COMPANY_DECISIONS
+        )
+    }
     for group in report["company_groups"]:
-        if group["recommendation"] != "merge":
-            continue
-        canonical_id = group["canonical_id"]
-        if canonical_id is None:
-            raise RuntimeError(f"Merge group {group['group_id']} has no canonical")
-        destination_id = UUID(canonical_id)
-        for member in group["members"]:
-            source_id = UUID(member["company_id"])
-            if source_id == destination_id:
-                continue
-            merge_companies(source_id, destination_id, staff)
-            merge_count += 1
-    return merge_count
-
-
-def _merge_detected_person_groups(staff: Staff) -> int:
-    report = DuplicateIdentityReportService().get_report()
-    merge_count = 0
-    for group in report["person_groups"]:
-        if group["recommendation"] != "merge":
-            continue
-        canonical_id = group["canonical_id"]
-        if canonical_id is None:
-            raise RuntimeError(f"Merge group {group['group_id']} has no canonical")
-        destination_id = UUID(canonical_id)
-        for member in group["members"]:
-            source_id = UUID(member["person_id"])
-            if source_id == destination_id:
-                continue
-            merge_people(source_id, destination_id, staff)
-            merge_count += 1
-    return merge_count
+        names = _normalised_names([member["name"] for member in group["members"]])
+        if not any(names <= retained for retained in retained_companies):
+            raise RuntimeError(
+                f"KAN-278 has an undefended retained Company group: {sorted(names)}"
+            )
 
+    retained_people = {
+        _normalised_names(list(decision.names))
+        for decision in (
+            USER_APPROVED_RETAINED_PERSON_DECISIONS + AGENT_RETAINED_PERSON_DECISIONS
+        )
+    }
+    for group in report["person_groups"]:
+        names = _normalised_names([member["name"] for member in group["members"]])
+        if not any(names <= retained for retained in retained_people):
+            raise RuntimeError(
+                f"KAN-278 has an undefended retained Person group: {sorted(names)}"
+            )
 
-def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
-    """Apply the reviewed Company-first then Person cleanup plan."""
-    company_pairs = [
-        (UUID(source_id), UUID(destination_id))
-        for source_id, destination_id in REVIEWED_COMPANY_MERGES
-    ]
-    company_ids = {company_id for pair in company_pairs for company_id in pair}
-    existing_company_ids = set(
-        Company.objects.filter(id__in=company_ids).values_list("id", flat=True)
-    )
-    if not existing_company_ids:
-        return 0, 0
 
-    staff = Staff.get_automation_user()
-    existing_merges = list(
+def _flatten_existing_company_merges(staff: Staff) -> None:
+    existing = list(
         Company.objects.filter(
             merged_into__isnull=False,
             merged_into__merged_into__isnull=True,
         ).values_list("id", "merged_into_id")
     )
-    for source_id, destination_id in existing_merges:
+    for source_id, destination_id in existing:
         if destination_id is None:
             raise RuntimeError(f"Merged Company {source_id} has no destination")
         merge_companies(source_id, destination_id, staff)
 
-    company_merge_count = 0
-    for source_id, destination_id in company_pairs:
-        source_exists = source_id in existing_company_ids
-        destination_exists = destination_id in existing_company_ids
-        if not source_exists and not destination_exists:
-            continue
-        if not source_exists or not destination_exists:
-            raise RuntimeError(
-                "KAN-278 Company merge evidence is incomplete: "
-                f"{source_id}, {destination_id}"
-            )
-        merge_companies(source_id, destination_id, staff)
-        company_merge_count += 1
-
-    matt_link = CompanyPersonLink.objects.filter(id=MATT_GREEN_LINK_ID).first()
-    if matt_link is not None:
-        ContactMethod.objects.filter(
-            person_id=matt_link.person_id,
-            normalized_value__in=MATT_WRONG_METHOD_VALUES,
-        ).delete()
-        Person.objects.filter(id=matt_link.person_id).update(email=None)
-
-    person_merge_count = _merge_person_components(_reviewed_person_components(), staff)
-    for _iteration in range(10):
-        detected_companies = _merge_detected_company_groups(staff)
-        detected_people = _merge_detected_person_groups(staff)
-        company_merge_count += detected_companies
-        person_merge_count += detected_people
-        if detected_companies == 0 and detected_people == 0:
-            break
-    else:
-        raise RuntimeError("KAN-278 cleanup did not converge after 10 iterations")
 
-    remaining = DuplicateIdentityReportService().get_report()["summary"]
-    remaining_automatic = (
-        remaining["company_merge_groups"] + remaining["person_merge_groups"]
-    )
-    if remaining_automatic:
-        raise RuntimeError(
-            f"KAN-278 cleanup left {remaining_automatic} automatic merge groups"
-        )
-    return company_merge_count, person_merge_count
+def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
+    """Apply the finite reviewed ledger and reject every unlisted residual."""
+    if not REVIEWED_COMPANY_MERGES:
+        return 0, 0
+    production_sentinel = REVIEWED_COMPANY_MERGES[0]
+    if not Company.objects.filter(name__in=production_sentinel.names).exists():
+        return 0, 0
+
+    # Resolve every human selector before touching data.  A changed production
+    # snapshot therefore fails with no partial cleanup.
+    company_groups = _resolve_company_decisions()
+    person_groups = _resolve_person_decisions()
+    invalid_links = _resolve_invalid_links()
+
+    staff = Staff.get_automation_user()
+    company_count = 0
+    person_count = 0
+    with transaction.atomic():
+        for link in invalid_links:
+            link.delete()
+        _repair_matt_green()
+
+        _flatten_existing_company_merges(staff)
+        for canonical, sources in company_groups:
+            for source in sources:
+                merge_companies(source.id, canonical.id, staff)
+                company_count += 1
+
+        for canonical, sources in person_groups:
+            for source in sources:
+                merge_people(source.id, canonical.id, staff)
+                person_count += 1
+
+        _assert_residuals_are_defended()
+
+    return company_count, person_count
diff --git a/apps/company/services/person_merge_service.py b/apps/company/services/person_merge_service.py
index da92bd911..b08a7e77f 100644
--- a/apps/company/services/person_merge_service.py
+++ b/apps/company/services/person_merge_service.py
@@ -134,6 +134,15 @@ def merge_people(
             if destination is None:
                 raise ValueError(f"Destination Person {destination_id} does not exist")
 
+            update_fields = ["updated_at"]
+            if not destination.email and source.email:
+                destination.email = source.email
+                update_fields.append("email")
+            if source.is_active and not destination.is_active:
+                destination.is_active = True
+                update_fields.append("is_active")
+            destination.save(update_fields=update_fields)
+
             links_moved, links_collapsed = _merge_links(source, destination)
             methods_moved, methods_collapsed = _merge_contact_methods(
                 source, destination
diff --git a/apps/company/tests/test_kan278_duplicate_cleanup.py b/apps/company/tests/test_kan278_duplicate_cleanup.py
index eb6172199..77eef774b 100644
--- a/apps/company/tests/test_kan278_duplicate_cleanup.py
+++ b/apps/company/tests/test_kan278_duplicate_cleanup.py
@@ -1,3 +1,5 @@
+import re
+from pathlib import Path
 from unittest.mock import patch
 
 from django.utils import timezone
@@ -5,6 +7,9 @@
 from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
 from apps.company.services import kan278_duplicate_cleanup
 from apps.company.services.kan278_duplicate_cleanup import (
+    CompanyMergeDecision,
+    PersonMergeDecision,
+    PersonSelector,
     apply_reviewed_duplicate_cleanup,
 )
 from apps.job.models import Job
@@ -12,7 +17,7 @@
 
 
 class ReviewedDuplicateCleanupTests(BaseTestCase):
-    def test_applies_company_first_then_person_merge(self) -> None:
+    def test_applies_named_company_then_person_decisions(self) -> None:
         destination_company = Company.objects.create(
             name="Northland Roofs NZ",
             xero_last_modified=timezone.now(),
@@ -26,11 +31,11 @@ def test_applies_company_first_then_person_merge(self) -> None:
             name="ACE PUNIA", email="ace@example.com"
         )
         source_person = Person.objects.create(name="Ace Punia", email="ACE@example.com")
-        destination_link = CompanyPersonLink.objects.create(
+        CompanyPersonLink.objects.create(
             company=destination_company,
             person=destination_person,
         )
-        source_link = CompanyPersonLink.objects.create(
+        CompanyPersonLink.objects.create(
             company=source_company,
             person=source_person,
         )
@@ -47,26 +52,44 @@ def test_applies_company_first_then_person_merge(self) -> None:
         )
         job.save(staff=self.test_staff)
 
+        company_decision = CompanyMergeDecision(
+            canonical_name="Northland Roofs NZ",
+            names=("CASH SALE - Northland Roofs NZ", "Northland Roofs NZ"),
+            expected_rows=2,
+            evidence="same production email, phone and Ace Punia",
+        )
+        person_decision = PersonMergeDecision(
+            canonical=PersonSelector(
+                "ACE PUNIA", "ace@example.com", "Northland Roofs NZ"
+            ),
+            members=(
+                PersonSelector("ACE PUNIA", "ace@example.com", "Northland Roofs NZ"),
+                PersonSelector(
+                    "Ace Punia",
+                    "ACE@example.com",
+                    "CASH SALE - Northland Roofs NZ",
+                ),
+            ),
+            expected_people=2,
+            evidence="same production email and phone",
+        )
+
         with (
             patch.object(
                 kan278_duplicate_cleanup,
                 "REVIEWED_COMPANY_MERGES",
-                ((str(source_company.id), str(destination_company.id)),),
+                (company_decision,),
             ),
             patch.object(
                 kan278_duplicate_cleanup,
-                "REVIEWED_PERSON_LINK_EDGES",
-                ((str(source_link.id), str(destination_link.id)),),
+                "REVIEWED_PERSON_MERGES",
+                (person_decision,),
             ),
+            patch.object(kan278_duplicate_cleanup, "INVALID_LINKS", ()),
+            patch.object(kan278_duplicate_cleanup, "_repair_matt_green"),
             patch.object(
                 kan278_duplicate_cleanup,
-                "MATT_GREEN_LINK_ID",
-                source_link.id,
-            ),
-            patch.object(
-                kan278_duplicate_cleanup,
-                "MATT_WRONG_METHOD_VALUES",
-                set(),
+                "_assert_residuals_are_defended",
             ),
         ):
             company_count, person_count = apply_reviewed_duplicate_cleanup()
@@ -79,27 +102,39 @@ def test_applies_company_first_then_person_merge(self) -> None:
         self.assertFalse(source_company.allow_jobs)
         self.assertEqual(source_company.xero_contact_id, "source-xero-id")
         self.assertEqual(job.company_id, destination_company.id)
-        self.assertIn(job.person_id, {source_person.id, destination_person.id})
-        self.assertEqual(
-            Person.objects.filter(
-                id__in=[source_person.id, destination_person.id]
-            ).count(),
-            1,
-        )
-        self.assertEqual(
-            CompanyPersonLink.objects.filter(company=destination_company).count(), 1
-        )
+        self.assertEqual(job.person_id, destination_person.id)
+        self.assertFalse(Person.objects.filter(id=source_person.id).exists())
 
-    def test_rejects_partially_present_company_evidence(self) -> None:
+    def test_changed_named_evidence_aborts_before_writes(self) -> None:
         destination = Company.objects.create(
             name="Destination",
             xero_last_modified=timezone.now(),
         )
+        decision = CompanyMergeDecision(
+            canonical_name="Destination",
+            names=("Missing source", "Destination"),
+            expected_rows=2,
+            evidence="fixture evidence",
+        )
 
-        with patch.object(
-            kan278_duplicate_cleanup,
-            "REVIEWED_COMPANY_MERGES",
-            (("00000000-0000-0000-0000-000000000278", str(destination.id)),),
+        with (
+            patch.object(
+                kan278_duplicate_cleanup,
+                "REVIEWED_COMPANY_MERGES",
+                (decision,),
+            ),
+            patch.object(kan278_duplicate_cleanup, "REVIEWED_PERSON_MERGES", ()),
+            patch.object(kan278_duplicate_cleanup, "INVALID_LINKS", ()),
         ):
-            with self.assertRaisesRegex(RuntimeError, "Company merge evidence"):
+            with self.assertRaisesRegex(RuntimeError, "Company evidence changed"):
                 apply_reviewed_duplicate_cleanup()
+
+        destination.refresh_from_db()
+        self.assertIsNone(destination.merged_into_id)
+
+    def test_cleanup_manifest_contains_no_uuid_literals(self) -> None:
+        source = Path(kan278_duplicate_cleanup.__file__).read_text()
+        uuid_literal = re.compile(
+            r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+        )
+        self.assertIsNone(uuid_literal.search(source))
diff --git a/apps/company/tests/test_person_merge_service.py b/apps/company/tests/test_person_merge_service.py
index 3e21034f4..d90dead1f 100644
--- a/apps/company/tests/test_person_merge_service.py
+++ b/apps/company/tests/test_person_merge_service.py
@@ -120,6 +120,20 @@ def test_collapses_same_company_link_and_exact_method(self) -> None:
         self.assertEqual(counts["links_collapsed"], 1)
         self.assertEqual(counts["contact_methods_collapsed"], 1)
 
+    def test_preserves_source_scalar_fields_missing_from_destination(self) -> None:
+        source = Person.objects.create(
+            name="Jane Smith",
+            email="jane@example.com",
+            is_active=True,
+        )
+        destination = Person.objects.create(name="J Smith", is_active=False)
+
+        merge_people(source.id, destination.id, self.test_staff)
+
+        destination.refresh_from_db()
+        self.assertEqual(destination.email, "jane@example.com")
+        self.assertTrue(destination.is_active)
+
     def test_unexpected_failure_rolls_back_and_persists_once(self) -> None:
         """A mid-merge failure must not strand links or create duplicate AppErrors."""
         source = Person.objects.create(name="J Smith")

From f79d02a7608232e312a581400517b4a2796561b0 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 11:14:12 +1200
Subject: [PATCH 23/73] fix: satisfy KAN-278 type gate

---
 .../0008_apply_reviewed_duplicate_cleanup.py  |  6 ++++-
 .../services/kan278_duplicate_cleanup.py      | 24 +++++++++++--------
 mypy-baseline.txt                             |  1 -
 3 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
index 4baa226e5..26aafc441 100644
--- a/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
+++ b/apps/company/migrations/0008_apply_reviewed_duplicate_cleanup.py
@@ -1,7 +1,11 @@
+from django.apps.registry import Apps
 from django.db import migrations
+from django.db.backends.base.schema import BaseDatabaseSchemaEditor
 
 
-def apply_reviewed_cleanup(apps, schema_editor) -> None:
+def apply_reviewed_cleanup(
+    apps: Apps, schema_editor: BaseDatabaseSchemaEditor
+) -> None:
     # This installation-specific cleanup intentionally uses the tested merge
     # services so JobEvents and every cross-app Company FK remain consistent.
     from apps.company.services.kan278_duplicate_cleanup import (
diff --git a/apps/company/services/kan278_duplicate_cleanup.py b/apps/company/services/kan278_duplicate_cleanup.py
index b9be6905b..c39b97634 100644
--- a/apps/company/services/kan278_duplicate_cleanup.py
+++ b/apps/company/services/kan278_duplicate_cleanup.py
@@ -2975,8 +2975,10 @@ def _assert_residuals_are_defended() -> None:
             USER_APPROVED_RETAINED_COMPANY_DECISIONS + AGENT_RETAINED_COMPANY_DECISIONS
         )
     }
-    for group in report["company_groups"]:
-        names = _normalised_names([member["name"] for member in group["members"]])
+    for company_group in report["company_groups"]:
+        names = _normalised_names(
+            [member["name"] for member in company_group["members"]]
+        )
         if not any(names <= retained for retained in retained_companies):
             raise RuntimeError(
                 f"KAN-278 has an undefended retained Company group: {sorted(names)}"
@@ -2988,8 +2990,10 @@ def _assert_residuals_are_defended() -> None:
             USER_APPROVED_RETAINED_PERSON_DECISIONS + AGENT_RETAINED_PERSON_DECISIONS
         )
     }
-    for group in report["person_groups"]:
-        names = _normalised_names([member["name"] for member in group["members"]])
+    for person_group in report["person_groups"]:
+        names = _normalised_names(
+            [member["name"] for member in person_group["members"]]
+        )
         if not any(names <= retained for retained in retained_people):
             raise RuntimeError(
                 f"KAN-278 has an undefended retained Person group: {sorted(names)}"
@@ -3032,14 +3036,14 @@ def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
         _repair_matt_green()
 
         _flatten_existing_company_merges(staff)
-        for canonical, sources in company_groups:
-            for source in sources:
-                merge_companies(source.id, canonical.id, staff)
+        for canonical_company, source_companies in company_groups:
+            for source_company in source_companies:
+                merge_companies(source_company.id, canonical_company.id, staff)
                 company_count += 1
 
-        for canonical, sources in person_groups:
-            for source in sources:
-                merge_people(source.id, canonical.id, staff)
+        for canonical_person, source_people in person_groups:
+            for source_person in source_people:
+                merge_people(source_person.id, canonical_person.id, staff)
                 person_count += 1
 
         _assert_residuals_are_defended()
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index 0d212b9ef..19589b8de 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -484,7 +484,6 @@ apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types
 apps/accounting/services/sales_pipeline_service.py:0: error: Incompatible types in assignment (expression has type "float | None", target has type "float")  [assignment]
 apps/accounting/services/sales_pipeline_service.py:0: error: Item "None" of "Company | None" has no attribute "name"  [union-attr]
 apps/accounting/services/invoice_calculation.py:0: error: Returning Any from function declared to return "Job"  [no-any-return]
-apps/company/services/company_merge_service.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]
 apps/company/management/commands/merge_companies.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/management/commands/merge_companies.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/quoting/services/providers/gemini_provider.py:0: error: Function is missing a type annotation for one or more parameters  [no-untyped-def]

From c589642e43c074bff132ba686f8e07e0e8632eed Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 11:59:47 +1200
Subject: [PATCH 24/73] fix: address KAN-278 review findings

---
 .../commands/cleanup_duplicate_identities.py  | 179 ------------------
 .../0007_remove_xero_person_identity.py       |   3 +-
 .../services/duplicate_person_report.py       |  30 ++-
 .../services/kan278_duplicate_cleanup.py      |  44 ++++-
 ...st_cleanup_duplicate_identities_command.py |  35 ----
 .../tests/test_duplicate_person_report.py     |  21 ++
 .../tests/test_kan278_duplicate_cleanup.py    |  87 +++++++++
 7 files changed, 167 insertions(+), 232 deletions(-)
 delete mode 100644 apps/company/management/commands/cleanup_duplicate_identities.py
 delete mode 100644 apps/company/tests/test_cleanup_duplicate_identities_command.py

diff --git a/apps/company/management/commands/cleanup_duplicate_identities.py b/apps/company/management/commands/cleanup_duplicate_identities.py
deleted file mode 100644
index c0ff2d7b4..000000000
--- a/apps/company/management/commands/cleanup_duplicate_identities.py
+++ /dev/null
@@ -1,179 +0,0 @@
-"""Preview and apply grouped Company and Person duplicate decisions."""
-
-import csv
-from pathlib import Path
-from typing import Any, Literal
-from uuid import UUID
-
-from django.core.management.base import BaseCommand, CommandError
-from django.db import transaction
-
-from apps.accounts.models import Staff
-from apps.company.services.company_merge_service import merge_companies
-from apps.company.services.duplicate_identity_report import (
-    DuplicateCompanyGroup,
-    DuplicateIdentityReportService,
-    DuplicatePersonGroup,
-)
-from apps.company.services.person_merge_service import merge_people
-
-EntityKind = Literal["company", "person"]
-CSV_COLUMNS = [
-    "entity_kind",
-    "action",
-    "group_id",
-    "fingerprint",
-    "recommendation",
-    "canonical_id",
-    "members",
-    "reason_codes",
-    "evidence",
-]
-
-
-class Command(BaseCommand):
-    help = "Preview duplicate identity groups or apply a reviewed merge CSV"
-
-    def add_arguments(self, parser: Any) -> None:
-        modes = parser.add_mutually_exclusive_group(required=True)
-        modes.add_argument("--preview", type=str, help="Write grouped candidate CSV")
-        modes.add_argument("--apply", type=str, help="Apply reviewed grouped CSV")
-
-    def handle(self, *args: Any, **options: Any) -> None:
-        preview_path = options["preview"]
-        apply_path = options["apply"]
-        if preview_path is not None:
-            self._preview(Path(preview_path))
-        elif apply_path is not None:
-            self._apply(Path(apply_path))
-        else:
-            raise CommandError("Specify --preview or --apply")
-
-    def _preview(self, path: Path) -> None:
-        if not path.parent.exists():
-            raise CommandError(f"Output directory does not exist: {path.parent}")
-        report = DuplicateIdentityReportService().get_report()
-        rows = [self._company_row(group) for group in report["company_groups"]] + [
-            self._person_row(group) for group in report["person_groups"]
-        ]
-        with path.open("w", newline="", encoding="utf-8") as output:
-            writer = csv.DictWriter(output, fieldnames=CSV_COLUMNS)
-            writer.writeheader()
-            writer.writerows(rows)
-        self.stdout.write(
-            self.style.SUCCESS(f"Wrote {len(rows)} duplicate identity groups to {path}")
-        )
-
-    @staticmethod
-    def _company_row(group: DuplicateCompanyGroup) -> dict[str, str]:
-        return {
-            "entity_kind": "company",
-            "action": "merge" if group["recommendation"] == "merge" else "",
-            "group_id": group["group_id"],
-            "fingerprint": group["fingerprint"],
-            "recommendation": group["recommendation"],
-            "canonical_id": group["canonical_id"] or "",
-            "members": "; ".join(
-                f"{member['company_id']}={member['name']}"
-                for member in group["members"]
-            ),
-            "reason_codes": ";".join(group["reason_codes"]),
-            "evidence": "; ".join(
-                f"{item['kind']}={item['normalized_value']}"
-                for item in group["evidence"]
-            ),
-        }
-
-    @staticmethod
-    def _person_row(group: DuplicatePersonGroup) -> dict[str, str]:
-        return {
-            "entity_kind": "person",
-            "action": "merge" if group["recommendation"] == "merge" else "",
-            "group_id": group["group_id"],
-            "fingerprint": group["fingerprint"],
-            "recommendation": group["recommendation"],
-            "canonical_id": group["canonical_id"] or "",
-            "members": "; ".join(
-                f"{member['person_id']}={member['name']}" for member in group["members"]
-            ),
-            "reason_codes": ";".join(group["reason_codes"]),
-            "evidence": "; ".join(
-                f"{item['kind']}={item['normalized_value']}"
-                for item in group["evidence"]
-            ),
-        }
-
-    def _apply(self, path: Path) -> None:
-        if not path.is_file():
-            raise CommandError(f"CSV file not found: {path}")
-        with path.open(newline="", encoding="utf-8") as input_file:
-            reader = csv.DictReader(input_file)
-            if reader.fieldnames != CSV_COLUMNS:
-                raise CommandError("CSV columns do not match the preview contract")
-            selected = [row for row in reader if row["action"].strip() == "merge"]
-        if not selected:
-            raise CommandError("CSV contains no rows with action=merge")
-
-        report = DuplicateIdentityReportService().get_report()
-        current_companies = {
-            ("company", group["group_id"]): group for group in report["company_groups"]
-        }
-        current_people = {
-            ("person", group["group_id"]): group for group in report["person_groups"]
-        }
-        decisions: list[tuple[EntityKind, UUID, list[UUID]]] = []
-        for row_number, row in enumerate(selected, 2):
-            entity_kind = row["entity_kind"]
-            canonical_id = self._uuid(row["canonical_id"], row_number)
-            if entity_kind == "company":
-                company_group = current_companies.get(("company", row["group_id"]))
-                if (
-                    company_group is None
-                    or company_group["fingerprint"] != row["fingerprint"]
-                ):
-                    raise CommandError(
-                        f"Row {row_number}: group is stale or no longer exists"
-                    )
-                member_ids = [
-                    UUID(member["company_id"]) for member in company_group["members"]
-                ]
-                decision_kind: EntityKind = "company"
-            elif entity_kind == "person":
-                person_group = current_people.get(("person", row["group_id"]))
-                if (
-                    person_group is None
-                    or person_group["fingerprint"] != row["fingerprint"]
-                ):
-                    raise CommandError(
-                        f"Row {row_number}: group is stale or no longer exists"
-                    )
-                member_ids = [
-                    UUID(member["person_id"]) for member in person_group["members"]
-                ]
-                decision_kind = "person"
-            else:
-                raise CommandError(f"Row {row_number}: invalid entity_kind")
-            if canonical_id not in member_ids:
-                raise CommandError(f"Row {row_number}: canonical_id is not a member")
-            decisions.append((decision_kind, canonical_id, member_ids))
-
-        staff = Staff.get_automation_user()
-        merge_count = 0
-        with transaction.atomic():
-            for entity_kind, canonical_id, member_ids in decisions:
-                for source_id in member_ids:
-                    if source_id == canonical_id:
-                        continue
-                    if entity_kind == "company":
-                        merge_companies(source_id, canonical_id, staff)
-                    else:
-                        merge_people(source_id, canonical_id, staff)
-                    merge_count += 1
-        self.stdout.write(self.style.SUCCESS(f"Applied {merge_count} identity merges"))
-
-    @staticmethod
-    def _uuid(raw_value: str, row_number: int) -> UUID:
-        try:
-            return UUID(raw_value)
-        except ValueError as exc:
-            raise CommandError(f"Row {row_number}: invalid canonical_id") from exc
diff --git a/apps/company/migrations/0007_remove_xero_person_identity.py b/apps/company/migrations/0007_remove_xero_person_identity.py
index 096225f9b..e89172ba9 100644
--- a/apps/company/migrations/0007_remove_xero_person_identity.py
+++ b/apps/company/migrations/0007_remove_xero_person_identity.py
@@ -7,7 +7,8 @@
 
 def delete_unreferenced_people(apps: Any, schema_editor: Any) -> None:
     Person = apps.get_model("company", "Person")
-    Person.objects.filter(
+    database_alias = schema_editor.connection.alias
+    Person.objects.using(database_alias).filter(
         company_links__isnull=True,
         contact_methods__isnull=True,
         jobs__isnull=True,
diff --git a/apps/company/services/duplicate_person_report.py b/apps/company/services/duplicate_person_report.py
index 9239a61ca..7653de51c 100644
--- a/apps/company/services/duplicate_person_report.py
+++ b/apps/company/services/duplicate_person_report.py
@@ -106,6 +106,22 @@ def _alias_groups() -> dict[str, set[str]]:
     return groups
 
 
+def _build_alias_index(groups: dict[str, set[str]]) -> dict[str, frozenset[str]]:
+    canonical_by_name: dict[str, set[str]] = defaultdict(set)
+    for canonical, names in groups.items():
+        for name in names:
+            canonical_by_name[name].add(canonical)
+    return {
+        name: frozenset(canonical_names)
+        for name, canonical_names in canonical_by_name.items()
+    }
+
+
+@lru_cache(maxsize=1)
+def _default_alias_index() -> dict[str, frozenset[str]]:
+    return _build_alias_index(_alias_groups())
+
+
 def person_names_compatible(
     first_name: str,
     second_name: str,
@@ -120,14 +136,14 @@ def person_names_compatible(
     if first_tokens == second_tokens:
         return True
 
-    groups = _alias_groups() if alias_groups is None else alias_groups
+    alias_index = (
+        _default_alias_index()
+        if alias_groups is None
+        else _build_alias_index(alias_groups)
+    )
     first_names_match = first_tokens[0] == second_tokens[0]
-    first_canonical = {
-        canonical for canonical, names in groups.items() if first_tokens[0] in names
-    }
-    second_canonical = {
-        canonical for canonical, names in groups.items() if second_tokens[0] in names
-    }
+    first_canonical = alias_index.get(first_tokens[0], frozenset())
+    second_canonical = alias_index.get(second_tokens[0], frozenset())
     if not first_names_match and not first_canonical & second_canonical:
         return False
 
diff --git a/apps/company/services/kan278_duplicate_cleanup.py b/apps/company/services/kan278_duplicate_cleanup.py
index c39b97634..89207359a 100644
--- a/apps/company/services/kan278_duplicate_cleanup.py
+++ b/apps/company/services/kan278_duplicate_cleanup.py
@@ -7,6 +7,7 @@
 """
 
 from dataclasses import dataclass
+from uuid import UUID
 
 from django.db import transaction
 from django.db.models import Q
@@ -3001,16 +3002,38 @@ def _assert_residuals_are_defended() -> None:
 
 
 def _flatten_existing_company_merges(staff: Staff) -> None:
-    existing = list(
-        Company.objects.filter(
-            merged_into__isnull=False,
-            merged_into__merged_into__isnull=True,
-        ).values_list("id", "merged_into_id")
-    )
-    for source_id, destination_id in existing:
-        if destination_id is None:
-            raise RuntimeError(f"Merged Company {source_id} has no destination")
-        merge_companies(source_id, destination_id, staff)
+    company_rows = list(Company.objects.values_list("id", "merged_into_id"))
+    company_ids = {company_id for company_id, _destination_id in company_rows}
+    destinations = {
+        company_id: destination_id
+        for company_id, destination_id in company_rows
+        if destination_id is not None
+    }
+
+    for destination_id in destinations.values():
+        if destination_id not in company_ids:
+            raise RuntimeError(
+                f"Merged Company destination {destination_id} does not exist"
+            )
+
+    terminal_destinations: dict[UUID, UUID] = {}
+    for source_id, direct_destination_id in destinations.items():
+        visited = {source_id}
+        terminal_id = direct_destination_id
+        while terminal_id in destinations:
+            if terminal_id in visited:
+                raise RuntimeError(f"Company merge cycle includes {terminal_id}")
+            visited.add(terminal_id)
+            terminal_id = destinations[terminal_id]
+        terminal_destinations[source_id] = terminal_id
+
+    for source_id, terminal_id in terminal_destinations.items():
+        if destinations[source_id] != terminal_id:
+            Company.objects.filter(id=source_id).update(merged_into_id=terminal_id)
+        merge_companies(source_id, terminal_id, staff)
+
+    if Company.objects.filter(merged_into__merged_into__isnull=False).exists():
+        raise RuntimeError("KAN-278 cleanup left a multi-hop Company merge")
 
 
 def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
@@ -3040,6 +3063,7 @@ def apply_reviewed_duplicate_cleanup() -> tuple[int, int]:
             for source_company in source_companies:
                 merge_companies(source_company.id, canonical_company.id, staff)
                 company_count += 1
+        _flatten_existing_company_merges(staff)
 
         for canonical_person, source_people in person_groups:
             for source_person in source_people:
diff --git a/apps/company/tests/test_cleanup_duplicate_identities_command.py b/apps/company/tests/test_cleanup_duplicate_identities_command.py
deleted file mode 100644
index 3932ccc05..000000000
--- a/apps/company/tests/test_cleanup_duplicate_identities_command.py
+++ /dev/null
@@ -1,35 +0,0 @@
-import csv
-from pathlib import Path
-from tempfile import TemporaryDirectory
-
-from django.core.management import call_command
-from django.utils import timezone
-
-from apps.company.models import Company
-from apps.testing import BaseTestCase
-
-
-class CleanupDuplicateIdentitiesCommandTests(BaseTestCase):
-    def test_preview_and_apply_grouped_company_merge(self) -> None:
-        first = Company.objects.create(
-            name="Acme Ltd", xero_last_modified=timezone.now()
-        )
-        second = Company.objects.create(
-            name="CASH SALE - Acme Limited", xero_last_modified=timezone.now()
-        )
-        with TemporaryDirectory() as directory:
-            path = Path(directory) / "duplicates.csv"
-            call_command("cleanup_duplicate_identities", preview=str(path))
-
-            with path.open(newline="", encoding="utf-8") as input_file:
-                rows = list(csv.DictReader(input_file))
-            self.assertEqual(len(rows), 1)
-            self.assertEqual(rows[0]["entity_kind"], "company")
-            self.assertEqual(rows[0]["action"], "merge")
-
-            call_command("cleanup_duplicate_identities", apply=str(path))
-
-        first.refresh_from_db()
-        second.refresh_from_db()
-        merged = [company for company in (first, second) if company.merged_into_id]
-        self.assertEqual(len(merged), 1)
diff --git a/apps/company/tests/test_duplicate_person_report.py b/apps/company/tests/test_duplicate_person_report.py
index e744fc6a8..6b92ede3d 100644
--- a/apps/company/tests/test_duplicate_person_report.py
+++ b/apps/company/tests/test_duplicate_person_report.py
@@ -106,3 +106,24 @@ def test_two_contact_signals_with_incompatible_names_is_medium(self) -> None:
 
     def test_nickname_does_not_override_conflicting_surnames(self) -> None:
         self.assertFalse(person_names_compatible("Robert Grant", "Rob Smith"))
+
+    def test_custom_overlapping_alias_groups_preserve_any_canonical_match(self) -> None:
+        alias_groups = {
+            "robert": {"rob"},
+            "robin": {"rob", "bob"},
+        }
+
+        self.assertTrue(
+            person_names_compatible(
+                "Rob Grant",
+                "Bob Grant",
+                alias_groups=alias_groups,
+            )
+        )
+        self.assertFalse(
+            person_names_compatible(
+                "Rob Grant",
+                "Bob Smith",
+                alias_groups=alias_groups,
+            )
+        )
diff --git a/apps/company/tests/test_kan278_duplicate_cleanup.py b/apps/company/tests/test_kan278_duplicate_cleanup.py
index 77eef774b..d8f48bc8a 100644
--- a/apps/company/tests/test_kan278_duplicate_cleanup.py
+++ b/apps/company/tests/test_kan278_duplicate_cleanup.py
@@ -17,6 +17,40 @@
 
 
 class ReviewedDuplicateCleanupTests(BaseTestCase):
+    def test_flattens_existing_multi_hop_company_merges(self) -> None:
+        terminal = Company.objects.create(
+            name="Terminal Company",
+            xero_last_modified=timezone.now(),
+        )
+        middle = Company.objects.create(
+            name="Middle Company",
+            xero_last_modified=timezone.now(),
+            merged_into=terminal,
+        )
+        source = Company.objects.create(
+            name="Source Company",
+            xero_last_modified=timezone.now(),
+            merged_into=middle,
+        )
+        job = Job(
+            company=source,
+            name="Stranded historical job",
+            job_number=998279,
+        )
+        job.save(staff=self.test_staff)
+
+        kan278_duplicate_cleanup._flatten_existing_company_merges(self.test_staff)
+
+        source.refresh_from_db()
+        middle.refresh_from_db()
+        job.refresh_from_db()
+        self.assertEqual(source.merged_into_id, terminal.id)
+        self.assertEqual(middle.merged_into_id, terminal.id)
+        self.assertEqual(job.company_id, terminal.id)
+        self.assertFalse(
+            Company.objects.filter(merged_into__merged_into__isnull=False).exists()
+        )
+
     def test_applies_named_company_then_person_decisions(self) -> None:
         destination_company = Company.objects.create(
             name="Northland Roofs NZ",
@@ -105,6 +139,59 @@ def test_applies_named_company_then_person_decisions(self) -> None:
         self.assertEqual(job.person_id, destination_person.id)
         self.assertFalse(Person.objects.filter(id=source_person.id).exists())
 
+    def test_flattens_chain_created_by_reviewed_company_decisions(self) -> None:
+        terminal = Company.objects.create(
+            name="Terminal Company",
+            xero_last_modified=timezone.now(),
+        )
+        middle = Company.objects.create(
+            name="Middle Company",
+            xero_last_modified=timezone.now(),
+        )
+        source = Company.objects.create(
+            name="Source Company",
+            xero_last_modified=timezone.now(),
+            merged_into=middle,
+        )
+        decisions = (
+            CompanyMergeDecision(
+                canonical_name="Terminal Company",
+                names=("Middle Company", "Terminal Company"),
+                expected_rows=2,
+                evidence="fixture reviewed merge",
+            ),
+        )
+
+        with (
+            patch.object(
+                kan278_duplicate_cleanup,
+                "REVIEWED_COMPANY_MERGES",
+                decisions,
+            ),
+            patch.object(
+                kan278_duplicate_cleanup,
+                "REVIEWED_PERSON_MERGES",
+                (),
+            ),
+            patch.object(kan278_duplicate_cleanup, "INVALID_LINKS", ()),
+            patch.object(kan278_duplicate_cleanup, "_repair_matt_green"),
+            patch.object(
+                kan278_duplicate_cleanup,
+                "_assert_residuals_are_defended",
+            ),
+        ):
+            company_count, person_count = apply_reviewed_duplicate_cleanup()
+
+        source.refresh_from_db()
+        middle.refresh_from_db()
+        self.assertEqual(company_count, 1)
+        self.assertEqual(person_count, 0)
+        self.assertEqual(source.merged_into_id, terminal.id)
+        self.assertEqual(middle.merged_into_id, terminal.id)
+        self.assertFalse(
+            Company.objects.filter(merged_into__merged_into__isnull=False).exists()
+        )
+
     def test_changed_named_evidence_aborts_before_writes(self) -> None:
         destination = Company.objects.create(
             name="Destination",

From d6242551f2877d351c07e3e449f2fc1970fcb4c4 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 13:01:51 +1200
Subject: [PATCH 25/73] test: detect uppercase UUID literals

---
 apps/company/tests/test_kan278_duplicate_cleanup.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/apps/company/tests/test_kan278_duplicate_cleanup.py b/apps/company/tests/test_kan278_duplicate_cleanup.py
index d8f48bc8a..c3df67d59 100644
--- a/apps/company/tests/test_kan278_duplicate_cleanup.py
+++ b/apps/company/tests/test_kan278_duplicate_cleanup.py
@@ -222,6 +222,7 @@ def test_changed_named_evidence_aborts_before_writes(self) -> None:
     def test_cleanup_manifest_contains_no_uuid_literals(self) -> None:
         source = Path(kan278_duplicate_cleanup.__file__).read_text()
         uuid_literal = re.compile(
-            r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+            r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}",
+            re.IGNORECASE,
         )
         self.assertIsNone(uuid_literal.search(source))

From 5bf012f3e55d58823c7542945dd5827f25b9293b Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 14:13:26 +1200
Subject: [PATCH 26/73] feat: complete first-class people management

---
 apps/company/__init__.py                      |   30 +
 apps/company/models.py                        |   26 +-
 apps/company/person_serializers.py            |  201 +++
 apps/company/services/__init__.py             |   26 +
 apps/company/services/person_service.py       |  346 ++++++
 apps/company/tests/test_contact_methods.py    |   70 +-
 apps/company/tests/test_person_api.py         |  227 ++++
 apps/company/urls_people_rest.py              |   39 +
 apps/company/urls_rest.py                     |   18 +-
 apps/company/views/__init__.py                |   20 +-
 apps/company/views/contact_method_viewset.py  |    7 +-
 apps/company/views/contact_viewset.py         |   70 --
 apps/company/views/person_views.py            |  282 +++++
 apps/crm/services/phone_call_service.py       |    4 +-
 apps/crm/tests/test_phone_call_service.py     |    9 -
 apps/crm/views/phone_call_views.py            |    2 -
 ..._rename_remaining_crm_telemetry_sources.py |   32 +
 .../tests/test_search_telemetry_migration.py  |   32 +-
 docketworks/settings.py                       |   13 +-
 docketworks/urls.py                           |    1 +
 .../client_contact_management_test_plan.md    |  168 ---
 .../company_people_management_test_plan.md    |   70 ++
 docs/urls/client.md                           |   45 -
 docs/urls/company.md                          |   20 +
 frontend/docs/jobview-etag-guide.md           |    4 +-
 frontend/router-auto-options.ts               |    2 +
 frontend/schema.yml                           | 1104 ++++++++++++-----
 frontend/scripts/capture-screenshots.ts       |   14 +-
 frontend/src/api/generated/api.ts             |  621 +++++++---
 frontend/src/assets/main.css                  |    4 -
 frontend/src/components/AppNavbar.vue         |   16 +
 .../src/components/PersonSelectionModal.vue   |  187 ++-
 frontend/src/components/PersonSelector.vue    |   82 +-
 .../__tests__/CompanyLookup.test.ts           |    2 +-
 ...PersonSelectionModal.phoneConflict.test.ts |  125 ++
 .../src/components/crm/PhoneNumberManager.vue |    4 +-
 .../src/components/job/JobSettingsTab.vue     |   16 +-
 .../__tests__/usePersonManagement.test.ts     |  217 +++-
 frontend/src/composables/useCompanyLookup.ts  |   16 +-
 .../src/composables/usePersonManagement.ts    |  265 ++--
 frontend/src/pages/crm/calls.vue              |   10 +-
 frontend/src/pages/crm/companies/(index).vue  |    2 +-
 frontend/src/pages/crm/companies/[id].vue     |   43 +-
 frontend/src/pages/crm/people/(index).vue     |  224 ++++
 frontend/src/pages/crm/people/[id].vue        |  436 +++++++
 .../people/__tests__/people-directory.test.ts |   62 +
 .../people/__tests__/person-detail.test.ts    |  121 ++
 frontend/src/pages/jobs/create.vue            |    8 +-
 frontend/src/pages/purchasing/po/[id].vue     |    8 +-
 .../src/stores/__tests__/companyStore.test.ts |   33 +-
 frontend/src/stores/companyStore.ts           |   18 +-
 frontend/src/typed-router.d.ts                |   26 +
 frontend/tests/crm/people.spec.ts             |  100 ++
 mypy-baseline.txt                             |    4 -
 54 files changed, 4244 insertions(+), 1288 deletions(-)
 create mode 100644 apps/company/person_serializers.py
 create mode 100644 apps/company/services/person_service.py
 create mode 100644 apps/company/tests/test_person_api.py
 create mode 100644 apps/company/urls_people_rest.py
 delete mode 100644 apps/company/views/contact_viewset.py
 create mode 100644 apps/company/views/person_views.py
 create mode 100644 apps/workflow/migrations/0009_rename_remaining_crm_telemetry_sources.py
 delete mode 100644 docs/test_plans/client_contact_management_test_plan.md
 create mode 100644 docs/test_plans/company_people_management_test_plan.md
 delete mode 100644 docs/urls/client.md
 create mode 100644 frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
 create mode 100644 frontend/src/pages/crm/people/(index).vue
 create mode 100644 frontend/src/pages/crm/people/[id].vue
 create mode 100644 frontend/src/pages/crm/people/__tests__/people-directory.test.ts
 create mode 100644 frontend/src/pages/crm/people/__tests__/person-detail.test.ts
 create mode 100644 frontend/tests/crm/people.spec.ts

diff --git a/apps/company/__init__.py b/apps/company/__init__.py
index b15721916..2b2841847 100644
--- a/apps/company/__init__.py
+++ b/apps/company/__init__.py
@@ -19,6 +19,22 @@
             SupplierPickupAddress,
             SupplierSearchAlias,
         )
+        from .person_serializers import (
+            CompanyLinkWriteSerializer,
+            CompanyPersonCreateSerializer,
+            CompanyPersonSerializer,
+            PersonCompanyLinkSerializer,
+            PersonCompanySummarySerializer,
+            PersonContactMethodWriteSerializer,
+            PersonDetailSerializer,
+            PersonIdentityUpdateSerializer,
+            PersonSummarySerializer,
+            PhoneCompanyOwnerSerializer,
+            PhoneOwnershipConflictSerializer,
+            PhoneOwnershipRequestSerializer,
+            PhoneOwnershipSerializer,
+            PhonePersonMatchSerializer,
+        )
         from .serializers import (
             CompanyCreateResponseSerializer,
             CompanyCreateSerializer,
@@ -64,14 +80,17 @@
     "CompanyErrorResponseSerializer",
     "CompanyJobHeaderSerializer",
     "CompanyJobsResponseSerializer",
+    "CompanyLinkWriteSerializer",
     "CompanyListResponseSerializer",
     "CompanyNameOnlySerializer",
     "CompanyPersonCreateAttrs",
+    "CompanyPersonCreateSerializer",
     "CompanyPersonLink",
     "CompanyPersonLinkCreateAttrs",
     "CompanyPersonLinkModelCreateAttrs",
     "CompanyPersonLinkSerializer",
     "CompanyPersonLinkUpdateAttrs",
+    "CompanyPersonSerializer",
     "CompanyPersonUpdateAttrs",
     "CompanyQuerySet",
     "CompanySearchResponseSerializer",
@@ -85,7 +104,18 @@
     "JobPersonResponseSerializer",
     "JobPersonUpdateSerializer",
     "Person",
+    "PersonCompanyLinkSerializer",
+    "PersonCompanySummarySerializer",
+    "PersonContactMethodWriteSerializer",
+    "PersonDetailSerializer",
+    "PersonIdentityUpdateSerializer",
+    "PersonSummarySerializer",
     "PhoneAssignmentConflictError",
+    "PhoneCompanyOwnerSerializer",
+    "PhoneOwnershipConflictSerializer",
+    "PhoneOwnershipRequestSerializer",
+    "PhoneOwnershipSerializer",
+    "PhonePersonMatchSerializer",
     "StandardErrorSerializer",
     "Supplier",
     "SupplierPickupAddress",
diff --git a/apps/company/models.py b/apps/company/models.py
index ce8433e28..96a85433b 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -387,9 +387,9 @@ def save(
         update_fields = _augment_update_fields(update_fields, "updated_at")
         # If this link is being set as primary, ensure no other links
         # for this company are marked as primary
-        if self.is_primary:
+        if self.is_primary and self.is_active:
             CompanyPersonLink.objects.filter(
-                company=self.company, is_primary=True
+                company=self.company, is_primary=True, is_active=True
             ).exclude(id=self.id).update(is_primary=False)
         super().save(
             force_insert=force_insert,
@@ -628,8 +628,16 @@ def owner_company_ids(self) -> set[uuid.UUID]:
             return {self.company_id}
         if self.person is not None:
             if "company_links" in getattr(self.person, "_prefetched_objects_cache", {}):
-                return {link.company_id for link in self.person.company_links.all()}
-            return set(self.person.company_links.values_list("company_id", flat=True))
+                return {
+                    link.company_id
+                    for link in self.person.company_links.all()
+                    if link.is_active
+                }
+            return set(
+                self.person.company_links.filter(is_active=True).values_list(
+                    "company_id", flat=True
+                )
+            )
         return set()
 
     @classmethod
@@ -649,6 +657,14 @@ def conflicting_company(
         queryset = (
             cls.objects.using(using)
             .select_related("company", "person")
+            .prefetch_related(
+                models.Prefetch(
+                    "person__company_links",
+                    queryset=CompanyPersonLink.objects.using(using).filter(
+                        is_active=True
+                    ),
+                )
+            )
             .filter(
                 method_type=cls.MethodType.PHONE,
                 normalized_value=normalized_value,
@@ -722,7 +738,7 @@ def check_phone_assignment(
         elif person is not None:
             effective_company_ids = set(
                 CompanyPersonLink.objects.using(using)
-                .filter(person_id=person.pk)
+                .filter(person_id=person.pk, is_active=True)
                 .values_list("company_id", flat=True)
             )
         else:
diff --git a/apps/company/person_serializers.py b/apps/company/person_serializers.py
new file mode 100644
index 000000000..335aab02e
--- /dev/null
+++ b/apps/company/person_serializers.py
@@ -0,0 +1,201 @@
+"""API contracts for first-class People and their company relationships."""
+
+from typing import Any
+
+from drf_spectacular.utils import extend_schema_field
+from rest_framework import serializers
+
+from apps.company.models import CompanyPersonLink, ContactMethod, Person
+from apps.company.services.person_service import (
+    PersonCompanyLinkData,
+    PersonDirectoryService,
+    PhoneCompanyOwner,
+    PhoneOwnershipResult,
+    PhonePersonMatch,
+)
+
+
+class PersonCompanyLinkSerializer(
+    serializers.Serializer[PersonCompanyLinkData | list[PersonCompanyLinkData]]
+):
+    company_id = serializers.UUIDField()
+    company_name = serializers.CharField()
+    position = serializers.CharField(allow_null=True)
+    is_primary = serializers.BooleanField()
+    notes = serializers.CharField(allow_null=True)
+    is_active = serializers.BooleanField()
+
+
+class PersonCompanySummarySerializer(serializers.Serializer[dict[str, str]]):
+    company_id = serializers.UUIDField()
+    company_name = serializers.CharField()
+
+
+class PersonSummarySerializer(serializers.ModelSerializer[Person]):
+    primary_phone = serializers.SerializerMethodField()
+    companies = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Person
+        fields = ["id", "name", "email", "primary_phone", "companies"]
+
+    def get_primary_phone(self, person: Person) -> str:
+        if "primary_phone" in person.__dict__:
+            return str(person.__dict__["primary_phone"])
+        method = (
+            person.contact_methods.filter(method_type=ContactMethod.MethodType.PHONE)
+            .order_by("-is_primary", "label", "value")
+            .first()
+        )
+        return method.value if method else ""
+
+    @extend_schema_field(PersonCompanySummarySerializer(many=True))
+    def get_companies(self, person: Person) -> list[dict[str, str]]:
+        return [
+            {
+                "company_id": link["company_id"],
+                "company_name": link["company_name"],
+            }
+            for link in sorted(
+                (
+                    link
+                    for link in PersonDirectoryService.company_links(person)
+                    if link["is_active"]
+                ),
+                key=lambda link: link["company_name"],
+            )
+        ]
+
+
+class PersonDetailSerializer(PersonSummarySerializer):
+    company_links = serializers.SerializerMethodField()
+
+    class Meta(PersonSummarySerializer.Meta):
+        fields = [
+            "id",
+            "name",
+            "email",
+            "is_active",
+            "created_at",
+            "updated_at",
+            "primary_phone",
+            "companies",
+            "company_links",
+        ]
+
+    @extend_schema_field(PersonCompanyLinkSerializer(many=True))
+    def get_company_links(self, person: Person) -> list[PersonCompanyLinkData]:
+        return list(PersonDirectoryService.company_links(person))
+
+
+class PersonIdentityUpdateSerializer(serializers.ModelSerializer[Person]):
+    class Meta:
+        model = Person
+        fields = ["name", "email"]
+        extra_kwargs = {
+            "name": {"required": False},
+            "email": {
+                "required": False,
+                "allow_blank": True,
+                "allow_null": True,
+            },
+        }
+
+
+class CompanyPersonSerializer(serializers.ModelSerializer[CompanyPersonLink]):
+    person_id = serializers.UUIDField(source="person.id", read_only=True)
+    person_name = serializers.CharField(source="person.name", read_only=True)
+    person_email = serializers.EmailField(
+        source="person.email", read_only=True, allow_null=True
+    )
+    primary_phone = serializers.CharField(source="phone", read_only=True)
+
+    class Meta:
+        model = CompanyPersonLink
+        fields = [
+            "person_id",
+            "person_name",
+            "person_email",
+            "primary_phone",
+            "position",
+            "is_primary",
+            "notes",
+        ]
+
+
+class CompanyPersonCreateSerializer(serializers.Serializer[None]):
+    name = serializers.CharField(max_length=255)
+    email = serializers.EmailField(required=False, allow_blank=True, allow_null=True)
+    phone = serializers.CharField(required=False, allow_blank=True, allow_null=True)
+    position = serializers.CharField(
+        required=False, allow_blank=True, allow_null=True, max_length=255
+    )
+    notes = serializers.CharField(required=False, allow_blank=True, allow_null=True)
+    is_primary = serializers.BooleanField(required=False, default=False)
+
+    def validate_phone(self, value: str | None) -> str | None:
+        if value and not ContactMethod.normalize_phone(value):
+            raise serializers.ValidationError(
+                "Phone number must contain at least one digit"
+            )
+        return value
+
+
+class CompanyLinkWriteSerializer(serializers.Serializer[None]):
+    position = serializers.CharField(
+        required=False, allow_blank=True, allow_null=True, max_length=255, default=None
+    )
+    notes = serializers.CharField(
+        required=False, allow_blank=True, allow_null=True, default=None
+    )
+    is_primary = serializers.BooleanField(required=False, default=False)
+
+
+class PhoneOwnershipRequestSerializer(serializers.Serializer[None]):
+    phone = serializers.CharField()
+
+    def validate_phone(self, value: str) -> str:
+        if not ContactMethod.normalize_phone(value):
+            raise serializers.ValidationError(
+                "Phone number must contain at least one digit"
+            )
+        return value
+
+
+class PhonePersonMatchSerializer(serializers.Serializer[PhonePersonMatch]):
+    person_id = serializers.UUIDField()
+    person_name = serializers.CharField()
+    person_email = serializers.EmailField(allow_null=True)
+    company_links = PersonCompanyLinkSerializer(many=True)
+
+
+class PhoneCompanyOwnerSerializer(serializers.Serializer[PhoneCompanyOwner]):
+    company_id = serializers.UUIDField()
+    company_name = serializers.CharField()
+
+
+class PhoneOwnershipSerializer(serializers.Serializer[PhoneOwnershipResult]):
+    status = serializers.ChoiceField(
+        choices=["available", "people", "company", "internal"]
+    )
+    normalized_phone = serializers.CharField()
+    can_create_person = serializers.BooleanField()
+    people = PhonePersonMatchSerializer(many=True)
+    companies = PhoneCompanyOwnerSerializer(many=True)
+
+
+class PhoneOwnershipConflictSerializer(PhoneOwnershipSerializer):
+    pass
+
+
+class PersonContactMethodWriteSerializer(serializers.Serializer[None]):
+    method_type = serializers.ChoiceField(choices=ContactMethod.MethodType.choices)
+    value = serializers.CharField(max_length=255)
+    is_primary = serializers.BooleanField(required=False, default=False)
+
+    def get_fields(self) -> dict[str, "serializers.Field[Any, Any, Any, Any]"]:
+        fields = super().get_fields()
+        fields["label"] = serializers.CharField(
+            required=False, allow_blank=True, default=""
+        )
+        return fields
diff --git a/apps/company/services/__init__.py b/apps/company/services/__init__.py
index f268f073e..2ba8b96d6 100644
--- a/apps/company/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -60,11 +60,26 @@
             apply_reviewed_duplicate_cleanup,
         )
         from .person_merge_service import PersonMergeCounts, merge_people
+        from .person_service import (
+            CompanyLinkData,
+            NewPersonData,
+            PersonCompanyLinkData,
+            PersonDirectoryService,
+            PersonPhoneConflictError,
+            PhoneCompanyOwner,
+            PhoneOwnershipResult,
+            PhonePersonMatch,
+            classify_phone_ownership,
+            create_person_for_company,
+            put_company_link,
+            remove_company_link,
+        )
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
     pass
 
 __all__ = [
+    "CompanyLinkData",
     "CompanyMergeCounts",
     "CompanyMergeDecision",
     "CompanyPhoneAnnotations",
@@ -94,11 +109,20 @@
     "GeocodingNotConfiguredError",
     "GeocodingResult",
     "InvalidLinkDecision",
+    "NewPersonData",
+    "PersonCompanyLinkData",
+    "PersonDirectoryService",
     "PersonMergeCounts",
     "PersonMergeDecision",
+    "PersonPhoneConflictError",
     "PersonSelector",
+    "PhoneCompanyOwner",
+    "PhoneOwnershipResult",
+    "PhonePersonMatch",
     "RetainedDecision",
     "apply_reviewed_duplicate_cleanup",
+    "classify_phone_ownership",
+    "create_person_for_company",
     "geocode_address",
     "get_api_key",
     "merge_companies",
@@ -109,5 +133,7 @@
     "normalize_person_name",
     "person_names_compatible",
     "person_names_strongly_compatible",
+    "put_company_link",
     "reassign_company_fk_records",
+    "remove_company_link",
 ]
diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
new file mode 100644
index 000000000..7d46950d8
--- /dev/null
+++ b/apps/company/services/person_service.py
@@ -0,0 +1,346 @@
+"""First-class Person directory and company-relationship operations."""
+
+from typing import NotRequired, TypedDict
+from uuid import UUID
+
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.db import transaction
+from django.db.models import Prefetch, Q, QuerySet
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+
+
+class PersonCompanyLinkData(TypedDict):
+    company_id: str
+    company_name: str
+    position: str | None
+    is_primary: bool
+    notes: str | None
+    is_active: bool
+
+
+class PhonePersonMatch(TypedDict):
+    person_id: str
+    person_name: str
+    person_email: str | None
+    company_links: list[PersonCompanyLinkData]
+
+
+class PhoneCompanyOwner(TypedDict):
+    company_id: str
+    company_name: str
+
+
+class PhoneOwnershipResult(TypedDict):
+    status: str
+    normalized_phone: str
+    can_create_person: bool
+    people: list[PhonePersonMatch]
+    companies: list[PhoneCompanyOwner]
+
+
+class NewPersonData(TypedDict):
+    name: str
+    email: NotRequired[str | None]
+    phone: NotRequired[str | None]
+    position: NotRequired[str | None]
+    notes: NotRequired[str | None]
+    is_primary: NotRequired[bool]
+
+
+class CompanyLinkData(TypedDict):
+    position: str | None
+    notes: str | None
+    is_primary: bool
+
+
+class PersonPhoneConflictError(Exception):
+    def __init__(self, ownership: PhoneOwnershipResult) -> None:
+        self.ownership = ownership
+        super().__init__("Phone number is already owned by another CRM record")
+
+
+class PersonDirectoryService:
+    @staticmethod
+    def search(query: str) -> QuerySet[Person]:
+        people = (
+            Person.objects.filter(is_active=True)
+            .annotate(
+                primary_phone=ContactMethod.primary_phone_annotation(
+                    owner="person", outer_ref="pk"
+                )
+            )
+            .prefetch_related(
+                Prefetch(
+                    "company_links",
+                    queryset=CompanyPersonLink.objects.filter(
+                        is_active=True
+                    ).select_related("company"),
+                )
+            )
+        )
+        search = query.strip()
+        if not search:
+            return people.order_by("name", "id")
+
+        normalized_phone = ContactMethod.normalize_phone(search)
+        filters = (
+            Q(name__icontains=search)
+            | Q(email__icontains=search)
+            | Q(
+                company_links__is_active=True,
+                company_links__company__name__icontains=search,
+            )
+        )
+        if normalized_phone:
+            filters |= Q(
+                contact_methods__method_type=ContactMethod.MethodType.PHONE,
+                contact_methods__normalized_value__contains=normalized_phone.lstrip(
+                    "+"
+                ),
+            )
+        return people.filter(filters).distinct().order_by("name", "id")
+
+    @staticmethod
+    def company_links(person: Person) -> list[PersonCompanyLinkData]:
+        prefetched = getattr(person, "_prefetched_objects_cache", {}).get(
+            "company_links"
+        )
+        if prefetched is None:
+            links = list(
+                CompanyPersonLink.objects.filter(person=person).select_related(
+                    "company"
+                )
+            )
+        else:
+            links = list(person.company_links.all())
+        links.sort(
+            key=lambda link: (
+                not link.is_active,
+                not link.is_primary,
+                link.company.name,
+            )
+        )
+        return [
+            {
+                "company_id": str(link.company_id),
+                "company_name": link.company.name,
+                "position": link.position,
+                "is_primary": link.is_primary,
+                "notes": link.notes,
+                "is_active": link.is_active,
+            }
+            for link in links
+        ]
+
+
+def classify_phone_ownership(
+    *, company: Company, raw_phone: str
+) -> PhoneOwnershipResult:
+    normalized = ContactMethod.normalize_phone(raw_phone)
+    if not normalized:
+        raise ValueError("Phone number must contain at least one digit")
+
+    from apps.crm.models import PhoneEndpoint
+
+    if PhoneEndpoint.objects.filter(
+        normalized_number=normalized, is_active=True
+    ).exists():
+        return {
+            "status": "internal",
+            "normalized_phone": normalized,
+            "can_create_person": False,
+            "people": [],
+            "companies": [],
+        }
+
+    methods = list(
+        ContactMethod.objects.filter(
+            method_type=ContactMethod.MethodType.PHONE,
+            normalized_value=normalized,
+        )
+        .select_related("company", "person")
+        .prefetch_related(
+            Prefetch(
+                "person__company_links",
+                queryset=CompanyPersonLink.objects.select_related("company"),
+            )
+        )
+        .order_by("id")
+    )
+    people_by_id: dict[UUID, PhonePersonMatch] = {}
+    companies_by_id: dict[UUID, PhoneCompanyOwner] = {}
+    for method in methods:
+        if method.person_id is not None:
+            person = method.person
+            if person is None or not person.is_active:
+                continue
+            people_by_id.setdefault(
+                person.id,
+                {
+                    "person_id": str(person.id),
+                    "person_name": person.name,
+                    "person_email": person.email,
+                    "company_links": PersonDirectoryService.company_links(person),
+                },
+            )
+        elif method.company_id is not None:
+            owner = method.company
+            if owner is None:
+                raise RuntimeError(f"Contact method {method.id} has no company")
+            companies_by_id.setdefault(
+                owner.id,
+                {"company_id": str(owner.id), "company_name": owner.name},
+            )
+        else:
+            raise RuntimeError(f"Contact method {method.id} has no owner")
+
+    conflict = ContactMethod.conflicting_company(normalized, {company.id})
+    people = sorted(people_by_id.values(), key=lambda row: row["person_name"])
+    companies = sorted(companies_by_id.values(), key=lambda row: row["company_name"])
+    if people:
+        status = "people"
+    elif conflict is not None:
+        status = "company"
+    else:
+        status = "available"
+    return {
+        "status": status,
+        "normalized_phone": normalized,
+        "can_create_person": conflict is None,
+        "people": people,
+        "companies": companies,
+    }
+
+
+def _person_phone_numbers(person: Person) -> list[str]:
+    return list(
+        person.contact_methods.filter(
+            method_type=ContactMethod.MethodType.PHONE
+        ).values_list("normalized_value", flat=True)
+    )
+
+
+def _schedule_person_phone_rematch(person: Person) -> None:
+    numbers = sorted(set(_person_phone_numbers(person)))
+    if not numbers:
+        return
+    from apps.crm.tasks import rematch_phone_calls_task
+
+    transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
+
+
+def create_person_for_company(
+    *, company: Company, data: NewPersonData
+) -> CompanyPersonLink:
+    raw_phone = data.get("phone")
+    if raw_phone:
+        ownership = classify_phone_ownership(company=company, raw_phone=raw_phone)
+        if not ownership["can_create_person"]:
+            raise PersonPhoneConflictError(ownership)
+
+    with transaction.atomic():
+        person = Person.objects.create(
+            name=data["name"].strip(),
+            email=data.get("email"),
+            is_active=True,
+        )
+        has_active_people = CompanyPersonLink.objects.filter(
+            company=company, is_active=True
+        ).exists()
+        link = CompanyPersonLink.objects.create(
+            company=company,
+            person=person,
+            position=data.get("position"),
+            notes=data.get("notes"),
+            is_primary=data.get("is_primary", False) or not has_active_people,
+            is_active=True,
+        )
+        if raw_phone:
+            from apps.company.serializers import set_primary_phone
+
+            try:
+                set_primary_phone(person, raw_phone)
+            except DjangoValidationError as exc:
+                ownership = classify_phone_ownership(
+                    company=company, raw_phone=raw_phone
+                )
+                raise PersonPhoneConflictError(ownership) from exc
+        return link
+
+
+def put_company_link(
+    *, person: Person, company: Company, data: CompanyLinkData
+) -> CompanyPersonLink:
+    with transaction.atomic():
+        existing = (
+            CompanyPersonLink.objects.select_for_update()
+            .filter(person=person, company=company)
+            .first()
+        )
+        other_active_exists = (
+            CompanyPersonLink.objects.filter(company=company, is_active=True)
+            .exclude(person=person)
+            .exists()
+        )
+        is_primary = data["is_primary"] or not other_active_exists
+        if existing is None:
+            link = CompanyPersonLink.objects.create(
+                person=person,
+                company=company,
+                position=data["position"],
+                notes=data["notes"],
+                is_primary=is_primary,
+                is_active=True,
+            )
+        else:
+            existing.position = data["position"]
+            existing.notes = data["notes"]
+            existing.is_primary = is_primary
+            existing.is_active = True
+            existing.save(
+                update_fields=[
+                    "position",
+                    "notes",
+                    "is_primary",
+                    "is_active",
+                    "updated_at",
+                ]
+            )
+            link = existing
+        _schedule_person_phone_rematch(person)
+        return link
+
+
+def remove_company_link(*, person: Person, company: Company) -> None:
+    with transaction.atomic():
+        link = (
+            CompanyPersonLink.objects.select_for_update()
+            .filter(person=person, company=company, is_active=True)
+            .first()
+        )
+        if link is None:
+            raise ValueError("Active company link not found")
+        projected_company_ids = set(
+            person.company_links.filter(is_active=True)
+            .exclude(company=company)
+            .values_list("company_id", flat=True)
+        )
+        phones = person.contact_methods.filter(
+            method_type=ContactMethod.MethodType.PHONE
+        )
+        for method in phones:
+            conflict = ContactMethod.conflicting_company(
+                method.normalized_value,
+                projected_company_ids,
+                exclude_id=method.id,
+            )
+            if conflict is not None:
+                raise ValueError(
+                    f"Removing this link would make {method.value} conflict with "
+                    f"{conflict.owner_display_name()}"
+                )
+        link.is_active = False
+        link.is_primary = False
+        link.save(update_fields=["is_active", "is_primary", "updated_at"])
+        _schedule_person_phone_rematch(person)
diff --git a/apps/company/tests/test_contact_methods.py b/apps/company/tests/test_contact_methods.py
index 04d3ad790..f1f159c4c 100644
--- a/apps/company/tests/test_contact_methods.py
+++ b/apps/company/tests/test_contact_methods.py
@@ -415,13 +415,12 @@ def test_searched_clients_include_phone(self) -> None:
 
 
 class CompanyPersonLinkApiPhoneTests(BaseAPITestCase):
-    """Guards the contact phone read/write restored on the contacts endpoint
-    (company detail People card, PersonSelectionModal, person picker)."""
-
-    URL = "/api/companies/person-links/"
+    """Guards company People and Person contact-method API integration."""
 
     def setUp(self) -> None:
         super().setUp()
+        self.test_staff.is_office_staff = True
+        self.test_staff.save(update_fields=["is_office_staff"])
         self.client.force_authenticate(user=self.test_staff)
         self.job_client = Company.objects.create(
             name="Acme Ltd", xero_last_modified=timezone.now()
@@ -445,12 +444,10 @@ def test_list_includes_contact_phone_without_lazy_queries(self) -> None:
         self._contact("No Phone")
 
         with CaptureQueriesContext(connection) as captured:
-            response = self.client.get(
-                self.URL, {"company_id": str(self.job_client.id)}
-            )
+            response = self.client.get(f"/api/companies/{self.job_client.id}/people/")
 
         self.assertEqual(response.status_code, 200)
-        phones = {row["person_name"]: row["phone"] for row in response.json()}
+        phones = {row["person_name"]: row["primary_phone"] for row in response.json()}
         self.assertEqual(phones["Jane Smith"], "021 111 111")
         self.assertEqual(phones["No Phone"], "")
         lazy = [
@@ -464,37 +461,34 @@ def test_create_contact_with_phone_creates_primary_method(self) -> None:
         with patch("apps.crm.tasks.rematch_phone_calls_task.delay") as rematch:
             with self.captureOnCommitCallbacks(execute=True):
                 response = self.client.post(
-                    self.URL,
+                    f"/api/companies/{self.job_client.id}/people/",
                     {
-                        "company": str(self.job_client.id),
-                        "person_name": "Bob Brown",
+                        "name": "Bob Brown",
                         "phone": "021 222 222",
                     },
                     format="json",
                 )
 
         self.assertEqual(response.status_code, 201)
-        self.assertEqual(response.json()["phone"], "021 222 222")
+        self.assertEqual(response.json()["primary_phone"], "021 222 222")
         method = ContactMethod.objects.get(person__name="Bob Brown")
         self.assertEqual(method.method_type, ContactMethod.MethodType.PHONE)
         self.assertTrue(method.is_primary)
         rematch.assert_called_once_with(["+6421222222"])
 
-    def test_create_contact_sets_person_fields_and_ignores_is_active(self) -> None:
+    def test_create_contact_sets_person_fields_and_active_link(self) -> None:
         response = self.client.post(
-            self.URL,
+            f"/api/companies/{self.job_client.id}/people/",
             {
-                "company": str(self.job_client.id),
-                "person_name": "Bob Brown",
-                "person_email": "bob@example.com",
-                "is_active": False,
+                "name": "Bob Brown",
+                "email": "bob@example.com",
             },
             format="json",
         )
 
         self.assertEqual(response.status_code, 201)
         link = CompanyPersonLink.objects.select_related("person").get(
-            pk=response.json()["id"]
+            person_id=response.json()["person_id"], company=self.job_client
         )
         self.assertEqual(link.person.name, "Bob Brown")
         self.assertEqual(link.person.email, "bob@example.com")
@@ -505,10 +499,10 @@ def test_update_contact_updates_person_name_and_email(self) -> None:
         contact = self._contact("Jane Smith")
 
         response = self.client.patch(
-            f"{self.URL}{contact.id}/",
+            f"/api/people/{contact.person_id}/",
             {
-                "person_name": "Jane Brown",
-                "person_email": "jane@example.com",
+                "name": "Jane Brown",
+                "email": "jane@example.com",
             },
             format="json",
         )
@@ -525,19 +519,19 @@ def test_update_phone_updates_existing_primary_method(self) -> None:
         with patch("apps.crm.tasks.rematch_phone_calls_task.delay") as rematch:
             with self.captureOnCommitCallbacks(execute=True):
                 response = self.client.patch(
-                    f"{self.URL}{contact.id}/",
-                    {"phone": "021 333 333"},
+                    f"/api/people/{contact.person_id}/contact-methods/{method.id}/",
+                    {"value": "021 333 333"},
                     format="json",
                 )
 
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.json()["phone"], "021 333 333")
+        self.assertEqual(response.json()["value"], "021 333 333")
         method.refresh_from_db()
         self.assertEqual(method.value, "021 333 333")
         self.assertEqual(contact.person.contact_methods.count(), 1)
         rematch.assert_called_once_with(["+6421111111", "+6421333333"])
 
-    def test_update_phone_matching_secondary_promotes_it(self) -> None:
+    def test_update_secondary_phone_promotes_it(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
         secondary = ContactMethod.objects.create(
             person=contact.person,
@@ -546,8 +540,8 @@ def test_update_phone_matching_secondary_promotes_it(self) -> None:
         )
 
         response = self.client.patch(
-            f"{self.URL}{contact.id}/",
-            {"phone": "021 444 444"},
+            f"/api/people/{contact.person_id}/contact-methods/{secondary.id}/",
+            {"is_primary": True},
             format="json",
         )
 
@@ -558,17 +552,16 @@ def test_update_phone_matching_secondary_promotes_it(self) -> None:
             contact.person.contact_methods.filter(is_primary=True).count(), 1
         )
 
-    def test_blank_phone_leaves_methods_untouched(self) -> None:
+    def test_relationship_update_leaves_phone_methods_untouched(self) -> None:
         contact = self._contact("Jane Smith", phone="021 111 111")
 
-        response = self.client.patch(
-            f"{self.URL}{contact.id}/",
-            {"phone": "", "position": "Manager"},
+        response = self.client.put(
+            f"/api/people/{contact.person_id}/company-links/{self.job_client.id}/",
+            {"position": "Manager", "notes": None, "is_primary": False},
             format="json",
         )
 
         self.assertEqual(response.status_code, 200)
-        self.assertEqual(response.json()["phone"], "021 111 111")
         self.assertEqual(contact.person.contact_methods.count(), 1)
 
     def test_conflicting_phone_returns_400_and_creates_nothing(self) -> None:
@@ -582,14 +575,17 @@ def test_conflicting_phone_returns_400_and_creates_nothing(self) -> None:
         )
         contact = self._contact("Jane Smith")
 
-        response = self.client.patch(
-            f"{self.URL}{contact.id}/",
-            {"phone": "021 555 555"},
+        response = self.client.post(
+            f"/api/people/{contact.person_id}/contact-methods/",
+            {
+                "method_type": "phone",
+                "value": "021 555 555",
+                "is_primary": True,
+            },
             format="json",
         )
 
         self.assertEqual(response.status_code, 400)
-        self.assertIn("phone", response.json())
         self.assertEqual(contact.person.contact_methods.count(), 0)
 
 
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
new file mode 100644
index 000000000..6b2052884
--- /dev/null
+++ b/apps/company/tests/test_person_api.py
@@ -0,0 +1,227 @@
+from unittest.mock import patch
+
+from django.utils import timezone
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.testing import BaseAPITestCase
+
+
+class PersonApiTests(BaseAPITestCase):
+    def setUp(self) -> None:
+        super().setUp()
+        self.test_staff.is_office_staff = True
+        self.test_staff.save(update_fields=["is_office_staff"])
+        self.client.force_authenticate(user=self.test_staff)
+        self.company_a = Company.objects.create(
+            name="Acme Engineering", xero_last_modified=timezone.now()
+        )
+        self.company_b = Company.objects.create(
+            name="Beta Fabrication", xero_last_modified=timezone.now()
+        )
+
+    def _person(
+        self, name: str = "Jane Smith", company: Company | None = None
+    ) -> Person:
+        person = Person.objects.create(name=name, email="jane@example.com")
+        if company is not None:
+            CompanyPersonLink.objects.create(company=company, person=person)
+        return person
+
+    def test_directory_search_returns_one_person_for_multiple_matching_links(
+        self,
+    ) -> None:
+        """A join-based search must not duplicate a person who works at two companies."""
+        person = self._person(company=self.company_a)
+        CompanyPersonLink.objects.create(company=self.company_b, person=person)
+
+        response = self.client.get("/api/people/", {"q": "Fabrication"})
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["count"], 1)
+        self.assertEqual(response.json()["results"][0]["name"], "Jane Smith")
+
+    def test_directory_includes_person_without_company(self) -> None:
+        """Existing unaffiliated people must remain discoverable so they can be repaired."""
+        self._person(name="Unaffiliated Person")
+
+        response = self.client.get("/api/people/", {"q": "Unaffiliated"})
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response.json()["results"][0]["companies"], [])
+
+    def test_create_company_person_is_atomic_on_cross_company_phone_conflict(
+        self,
+    ) -> None:
+        """A duplicate-phone rejection must not leave an orphan Person behind."""
+        existing = self._person(company=self.company_a)
+        ContactMethod.objects.create(
+            person=existing,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 111 1111",
+            is_primary=True,
+        )
+        people_before = Person.objects.count()
+
+        response = self.client.post(
+            f"/api/companies/{self.company_b.id}/people/",
+            {"name": "Jane Duplicate", "phone": "0211111111"},
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 409)
+        self.assertEqual(response.json()["status"], "people")
+        self.assertFalse(response.json()["can_create_person"])
+        self.assertEqual(response.json()["people"][0]["person_name"], "Jane Smith")
+        self.assertEqual(Person.objects.count(), people_before)
+
+    def test_same_company_shared_phone_can_create_another_person(self) -> None:
+        """Two employees may legitimately share their company's office phone."""
+        existing = self._person(company=self.company_a)
+        ContactMethod.objects.create(
+            person=existing,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="09 555 0000",
+        )
+
+        lookup = self.client.post(
+            f"/api/companies/{self.company_a.id}/people/phone-ownership/",
+            {"phone": "095550000"},
+            format="json",
+        )
+        created = self.client.post(
+            f"/api/companies/{self.company_a.id}/people/",
+            {"name": "John Smith", "phone": "095550000"},
+            format="json",
+        )
+
+        self.assertEqual(lookup.status_code, 200)
+        self.assertTrue(lookup.json()["can_create_person"])
+        self.assertEqual(created.status_code, 201)
+        self.assertEqual(created.json()["person_name"], "John Smith")
+
+    def test_phone_ownership_rejects_a_value_without_digits(self) -> None:
+        response = self.client.post(
+            f"/api/companies/{self.company_a.id}/people/phone-ownership/",
+            {"phone": "not a phone"},
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 400)
+        self.assertEqual(
+            response.json()["phone"],
+            ["Phone number must contain at least one digit"],
+        )
+
+    def test_contact_method_patch_cannot_change_its_owner(self) -> None:
+        person = self._person(company=self.company_a)
+        other_person = self._person(name="Other Person", company=self.company_a)
+        method = ContactMethod.objects.create(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 222 3333",
+        )
+
+        response = self.client.patch(
+            f"/api/people/{person.id}/contact-methods/{method.id}/",
+            {
+                "label": "Mobile",
+                "person": str(other_person.id),
+                "company": str(self.company_b.id),
+            },
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 200)
+        method.refresh_from_db()
+        self.assertEqual(method.person_id, person.id)
+        self.assertIsNone(method.company_id)
+        self.assertEqual(method.label, "Mobile")
+
+    def test_put_reactivates_existing_company_link_without_duplication(self) -> None:
+        """Restoring employment must reuse the soft-deleted unique link row."""
+        person = self._person()
+        link = CompanyPersonLink.objects.create(
+            company=self.company_a, person=person, is_active=False
+        )
+
+        response = self.client.put(
+            f"/api/people/{person.id}/company-links/{self.company_a.id}/",
+            {"position": "Manager", "notes": "Restored", "is_primary": False},
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 200)
+        link.refresh_from_db()
+        self.assertTrue(link.is_active)
+        self.assertTrue(link.is_primary)
+        self.assertEqual(link.position, "Manager")
+        self.assertEqual(
+            CompanyPersonLink.objects.filter(
+                company=self.company_a, person=person
+            ).count(),
+            1,
+        )
+
+    def test_removing_link_preserves_person_and_other_company(self) -> None:
+        """Unlinking one employer must not delete the shared human identity."""
+        person = self._person(company=self.company_a)
+        other = CompanyPersonLink.objects.create(company=self.company_b, person=person)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        self.assertEqual(response.status_code, 204)
+        self.assertTrue(Person.objects.filter(id=person.id).exists())
+        other.refresh_from_db()
+        self.assertTrue(other.is_active)
+
+    def test_removing_link_is_blocked_when_phone_would_cross_companies(self) -> None:
+        """Relationship edits must not create the duplicate-phone problem they manage."""
+        person = self._person(company=self.company_a)
+        CompanyPersonLink.objects.create(company=self.company_b, person=person)
+        ContactMethod.objects.create(
+            company=self.company_a,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="09 444 4444",
+        )
+        ContactMethod.objects.create(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="09 444 4444",
+        )
+
+        response = self.client.delete(
+            f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+        )
+
+        self.assertEqual(response.status_code, 400)
+        self.assertTrue(
+            CompanyPersonLink.objects.get(
+                person=person, company=self.company_a
+            ).is_active
+        )
+
+    def test_identity_patch_does_not_change_company_relationship(self) -> None:
+        """Editing canonical identity must not overwrite company-specific role data."""
+        person = self._person(company=self.company_a)
+        link = CompanyPersonLink.objects.get(person=person, company=self.company_a)
+        link.position = "Estimator"
+        link.save(update_fields=["position"])
+
+        response = self.client.patch(
+            f"/api/people/{person.id}/",
+            {"name": "Jane Brown"},
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 200)
+        link.refresh_from_db()
+        self.assertEqual(link.position, "Estimator")
+
+    def test_old_person_links_collection_is_removed(self) -> None:
+        """A caller migration must not accidentally leave two person-link APIs active."""
+        response = self.client.get("/api/companies/person-links/")
+
+        self.assertEqual(response.status_code, 404)
diff --git a/apps/company/urls_people_rest.py b/apps/company/urls_people_rest.py
new file mode 100644
index 000000000..e956bc35c
--- /dev/null
+++ b/apps/company/urls_people_rest.py
@@ -0,0 +1,39 @@
+"""REST URLs for first-class People and their company relationships."""
+
+from django.urls import path
+
+from apps.company.views.person_views import (
+    PersonCompanyLinkDetailView,
+    PersonCompanyLinksView,
+    PersonContactMethodDetailView,
+    PersonContactMethodsView,
+    PersonDetailView,
+    PersonListView,
+)
+
+app_name = "people_rest"
+
+urlpatterns = [
+    path("", PersonListView.as_view(), name="person_list"),
+    path("<uuid:person_id>/", PersonDetailView.as_view(), name="person_detail"),
+    path(
+        "<uuid:person_id>/company-links/",
+        PersonCompanyLinksView.as_view(),
+        name="person_company_links",
+    ),
+    path(
+        "<uuid:person_id>/company-links/<uuid:company_id>/",
+        PersonCompanyLinkDetailView.as_view(),
+        name="person_company_link_detail",
+    ),
+    path(
+        "<uuid:person_id>/contact-methods/",
+        PersonContactMethodsView.as_view(),
+        name="person_contact_methods",
+    ),
+    path(
+        "<uuid:person_id>/contact-methods/<uuid:method_id>/",
+        PersonContactMethodDetailView.as_view(),
+        name="person_contact_method_detail",
+    ),
+]
diff --git a/apps/company/urls_rest.py b/apps/company/urls_rest.py
index 07645d1c1..73be36ea4 100644
--- a/apps/company/urls_rest.py
+++ b/apps/company/urls_rest.py
@@ -21,7 +21,10 @@
     JobPersonRestView,
 )
 from apps.company.views.contact_method_viewset import ContactMethodViewSet
-from apps.company.views.contact_viewset import CompanyPersonLinkViewSet
+from apps.company.views.person_views import (
+    CompanyPeopleView,
+    CompanyPersonPhoneOwnershipView,
+)
 from apps.company.views.supplier_pickup_address_viewset import (
     SupplierPickupAddressViewSet,
 )
@@ -39,9 +42,6 @@
     ContactMethodViewSet,
     basename="contact-method",
 )
-router.register(
-    "person-links", CompanyPersonLinkViewSet, basename="company-person-link"
-)
 router.register(
     "pickup-addresses", SupplierPickupAddressViewSet, basename="supplier-pickup-address"
 )
@@ -83,6 +83,16 @@
         CompanyJobsRestView.as_view(),
         name="company_jobs_rest",
     ),
+    path(
+        "<uuid:company_id>/people/",
+        CompanyPeopleView.as_view(),
+        name="company_people_rest",
+    ),
+    path(
+        "<uuid:company_id>/people/phone-ownership/",
+        CompanyPersonPhoneOwnershipView.as_view(),
+        name="company_person_phone_ownership_rest",
+    ),
     path(
         "<uuid:company_id>/supplier-aliases/",
         CompanySupplierAliasListCreateView.as_view(),
diff --git a/apps/company/views/__init__.py b/apps/company/views/__init__.py
index ab6214ffd..584d63562 100644
--- a/apps/company/views/__init__.py
+++ b/apps/company/views/__init__.py
@@ -10,6 +10,16 @@
     CompanyUpdateRestView,
     JobPersonRestView,
 )
+from .person_views import (
+    CompanyPeopleView,
+    CompanyPersonPhoneOwnershipView,
+    PersonCompanyLinkDetailView,
+    PersonCompanyLinksView,
+    PersonContactMethodDetailView,
+    PersonContactMethodsView,
+    PersonDetailView,
+    PersonListView,
+)
 from .supplier_search_alias_views import (
     CompanySupplierAliasListCreateView,
     SupplierAliasDetailView,
@@ -21,7 +31,6 @@
 
     if apps.ready:
         from .contact_method_viewset import ContactMethodViewSet
-        from .contact_viewset import CompanyPersonLinkViewSet
         from .supplier_pickup_address_viewset import SupplierPickupAddressViewSet
 except (ImportError, RuntimeError):
     # Django not ready or circular import, skip conditional imports
@@ -32,13 +41,20 @@
     "CompanyCreateRestView",
     "CompanyJobsRestView",
     "CompanyListAllRestView",
-    "CompanyPersonLinkViewSet",
+    "CompanyPeopleView",
+    "CompanyPersonPhoneOwnershipView",
     "CompanyRetrieveRestView",
     "CompanySearchRestView",
     "CompanySupplierAliasListCreateView",
     "CompanyUpdateRestView",
     "ContactMethodViewSet",
     "JobPersonRestView",
+    "PersonCompanyLinkDetailView",
+    "PersonCompanyLinksView",
+    "PersonContactMethodDetailView",
+    "PersonContactMethodsView",
+    "PersonDetailView",
+    "PersonListView",
     "SupplierAliasDetailView",
     "SupplierPickupAddressViewSet",
 ]
diff --git a/apps/company/views/contact_method_viewset.py b/apps/company/views/contact_method_viewset.py
index 72809b673..669e8d9b1 100644
--- a/apps/company/views/contact_method_viewset.py
+++ b/apps/company/views/contact_method_viewset.py
@@ -76,13 +76,16 @@ def get_queryset(self):
         ).prefetch_related(
             Prefetch(
                 "person__company_links",
-                queryset=CompanyPersonLink.objects.select_related("company"),
+                queryset=CompanyPersonLink.objects.filter(
+                    is_active=True
+                ).select_related("company"),
             ),
         )
         company_id = self.request.query_params.get("company_id")
         if company_id:
             queryset = queryset.filter(company_id=company_id) | queryset.filter(
-                person__company_links__company_id=company_id
+                person__company_links__company_id=company_id,
+                person__company_links__is_active=True,
             )
 
         person_id = self.request.query_params.get("person_id")
diff --git a/apps/company/views/contact_viewset.py b/apps/company/views/contact_viewset.py
deleted file mode 100644
index 164bee66a..000000000
--- a/apps/company/views/contact_viewset.py
+++ /dev/null
@@ -1,70 +0,0 @@
-"""
-CompanyPersonLink ViewSet
-
-ViewSet for CompanyPersonLink CRUD operations using DRF's ModelViewSet.
-Provides list, create, retrieve, update, partial_update, and destroy actions.
-"""
-
-from drf_spectacular.types import OpenApiTypes
-from drf_spectacular.utils import OpenApiParameter, extend_schema
-from rest_framework import permissions, viewsets
-
-from apps.company.models import CompanyPersonLink, ContactMethod
-from apps.company.serializers import CompanyPersonLinkSerializer
-
-
-class CompanyPersonLinkViewSet(viewsets.ModelViewSet):
-    """
-    ViewSet for CompanyPersonLink CRUD operations.
-
-    Endpoints:
-    - GET    /api/companies/person-links/       - list all company-person links
-    - POST   /api/companies/person-links/       - create link
-    - GET    /api/companies/person-links/<id>/  - retrieve link
-    - PUT    /api/companies/person-links/<id>/  - full update
-    - PATCH  /api/companies/person-links/<id>/  - partial update
-    - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-    Query Parameters:
-    - company_id: Filter links by company UUID
-    """
-
-    queryset = CompanyPersonLink.objects.filter(is_active=True)
-    serializer_class = CompanyPersonLinkSerializer
-    permission_classes = [permissions.IsAuthenticated]
-
-    @extend_schema(
-        parameters=[
-            OpenApiParameter(
-                name="company_id",
-                type=OpenApiTypes.UUID,
-                location=OpenApiParameter.QUERY,
-                description="Filter links by company UUID",
-                required=False,
-            ),
-        ]
-    )
-    def list(self, request, *args, **kwargs):
-        """List all company-person links, optionally filtered by company_id."""
-        return super().list(request, *args, **kwargs)
-
-    def get_queryset(self):
-        """
-        Filter to only active links, optionally filtered by company_id.
-        """
-        queryset = (
-            CompanyPersonLink.objects.filter(is_active=True)
-            .select_related("person")
-            .annotate(phone=ContactMethod.primary_phone_for_link_annotation())
-        )
-        company_id = self.request.query_params.get("company_id")
-        if company_id:
-            queryset = queryset.filter(company_id=company_id)
-        return queryset.order_by("-is_primary", "person__name")
-
-    def perform_destroy(self, instance):
-        """
-        Soft delete - set is_active=False instead of actually deleting.
-        """
-        instance.is_active = False
-        instance.save(update_fields=["is_active"])
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
new file mode 100644
index 000000000..68ae28514
--- /dev/null
+++ b/apps/company/views/person_views.py
@@ -0,0 +1,282 @@
+"""First-class Person directory, relationship, and contact-method APIs."""
+
+from typing import cast
+
+from django.db import transaction
+from django.db.models import QuerySet
+from django.shortcuts import get_object_or_404
+from drf_spectacular.types import OpenApiTypes
+from drf_spectacular.utils import OpenApiParameter, extend_schema
+from rest_framework import generics, permissions, serializers, status
+from rest_framework.exceptions import ValidationError
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.company.person_serializers import (
+    CompanyLinkWriteSerializer,
+    CompanyPersonCreateSerializer,
+    CompanyPersonSerializer,
+    PersonCompanyLinkSerializer,
+    PersonContactMethodWriteSerializer,
+    PersonDetailSerializer,
+    PersonIdentityUpdateSerializer,
+    PersonSummarySerializer,
+    PhoneOwnershipConflictSerializer,
+    PhoneOwnershipRequestSerializer,
+    PhoneOwnershipSerializer,
+)
+from apps.company.serializers import ContactMethodSerializer
+from apps.company.services.person_service import (
+    CompanyLinkData,
+    NewPersonData,
+    PersonCompanyLinkData,
+    PersonDirectoryService,
+    PersonPhoneConflictError,
+    classify_phone_ownership,
+    create_person_for_company,
+    put_company_link,
+    remove_company_link,
+)
+from apps.crm.tasks import rematch_phone_calls_task
+from apps.job.permissions import IsOfficeStaff
+from apps.workflow.api.pagination import PageSizePagination
+
+PERSON_PERMISSIONS = [permissions.IsAuthenticated, IsOfficeStaff]
+
+
+class PersonListView(generics.ListAPIView[Person]):
+    """List and search active people across company relationships."""
+
+    serializer_class = PersonSummarySerializer
+    permission_classes = PERSON_PERMISSIONS
+    pagination_class = PageSizePagination
+
+    @extend_schema(
+        parameters=[
+            OpenApiParameter(
+                name="q",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Search people by name, email, phone, or company.",
+            )
+        ]
+    )
+    def get(self, request: Request, *args: object, **kwargs: object) -> Response:
+        return super().get(request, *args, **kwargs)
+
+    def get_queryset(self) -> QuerySet[Person]:
+        return PersonDirectoryService.search(self.request.query_params.get("q", ""))
+
+
+class PersonDetailView(generics.RetrieveUpdateAPIView[Person]):
+    """Retrieve or update a Person's identity fields."""
+
+    queryset = Person.objects.filter(is_active=True)
+    permission_classes = PERSON_PERMISSIONS
+    lookup_url_kwarg = "person_id"
+
+    def get_serializer_class(self) -> type[serializers.BaseSerializer[Person]]:
+        if self.request.method in {"PUT", "PATCH"}:
+            return PersonIdentityUpdateSerializer
+        return PersonDetailSerializer
+
+    def update(self, request: Request, *args: object, **kwargs: object) -> Response:
+        super().update(request, *args, **kwargs)
+        person = self.get_object()
+        return Response(PersonDetailSerializer(person).data)
+
+
+class CompanyPeopleView(APIView):
+    """List a company's people or create a Person with its initial link."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(responses={200: CompanyPersonSerializer(many=True)})
+    def get(self, request: Request, company_id: str) -> Response:
+        company = get_object_or_404(Company, id=company_id)
+        links = (
+            CompanyPersonLink.objects.filter(company=company, is_active=True)
+            .select_related("person")
+            .annotate(phone=ContactMethod.primary_phone_for_link_annotation())
+            .order_by("-is_primary", "person__name")
+        )
+        return Response(CompanyPersonSerializer(links, many=True).data)
+
+    @extend_schema(
+        request=CompanyPersonCreateSerializer,
+        responses={
+            201: CompanyPersonSerializer,
+            409: PhoneOwnershipConflictSerializer,
+        },
+    )
+    def post(self, request: Request, company_id: str) -> Response:
+        company = get_object_or_404(Company, id=company_id)
+        payload = CompanyPersonCreateSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        data = cast(NewPersonData, payload.validated_data)
+        try:
+            link = create_person_for_company(company=company, data=data)
+        except PersonPhoneConflictError as exc:
+            response = PhoneOwnershipConflictSerializer(data=exc.ownership)
+            response.is_valid(raise_exception=True)
+            return Response(response.data, status=status.HTTP_409_CONFLICT)
+        link = (
+            CompanyPersonLink.objects.select_related("person")
+            .annotate(phone=ContactMethod.primary_phone_for_link_annotation())
+            .get(pk=link.pk)
+        )
+        return Response(
+            CompanyPersonSerializer(link).data, status=status.HTTP_201_CREATED
+        )
+
+
+class CompanyPersonPhoneOwnershipView(APIView):
+    """Classify a phone before creating a Person for a company."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(
+        request=PhoneOwnershipRequestSerializer,
+        responses={200: PhoneOwnershipSerializer},
+    )
+    def post(self, request: Request, company_id: str) -> Response:
+        company = get_object_or_404(Company, id=company_id)
+        payload = PhoneOwnershipRequestSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        result = classify_phone_ownership(
+            company=company, raw_phone=payload.validated_data["phone"]
+        )
+        return Response(PhoneOwnershipSerializer(result).data)
+
+
+class PersonCompanyLinksView(APIView):
+    """List all active company relationships for a Person."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(responses={200: PersonCompanyLinkSerializer(many=True)})
+    def get(self, request: Request, person_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id, is_active=True)
+        links = PersonDirectoryService.company_links(person)
+        return Response(PersonCompanyLinkSerializer(links, many=True).data)
+
+
+class PersonCompanyLinkDetailView(APIView):
+    """Create, update, reactivate, or remove a Person-company relationship."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(
+        request=CompanyLinkWriteSerializer,
+        responses={200: PersonCompanyLinkSerializer},
+    )
+    def put(self, request: Request, person_id: str, company_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id, is_active=True)
+        company = get_object_or_404(Company, id=company_id)
+        payload = CompanyLinkWriteSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        link = put_company_link(
+            person=person,
+            company=company,
+            data=cast(CompanyLinkData, payload.validated_data),
+        )
+        response_data: PersonCompanyLinkData = {
+            "company_id": str(link.company_id),
+            "company_name": company.name,
+            "position": link.position,
+            "is_primary": link.is_primary,
+            "notes": link.notes,
+            "is_active": link.is_active,
+        }
+        return Response(PersonCompanyLinkSerializer(response_data).data)
+
+    @extend_schema(responses={204: None})
+    def delete(self, request: Request, person_id: str, company_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id, is_active=True)
+        company = get_object_or_404(Company, id=company_id)
+        try:
+            remove_company_link(person=person, company=company)
+        except ValueError as exc:
+            raise ValidationError({"company_link": [str(exc)]}) from exc
+        return Response(status=status.HTTP_204_NO_CONTENT)
+
+
+def _schedule_contact_method_rematch(method: ContactMethod) -> None:
+    if method.method_type != ContactMethod.MethodType.PHONE:
+        return
+    normalized = method.normalized_value
+    transaction.on_commit(lambda: rematch_phone_calls_task.delay([normalized]))
+
+
+class PersonContactMethodsView(APIView):
+    """List or create a Person's contact methods."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(responses={200: ContactMethodSerializer(many=True)})
+    def get(self, request: Request, person_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id, is_active=True)
+        methods = person.contact_methods.order_by(
+            "method_type", "-is_primary", "label", "value"
+        )
+        return Response(ContactMethodSerializer(methods, many=True).data)
+
+    @extend_schema(
+        request=PersonContactMethodWriteSerializer,
+        responses={201: ContactMethodSerializer},
+    )
+    def post(self, request: Request, person_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id, is_active=True)
+        payload = PersonContactMethodWriteSerializer(data=request.data)
+        payload.is_valid(raise_exception=True)
+        serializer = ContactMethodSerializer(
+            data={
+                **payload.validated_data,
+                "company": None,
+                "person": str(person.id),
+                "source": ContactMethod.Source.LOCAL,
+            }
+        )
+        serializer.is_valid(raise_exception=True)
+        method = serializer.save()
+        _schedule_contact_method_rematch(method)
+        return Response(
+            ContactMethodSerializer(method).data, status=status.HTTP_201_CREATED
+        )
+
+
+class PersonContactMethodDetailView(APIView):
+    """Update or delete one Person contact method."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(
+        request=PersonContactMethodWriteSerializer,
+        responses={200: ContactMethodSerializer},
+    )
+    def patch(self, request: Request, person_id: str, method_id: str) -> Response:
+        method = get_object_or_404(ContactMethod, id=method_id, person_id=person_id)
+        payload = PersonContactMethodWriteSerializer(data=request.data, partial=True)
+        payload.is_valid(raise_exception=True)
+        serializer = ContactMethodSerializer(
+            method, data=payload.validated_data, partial=True
+        )
+        serializer.is_valid(raise_exception=True)
+        old_normalized = method.normalized_value
+        updated = serializer.save()
+        if updated.method_type == ContactMethod.MethodType.PHONE:
+            numbers = sorted({old_normalized, updated.normalized_value})
+            transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
+        return Response(ContactMethodSerializer(updated).data)
+
+    @extend_schema(responses={204: None})
+    def delete(self, request: Request, person_id: str, method_id: str) -> Response:
+        method = get_object_or_404(ContactMethod, id=method_id, person_id=person_id)
+        normalized = method.normalized_value
+        is_phone = method.method_type == ContactMethod.MethodType.PHONE
+        method.delete()
+        if is_phone:
+            transaction.on_commit(lambda: rematch_phone_calls_task.delay([normalized]))
+        return Response(status=status.HTTP_204_NO_CONTENT)
diff --git a/apps/crm/services/phone_call_service.py b/apps/crm/services/phone_call_service.py
index 6f95257dd..6c344d1a8 100644
--- a/apps/crm/services/phone_call_service.py
+++ b/apps/crm/services/phone_call_service.py
@@ -816,7 +816,9 @@ def assign_phone_number(
             person = Person.objects.get(id=person_uuid, is_active=True)
         except Person.DoesNotExist as exc:
             raise ValueError("Person not found") from exc
-        if not person.company_links.filter(company_id=company_uuid).exists():
+        if not person.company_links.filter(
+            company_id=company_uuid, is_active=True
+        ).exists():
             raise ValueError("Person is not linked to the selected company")
         owner_filter = {
             "person": person,
diff --git a/apps/crm/tests/test_phone_call_service.py b/apps/crm/tests/test_phone_call_service.py
index ba3b06afb..5f962d779 100644
--- a/apps/crm/tests/test_phone_call_service.py
+++ b/apps/crm/tests/test_phone_call_service.py
@@ -631,15 +631,6 @@ def test_list_filters_unmatched_and_unlinked_calls(self) -> None:
             [str(unlinked.id)],
         )
 
-    def test_list_rejects_legacy_client_match_filter(self) -> None:
-        response = self.api.get(
-            "/api/crm/phone-calls/",
-            {"client_match": "matched"},
-        )
-
-        self.assertEqual(response.status_code, 400)
-        self.assertEqual(response.data["client_match"], ["Use company_match."])
-
     def test_list_filters_by_direction_recording_date_and_search(self) -> None:
         """Catches recent-call filters drifting from provider call fields."""
         PhoneEndpoint.objects.update_or_create(
diff --git a/apps/crm/views/phone_call_views.py b/apps/crm/views/phone_call_views.py
index ba1eb643b..c45e2ede4 100644
--- a/apps/crm/views/phone_call_views.py
+++ b/apps/crm/views/phone_call_views.py
@@ -207,8 +207,6 @@ def _filter_phone_call_queryset(
     queryset: QuerySet[PhoneCallRecord],
     request: Request,
 ) -> QuerySet[PhoneCallRecord]:
-    if "client_match" in request.query_params:
-        raise ValidationError({"client_match": ["Use company_match."]})
     company_match = _query_choice(
         request.query_params.get("company_match"),
         "company_match",
diff --git a/apps/workflow/migrations/0009_rename_remaining_crm_telemetry_sources.py b/apps/workflow/migrations/0009_rename_remaining_crm_telemetry_sources.py
new file mode 100644
index 000000000..97d334801
--- /dev/null
+++ b/apps/workflow/migrations/0009_rename_remaining_crm_telemetry_sources.py
@@ -0,0 +1,32 @@
+from typing import Any
+
+from django.db import migrations
+
+SOURCE_RENAMES = {
+    "crm_clients_table": "crm_companies_table",
+    "crm_client_detail_phone_numbers": "crm_company_detail_phone_numbers",
+}
+
+
+def forwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    database = schema_editor.connection.alias
+    for old_source, new_source in SOURCE_RENAMES.items():
+        SearchTelemetryEvent.objects.using(database).filter(source=old_source).update(
+            source=new_source
+        )
+
+
+def backwards(apps: Any, schema_editor: Any) -> None:
+    SearchTelemetryEvent = apps.get_model("workflow", "SearchTelemetryEvent")
+    database = schema_editor.connection.alias
+    for old_source, new_source in SOURCE_RENAMES.items():
+        SearchTelemetryEvent.objects.using(database).filter(source=new_source).update(
+            source=old_source
+        )
+
+
+class Migration(migrations.Migration):
+    dependencies = [("workflow", "0008_rename_search_telemetry_company_lookup_source")]
+
+    operations = [migrations.RunPython(forwards, backwards)]
diff --git a/apps/workflow/tests/test_search_telemetry_migration.py b/apps/workflow/tests/test_search_telemetry_migration.py
index 24466c729..ee49efc15 100644
--- a/apps/workflow/tests/test_search_telemetry_migration.py
+++ b/apps/workflow/tests/test_search_telemetry_migration.py
@@ -10,7 +10,7 @@ class SearchTelemetryTerminologyMigrationTests(TransactionTestCase):
         ("workflow", "0007_rename_search_telemetry_client_domain"),
     )
     migrate_to: ClassVar[tuple[tuple[str, str], ...]] = (
-        ("workflow", "0008_rename_search_telemetry_company_lookup_source"),
+        ("workflow", "0009_rename_remaining_crm_telemetry_sources"),
     )
 
     def setUp(self) -> None:
@@ -35,6 +35,20 @@ def test_forward_and_reverse_rename_company_lookup_source(self) -> None:
             query="Acme",
             normalized_query="acme",
         )
+        companies_table = SearchTelemetryEvent.objects.create(
+            event_type="click",
+            domain="company",
+            source="crm_clients_table",
+            query="Beta",
+            normalized_query="beta",
+        )
+        company_detail = SearchTelemetryEvent.objects.create(
+            event_type="click",
+            domain="company",
+            source="crm_client_detail_phone_numbers",
+            query="Gamma",
+            normalized_query="gamma",
+        )
 
         self.executor.loader.build_graph()
         self.executor.migrate(self.migrate_to)
@@ -43,6 +57,14 @@ def test_forward_and_reverse_rename_company_lookup_source(self) -> None:
 
         event = SearchTelemetryEvent.objects.get(pk=event.pk)
         self.assertEqual(event.source, "company_lookup")
+        self.assertEqual(
+            SearchTelemetryEvent.objects.get(pk=companies_table.pk).source,
+            "crm_companies_table",
+        )
+        self.assertEqual(
+            SearchTelemetryEvent.objects.get(pk=company_detail.pk).source,
+            "crm_company_detail_phone_numbers",
+        )
 
         self.executor.loader.build_graph()
         self.executor.migrate(self.migrate_from)
@@ -53,3 +75,11 @@ def test_forward_and_reverse_rename_company_lookup_source(self) -> None:
 
         event = SearchTelemetryEvent.objects.get(pk=event.pk)
         self.assertEqual(event.source, "client_lookup")
+        self.assertEqual(
+            SearchTelemetryEvent.objects.get(pk=companies_table.pk).source,
+            "crm_clients_table",
+        )
+        self.assertEqual(
+            SearchTelemetryEvent.objects.get(pk=company_detail.pk).source,
+            "crm_client_detail_phone_numbers",
+        )
diff --git a/docketworks/settings.py b/docketworks/settings.py
index 9704dc81b..4804c4d3e 100644
--- a/docketworks/settings.py
+++ b/docketworks/settings.py
@@ -338,8 +338,7 @@ def require_positive_int_env(name: str) -> int:
     "VERSION": "1.0.0",
     "SERVE_INCLUDE_SCHEMA": False,
     # Split request/response schemas so code generators don't require readOnly fields
-    # on request bodies. This creates e.g. ClientContact (response) and
-    # ClientContactRequest (request) schemas automatically.
+    # on request bodies. This creates separate response/request schemas automatically.
     "COMPONENT_SPLIT_REQUEST": True,
     # ENUM_NAME_OVERRIDES: key = desired schema name, value = choices tuple.
     # Resolves collisions where multiple models share a field name (e.g. "kind",
@@ -359,6 +358,16 @@ def require_positive_int_env(name: str) -> int:
             ("quote", "Quote"),
             ("actual", "Actual"),
         ),
+        "ContactMethodTypeEnum": (
+            ("phone", "Phone"),
+            ("email", "Email"),
+        ),
+        "PhoneOwnershipStatusEnum": (
+            ("available", "available"),
+            ("people", "people"),
+            ("company", "company"),
+            ("internal", "internal"),
+        ),
         "InvoiceStatusEnum": (
             ("DRAFT", "Draft"),
             ("SUBMITTED", "Submitted"),
diff --git a/docketworks/urls.py b/docketworks/urls.py
index 56524f778..9da2af4d9 100644
--- a/docketworks/urls.py
+++ b/docketworks/urls.py
@@ -12,6 +12,7 @@
         "api/quoting/", include(("apps.quoting.urls", "quoting"), namespace="quoting")
     ),
     path("api/companies/", include("apps.company.urls_rest", namespace="companies")),
+    path("api/people/", include("apps.company.urls_people_rest", namespace="people")),
     path("api/crm/", include("apps.crm.urls", namespace="crm")),
     path("api/purchasing/", include("apps.purchasing.urls", namespace="purchasing")),
     path("api/accounting/", include("apps.accounting.urls", namespace="accounting")),
diff --git a/docs/test_plans/client_contact_management_test_plan.md b/docs/test_plans/client_contact_management_test_plan.md
deleted file mode 100644
index deffa8fb0..000000000
--- a/docs/test_plans/client_contact_management_test_plan.md
+++ /dev/null
@@ -1,168 +0,0 @@
-# Test Plan: Company People Management Feature
-
-## Overview
-
-This test plan covers company people management: people are stored locally,
-linked to companies, and selected on jobs without relying on Xero contact-person
-sync for day-to-day job assignment.
-
-## Prerequisites
-
-- [ ] Ensure migrations have been applied (`python manage.py migrate`)
-- [ ] Have at least one company in the system
-- [ ] Have access to create and edit jobs
-
-## Test Cases
-
-### 1. View Existing Person Data
-
-- [ ] Navigate to an existing job that has person and phone data
-- [ ] Verify the person information is displayed in the read-only field
-- [ ] Verify format is "Name - Phone" or just "Name" if no phone
-
-### 2. Open Person Management Modal
-
-- [ ] Click the "Manage" button next to the Person field
-- [ ] Verify modal opens with:
-  - [ ] Company name displayed at top
-  - [ ] List of existing people (if any)
-  - [ ] Form to add a new person
-
-### 3. Create New Person
-
-- [ ] In the modal, fill in the new person form:
-  - Name: "John Smith" (required)
-  - Position: "Project Manager" (optional)
-  - Email: "john@example.com" (optional)
-  - Phone: "555-1234" (optional)
-  - Notes: "Primary contact for all orders" (optional)
-  - Check "Set as primary contact"
-- [ ] Click "Save Person"
-- [ ] Verify modal closes
-- [ ] Verify person display updates to "John Smith - 555-1234"
-- [ ] Verify hidden person_id field is populated
-- [ ] Verify autosave triggers (check network tab or console)
-
-### 4. Select Existing Person
-
-- [ ] Open modal again
-- [ ] Verify "John Smith" appears in the existing people list with "Primary" badge
-- [ ] Add another person "Jane Doe" without marking as primary
-- [ ] Close and reopen modal
-- [ ] Click "Select" button next to "Jane Doe"
-- [ ] Click "Save Person"
-- [ ] Verify person display updates to "Jane Doe"
-
-### 5. Person Without Company
-
-- [ ] Create a new job or use one without a company selected
-- [ ] Click "Manage" person button
-- [ ] Verify modal shows warning: "Please select a company first."
-- [ ] Verify Save button is disabled
-
-### 6. Primary Person Behavior
-
-- [ ] For a company with multiple people, mark a different one as primary
-- [ ] Verify only one person can be primary at a time
-- [ ] Verify primary people appear first in the list
-
-### 7. Autosave Integration
-
-- [ ] Select/create a person for a job
-- [ ] Make another change to the job (e.g., change job name)
-- [ ] Verify both changes are saved
-- [ ] Refresh the page
-- [ ] Verify person selection persists
-
-### 8. API Testing (Developer Console)
-
-- [ ] Test fetching company people:
-
-```javascript
-// Replace [COMPANY_ID] with actual company UUID
-fetch("/api/companies/person-links/?company_id=[COMPANY_ID]")
-  .then((r) => r.json())
-  .then(console.log);
-```
-
-- [ ] Test creating a person link:
-
-```javascript
-// Replace [COMPANY_ID] with actual company UUID
-fetch("/api/companies/person-links/", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    "X-CSRFToken": document.querySelector("[name=csrfmiddlewaretoken]").value,
-  },
-  body: JSON.stringify({
-    company: "[COMPANY_ID]",
-    person_name: "Test Person",
-    person_email: "test@example.com",
-    phone: "555-5555",
-    is_primary: false,
-  }),
-})
-  .then((r) => r.json())
-  .then(console.log);
-```
-
-### 9. Edge Cases
-
-- [ ] Try to save without selecting any person (should close modal without changes)
-- [ ] Create a person with only name (minimum required field)
-- [ ] Create a person with very long name/phone/email
-- [ ] Try special characters in person fields
-
-### 10. Migrated Data
-
-- [ ] Find a job with migrated person/phone data
-- [ ] Verify it displays correctly
-- [ ] Select a new person from modal
-- [ ] Verify the job stores the selected person_id
-
-### 11. Multiple Browser Testing
-
-- [ ] Test in Chrome
-- [ ] Test in Firefox
-- [ ] Test in Safari (if available)
-- [ ] Test in Edge
-
-### 12. Performance Testing
-
-- [ ] Test with a company that has 50+ people
-- [ ] Verify modal loads quickly
-- [ ] Verify people list is scrollable and responsive
-
-## Expected Results
-
-- All person data is stored locally in Person and CompanyPersonLink models
-- No API calls to Xero for person management
-- Smooth user experience with modal interface
-- Primary person designation works correctly
-
-## Known Limitations
-
-- Person email is not currently displayed in the selection (only name and phone)
-- No search/filter functionality in the people list yet
-- No bulk import of people
-
-## Rollback Plan
-
-If critical issues are found:
-
-1. Reverse to the previous migration checkpoint in a development copy.
-2. Restore the previous branch if production rollout is blocked.
-3. Hide the modal by removing the "Manage" button from the template if needed.
-
-## Sign-off
-
-- [ ] Developer testing complete
-- [ ] User acceptance testing complete
-- [ ] Ready for production deployment
-
----
-
-_Test Plan Created: 2025-06-09_
-_Feature: Company People Management_
-_Version: 1.0_
diff --git a/docs/test_plans/company_people_management_test_plan.md b/docs/test_plans/company_people_management_test_plan.md
new file mode 100644
index 000000000..ab7fa65fc
--- /dev/null
+++ b/docs/test_plans/company_people_management_test_plan.md
@@ -0,0 +1,70 @@
+# Test Plan: Company People Management
+
+## Purpose
+
+Verify that a Person has one identity, can be linked to one or more companies,
+and can be managed from both the People directory and a company page.
+
+## Preconditions
+
+- Migrations are applied.
+- The tester is signed in as office staff.
+- At least two companies exist.
+
+## People Directory
+
+- [ ] Open `/crm/people` and confirm active people are listed once each.
+- [ ] Search by person name, email, phone, and company name.
+- [ ] Open a person and edit their name and email.
+- [ ] Add, edit, make primary, and delete a contact method.
+- [ ] Add a second company relationship and confirm the Person remains one record.
+- [ ] Remove one relationship and confirm the Person and other relationship remain.
+
+## Company People
+
+- [ ] Open a company and confirm its active people are shown.
+- [ ] Create a Person with name only and confirm the company link is created.
+- [ ] Create a Person with email, phone, position, notes, and primary status.
+- [ ] Link an existing Person from the People directory to the company.
+- [ ] Confirm only one active Person link is primary for a company.
+- [ ] Confirm creating a Person without an initial company is not offered.
+
+## Duplicate-Phone Decisions
+
+- [ ] Enter an unused phone and confirm a new Person can be created.
+- [ ] Enter a phone used by another Person at the same company and confirm the UI
+      allows creation because an office number may be shared.
+- [ ] Enter a phone owned by a Person at another company and confirm the UI offers
+      the existing Person for linking instead of creating a duplicate.
+- [ ] Link that existing Person and confirm both company relationships are visible.
+- [ ] Attempt to remove a relationship when that would turn a shared phone into an
+      unexplained cross-company collision; confirm removal is blocked with a clear
+      validation message.
+
+## Job Integration
+
+- [ ] On a job with a company, select one of that company's people.
+- [ ] Create a Person from the job Person control and confirm it receives the job's
+      company as its initial relationship.
+- [ ] Reload and confirm the selected Person persists.
+- [ ] On a job without a company, confirm a Person cannot be created until a company
+      is selected.
+
+## API Checks
+
+- [ ] `GET /api/people/?q=<term>` returns each matching Person once.
+- [ ] `GET /api/people/<person_id>/` separates identity from company links.
+- [ ] `GET /api/companies/<company_id>/people/` returns active company people.
+- [ ] `POST /api/companies/<company_id>/people/` creates the Person and initial link
+      atomically, or returns the structured phone conflict without partial writes.
+- [ ] `PUT` and `DELETE /api/people/<person_id>/company-links/<company_id>/` update only
+      the relationship.
+- [ ] The removed `/api/companies/person-links/` collection returns 404.
+
+## Sign-off
+
+- [ ] Focused backend and frontend tests pass.
+- [ ] End-to-end tests pass and global teardown restores the database.
+- [ ] Migration and workflows are rehearsed against a disposable production copy.
+- [ ] Production-copy counts and ownership integrity checks pass before and after.
+- [ ] User acceptance testing is complete.
diff --git a/docs/urls/client.md b/docs/urls/client.md
deleted file mode 100644
index ac223602d..000000000
--- a/docs/urls/client.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Company URLs Documentation
-
-<!-- This file is auto-generated. To regenerate, run: python scripts/generate_url_docs.py -->
-
-### Addresses Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/addresses/validate/` | `address_views.AddressValidateView` | `companies:address_validate` | Validate and clean an address using Google Address Validation API. |
-
-### All Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/all/` | `company_rest_views.CompanyListAllRestView` | `companies:company_list_all_rest` | REST view for listing all companies. |
-
-### Create Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/create/` | `company_rest_views.CompanyCreateRestView` | `companies:company_create_rest` | REST view for creating new companies. |
-
-### Jobs Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/<uuid:company_id>/jobs/` | `company_rest_views.CompanyJobsRestView` | `companies:company_jobs_rest` | REST view for fetching all jobs for a specific company. |
-| `/jobs/<uuid:job_id>/person/` | `company_rest_views.JobPersonRestView` | `companies:job_person_rest` | REST view for person information operations for a job. |
-
-### Other
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/<uuid:company_id>/` | `company_rest_views.CompanyRetrieveRestView` | `companies:company_retrieve_rest` | REST view for retrieving a specific company by ID. |
-
-### Search Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/search/` | `company_rest_views.CompanySearchRestView` | `companies:company_search_rest` | REST view for company search with pagination and sorting. |
-
-### Supplier-Aliases Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/<uuid:company_id>/supplier-aliases/` | `supplier_search_alias_views.CompanySupplierAliasListCreateView` | `companies:company_supplier_aliases_rest` | List and create search aliases for a company/supplier contact. |
-| `/supplier-aliases/<uuid:alias_id>/` | `supplier_search_alias_views.SupplierAliasDetailView` | `companies:supplier_alias_detail_rest` | Deactivate a supplier search alias. |
-
-### Update Management
-| URL Pattern | View | Name | Description |
-|-------------|------|------|-------------|
-| `/<uuid:company_id>/update/` | `company_rest_views.CompanyUpdateRestView` | `companies:company_update_rest` | REST view for updating company information. |
diff --git a/docs/urls/company.md b/docs/urls/company.md
index 17640ba1a..eb7bfe7e9 100644
--- a/docs/urls/company.md
+++ b/docs/urls/company.md
@@ -18,6 +18,18 @@
 | `/company-defaults/schema/` | `company_defaults_schema_api.CompanyDefaultsSchemaAPIView` | `api_company_defaults_schema` | API endpoint that returns field metadata for CompanyDefaults. |
 | `/company-defaults/upload-logo/` | `company_defaults_logo_api.CompanyDefaultsLogoAPIView` | `api_company_defaults_upload_logo` | API view for uploading and deleting company logo images. |
 
+### Company-Links Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:person_id>/company-links/` | `person_views.PersonCompanyLinksView` | `people:person_company_links` | List all active company relationships for a Person. |
+| `/<uuid:person_id>/company-links/<uuid:company_id>/` | `person_views.PersonCompanyLinkDetailView` | `people:person_company_link_detail` | Create, update, reactivate, or remove a Person-company relationship. |
+
+### Contact-Methods Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:person_id>/contact-methods/` | `person_views.PersonContactMethodsView` | `people:person_contact_methods` | List or create a Person's contact methods. |
+| `/<uuid:person_id>/contact-methods/<uuid:method_id>/` | `person_views.PersonContactMethodDetailView` | `people:person_contact_method_detail` | Update or delete one Person contact method. |
+
 ### Create Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
@@ -32,7 +44,15 @@
 ### Other
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
+| `/` | `person_views.PersonListView` | `people:person_list` | List and search active people across company relationships. |
 | `/<uuid:company_id>/` | `company_rest_views.CompanyRetrieveRestView` | `companies:company_retrieve_rest` | REST view for retrieving a specific company by ID. |
+| `/<uuid:person_id>/` | `person_views.PersonDetailView` | `people:person_detail` | Retrieve or update a Person's identity fields. |
+
+### People Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:company_id>/people/` | `person_views.CompanyPeopleView` | `companies:company_people_rest` | List a company's people or create a Person with its initial link. |
+| `/<uuid:company_id>/people/phone-ownership/` | `person_views.CompanyPersonPhoneOwnershipView` | `companies:company_person_phone_ownership_rest` | Classify a phone before creating a Person for a company. |
 
 ### Search Management
 | URL Pattern | View | Name | Description |
diff --git a/frontend/docs/jobview-etag-guide.md b/frontend/docs/jobview-etag-guide.md
index 7c25026f3..4a7e903d7 100644
--- a/frontend/docs/jobview-etag-guide.md
+++ b/frontend/docs/jobview-etag-guide.md
@@ -146,13 +146,13 @@ Testing checklist
 - GET Job detail, capture ETag. Repeat GET with If-None-Match to confirm 304.
 - Open Job in two tabs. Change from Tab A (PUT/PATCH). From Tab B, attempt mutation using old ETag and confirm 412. Tab B then GETs, receives new ETag, retries successfully.
 - Rapidly press add event; duplicates are prevented and ETag is respected.
-- Change client and ensure contact remains consistent or is cleared by backend protection if mismatched.
+- Change company and ensure the selected person remains consistent or is cleared by backend protection if mismatched.
 
 Change log
 
 - ETag enforcement and conditional GET added in views and services; see references above.
 - 412 PreconditionFailed mapped in Base view; see BaseJobRestView.handle_service_error().
-- Additional defensive checks in service to prevent cross-client contact leakage post-update.
+- Additional defensive checks in service prevent a person from leaking across unrelated companies after an update.
 
 ---
 
diff --git a/frontend/router-auto-options.ts b/frontend/router-auto-options.ts
index 07a696f92..535bb91d9 100644
--- a/frontend/router-auto-options.ts
+++ b/frontend/router-auto-options.ts
@@ -19,6 +19,8 @@ const TITLES: Record<string, string> = {
   '/xero': 'Xero Sync - DocketWorks',
   '/crm/companies': 'Companies - DocketWorks',
   '/crm/companies/:id': 'Company Details - DocketWorks',
+  '/crm/people': 'People - DocketWorks',
+  '/crm/people/:id': 'Person Details - DocketWorks',
   '/crm/calls': 'Calls - DocketWorks',
   '/purchasing/po': 'Purchase Orders - DocketWorks',
   '/purchasing/po/create': 'Create Purchase Order - DocketWorks',
diff --git a/frontend/schema.yml b/frontend/schema.yml
index c8b779f0c..4968bcf2d 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -1206,6 +1206,103 @@ paths:
               schema:
                 $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
+  /api/companies/{company_id}/people/:
+    get:
+      operationId: companies_people_list
+      description: List a company's people or create a Person with its initial link.
+      parameters:
+        - in: path
+          name: company_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - companies
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/CompanyPerson'
+          description: ''
+    post:
+      operationId: companies_people_create
+      description: List a company's people or create a Person with its initial link.
+      parameters:
+        - in: path
+          name: company_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - companies
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompanyPersonCreateRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/CompanyPersonCreateRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/CompanyPersonCreateRequest'
+        required: true
+      security:
+        - cookieAuth: []
+      responses:
+        '201':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompanyPerson'
+          description: ''
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PhoneOwnershipConflict'
+          description: ''
+  /api/companies/{company_id}/people/phone-ownership/:
+    post:
+      operationId: companies_people_phone_ownership_create
+      description: Classify a phone before creating a Person for a company.
+      parameters:
+        - in: path
+          name: company_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - companies
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PhoneOwnershipRequestRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/PhoneOwnershipRequestRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PhoneOwnershipRequestRequest'
+        required: true
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PhoneOwnership'
+          description: ''
   /api/companies/{company_id}/supplier-aliases/:
     get:
       operationId: companies_supplier_aliases_list
@@ -1773,224 +1870,6 @@ paths:
               schema:
                 $ref: '#/components/schemas/CompanyErrorResponse'
           description: ''
-  /api/companies/person-links/:
-    get:
-      operationId: companies_person_links_list
-      description: List all company-person links, optionally filtered by company_id.
-      parameters:
-        - in: query
-          name: company_id
-          schema:
-            type: string
-            format: uuid
-          description: Filter links by company UUID
-      tags:
-        - companies
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  $ref: '#/components/schemas/CompanyPersonLink'
-          description: ''
-    post:
-      operationId: companies_person_links_create
-      description: |-
-        ViewSet for CompanyPersonLink CRUD operations.
-
-        Endpoints:
-        - GET    /api/companies/person-links/       - list all company-person links
-        - POST   /api/companies/person-links/       - create link
-        - GET    /api/companies/person-links/<id>/  - retrieve link
-        - PUT    /api/companies/person-links/<id>/  - full update
-        - PATCH  /api/companies/person-links/<id>/  - partial update
-        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-        Query Parameters:
-        - company_id: Filter links by company UUID
-      tags:
-        - companies
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-          application/x-www-form-urlencoded:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-        required: true
-      security:
-        - cookieAuth: []
-      responses:
-        '201':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyPersonLink'
-          description: ''
-  /api/companies/person-links/{id}/:
-    get:
-      operationId: companies_person_links_retrieve
-      description: |-
-        ViewSet for CompanyPersonLink CRUD operations.
-
-        Endpoints:
-        - GET    /api/companies/person-links/       - list all company-person links
-        - POST   /api/companies/person-links/       - create link
-        - GET    /api/companies/person-links/<id>/  - retrieve link
-        - PUT    /api/companies/person-links/<id>/  - full update
-        - PATCH  /api/companies/person-links/<id>/  - partial update
-        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-        Query Parameters:
-        - company_id: Filter links by company UUID
-      parameters:
-        - in: path
-          name: id
-          schema:
-            type: string
-            format: uuid
-          description: A UUID string identifying this Company Person Link.
-          required: true
-      tags:
-        - companies
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyPersonLink'
-          description: ''
-    put:
-      operationId: companies_person_links_update
-      description: |-
-        ViewSet for CompanyPersonLink CRUD operations.
-
-        Endpoints:
-        - GET    /api/companies/person-links/       - list all company-person links
-        - POST   /api/companies/person-links/       - create link
-        - GET    /api/companies/person-links/<id>/  - retrieve link
-        - PUT    /api/companies/person-links/<id>/  - full update
-        - PATCH  /api/companies/person-links/<id>/  - partial update
-        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-        Query Parameters:
-        - company_id: Filter links by company UUID
-      parameters:
-        - in: path
-          name: id
-          schema:
-            type: string
-            format: uuid
-          description: A UUID string identifying this Company Person Link.
-          required: true
-      tags:
-        - companies
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-          application/x-www-form-urlencoded:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/CompanyPersonLinkRequest'
-        required: true
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyPersonLink'
-          description: ''
-    patch:
-      operationId: companies_person_links_partial_update
-      description: |-
-        ViewSet for CompanyPersonLink CRUD operations.
-
-        Endpoints:
-        - GET    /api/companies/person-links/       - list all company-person links
-        - POST   /api/companies/person-links/       - create link
-        - GET    /api/companies/person-links/<id>/  - retrieve link
-        - PUT    /api/companies/person-links/<id>/  - full update
-        - PATCH  /api/companies/person-links/<id>/  - partial update
-        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-        Query Parameters:
-        - company_id: Filter links by company UUID
-      parameters:
-        - in: path
-          name: id
-          schema:
-            type: string
-            format: uuid
-          description: A UUID string identifying this Company Person Link.
-          required: true
-      tags:
-        - companies
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
-          application/x-www-form-urlencoded:
-            schema:
-              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
-          multipart/form-data:
-            schema:
-              $ref: '#/components/schemas/PatchedCompanyPersonLinkRequest'
-      security:
-        - cookieAuth: []
-      responses:
-        '200':
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/CompanyPersonLink'
-          description: ''
-    delete:
-      operationId: companies_person_links_destroy
-      description: |-
-        ViewSet for CompanyPersonLink CRUD operations.
-
-        Endpoints:
-        - GET    /api/companies/person-links/       - list all company-person links
-        - POST   /api/companies/person-links/       - create link
-        - GET    /api/companies/person-links/<id>/  - retrieve link
-        - PUT    /api/companies/person-links/<id>/  - full update
-        - PATCH  /api/companies/person-links/<id>/  - partial update
-        - DELETE /api/companies/person-links/<id>/  - soft delete (sets is_active=False)
-
-        Query Parameters:
-        - company_id: Filter links by company UUID
-      parameters:
-        - in: path
-          name: id
-          schema:
-            type: string
-            format: uuid
-          description: A UUID string identifying this Company Person Link.
-          required: true
-      tags:
-        - companies
-      security:
-        - cookieAuth: []
-      responses:
-        '204':
-          description: No response body
   /api/companies/pickup-addresses/:
     get:
       operationId: companies_pickup_addresses_list
@@ -5895,12 +5774,30 @@ paths:
               schema:
                 $ref: '#/components/schemas/WorkshopScheduleResponse'
           description: ''
-  /api/process/categories/:
+  /api/people/:
     get:
-      operationId: process_categories_retrieve
-      description: Return available categories for procedures and forms.
+      operationId: people_list
+      description: List and search active people across company relationships.
+      parameters:
+        - name: page
+          required: false
+          in: query
+          description: A page number within the paginated result set.
+          schema:
+            type: integer
+        - name: page_size
+          required: false
+          in: query
+          description: Number of results to return per page.
+          schema:
+            type: integer
+        - in: query
+          name: q
+          schema:
+            type: string
+          description: Search people by name, email, phone, or company.
       tags:
-        - process
+        - people
       security:
         - cookieAuth: []
       responses:
@@ -5908,13 +5805,319 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/CategoriesResponse'
+                $ref: '#/components/schemas/PaginatedPersonSummaryList'
           description: ''
-  /api/process/forms/{category}/:
+  /api/people/{person_id}/:
     get:
-      operationId: process_forms_list
-      description: |-
-        CRUD for form/register definitions (fillable templates with entries, no Google Docs).
+      operationId: people_retrieve
+      description: Retrieve or update a Person's identity fields.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PersonDetail'
+          description: ''
+    put:
+      operationId: people_update
+      description: Retrieve or update a Person's identity fields.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PersonIdentityUpdateRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/PersonIdentityUpdateRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PersonIdentityUpdateRequest'
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PersonIdentityUpdate'
+          description: ''
+    patch:
+      operationId: people_partial_update
+      description: Retrieve or update a Person's identity fields.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonIdentityUpdateRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonIdentityUpdateRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonIdentityUpdateRequest'
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PersonIdentityUpdate'
+          description: ''
+  /api/people/{person_id}/company-links/:
+    get:
+      operationId: people_company_links_list
+      description: List all active company relationships for a Person.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/PersonCompanyLink'
+          description: ''
+  /api/people/{person_id}/company-links/{company_id}/:
+    put:
+      operationId: people_company_links_update
+      description: Create, update, reactivate, or remove a Person-company relationship.
+      parameters:
+        - in: path
+          name: company_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompanyLinkWriteRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/CompanyLinkWriteRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/CompanyLinkWriteRequest'
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PersonCompanyLink'
+          description: ''
+    delete:
+      operationId: people_company_links_destroy
+      description: Create, update, reactivate, or remove a Person-company relationship.
+      parameters:
+        - in: path
+          name: company_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '204':
+          description: No response body
+  /api/people/{person_id}/contact-methods/:
+    get:
+      operationId: people_contact_methods_list
+      description: List or create a Person's contact methods.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ContactMethod'
+          description: ''
+    post:
+      operationId: people_contact_methods_create
+      description: List or create a Person's contact methods.
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PersonContactMethodWriteRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/PersonContactMethodWriteRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PersonContactMethodWriteRequest'
+        required: true
+      security:
+        - cookieAuth: []
+      responses:
+        '201':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ContactMethod'
+          description: ''
+  /api/people/{person_id}/contact-methods/{method_id}/:
+    patch:
+      operationId: people_contact_methods_partial_update
+      description: Update or delete one Person contact method.
+      parameters:
+        - in: path
+          name: method_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonContactMethodWriteRequest'
+          application/x-www-form-urlencoded:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonContactMethodWriteRequest'
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/PatchedPersonContactMethodWriteRequest'
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ContactMethod'
+          description: ''
+    delete:
+      operationId: people_contact_methods_destroy
+      description: Update or delete one Person contact method.
+      parameters:
+        - in: path
+          name: method_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '204':
+          description: No response body
+  /api/process/categories/:
+    get:
+      operationId: process_categories_retrieve
+      description: Return available categories for procedures and forms.
+      tags:
+        - process
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CategoriesResponse'
+          description: ''
+  /api/process/forms/{category}/:
+    get:
+      operationId: process_forms_list
+      description: |-
+        CRUD for form/register definitions (fillable templates with entries, no Google Docs).
 
         Category is taken from the URL kwarg, e.g. /rest/forms/safety/.
       parameters:
@@ -11142,6 +11345,19 @@ components:
             $ref: '#/components/schemas/CompanyJobHeader'
       required:
         - results
+    CompanyLinkWriteRequest:
+      type: object
+      properties:
+        position:
+          type: string
+          nullable: true
+          maxLength: 255
+        notes:
+          type: string
+          nullable: true
+        is_primary:
+          type: boolean
+          default: false
     CompanyNameOnly:
       type: object
       properties:
@@ -11155,28 +11371,24 @@ components:
       required:
         - id
         - name
-    CompanyPersonLink:
+    CompanyPerson:
       type: object
-      description: Serializer for a person's relationship to a company.
       properties:
-        id:
-          type: string
-          format: uuid
-          readOnly: true
-        company:
-          type: string
-          format: uuid
-          description: The company this person is linked to
-        person:
+        person_id:
           type: string
           format: uuid
           readOnly: true
         person_name:
           type: string
+          readOnly: true
         person_email:
           type: string
           format: email
+          readOnly: true
           nullable: true
+        primary_phone:
+          type: string
+          readOnly: true
         position:
           type: string
           nullable: true
@@ -11184,70 +11396,42 @@ components:
           maxLength: 255
         is_primary:
           type: boolean
-          description: Indicates if this is the primary person for the company
+          description: Indicates if this is the primary contact for the company
         notes:
           type: string
           nullable: true
-          description: Additional notes about this person
-        is_active:
-          type: boolean
-          readOnly: true
-          description: Soft delete flag - inactive contacts are hidden from normal
-            queries
-        created_at:
-          type: string
-          format: date-time
-          readOnly: true
-        updated_at:
-          type: string
-          format: date-time
-          readOnly: true
-        phone:
-          type: string
-          nullable: true
-          default: ''
+          description: Additional notes about this contact
       required:
-        - company
-        - created_at
-        - id
-        - is_active
-        - person
+        - person_email
+        - person_id
         - person_name
-        - updated_at
-    CompanyPersonLinkRequest:
+        - primary_phone
+    CompanyPersonCreateRequest:
       type: object
-      description: Serializer for a person's relationship to a company.
       properties:
-        company:
-          type: string
-          format: uuid
-          description: The company this person is linked to
-        person_name:
+        name:
           type: string
           minLength: 1
-        person_email:
+          maxLength: 255
+        email:
           type: string
           format: email
           nullable: true
+        phone:
+          type: string
+          nullable: true
         position:
           type: string
           nullable: true
-          description: Job title if it's helpful - else leave blank
           maxLength: 255
-        is_primary:
-          type: boolean
-          description: Indicates if this is the primary person for the company
         notes:
           type: string
           nullable: true
-          description: Additional notes about this person
-        phone:
-          type: string
-          nullable: true
-          default: ''
+        is_primary:
+          type: boolean
+          default: false
       required:
-        - company
-        - person_name
+        - name
     CompanySearchResponse:
       type: object
       description: Serializer for paginated company search response
@@ -11421,7 +11605,7 @@ components:
           type: string
           readOnly: true
         method_type:
-          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodTypeEnum'
         value:
           type: string
           maxLength: 255
@@ -11454,14 +11638,6 @@ components:
         - person_name
         - updated_at
         - value
-    ContactMethodMethodTypeEnum:
-      enum:
-        - phone
-        - email
-      type: string
-      description: |-
-        * `phone` - Phone
-        * `email` - Email
     ContactMethodRequest:
       type: object
       description: Serializer for canonical company/person phone and email methods.
@@ -11475,7 +11651,7 @@ components:
           format: uuid
           nullable: true
         method_type:
-          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodTypeEnum'
         value:
           type: string
           minLength: 1
@@ -11499,6 +11675,14 @@ components:
       description: |-
         * `imported` - Imported
         * `local` - Local
+    ContactMethodTypeEnum:
+      enum:
+        - phone
+        - email
+      type: string
+      description: |-
+        * `phone` - Phone
+        * `email` - Email
     CostLine:
       type: object
       description: Serializer for CostLine model - read-only with basic depth
@@ -16269,7 +16453,32 @@ components:
         results:
           type: array
           items:
-            $ref: '#/components/schemas/ContactMethod'
+            $ref: '#/components/schemas/ContactMethod'
+        count:
+          type: integer
+          example: 123
+        page:
+          type: integer
+          example: 1
+        page_size:
+          type: integer
+          example: 50
+        total_pages:
+          type: integer
+          example: 3
+    PaginatedPersonSummaryList:
+      type: object
+      required:
+        - results
+        - count
+        - page
+        - page_size
+        - total_pages
+      properties:
+        results:
+          type: array
+          items:
+            $ref: '#/components/schemas/PersonSummary'
         count:
           type: integer
           example: 123
@@ -16751,37 +16960,6 @@ components:
           type: string
           format: uuid
           description: Internal company used for tracking shop work.
-    PatchedCompanyPersonLinkRequest:
-      type: object
-      description: Serializer for a person's relationship to a company.
-      properties:
-        company:
-          type: string
-          format: uuid
-          description: The company this person is linked to
-        person_name:
-          type: string
-          minLength: 1
-        person_email:
-          type: string
-          format: email
-          nullable: true
-        position:
-          type: string
-          nullable: true
-          description: Job title if it's helpful - else leave blank
-          maxLength: 255
-        is_primary:
-          type: boolean
-          description: Indicates if this is the primary person for the company
-        notes:
-          type: string
-          nullable: true
-          description: Additional notes about this person
-        phone:
-          type: string
-          nullable: true
-          default: ''
     PatchedCompanyUpdateRequest:
       type: object
       description: Serializer for company update request
@@ -16815,7 +16993,7 @@ components:
           format: uuid
           nullable: true
         method_type:
-          $ref: '#/components/schemas/ContactMethodMethodTypeEnum'
+          $ref: '#/components/schemas/ContactMethodTypeEnum'
         value:
           type: string
           minLength: 1
@@ -17009,6 +17187,33 @@ components:
           minimum: 0
           exclusiveMaximum: true
           description: Company-level rate used to seed JobLabourRate on new jobs
+    PatchedPersonContactMethodWriteRequest:
+      type: object
+      properties:
+        method_type:
+          $ref: '#/components/schemas/ContactMethodTypeEnum'
+        value:
+          type: string
+          minLength: 1
+          maxLength: 255
+        is_primary:
+          type: boolean
+          default: false
+        label:
+          type: string
+          default: ''
+    PatchedPersonIdentityUpdateRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        email:
+          type: string
+          format: email
+          nullable: true
+          maxLength: 254
     PatchedPhoneEndpointRequest:
       type: object
       properties:
@@ -17805,6 +18010,157 @@ components:
         - jm_hours
         - xero_gross
         - xero_hours
+    PersonCompanyLink:
+      type: object
+      properties:
+        company_id:
+          type: string
+          format: uuid
+        company_name:
+          type: string
+        position:
+          type: string
+          nullable: true
+        is_primary:
+          type: boolean
+        notes:
+          type: string
+          nullable: true
+        is_active:
+          type: boolean
+      required:
+        - company_id
+        - company_name
+        - is_active
+        - is_primary
+        - notes
+        - position
+    PersonCompanySummary:
+      type: object
+      properties:
+        company_id:
+          type: string
+          format: uuid
+        company_name:
+          type: string
+      required:
+        - company_id
+        - company_name
+    PersonContactMethodWriteRequest:
+      type: object
+      properties:
+        method_type:
+          $ref: '#/components/schemas/ContactMethodTypeEnum'
+        value:
+          type: string
+          minLength: 1
+          maxLength: 255
+        is_primary:
+          type: boolean
+          default: false
+        label:
+          type: string
+          default: ''
+      required:
+        - method_type
+        - value
+    PersonDetail:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        name:
+          type: string
+          maxLength: 255
+        email:
+          type: string
+          format: email
+          nullable: true
+          maxLength: 254
+        is_active:
+          type: boolean
+        created_at:
+          type: string
+          format: date-time
+          readOnly: true
+        updated_at:
+          type: string
+          format: date-time
+          readOnly: true
+        primary_phone:
+          type: string
+          readOnly: true
+        companies:
+          type: array
+          items:
+            $ref: '#/components/schemas/PersonCompanySummary'
+          readOnly: true
+        company_links:
+          type: array
+          items:
+            $ref: '#/components/schemas/PersonCompanyLink'
+          readOnly: true
+      required:
+        - companies
+        - company_links
+        - created_at
+        - id
+        - name
+        - primary_phone
+        - updated_at
+    PersonIdentityUpdate:
+      type: object
+      properties:
+        name:
+          type: string
+          maxLength: 255
+        email:
+          type: string
+          format: email
+          nullable: true
+          maxLength: 254
+    PersonIdentityUpdateRequest:
+      type: object
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 255
+        email:
+          type: string
+          format: email
+          nullable: true
+          maxLength: 254
+    PersonSummary:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          readOnly: true
+        name:
+          type: string
+          maxLength: 255
+        email:
+          type: string
+          format: email
+          nullable: true
+          maxLength: 254
+        primary_phone:
+          type: string
+          readOnly: true
+        companies:
+          type: array
+          items:
+            $ref: '#/components/schemas/PersonCompanySummary'
+          readOnly: true
+      required:
+        - companies
+        - id
+        - name
+        - primary_phone
     PhoneCallJobLinkRequest:
       type: object
       description: Request body for linking a phone call to a job.
@@ -18055,6 +18411,17 @@ components:
         - provider_recording_id
         - sha256
         - updated_at
+    PhoneCompanyOwner:
+      type: object
+      properties:
+        company_id:
+          type: string
+          format: uuid
+        company_name:
+          type: string
+      required:
+        - company_id
+        - company_name
     PhoneEndpoint:
       type: object
       properties:
@@ -18150,6 +18517,93 @@ components:
           maxLength: 255
       required:
         - company
+    PhoneOwnership:
+      type: object
+      properties:
+        status:
+          $ref: '#/components/schemas/PhoneOwnershipStatusEnum'
+        normalized_phone:
+          type: string
+        can_create_person:
+          type: boolean
+        people:
+          type: array
+          items:
+            $ref: '#/components/schemas/PhonePersonMatch'
+        companies:
+          type: array
+          items:
+            $ref: '#/components/schemas/PhoneCompanyOwner'
+      required:
+        - can_create_person
+        - companies
+        - normalized_phone
+        - people
+        - status
+    PhoneOwnershipConflict:
+      type: object
+      properties:
+        status:
+          $ref: '#/components/schemas/PhoneOwnershipStatusEnum'
+        normalized_phone:
+          type: string
+        can_create_person:
+          type: boolean
+        people:
+          type: array
+          items:
+            $ref: '#/components/schemas/PhonePersonMatch'
+        companies:
+          type: array
+          items:
+            $ref: '#/components/schemas/PhoneCompanyOwner'
+      required:
+        - can_create_person
+        - companies
+        - normalized_phone
+        - people
+        - status
+    PhoneOwnershipRequestRequest:
+      type: object
+      properties:
+        phone:
+          type: string
+          minLength: 1
+      required:
+        - phone
+    PhoneOwnershipStatusEnum:
+      enum:
+        - available
+        - people
+        - company
+        - internal
+      type: string
+      description: |-
+        * `available` - available
+        * `people` - people
+        * `company` - company
+        * `internal` - internal
+    PhonePersonMatch:
+      type: object
+      properties:
+        person_id:
+          type: string
+          format: uuid
+        person_name:
+          type: string
+        person_email:
+          type: string
+          format: email
+          nullable: true
+        company_links:
+          type: array
+          items:
+            $ref: '#/components/schemas/PersonCompanyLink'
+      required:
+        - company_links
+        - person_email
+        - person_id
+        - person_name
     PhoneProviderSettings:
       type: object
       properties:
diff --git a/frontend/scripts/capture-screenshots.ts b/frontend/scripts/capture-screenshots.ts
index 03480f59b..2a9d69b94 100644
--- a/frontend/scripts/capture-screenshots.ts
+++ b/frontend/scripts/capture-screenshots.ts
@@ -200,11 +200,17 @@ const SCREENSHOTS: ScreenshotDef[] = [
     fullPage: true,
   },
 
-  // === CLIENTS ===
+  // === CRM ===
   {
-    id: 'clients-list',
-    description: 'Client list with search and filters',
-    route: '/crm/clients',
+    id: 'companies-list',
+    description: 'Company list with search and filters',
+    route: '/crm/companies',
+    waitFor: 'main',
+  },
+  {
+    id: 'people-list',
+    description: 'People directory with company relationships',
+    route: '/crm/people',
     waitFor: 'main',
   },
 
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index d9d4748c4..0388ee89f 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -668,6 +668,57 @@ const CompanyJobHeader = z.object({
   max_people: z.number().int(),
 })
 const CompanyJobsResponse = z.object({ results: z.array(CompanyJobHeader) })
+const CompanyPerson = z.object({
+  person_id: z.string().uuid(),
+  person_name: z.string(),
+  person_email: z.string().email().nullable(),
+  primary_phone: z.string(),
+  position: z.string().max(255).nullish(),
+  is_primary: z.boolean().optional(),
+  notes: z.string().nullish(),
+})
+const CompanyPersonCreateRequest = z.object({
+  name: z.string().min(1).max(255),
+  email: z.string().email().nullish(),
+  phone: z.string().nullish(),
+  position: z.string().max(255).nullish(),
+  notes: z.string().nullish(),
+  is_primary: z.boolean().optional().default(false),
+})
+const PhoneOwnershipStatusEnum = z.enum(['available', 'people', 'company', 'internal'])
+const PersonCompanyLink = z.object({
+  company_id: z.string().uuid(),
+  company_name: z.string(),
+  position: z.string().nullable(),
+  is_primary: z.boolean(),
+  notes: z.string().nullable(),
+  is_active: z.boolean(),
+})
+const PhonePersonMatch = z.object({
+  person_id: z.string().uuid(),
+  person_name: z.string(),
+  person_email: z.string().email().nullable(),
+  company_links: z.array(PersonCompanyLink),
+})
+const PhoneCompanyOwner = z.object({
+  company_id: z.string().uuid(),
+  company_name: z.string(),
+})
+const PhoneOwnershipConflict = z.object({
+  status: PhoneOwnershipStatusEnum,
+  normalized_phone: z.string(),
+  can_create_person: z.boolean(),
+  people: z.array(PhonePersonMatch),
+  companies: z.array(PhoneCompanyOwner),
+})
+const PhoneOwnershipRequestRequest = z.object({ phone: z.string().min(1) })
+const PhoneOwnership = z.object({
+  status: PhoneOwnershipStatusEnum,
+  normalized_phone: z.string(),
+  can_create_person: z.boolean(),
+  people: z.array(PhonePersonMatch),
+  companies: z.array(PhoneCompanyOwner),
+})
 const SupplierSearchAlias = z.object({
   id: z.string().uuid(),
   company: z.string().uuid(),
@@ -705,7 +756,7 @@ const PatchedCompanyUpdateRequest = z
   })
   .partial()
 const CompanyNameOnly = z.object({ id: z.string().uuid(), name: z.string() })
-const ContactMethodMethodTypeEnum = z.enum(['phone', 'email'])
+const ContactMethodTypeEnum = z.enum(['phone', 'email'])
 const ContactMethodSourceEnum = z.enum(['imported', 'local'])
 const ContactMethod = z.object({
   id: z.string().uuid(),
@@ -714,7 +765,7 @@ const ContactMethod = z.object({
   company_name: z.string(),
   person: z.string().uuid().nullish(),
   person_name: z.string(),
-  method_type: ContactMethodMethodTypeEnum,
+  method_type: ContactMethodTypeEnum,
   value: z.string().max(255),
   normalized_value: z.string(),
   label: z.string().max(255).optional(),
@@ -733,7 +784,7 @@ const PaginatedContactMethodList = z.object({
 const ContactMethodRequest = z.object({
   company: z.string().uuid().nullish(),
   person: z.string().uuid().nullish(),
-  method_type: ContactMethodMethodTypeEnum,
+  method_type: ContactMethodTypeEnum,
   value: z.string().min(1).max(255),
   label: z.string().max(255).optional(),
   is_primary: z.boolean().optional().default(false),
@@ -743,7 +794,7 @@ const PatchedContactMethodRequest = z
   .object({
     company: z.string().uuid().nullable(),
     person: z.string().uuid().nullable(),
-    method_type: ContactMethodMethodTypeEnum,
+    method_type: ContactMethodTypeEnum,
     value: z.string().min(1).max(255),
     label: z.string().max(255),
     is_primary: z.boolean().default(false),
@@ -791,40 +842,6 @@ const JobPersonUpdateRequest = z.object({
   name: z.string().min(1),
   email: z.string().nullable(),
 })
-const CompanyPersonLink = z.object({
-  id: z.string().uuid(),
-  company: z.string().uuid(),
-  person: z.string().uuid(),
-  person_name: z.string(),
-  person_email: z.string().email().nullish(),
-  position: z.string().max(255).nullish(),
-  is_primary: z.boolean().optional(),
-  notes: z.string().nullish(),
-  is_active: z.boolean(),
-  created_at: z.string().datetime({ offset: true }),
-  updated_at: z.string().datetime({ offset: true }),
-  phone: z.string().nullish().default(''),
-})
-const CompanyPersonLinkRequest = z.object({
-  company: z.string().uuid(),
-  person_name: z.string().min(1),
-  person_email: z.string().email().nullish(),
-  position: z.string().max(255).nullish(),
-  is_primary: z.boolean().optional(),
-  notes: z.string().nullish(),
-  phone: z.string().nullish().default(''),
-})
-const PatchedCompanyPersonLinkRequest = z
-  .object({
-    company: z.string().uuid(),
-    person_name: z.string().min(1),
-    person_email: z.string().email().nullable(),
-    position: z.string().max(255).nullable(),
-    is_primary: z.boolean(),
-    notes: z.string().nullable(),
-    phone: z.string().nullable().default(''),
-  })
-  .partial()
 const SupplierPickupAddress = z.object({
   id: z.string().uuid(),
   company: z.string().uuid(),
@@ -2483,6 +2500,74 @@ const WorkshopScheduleResponse = z.object({
   jobs: z.array(ScheduledJob),
   unscheduled_jobs: z.array(UnscheduledJob),
 })
+const PersonCompanySummary = z.object({
+  company_id: z.string().uuid(),
+  company_name: z.string(),
+})
+const PersonSummary = z.object({
+  id: z.string().uuid(),
+  name: z.string().max(255),
+  email: z.string().max(254).email().nullish(),
+  primary_phone: z.string(),
+  companies: z.array(PersonCompanySummary),
+})
+const PaginatedPersonSummaryList = z.object({
+  results: z.array(PersonSummary),
+  count: z.number().int(),
+  page: z.number().int(),
+  page_size: z.number().int(),
+  total_pages: z.number().int(),
+})
+const PersonDetail = z.object({
+  id: z.string().uuid(),
+  name: z.string().max(255),
+  email: z.string().max(254).email().nullish(),
+  is_active: z.boolean().optional(),
+  created_at: z.string().datetime({ offset: true }),
+  updated_at: z.string().datetime({ offset: true }),
+  primary_phone: z.string(),
+  companies: z.array(PersonCompanySummary),
+  company_links: z.array(PersonCompanyLink),
+})
+const PersonIdentityUpdateRequest = z
+  .object({
+    name: z.string().min(1).max(255),
+    email: z.string().max(254).email().nullable(),
+  })
+  .partial()
+const PersonIdentityUpdate = z
+  .object({
+    name: z.string().max(255),
+    email: z.string().max(254).email().nullable(),
+  })
+  .partial()
+const PatchedPersonIdentityUpdateRequest = z
+  .object({
+    name: z.string().min(1).max(255),
+    email: z.string().max(254).email().nullable(),
+  })
+  .partial()
+const CompanyLinkWriteRequest = z
+  .object({
+    position: z.string().max(255).nullable(),
+    notes: z.string().nullable(),
+    is_primary: z.boolean().default(false),
+  })
+  .partial()
+const PersonContactMethodWriteRequest = z.object({
+  method_type: ContactMethodTypeEnum,
+  value: z.string().min(1).max(255),
+  label: z.string().optional().default(''),
+  is_primary: z.boolean().optional().default(false),
+})
+const PatchedPersonContactMethodWriteRequest = z
+  .object({
+    method_type: ContactMethodTypeEnum,
+    value: z.string().min(1).max(255),
+    label: z.string().default(''),
+    is_primary: z.boolean().default(false),
+  })
+  .partial()
 const CategoriesResponse = z.object({
   procedures: z.array(z.string()),
   forms: z.array(z.string()),
@@ -3675,13 +3760,22 @@ export const schemas = {
   CompanyErrorResponse,
   CompanyJobHeader,
   CompanyJobsResponse,
+  CompanyPerson,
+  CompanyPersonCreateRequest,
+  PhoneOwnershipStatusEnum,
+  PersonCompanyLink,
+  PhonePersonMatch,
+  PhoneCompanyOwner,
+  PhoneOwnershipConflict,
+  PhoneOwnershipRequestRequest,
+  PhoneOwnership,
   SupplierSearchAlias,
   SupplierSearchAliasCreateRequest,
   CompanyUpdateRequest,
   CompanyUpdateResponse,
   PatchedCompanyUpdateRequest,
   CompanyNameOnly,
-  ContactMethodMethodTypeEnum,
+  ContactMethodTypeEnum,
   ContactMethodSourceEnum,
   ContactMethod,
   PaginatedContactMethodList,
@@ -3693,9 +3787,6 @@ export const schemas = {
   CompanyDuplicateErrorResponse,
   JobPersonResponse,
   JobPersonUpdateRequest,
-  CompanyPersonLink,
-  CompanyPersonLinkRequest,
-  PatchedCompanyPersonLinkRequest,
   SupplierPickupAddress,
   SupplierPickupAddressRequest,
   PatchedSupplierPickupAddressRequest,
@@ -3895,6 +3986,16 @@ export const schemas = {
   ScheduledJob,
   UnscheduledJob,
   WorkshopScheduleResponse,
+  PersonCompanySummary,
+  PersonSummary,
+  PaginatedPersonSummaryList,
+  PersonDetail,
+  PersonIdentityUpdateRequest,
+  PersonIdentityUpdate,
+  PatchedPersonIdentityUpdateRequest,
+  CompanyLinkWriteRequest,
+  PersonContactMethodWriteRequest,
+  PatchedPersonContactMethodWriteRequest,
   CategoriesResponse,
   FormDocumentTypeEnum,
   FormStatusEnum,
@@ -4918,6 +5019,67 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
       },
     ],
   },
+  {
+    method: 'get',
+    path: '/api/companies/:company_id/people/',
+    alias: 'companies_people_list',
+    description: `List a company&#x27;s people or create a Person with its initial link.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'company_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: z.array(CompanyPerson),
+  },
+  {
+    method: 'post',
+    path: '/api/companies/:company_id/people/',
+    alias: 'companies_people_create',
+    description: `List a company&#x27;s people or create a Person with its initial link.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: CompanyPersonCreateRequest,
+      },
+      {
+        name: 'company_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: CompanyPerson,
+    errors: [
+      {
+        status: 409,
+        schema: PhoneOwnershipConflict,
+      },
+    ],
+  },
+  {
+    method: 'post',
+    path: '/api/companies/:company_id/people/phone-ownership/',
+    alias: 'companies_people_phone_ownership_create',
+    description: `Classify a phone before creating a Person for a company.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: z.object({ phone: z.string().min(1) }),
+      },
+      {
+        name: 'company_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PhoneOwnership,
+  },
   {
     method: 'get',
     path: '/api/companies/:company_id/supplier-aliases/',
@@ -5291,161 +5453,6 @@ Endpoint: /api/app-errors/&lt;id&gt;/`,
       },
     ],
   },
-  {
-    method: 'get',
-    path: '/api/companies/person-links/',
-    alias: 'companies_person_links_list',
-    description: `List all company-person links, optionally filtered by company_id.`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'company_id',
-        type: 'Query',
-        schema: z.string().uuid().optional(),
-      },
-    ],
-    response: z.array(CompanyPersonLink),
-  },
-  {
-    method: 'post',
-    path: '/api/companies/person-links/',
-    alias: 'companies_person_links_create',
-    description: `ViewSet for CompanyPersonLink CRUD operations.
-
-Endpoints:
-- GET    /api/companies/person-links/       - list all company-person links
-- POST   /api/companies/person-links/       - create link
-- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
-- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
-- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
-- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
-
-Query Parameters:
-- company_id: Filter links by company UUID`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'body',
-        type: 'Body',
-        schema: CompanyPersonLinkRequest,
-      },
-    ],
-    response: CompanyPersonLink,
-  },
-  {
-    method: 'get',
-    path: '/api/companies/person-links/:id/',
-    alias: 'companies_person_links_retrieve',
-    description: `ViewSet for CompanyPersonLink CRUD operations.
-
-Endpoints:
-- GET    /api/companies/person-links/       - list all company-person links
-- POST   /api/companies/person-links/       - create link
-- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
-- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
-- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
-- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
-
-Query Parameters:
-- company_id: Filter links by company UUID`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: CompanyPersonLink,
-  },
-  {
-    method: 'put',
-    path: '/api/companies/person-links/:id/',
-    alias: 'companies_person_links_update',
-    description: `ViewSet for CompanyPersonLink CRUD operations.
-
-Endpoints:
-- GET    /api/companies/person-links/       - list all company-person links
-- POST   /api/companies/person-links/       - create link
-- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
-- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
-- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
-- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
-
-Query Parameters:
-- company_id: Filter links by company UUID`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'body',
-        type: 'Body',
-        schema: CompanyPersonLinkRequest,
-      },
-      {
-        name: 'id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: CompanyPersonLink,
-  },
-  {
-    method: 'patch',
-    path: '/api/companies/person-links/:id/',
-    alias: 'companies_person_links_partial_update',
-    description: `ViewSet for CompanyPersonLink CRUD operations.
-
-Endpoints:
-- GET    /api/companies/person-links/       - list all company-person links
-- POST   /api/companies/person-links/       - create link
-- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
-- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
-- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
-- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
-
-Query Parameters:
-- company_id: Filter links by company UUID`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'body',
-        type: 'Body',
-        schema: PatchedCompanyPersonLinkRequest,
-      },
-      {
-        name: 'id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: CompanyPersonLink,
-  },
-  {
-    method: 'delete',
-    path: '/api/companies/person-links/:id/',
-    alias: 'companies_person_links_destroy',
-    description: `ViewSet for CompanyPersonLink CRUD operations.
-
-Endpoints:
-- GET    /api/companies/person-links/       - list all company-person links
-- POST   /api/companies/person-links/       - create link
-- GET    /api/companies/person-links/&lt;id&gt;/  - retrieve link
-- PUT    /api/companies/person-links/&lt;id&gt;/  - full update
-- PATCH  /api/companies/person-links/&lt;id&gt;/  - partial update
-- DELETE /api/companies/person-links/&lt;id&gt;/  - soft delete (sets is_active&#x3D;False)
-
-Query Parameters:
-- company_id: Filter links by company UUID`,
-    requestFormat: 'json',
-    parameters: [
-      {
-        name: 'id',
-        type: 'Path',
-        schema: z.string().uuid(),
-      },
-    ],
-    response: z.void(),
-  },
   {
     method: 'get',
     path: '/api/companies/pickup-addresses/',
@@ -8120,6 +8127,226 @@ POST: Processes selected jobs for month-end archiving and status updates`,
     ],
     response: WorkshopScheduleResponse,
   },
+  {
+    method: 'get',
+    path: '/api/people/',
+    alias: 'people_list',
+    description: `List and search active people across company relationships.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'page',
+        type: 'Query',
+        schema: z.number().int().optional(),
+      },
+      {
+        name: 'page_size',
+        type: 'Query',
+        schema: z.number().int().optional(),
+      },
+      {
+        name: 'q',
+        type: 'Query',
+        schema: z.string().optional(),
+      },
+    ],
+    response: PaginatedPersonSummaryList,
+  },
+  {
+    method: 'get',
+    path: '/api/people/:person_id/',
+    alias: 'people_retrieve',
+    description: `Retrieve or update a Person&#x27;s identity fields.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PersonDetail,
+  },
+  {
+    method: 'put',
+    path: '/api/people/:person_id/',
+    alias: 'people_update',
+    description: `Retrieve or update a Person&#x27;s identity fields.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: PersonIdentityUpdateRequest,
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PersonIdentityUpdate,
+  },
+  {
+    method: 'patch',
+    path: '/api/people/:person_id/',
+    alias: 'people_partial_update',
+    description: `Retrieve or update a Person&#x27;s identity fields.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: PatchedPersonIdentityUpdateRequest,
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PersonIdentityUpdate,
+  },
+  {
+    method: 'get',
+    path: '/api/people/:person_id/company-links/',
+    alias: 'people_company_links_list',
+    description: `List all active company relationships for a Person.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: z.array(PersonCompanyLink),
+  },
+  {
+    method: 'put',
+    path: '/api/people/:person_id/company-links/:company_id/',
+    alias: 'people_company_links_update',
+    description: `Create, update, reactivate, or remove a Person-company relationship.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: CompanyLinkWriteRequest,
+      },
+      {
+        name: 'company_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PersonCompanyLink,
+  },
+  {
+    method: 'delete',
+    path: '/api/people/:person_id/company-links/:company_id/',
+    alias: 'people_company_links_destroy',
+    description: `Create, update, reactivate, or remove a Person-company relationship.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'company_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: z.void(),
+  },
+  {
+    method: 'get',
+    path: '/api/people/:person_id/contact-methods/',
+    alias: 'people_contact_methods_list',
+    description: `List or create a Person&#x27;s contact methods.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: z.array(ContactMethod),
+  },
+  {
+    method: 'post',
+    path: '/api/people/:person_id/contact-methods/',
+    alias: 'people_contact_methods_create',
+    description: `List or create a Person&#x27;s contact methods.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: PersonContactMethodWriteRequest,
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: ContactMethod,
+  },
+  {
+    method: 'patch',
+    path: '/api/people/:person_id/contact-methods/:method_id/',
+    alias: 'people_contact_methods_partial_update',
+    description: `Update or delete one Person contact method.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'body',
+        type: 'Body',
+        schema: PatchedPersonContactMethodWriteRequest,
+      },
+      {
+        name: 'method_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: ContactMethod,
+  },
+  {
+    method: 'delete',
+    path: '/api/people/:person_id/contact-methods/:method_id/',
+    alias: 'people_contact_methods_destroy',
+    description: `Update or delete one Person contact method.`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'method_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: z.void(),
+  },
   {
     method: 'get',
     path: '/api/process/categories/',
diff --git a/frontend/src/assets/main.css b/frontend/src/assets/main.css
index 1dbeeb1aa..d5a8fd4b8 100644
--- a/frontend/src/assets/main.css
+++ b/frontend/src/assets/main.css
@@ -366,10 +366,6 @@ body {
   @apply text-xs text-gray-500 font-mono;
 }
 
-.job-card-client {
-  @apply text-xs text-gray-600 mb-2 truncate;
-}
-
 .job-card-meta {
   @apply flex items-center justify-between text-xs text-gray-500;
 }
diff --git a/frontend/src/components/AppNavbar.vue b/frontend/src/components/AppNavbar.vue
index 4afa5dc11..0818d314c 100644
--- a/frontend/src/components/AppNavbar.vue
+++ b/frontend/src/components/AppNavbar.vue
@@ -226,6 +226,13 @@
                 >
                   <Users class="w-4 h-4 mr-2" /> Companies
                 </router-link>
+                <router-link
+                  to="/crm/people"
+                  class="flex items-center px-4 py-2 text-sm text-gray-700 hover:text-blue-600 hover:bg-blue-50 font-medium transition-all"
+                  data-automation-id="AppNavbar-people"
+                >
+                  <ContactRound class="w-4 h-4 mr-2" /> People
+                </router-link>
                 <router-link
                   v-if="userInfo.is_superuser"
                   to="/crm/calls"
@@ -743,6 +750,14 @@
                       >
                         <Users class="w-4 h-4 mr-2" /> Companies
                       </router-link>
+                      <router-link
+                        to="/crm/people"
+                        class="flex items-center px-2 py-1.5 text-sm text-gray-600 hover:text-blue-600 hover:bg-blue-50 rounded transition-all"
+                        data-automation-id="AppNavbar-people-mobile"
+                        @click="closeMobileMenu"
+                      >
+                        <ContactRound class="w-4 h-4 mr-2" /> People
+                      </router-link>
                       <router-link
                         v-if="userInfo.is_superuser"
                         to="/crm/calls"
@@ -1003,6 +1018,7 @@ import {
   Activity,
   PhoneCall,
   Fingerprint,
+  ContactRound,
 } from 'lucide-vue-next'
 import { useAppLayout } from '@/composables/useAppLayout'
 import { adminPages, adminExternalLinks } from '@/config/adminPages'
diff --git a/frontend/src/components/PersonSelectionModal.vue b/frontend/src/components/PersonSelectionModal.vue
index 357d20f98..03095ea9c 100644
--- a/frontend/src/components/PersonSelectionModal.vue
+++ b/frontend/src/components/PersonSelectionModal.vue
@@ -15,50 +15,72 @@
         </DialogHeader>
 
         <div
-          class="modal-body flex-1 overflow-hidden flex flex-col xl:flex-row gap-4 lg:gap-6 py-4"
+          v-if="phoneOwnership"
+          class="mt-4 max-h-64 overflow-y-auto rounded-lg border p-4"
+          :class="
+            phoneOwnership.status === 'people'
+              ? 'border-amber-300 bg-amber-50'
+              : 'border-red-300 bg-red-50'
+          "
+          data-automation-id="PersonSelectionModal-phone-conflict"
         >
-          <!-- Existing People Section -->
-          <div class="people-section flex-1 min-h-0 flex flex-col relative">
-            <!-- Delete Confirmation Overlay -->
+          <h4 class="font-semibold text-gray-900">This phone number is already in use</h4>
+          <p v-if="phoneOwnership.status === 'people'" class="mt-1 text-sm text-gray-700">
+            Choose the matching person. Their identity and contact details will be preserved.
+          </p>
+          <p v-else-if="phoneOwnership.status === 'company'" class="mt-1 text-sm text-red-800">
+            It belongs to
+            {{ phoneOwnership.companies.map((company) => company.company_name).join(', ') }} and
+            cannot be assigned to a person.
+          </p>
+          <p v-else class="mt-1 text-sm text-red-800">
+            It is an internal phone endpoint and cannot be assigned to a person.
+          </p>
+
+          <div v-if="phoneOwnership.status === 'people'" class="mt-3 space-y-2">
             <div
-              v-if="showDeleteConfirm"
-              class="absolute inset-0 bg-white/95 z-30 flex items-center justify-center rounded-lg"
+              v-for="match in phoneOwnership.people"
+              :key="match.person_id"
+              class="flex flex-col gap-2 rounded-md border border-amber-200 bg-white p-3 sm:flex-row sm:items-center sm:justify-between"
+              :data-automation-id="`PersonSelectionModal-phone-match-${match.person_id}`"
             >
-              <div class="text-center p-6 max-w-sm">
-                <div
-                  class="w-12 h-12 rounded-full bg-red-100 flex items-center justify-center mx-auto mb-4"
-                >
-                  <AlertTriangle class="w-6 h-6 text-red-600" />
-                </div>
-                <h4 class="text-lg font-semibold text-gray-900 mb-2">Delete Person?</h4>
-                <p class="text-sm text-gray-600 mb-4">
-                  Are you sure you want to remove
-                  <strong>{{ personToDelete?.person_name }}</strong
-                  >? The person will be marked as inactive.
-                </p>
-                <p
-                  v-if="personToDelete?.is_primary"
-                  class="text-sm text-amber-600 font-medium mb-4"
-                >
-                  This is the primary person for this company.
+              <div>
+                <p class="font-medium text-gray-900">{{ match.person_name }}</p>
+                <p class="text-xs text-gray-600">{{ match.person_email || 'No email' }}</p>
+                <p class="mt-1 text-xs text-gray-500">
+                  {{
+                    match.company_links
+                      .map((link) => `${link.company_name}${link.is_active ? '' : ' (inactive)'}`)
+                      .join(', ') || 'No company links'
+                  }}
                 </p>
-                <div class="flex gap-3 justify-center">
-                  <button
-                    class="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50"
-                    @click="cancelDelete"
-                  >
-                    Cancel
-                  </button>
-                  <button
-                    class="px-4 py-2 text-sm font-medium text-white bg-red-600 rounded-md hover:bg-red-700"
-                    @click="executeDelete"
-                  >
-                    Delete
-                  </button>
-                </div>
               </div>
+              <button
+                type="button"
+                class="rounded-md bg-amber-700 px-3 py-2 text-sm font-medium text-white hover:bg-amber-800"
+                :data-automation-id="`PersonSelectionModal-link-match-${match.person_id}`"
+                @click="emit('link-person', match)"
+              >
+                {{ matchAction(match) }}
+              </button>
             </div>
+            <button
+              v-if="phoneOwnership.can_create_person"
+              type="button"
+              class="text-sm font-medium text-amber-900 underline"
+              data-automation-id="PersonSelectionModal-create-separate"
+              @click="emit('create-separate-person')"
+            >
+              Create a separate person with this shared number
+            </button>
+          </div>
+        </div>
 
+        <div
+          class="modal-body flex-1 overflow-hidden flex flex-col xl:flex-row gap-4 lg:gap-6 py-4"
+        >
+          <!-- Existing People Section -->
+          <div class="people-section flex-1 min-h-0 flex flex-col relative">
             <div v-if="isLoading" class="flex-1 flex items-center justify-center">
               <div class="text-center">
                 <div
@@ -81,16 +103,13 @@
                   <div class="people-grid grid gap-3 pb-2">
                     <div
                       v-for="person in people || []"
-                      :key="person?.id || ''"
-                      :data-automation-id="`PersonSelectionModal-card-${person?.id}`"
+                      :key="person.person_id"
+                      :data-automation-id="`PersonSelectionModal-card-${person.person_id}`"
                       class="group relative bg-white border border-gray-200 rounded-lg p-2 cursor-pointer transition-all duration-200 hover:shadow-md hover:border-blue-300 hover:-translate-y-0.5"
                       :class="{
                         'ring-2 ring-blue-500 bg-blue-50 border-blue-500 shadow-md mt-1':
-                          selectedPerson?.id === person?.id,
-                        'ring-2 ring-amber-500 bg-amber-50 border-amber-500':
-                          editingPersonLink?.id === person?.id,
-                        'hover:bg-gray-50':
-                          selectedPerson?.id !== person?.id && editingPersonLink?.id !== person?.id,
+                          selectedPerson?.person_id === person.person_id,
+                        'hover:bg-gray-50': selectedPerson?.person_id !== person.person_id,
                       }"
                       @click="selectPerson(person)"
                     >
@@ -106,7 +125,7 @@
                       <!-- Person Info -->
                       <div class="space-y-1">
                         <div class="font-medium text-gray-900 text-sm truncate pr-4">
-                          {{ person?.person_name || '' }}
+                          {{ person.person_name }}
                         </div>
 
                         <div v-if="person?.position" class="text-xs text-gray-600 truncate">
@@ -132,7 +151,7 @@
                           </div>
 
                           <div
-                            v-if="person?.phone"
+                            v-if="person.primary_phone"
                             class="text-xs text-gray-500 truncate flex items-center"
                           >
                             <svg
@@ -144,7 +163,7 @@
                                 d="M2 3a1 1 0 011-1h2.153a1 1 0 01.986.836l.74 4.435a1 1 0 01-.54 1.06l-1.548.773a11.037 11.037 0 006.105 6.105l.774-1.548a1 1 0 011.059-.54l4.435.74a1 1 0 01.836.986V17a1 1 0 01-1 1h-2C7.82 18 2 12.18 2 5V3z"
                               />
                             </svg>
-                            {{ person?.phone }}
+                            {{ person.primary_phone }}
                           </div>
                         </div>
                       </div>
@@ -161,20 +180,6 @@
                         >
                           Select
                         </button>
-                        <button
-                          class="p-1.5 text-xs font-medium bg-gray-600 text-white rounded-md shadow-sm hover:bg-gray-700 transition-colors"
-                          @click.stop="emit('edit-person', person)"
-                          title="Edit person"
-                        >
-                          <PencilLine class="w-3.5 h-3.5" />
-                        </button>
-                        <button
-                          class="p-1.5 text-xs font-medium bg-red-600 text-white rounded-md shadow-sm hover:bg-red-700 transition-colors"
-                          @click.stop="confirmDeletePerson(person)"
-                          title="Delete person"
-                        >
-                          <Trash2 class="w-3.5 h-3.5" />
-                        </button>
                       </div>
                     </div>
                   </div>
@@ -196,17 +201,7 @@
             class="create-person-section w-full xl:w-80 2xl:w-96 flex-shrink-0 border-t xl:border-t-0 xl:border-l border-gray-200 pt-4 xl:pt-0 xl:pl-6"
           >
             <div class="flex items-center justify-between mb-4">
-              <h4 class="section-title text-sm font-semibold text-gray-900">
-                {{ isEditing ? 'Edit Person' : 'Create New Person' }}
-              </h4>
-              <button
-                v-if="isEditing"
-                type="button"
-                class="text-xs text-gray-500 hover:text-gray-700 underline"
-                @click="emit('cancel-edit')"
-              >
-                Cancel edit
-              </button>
+              <h4 class="section-title text-sm font-semibold text-gray-900">Create New Person</h4>
             </div>
 
             <div class="space-y-4">
@@ -300,7 +295,7 @@
             @click="handleSave"
             :disabled="isLoading || !localPersonForm.name.trim()"
           >
-            {{ isLoading ? 'Saving...' : isEditing ? 'Update Person' : 'Create Person' }}
+            {{ isLoading ? 'Saving...' : 'Create Person' }}
           </button>
         </DialogFooter>
       </div>
@@ -310,7 +305,7 @@
 
 <script setup lang="ts">
 import { ref, watch, reactive } from 'vue'
-import { Users, PencilLine, Trash2, AlertTriangle } from 'lucide-vue-next'
+import { Users } from 'lucide-vue-next'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
 import type { PersonFormData } from '@/composables/usePersonManagement'
@@ -324,26 +319,26 @@ import {
 } from '../components/ui/dialog'
 
 // Type aliases for schema-based types
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
+type PhoneOwnership = z.infer<typeof schemas.PhoneOwnership>
+type PhonePersonMatch = z.infer<typeof schemas.PhonePersonMatch>
 
 const props = defineProps<{
   isOpen: boolean
   companyId: string
   companyName: string
-  people: CompanyPersonLink[]
-  selectedPerson: CompanyPersonLink | null
+  people: CompanyPerson[]
+  selectedPerson: CompanyPerson | null
   isLoading: boolean
   personForm: PersonFormData
-  editingPersonLink: CompanyPersonLink | null
-  isEditing: boolean
+  phoneOwnership: PhoneOwnership | null
 }>()
 const emit = defineEmits<{
   close: []
-  'select-person': [person: CompanyPersonLink]
+  'select-person': [person: CompanyPerson]
   'save-person': [newPerson: PersonFormData]
-  'edit-person': [person: CompanyPersonLink]
-  'delete-person': [personLinkId: string]
-  'cancel-edit': []
+  'link-person': [person: PhonePersonMatch]
+  'create-separate-person': []
   'update:personForm': [personForm: PersonFormData]
 }>()
 
@@ -390,29 +385,15 @@ const handleSave = () => {
   emit('save-person', { ...localPersonForm })
 }
 
-const selectPerson = (person: CompanyPersonLink) => {
+const selectPerson = (person: CompanyPerson) => {
   emit('select-person', person)
 }
 
-// Delete confirmation state
-const personToDelete = ref<CompanyPersonLink | null>(null)
-const showDeleteConfirm = ref(false)
-
-const confirmDeletePerson = (person: CompanyPersonLink) => {
-  personToDelete.value = person
-  showDeleteConfirm.value = true
-}
-
-const cancelDelete = () => {
-  personToDelete.value = null
-  showDeleteConfirm.value = false
-}
-
-const executeDelete = () => {
-  if (personToDelete.value?.id) {
-    emit('delete-person', personToDelete.value.id)
-  }
-  cancelDelete()
+const matchAction = (match: PhonePersonMatch): string => {
+  const link = match.company_links.find((item) => item.company_id === props.companyId)
+  if (link?.is_active) return 'Select person'
+  if (link) return 'Restore company link'
+  return 'Link to this company'
 }
 </script>
 
diff --git a/frontend/src/components/PersonSelector.vue b/frontend/src/components/PersonSelector.vue
index c3e013239..d6e059948 100644
--- a/frontend/src/components/PersonSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -49,18 +49,16 @@
     :is-open="isModalOpen"
     :company-id="companyId"
     :company-name="companyName"
-    :people="activePersonLinks"
+    :people="activePeople"
     :selected-person="selectedPerson"
     :is-loading="isLoading"
     :person-form="personForm"
-    :editing-person-link="editingPersonLink"
-    :is-editing="isEditing"
+    :phone-ownership="phoneOwnership"
     @close="closeModal"
     @select-person="selectExistingPerson"
     @save-person="handleSavePerson"
-    @edit-person="handleEditPerson"
-    @delete-person="handleDeletePerson"
-    @cancel-edit="cancelEdit"
+    @link-person="handleLinkPerson"
+    @create-separate-person="handleCreateSeparatePerson"
     @update:person-form="updatePersonForm"
   />
 </template>
@@ -76,7 +74,8 @@ import PersonSelectionModal from './PersonSelectionModal.vue'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
 
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
+type PhonePersonMatch = z.infer<typeof schemas.PhonePersonMatch>
 
 const props = withDefaults(
   defineProps<{
@@ -99,7 +98,7 @@ const props = withDefaults(
 
 const emit = defineEmits<{
   'update:modelValue': [value: string]
-  'update:selectedPerson': [person: CompanyPersonLink | null]
+  'update:selectedPerson': [person: CompanyPerson | null]
 }>()
 
 const {
@@ -108,6 +107,7 @@ const {
   selectedPerson,
   isLoading,
   personForm,
+  phoneOwnership,
   displayValue,
   openModal,
   closeModal,
@@ -115,16 +115,11 @@ const {
   setSelectedPerson,
   selectExistingPerson: selectFromComposable,
   savePerson,
+  createNewPerson,
+  linkExistingPerson,
   clearSelection: clearFromComposable,
   findPrimaryPerson,
-  // Edit mode state and functions
-  editingPersonLink,
-  isEditing,
-  activePersonLinks,
-  startEditPerson,
-  cancelEdit,
-  updatePerson,
-  deletePerson,
+  activePeople,
 } = usePersonManagement()
 
 const suppressEmit = ref(false)
@@ -155,7 +150,7 @@ const handleOpenModal = async () => {
   })
 }
 
-const selectExistingPerson = (person: CompanyPersonLink) => {
+const selectExistingPerson = (person: CompanyPerson) => {
   debugLog('PersonSelector - selectExistingPerson:', person)
   selectFromComposable(person)
 }
@@ -164,7 +159,6 @@ const handleSavePerson = async () => {
   debugLog('PersonSelector - handleSavePerson: before save', {
     personForm: personForm.value,
     selectedPerson: selectedPerson.value,
-    isEditing: isEditing.value,
   })
 
   // Validate email format before saving
@@ -175,15 +169,8 @@ const handleSavePerson = async () => {
     return
   }
 
-  const actionLabel = isEditing.value ? 'Updating' : 'Creating'
-  toast.info(`${actionLabel} person...`, { id: 'save-person' })
-
-  let success: boolean
-  if (isEditing.value) {
-    success = await updatePerson()
-  } else {
-    success = await savePerson()
-  }
+  toast.info('Creating person...', { id: 'save-person' })
+  const success = await savePerson()
 
   toast.dismiss('save-person')
 
@@ -194,35 +181,28 @@ const handleSavePerson = async () => {
   })
 
   if (success) {
-    toast.success(`Person ${isEditing.value ? 'updated' : 'created'} successfully!`, {
+    toast.success('Person created successfully!', {
       dismissible: true,
       position: 'top-left',
     })
-  } else {
-    toast.error(
-      `Failed to ${isEditing.value ? 'update' : 'create'} person. Please check the form and try again.`,
-    )
+  } else if (!phoneOwnership.value) {
+    toast.error('Failed to create person. Please check the form and try again.')
   }
 }
 
-const handleEditPerson = (person: CompanyPersonLink) => {
-  debugLog('PersonSelector - handleEditPerson:', person)
-  startEditPerson(person)
+const handleLinkPerson = async (person: PhonePersonMatch) => {
+  toast.info('Linking existing person...', { id: 'save-person' })
+  const success = await linkExistingPerson(person)
+  toast.dismiss('save-person')
+  if (success) toast.success('Existing person linked successfully')
 }
 
-const handleDeletePerson = async (personLinkId: string) => {
-  debugLog('PersonSelector - handleDeletePerson:', personLinkId)
-  toast.info('Deleting person...', { id: 'delete-person' })
-
-  const success = await deletePerson(personLinkId)
-
-  toast.dismiss('delete-person')
-
-  if (success) {
-    toast.success('Person removed successfully')
-  } else {
-    toast.error('Failed to remove person. Please try again.')
-  }
+const handleCreateSeparatePerson = async () => {
+  toast.info('Creating separate person...', { id: 'save-person' })
+  const success = await createNewPerson(true)
+  toast.dismiss('save-person')
+  if (success) toast.success('Person created successfully')
+  else toast.error('Failed to create separate person')
 }
 
 // Email validation helper
@@ -316,7 +296,7 @@ watch(
   async ([companyId, initialId]) => {
     debugLog('PersonSelector - unified watch:', { companyId, initialId })
 
-    // Quando mudar o cliente: limpe estado local (sem emitir)
+    // Clear local selection without emitting when the company changes.
     suppressEmit.value = true
     displayValue.value = ''
     selectedPerson.value = null
@@ -331,7 +311,7 @@ watch(
     // Evitar corridas: token local
     const token = ++loadToken
 
-    // Carrega contatos do cliente atual
+    // Load people linked to the current company.
     await loadPeopleOnly(companyId)
     if (token !== loadToken) return // request antigo, ignora
 
@@ -343,7 +323,7 @@ watch(
     // (auto-selection should not trigger saves - only user actions should)
     const decideAndSelect = () => {
       const choose =
-        (initialId && people.value.find((c: CompanyPersonLink) => c.person === initialId)) ||
+        (initialId && people.value.find((person) => person.person_id === initialId)) ||
         (!initialId && findPrimaryPerson()) ||
         null
 
diff --git a/frontend/src/components/__tests__/CompanyLookup.test.ts b/frontend/src/components/__tests__/CompanyLookup.test.ts
index 4c14bd5e1..18327fd7e 100644
--- a/frontend/src/components/__tests__/CompanyLookup.test.ts
+++ b/frontend/src/components/__tests__/CompanyLookup.test.ts
@@ -29,7 +29,7 @@ function buildComposableStub(suggestions: Company[]) {
     displayValue: ref(''),
     searchCompanies: vi.fn(),
     selectCompany: vi.fn(),
-    loadCompanyPersonLinks: vi.fn(),
+    loadCompanyPeople: vi.fn(),
     getPrimaryPerson: vi.fn(),
     clearSelection: vi.fn(),
     handleInputChange: vi.fn(),
diff --git a/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts b/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
new file mode 100644
index 000000000..7121deb65
--- /dev/null
+++ b/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
@@ -0,0 +1,125 @@
+import { mount } from '@vue/test-utils'
+import { describe, expect, it } from 'vitest'
+
+import PersonSelectionModal from '@/components/PersonSelectionModal.vue'
+
+const companyId = '11111111-1111-4111-8111-111111111111'
+const form = {
+  name: 'Jane Duplicate',
+  email: 'jane@example.com',
+  phone: '021 555 0100',
+  position: '',
+  notes: '',
+  is_primary: false,
+}
+const dialogStubs = {
+  Dialog: { template: '<div><slot /></div>' },
+  DialogContent: { template: '<div><slot /></div>' },
+  DialogHeader: { template: '<div><slot /></div>' },
+  DialogTitle: { template: '<div><slot /></div>' },
+  DialogDescription: { template: '<div><slot /></div>' },
+  DialogFooter: { template: '<div><slot /></div>' },
+}
+
+describe('PersonSelectionModal phone ownership choices', () => {
+  it('renders every candidate with link, restore, or select wording', () => {
+    const wrapper = mount(PersonSelectionModal, {
+      props: {
+        isOpen: true,
+        companyId,
+        companyName: 'Current Company',
+        people: [],
+        selectedPerson: null,
+        isLoading: false,
+        personForm: form,
+        phoneOwnership: {
+          status: 'people',
+          normalized_phone: '+64215550100',
+          can_create_person: true,
+          companies: [],
+          people: [
+            {
+              person_id: '22222222-2222-4222-8222-222222222222',
+              person_name: 'Already Linked',
+              person_email: null,
+              company_links: [
+                {
+                  company_id: companyId,
+                  company_name: 'Current Company',
+                  position: null,
+                  notes: null,
+                  is_primary: true,
+                  is_active: true,
+                },
+              ],
+            },
+            {
+              person_id: '33333333-3333-4333-8333-333333333333',
+              person_name: 'Inactive Link',
+              person_email: null,
+              company_links: [
+                {
+                  company_id: companyId,
+                  company_name: 'Current Company',
+                  position: null,
+                  notes: null,
+                  is_primary: false,
+                  is_active: false,
+                },
+              ],
+            },
+            {
+              person_id: '44444444-4444-4444-8444-444444444444',
+              person_name: 'Other Company',
+              person_email: null,
+              company_links: [],
+            },
+          ],
+        },
+      },
+      global: { stubs: dialogStubs },
+    })
+
+    expect(wrapper.text()).toContain('Select person')
+    expect(wrapper.text()).toContain('Restore company link')
+    expect(wrapper.text()).toContain('Link to this company')
+    expect(
+      wrapper.find('[data-automation-id="PersonSelectionModal-create-separate"]').exists(),
+    ).toBe(true)
+  })
+
+  it('renders a hard company-owner conflict without reuse actions', () => {
+    const wrapper = mount(PersonSelectionModal, {
+      props: {
+        isOpen: true,
+        companyId,
+        companyName: 'Current Company',
+        people: [],
+        selectedPerson: null,
+        isLoading: false,
+        personForm: form,
+        phoneOwnership: {
+          status: 'company',
+          normalized_phone: '+6495550100',
+          can_create_person: false,
+          people: [],
+          companies: [
+            {
+              company_id: '55555555-5555-4555-8555-555555555555',
+              company_name: 'Owner Company',
+            },
+          ],
+        },
+      },
+      global: { stubs: dialogStubs },
+    })
+
+    expect(wrapper.text()).toContain('Owner Company')
+    expect(wrapper.find('[data-automation-id^="PersonSelectionModal-link-match-"]').exists()).toBe(
+      false,
+    )
+    expect(
+      wrapper.find('[data-automation-id="PersonSelectionModal-create-separate"]').exists(),
+    ).toBe(false)
+  })
+})
diff --git a/frontend/src/components/crm/PhoneNumberManager.vue b/frontend/src/components/crm/PhoneNumberManager.vue
index 933796911..fff340627 100644
--- a/frontend/src/components/crm/PhoneNumberManager.vue
+++ b/frontend/src/components/crm/PhoneNumberManager.vue
@@ -59,7 +59,7 @@
           :disabled="!selectedCompanyId"
         >
           <option value="">No specific person</option>
-          <option v-for="person in personOptions" :key="person.id" :value="person.person">
+          <option v-for="person in personOptions" :key="person.person_id" :value="person.person_id">
             {{ person.person_name }}
           </option>
         </select>
@@ -163,7 +163,7 @@ const {
   suggestions: companyOptions,
   people: personOptions,
   browseCompanies,
-  loadCompanyPersonLinks: loadPeople,
+  loadCompanyPeople: loadPeople,
   logSelectedCompanyClick,
 } = useCompanyLookup()
 
diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index 6cb93bd20..b0604f7c5 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -384,7 +384,7 @@ import { onConcurrencyRetry } from '@/composables/useConcurrencyEvents'
 import { useSaveFeedback } from '@/composables/useSaveFeedback'
 import { requiredNumber } from '@/utils/requiredNumber'
 
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
 
 // Use the existing JobHeaderResponse schema from generated API
 type Job = z.infer<typeof schemas.JobHeaderResponse>
@@ -1155,30 +1155,30 @@ const handleCompanyUpdated = (updatedCompany: Company) => {
   toast.success('Company updated successfully')
 }
 
-const handlePersonSelected = async (personLink: CompanyPersonLink | null) => {
+const handlePersonSelected = async (personLink: CompanyPerson | null) => {
   if (personLink) {
     // Skip API call if person is already set to this value
     // This handles:
     // - Scenario 4: Company change - backend sets person in response, no duplicate API call needed
     // - User re-selecting the same person
-    if (localJobData.value.person_id === personLink.person) {
+    if (localJobData.value.person_id === personLink.person_id) {
       // Still update display value in case it's stale
       localJobData.value.person_name = personLink.person_name
       personDisplayValue.value = personLink.person_name
       jobsStore.patchHeader(props.jobId, {
-        person_id: personLink.person,
+        person_id: personLink.person_id,
         person_name: personLink.person_name,
       })
       return
     }
 
-    localJobData.value.person_id = personLink.person
+    localJobData.value.person_id = personLink.person_id
     localJobData.value.person_name = personLink.person_name
     personDisplayValue.value = personLink.person_name
 
     // Ensure all fields are present for Zod validation (convert undefined to null)
     const personToSend = {
-      id: personLink.person,
+      id: personLink.person_id,
       name: personLink.person_name,
       email: personLink.person_email ?? null,
     } satisfies z.input<typeof schemas.JobPersonUpdateRequest>
@@ -1188,10 +1188,10 @@ const handlePersonSelected = async (personLink: CompanyPersonLink | null) => {
       await api.companies_jobs_person_update(personToSend, {
         params: { job_id: props.jobId },
       })
-      serverBaseline.value.person_id = personLink.person
+      serverBaseline.value.person_id = personLink.person_id
       serverBaseline.value.person_name = personLink.person_name
       jobsStore.patchHeader(props.jobId, {
-        person_id: personLink.person,
+        person_id: personLink.person_id,
         person_name: personLink.person_name,
       })
       toast.success('Person updated successfully')
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
index 5880efd5e..2017d5ceb 100644
--- a/frontend/src/composables/__tests__/usePersonManagement.test.ts
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -3,10 +3,10 @@ import { z } from 'zod'
 
 vi.mock('@/api/client', () => ({
   api: {
-    companies_person_links_list: vi.fn(),
-    companies_person_links_create: vi.fn(),
-    companies_person_links_partial_update: vi.fn(),
-    companies_person_links_destroy: vi.fn(),
+    companies_people_list: vi.fn(),
+    companies_people_create: vi.fn(),
+    companies_people_phone_ownership_create: vi.fn(),
+    people_company_links_update: vi.fn(),
   },
 }))
 
@@ -22,22 +22,19 @@ vi.mock('vue-sonner', () => ({
 
 import { usePersonManagement } from '../usePersonManagement'
 import { schemas } from '@/api/generated/api'
+import { api } from '@/api/client'
 
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
+type PhonePersonMatch = z.infer<typeof schemas.PhonePersonMatch>
 
-const buildPerson = (overrides: Partial<CompanyPersonLink> = {}): CompanyPersonLink => ({
-  id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0001',
-  company: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0002',
-  person: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0003',
+const buildPerson = (overrides: Partial<CompanyPerson> = {}): CompanyPerson => ({
+  person_id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0003',
   person_name: 'Jane Doe',
   person_email: 'jane@example.com',
   position: null,
   is_primary: true,
   notes: null,
-  is_active: true,
-  created_at: '2026-01-01T00:00:00+00:00',
-  updated_at: '2026-01-01T00:00:00+00:00',
-  phone: '+64 21 555 0100',
+  primary_phone: '+64 21 555 0100',
   ...overrides,
 })
 
@@ -59,7 +56,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
 
   it('skips the phone segment when the person has no phone', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
-    setSelectedPerson(buildPerson({ phone: '' }))
+    setSelectedPerson(buildPerson({ primary_phone: '' }))
     expect(displayValue.value).toBe('Jane Doe - jane@example.com')
   })
 
@@ -71,7 +68,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
 
   it('shows only the name when the person has neither phone nor email', () => {
     const { displayValue, setSelectedPerson } = usePersonManagement()
-    setSelectedPerson(buildPerson({ phone: '', person_email: null }))
+    setSelectedPerson(buildPerson({ primary_phone: '', person_email: null }))
     expect(displayValue.value).toBe('Jane Doe')
   })
 
@@ -83,7 +80,7 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
 
     expect(selectedPerson.value).toMatchObject({
       person_name: 'Bob Smith',
-      phone: '09 555 1234',
+      primary_phone: '09 555 1234',
       person_email: 'bob@example.com',
     })
   })
@@ -112,3 +109,191 @@ describe('usePersonManagement displayValue (KAN-281)', () => {
     })
   })
 })
+
+describe('usePersonManagement duplicate phone prevention', () => {
+  const companyId = 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0002'
+  const otherCompanyId = 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0004'
+  const match: PhonePersonMatch = {
+    person_id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0003',
+    person_name: 'Jane Doe',
+    person_email: 'jane@example.com',
+    company_links: [
+      {
+        company_id: otherCompanyId,
+        company_name: 'Other Company',
+        position: null,
+        notes: null,
+        is_primary: true,
+        is_active: true,
+      },
+    ],
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(api.companies_people_list).mockResolvedValue([])
+  })
+
+  it('offers existing people instead of creating a duplicate', async () => {
+    const secondMatch = {
+      ...match,
+      person_id: 'f6b4a1e2-0f7c-4b7d-9c65-3f2f9a1c0005',
+      person_name: 'Jane Smith',
+    }
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      status: 'people',
+      normalized_phone: '+64215550100',
+      can_create_person: false,
+      people: [match, secondMatch],
+      companies: [],
+    })
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+    manager.personForm.value = {
+      ...manager.personForm.value,
+      name: 'Jane Duplicate',
+      phone: '021 555 0100',
+    }
+
+    expect(await manager.createNewPerson()).toBe(false)
+    expect(manager.phoneOwnership.value?.people).toEqual([match, secondMatch])
+    expect(api.companies_people_create).not.toHaveBeenCalled()
+  })
+
+  it('allows an explicit separate identity only when the ownership result permits it', async () => {
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      status: 'people',
+      normalized_phone: '+64215550100',
+      can_create_person: true,
+      people: [
+        {
+          ...match,
+          company_links: [
+            {
+              company_id: companyId,
+              company_name: 'Current Company',
+              position: null,
+              notes: null,
+              is_primary: true,
+              is_active: true,
+            },
+          ],
+        },
+      ],
+      companies: [],
+    })
+    vi.mocked(api.companies_people_create).mockResolvedValue(buildPerson())
+    vi.mocked(api.companies_people_list)
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([buildPerson()])
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+    manager.personForm.value = {
+      ...manager.personForm.value,
+      name: 'Household Contact',
+      phone: '021 555 0100',
+    }
+
+    expect(await manager.createNewPerson()).toBe(false)
+    expect(await manager.createNewPerson(true)).toBe(true)
+    expect(api.companies_people_create).toHaveBeenCalledOnce()
+  })
+
+  it('blocks company-owned and internal numbers without attempting creation', async () => {
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      status: 'company',
+      normalized_phone: '+6495550100',
+      can_create_person: false,
+      people: [],
+      companies: [{ company_id: otherCompanyId, company_name: 'Other Company' }],
+    })
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+    manager.personForm.value = {
+      ...manager.personForm.value,
+      name: 'Invalid Owner',
+      phone: '09 555 0100',
+    }
+
+    expect(await manager.createNewPerson()).toBe(false)
+    expect(manager.phoneOwnership.value?.status).toBe('company')
+    expect(api.companies_people_create).not.toHaveBeenCalled()
+  })
+
+  it('surfaces a typed 409 race as the same candidate workflow', async () => {
+    const conflict = {
+      status: 'people' as const,
+      normalized_phone: '+64215550100',
+      can_create_person: false,
+      people: [match],
+      companies: [],
+    }
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      ...conflict,
+      status: 'available',
+      people: [],
+    })
+    vi.mocked(api.companies_people_create).mockRejectedValue({
+      isAxiosError: true,
+      response: { status: 409, data: conflict },
+    })
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+    manager.personForm.value = {
+      ...manager.personForm.value,
+      name: 'Racing Person',
+      phone: '021 555 0100',
+    }
+
+    expect(await manager.createNewPerson()).toBe(false)
+    expect(manager.phoneOwnership.value).toEqual(conflict)
+  })
+
+  it('links a cross-company match without changing its identity', async () => {
+    vi.mocked(api.people_company_links_update).mockResolvedValue({
+      company_id: companyId,
+      company_name: 'Current Company',
+      position: null,
+      notes: null,
+      is_primary: true,
+      is_active: true,
+    })
+    vi.mocked(api.companies_people_list)
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([buildPerson()])
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+
+    expect(await manager.linkExistingPerson(match)).toBe(true)
+    expect(api.people_company_links_update).toHaveBeenCalledWith(
+      expect.objectContaining({ is_primary: true }),
+      { params: { person_id: match.person_id, company_id: companyId } },
+    )
+    expect(manager.selectedPerson.value?.person_id).toBe(match.person_id)
+  })
+
+  it('selects an already-linked person without rewriting the link', async () => {
+    const linkedMatch: PhonePersonMatch = {
+      ...match,
+      company_links: [
+        {
+          company_id: companyId,
+          company_name: 'Current Company',
+          position: 'Buyer',
+          notes: 'Keep this relationship data',
+          is_primary: true,
+          is_active: true,
+        },
+      ],
+    }
+    vi.mocked(api.companies_people_list)
+      .mockResolvedValueOnce([])
+      .mockResolvedValueOnce([buildPerson()])
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+
+    expect(await manager.linkExistingPerson(linkedMatch)).toBe(true)
+    expect(api.people_company_links_update).not.toHaveBeenCalled()
+    expect(manager.selectedPerson.value?.person_id).toBe(linkedMatch.person_id)
+  })
+})
diff --git a/frontend/src/composables/useCompanyLookup.ts b/frontend/src/composables/useCompanyLookup.ts
index 5823cd14e..7f9b38f8c 100644
--- a/frontend/src/composables/useCompanyLookup.ts
+++ b/frontend/src/composables/useCompanyLookup.ts
@@ -8,7 +8,7 @@ import { logSearchResultClick } from '@/services/searchTelemetry.service'
 
 // Use generated schemas
 export type Company = z.infer<typeof schemas.CompanySearchResult>
-export type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+export type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
 
 type UseCompanyLookupOptions = {
   supplierLookup?: { value: boolean }
@@ -45,7 +45,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
   const isLoading = ref(false)
   const showSuggestions = ref(false)
   const selectedCompany = ref<Company | null>(null)
-  const people = ref<CompanyPersonLink[]>([])
+  const people = ref<CompanyPerson[]>([])
 
   const hasValidXeroId = computed(() => {
     debugLog('Selected company value: ', selectedCompany.value)
@@ -138,18 +138,18 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
 
     people.value = []
 
-    await loadCompanyPersonLinks(company.id)
+    await loadCompanyPeople(company.id)
   }
 
-  const loadCompanyPersonLinks = async (companyId: string) => {
+  const loadCompanyPeople = async (companyId: string) => {
     if (!companyId) {
       people.value = []
       return
     }
 
     try {
-      const response = await api.companies_person_links_list({
-        queries: { company_id: companyId },
+      const response = await api.companies_people_list({
+        params: { company_id: companyId },
       })
       people.value = response || []
     } catch (error) {
@@ -159,7 +159,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     }
   }
 
-  const getPrimaryPerson = (): CompanyPersonLink | null => {
+  const getPrimaryPerson = (): CompanyPerson | null => {
     if (people.value.length === 0) {
       return null
     }
@@ -258,7 +258,7 @@ export function useCompanyLookup(options: UseCompanyLookupOptions = {}) {
     browseCompanies,
     logSelectedCompanyClick,
     selectCompany,
-    loadCompanyPersonLinks,
+    loadCompanyPeople,
     getPrimaryPerson,
     clearSelection,
     handleInputChange,
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
index 215066db0..2538d4c45 100644
--- a/frontend/src/composables/usePersonManagement.ts
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -1,4 +1,5 @@
-import { ref, computed } from 'vue'
+import { ref, computed, watch } from 'vue'
+import { isAxiosError } from 'axios'
 import { schemas } from '@/api/generated/api'
 import { api } from '@/api/client'
 import { z } from 'zod'
@@ -6,13 +7,14 @@ import { debugLog } from '@/utils/debug'
 import { toast } from 'vue-sonner'
 
 // Schema-derived types (no custom interfaces)
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
-type PersonCreateRequest = z.input<typeof schemas.CompanyPersonLinkRequest>
-type PersonUpdateRequest = z.input<typeof schemas.PatchedCompanyPersonLinkRequest>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
+type PersonCreateRequest = z.input<typeof schemas.CompanyPersonCreateRequest>
+type PhoneOwnership = z.infer<typeof schemas.PhoneOwnership>
+type PhonePersonMatch = z.infer<typeof schemas.PhonePersonMatch>
 type PersonFormFields = {
-  name: PersonCreateRequest['person_name']
+  name: PersonCreateRequest['name']
   position: PersonCreateRequest['position']
-  email: PersonCreateRequest['person_email']
+  email: PersonCreateRequest['email']
   phone: PersonCreateRequest['phone']
   notes: PersonCreateRequest['notes']
   is_primary: boolean
@@ -29,11 +31,12 @@ export type PersonFormData = PersonFormFields
  */
 export function usePersonManagement() {
   const isModalOpen = ref(false)
-  const people = ref<CompanyPersonLink[]>([])
-  const selectedPerson = ref<CompanyPersonLink | null>(null)
+  const people = ref<CompanyPerson[]>([])
+  const selectedPerson = ref<CompanyPerson | null>(null)
   const isLoading = ref(false)
   const currentCompanyId = ref<string>('')
   const currentCompanyName = ref<string>('')
+  const phoneOwnership = ref<PhoneOwnership | null>(null)
 
   const personForm = ref<PersonFormData>({
     name: '',
@@ -45,22 +48,23 @@ export function usePersonManagement() {
   })
 
   // Edit mode state
-  const editingPersonLink = ref<CompanyPersonLink | null>(null)
-  const isEditing = computed(() => editingPersonLink.value !== null)
-
-  // Filter out inactive people for display
-  const activePersonLinks = computed(() =>
-    people.value.filter((person) => person.is_active !== false),
-  )
+  const activePeople = computed(() => people.value)
 
   const hasPeople = computed(() => people.value.length > 0)
 
+  watch(
+    () => personForm.value.phone,
+    () => {
+      phoneOwnership.value = null
+    },
+  )
+
   const displayValue = computed({
     get() {
       if (!selectedPerson.value) return ''
       const person = selectedPerson.value
       const parts = [person.person_name]
-      if (person.phone) parts.push(person.phone)
+      if (person.primary_phone) parts.push(person.primary_phone)
       if (person.person_email) parts.push(person.person_email)
       return parts.join(' - ')
     },
@@ -71,7 +75,7 @@ export function usePersonManagement() {
         selectedPerson.value = {
           ...selectedPerson.value,
           person_name: name,
-          phone: phone || '',
+          primary_phone: phone || '',
           person_email: email || '',
         }
       } else {
@@ -111,7 +115,7 @@ export function usePersonManagement() {
    */
   const closeModal = () => {
     isModalOpen.value = false
-    editingPersonLink.value = null
+    phoneOwnership.value = null
     resetPersonForm()
   }
 
@@ -129,8 +133,8 @@ export function usePersonManagement() {
 
     isLoading.value = true
     try {
-      const response = await api.companies_person_links_list({
-        queries: { company_id: companyId },
+      const response = await api.companies_people_list({
+        params: { company_id: companyId },
       })
       people.value = response || []
       personForm.value.is_primary = people.value.length === 0
@@ -159,7 +163,7 @@ export function usePersonManagement() {
    *
    * @param person - The person to select
    */
-  const setSelectedPerson = (person: CompanyPersonLink) => {
+  const setSelectedPerson = (person: CompanyPerson) => {
     selectedPerson.value = person
   }
 
@@ -169,7 +173,7 @@ export function usePersonManagement() {
    *
    * @param person - The person to select
    */
-  const selectExistingPerson = (person: CompanyPersonLink) => {
+  const selectExistingPerson = (person: CompanyPerson) => {
     selectedPerson.value = person
     closeModal()
   }
@@ -182,7 +186,7 @@ export function usePersonManagement() {
    *
    * @returns Promise<boolean> - True if person was created successfully, false otherwise
    */
-  const createNewPerson = async (): Promise<boolean> => {
+  const createNewPerson = async (createSeparate = false): Promise<boolean> => {
     if (!currentCompanyId.value) {
       debugLog('Cannot create person without company ID')
       return false
@@ -204,12 +208,26 @@ export function usePersonManagement() {
       const trimmedPhone = personForm.value.phone?.trim()
       const trimmedNotes = personForm.value.notes?.trim()
 
+      if (trimmedPhone && !createSeparate) {
+        const ownership = await api.companies_people_phone_ownership_create(
+          { phone: trimmedPhone },
+          { params: { company_id: currentCompanyId.value } },
+        )
+        if (ownership.status !== 'available') {
+          phoneOwnership.value = ownership
+          return false
+        }
+      }
+
+      if (createSeparate && !phoneOwnership.value?.can_create_person) {
+        throw new Error('This phone number cannot be assigned to a separate person')
+      }
+
       const personData: PersonCreateRequest = {
-        company: currentCompanyId.value,
-        person_name: personForm.value.name.trim(),
+        name: personForm.value.name.trim(),
         is_primary: shouldBePrimary,
         position: trimmedPosition || undefined,
-        person_email: trimmedEmail || undefined,
+        email: trimmedEmail || undefined,
         notes: trimmedNotes || undefined,
         // Omit phone entirely when blank so the backend leaves person methods untouched
         ...(trimmedPhone ? { phone: trimmedPhone } : {}),
@@ -217,13 +235,15 @@ export function usePersonManagement() {
 
       debugLog('Creating new person:', personData)
 
-      const response = await api.companies_person_links_create(personData)
+      const response = await api.companies_people_create(personData, {
+        params: { company_id: currentCompanyId.value },
+      })
 
-      if (!response || !response.id) {
+      if (!response || !response.person_id) {
         throw new Error('Invalid response from server')
       }
 
-      const newPerson = response as CompanyPersonLink
+      const newPerson = response
 
       debugLog('Person created successfully:', newPerson)
 
@@ -231,7 +251,7 @@ export function usePersonManagement() {
       await loadPeople(currentCompanyId.value)
 
       // Then find and select the newly created person
-      const createdPerson = people.value.find((person) => person.id === newPerson.id)
+      const createdPerson = people.value.find((person) => person.person_id === newPerson.person_id)
       if (createdPerson) {
         selectedPerson.value = createdPerson
         debugLog('New person selected:', createdPerson)
@@ -243,6 +263,13 @@ export function usePersonManagement() {
       closeModal()
       return true
     } catch (error) {
+      if (isAxiosError(error) && error.response?.status === 409) {
+        const parsed = schemas.PhoneOwnershipConflict.safeParse(error.response.data)
+        if (parsed.success) {
+          phoneOwnership.value = parsed.data
+          return false
+        }
+      }
       debugLog('Error creating person:', error)
       return false
     } finally {
@@ -250,101 +277,38 @@ export function usePersonManagement() {
     }
   }
 
-  /**
-   * Resets the new person form to its initial empty state
-   */
-  const resetPersonForm = () => {
-    personForm.value = {
-      name: '',
-      position: '',
-      email: '',
-      phone: '',
-      notes: '',
-      is_primary: people.value.length === 0,
-    }
-  }
-
-  /**
-   * Starts editing an existing person
-   * Populates the form with the person's current data
-   *
-   * @param person - The person to edit
-   */
-  const startEditPerson = (person: CompanyPersonLink) => {
-    editingPersonLink.value = person
-    personForm.value = {
-      name: person.person_name,
-      position: person.position || '',
-      email: person.person_email || '',
-      phone: person.phone || '',
-      notes: person.notes || '',
-      is_primary: person.is_primary || false,
-    }
-  }
-
-  /**
-   * Cancels the current edit operation and resets the form
-   */
-  const cancelEdit = () => {
-    editingPersonLink.value = null
-    resetPersonForm()
-  }
-
-  /**
-   * Updates an existing person with the current form data
-   *
-   * @returns Promise<boolean> - True if update was successful, false otherwise
-   */
-  const updatePerson = async (): Promise<boolean> => {
-    if (!editingPersonLink.value?.id) {
-      debugLog('Cannot update person without ID')
-      return false
-    }
-
-    if (!personForm.value.name.trim()) {
-      debugLog('Person name is required')
-      return false
-    }
-
+  const linkExistingPerson = async (match: PhonePersonMatch): Promise<boolean> => {
+    if (!currentCompanyId.value) return false
     isLoading.value = true
-
     try {
-      const trimmedPhone = personForm.value.phone?.trim()
-
-      const personData: PersonUpdateRequest = {
-        person_name: personForm.value.name.trim(),
-        is_primary: personForm.value.is_primary,
-        position: personForm.value.position?.trim() || null,
-        person_email: personForm.value.email?.trim() || null,
-        notes: personForm.value.notes?.trim() || null,
-        // Omit phone entirely when blank so the backend leaves person methods untouched
-        ...(trimmedPhone ? { phone: trimmedPhone } : {}),
+      const existingLink = match.company_links.find(
+        (link) => link.company_id === currentCompanyId.value,
+      )
+      if (!existingLink?.is_active) {
+        await api.people_company_links_update(
+          {
+            position: personForm.value.position?.trim() || null,
+            notes: personForm.value.notes?.trim() || null,
+            is_primary: personForm.value.is_primary || people.value.length === 0,
+          },
+          {
+            params: {
+              person_id: match.person_id,
+              company_id: currentCompanyId.value,
+            },
+          },
+        )
       }
 
-      debugLog('Updating person:', editingPersonLink.value.id, personData)
-
-      await api.companies_person_links_partial_update(personData, {
-        params: { id: editingPersonLink.value.id },
-      })
-
-      debugLog('Person updated successfully')
-
-      // Reload people to get updated list
       await loadPeople(currentCompanyId.value)
-
-      // If the updated person was selected, update the selection
-      if (selectedPerson.value?.id === editingPersonLink.value.id) {
-        const updated = people.value.find((c) => c.id === editingPersonLink.value!.id)
-        if (updated) {
-          selectedPerson.value = updated
-        }
-      }
-
-      cancelEdit()
+      const linked = people.value.find((person) => person.person_id === match.person_id)
+      if (!linked) throw new Error('Linked person was not returned for the company')
+      selectedPerson.value = linked
       closeModal()
       return true
     } catch (error) {
-      debugLog('Error updating person:', error)
+      debugLog('Error linking existing person:', error)
+      toast.error('Failed to link the existing person')
       return false
     } finally {
       isLoading.value = false
@@ -352,47 +316,16 @@ export function usePersonManagement() {
   }
 
   /**
-   * Soft deletes a person (sets is_active=false)
-   *
-   * @param personLinkId - The ID of the person to delete
-   * @returns Promise<boolean> - True if delete was successful, false otherwise
+   * Resets the new person form to its initial empty state
    */
-  const deletePerson = async (personLinkId: string): Promise<boolean> => {
-    if (!personLinkId) {
-      debugLog('Cannot delete person without ID')
-      return false
-    }
-
-    isLoading.value = true
-
-    try {
-      debugLog('Deleting person:', personLinkId)
-
-      await api.companies_person_links_destroy(undefined, {
-        params: { id: personLinkId },
-      })
-
-      debugLog('Person deleted successfully')
-
-      // Reload people to get updated list (inactive people filtered out)
-      await loadPeople(currentCompanyId.value)
-
-      // Clear selection if deleted person was selected
-      if (selectedPerson.value?.id === personLinkId) {
-        selectedPerson.value = null
-      }
-
-      // Clear editing state if we were editing the deleted person
-      if (editingPersonLink.value?.id === personLinkId) {
-        cancelEdit()
-      }
-
-      return true
-    } catch (error) {
-      debugLog('Error deleting person:', error)
-      return false
-    } finally {
-      isLoading.value = false
+  const resetPersonForm = () => {
+    personForm.value = {
+      name: '',
+      position: '',
+      email: '',
+      phone: '',
+      notes: '',
+      is_primary: people.value.length === 0,
     }
   }
 
@@ -433,16 +366,16 @@ export function usePersonManagement() {
    *
    * @param newPeople - Array of people to replace the current list
    */
-  const updatePersonsList = (newPeople: CompanyPersonLink[]) => {
+  const updatePersonsList = (newPeople: CompanyPerson[]) => {
     people.value = newPeople
   }
 
   /**
    * Finds the primary person from the current people list
    *
-   * @returns CompanyPersonLink | null - The primary person if found, null otherwise
+   * @returns CompanyPerson | null - The primary person if found, null otherwise
    */
-  const findPrimaryPerson = (): CompanyPersonLink | null => {
+  const findPrimaryPerson = (): CompanyPerson | null => {
     if (people.value.length === 0) {
       return null
     }
@@ -457,11 +390,10 @@ export function usePersonManagement() {
     isLoading,
     currentCompanyName,
     personForm,
+    phoneOwnership,
 
     // Edit mode state
-    editingPersonLink,
-    isEditing,
-    activePersonLinks,
+    activePeople,
 
     hasPeople,
     displayValue,
@@ -473,16 +405,11 @@ export function usePersonManagement() {
     setSelectedPerson,
     selectExistingPerson,
     createNewPerson,
+    linkExistingPerson,
     savePerson,
     clearSelection,
     updatePersonsList,
     findPrimaryPerson,
     resetPersonForm,
-
-    // Edit/delete functions
-    startEditPerson,
-    cancelEdit,
-    updatePerson,
-    deletePerson,
   }
 }
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index 13142a8ab..b528d5aae 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -122,7 +122,11 @@
               :disabled="!selectedCompanyId"
             >
               <option value="">No specific person</option>
-              <option v-for="person in personOptions" :key="person.id" :value="person.person">
+              <option
+                v-for="person in personOptions"
+                :key="person.person_id"
+                :value="person.person_id"
+              >
                 {{ person.person_name }}
               </option>
             </select>
@@ -211,7 +215,7 @@ const {
   suggestions: companyOptions,
   people: personOptions,
   browseCompanies: searchCompanies,
-  loadCompanyPersonLinks,
+  loadCompanyPeople,
   logSelectedCompanyClick,
 } = useCompanyLookup()
 
@@ -348,7 +352,7 @@ watch(selectedCompanyId, (companyId) => {
   if (!companyId) {
     selectedPersonId.value = ''
   }
-  void loadCompanyPersonLinks(companyId)
+  void loadCompanyPeople(companyId)
 })
 
 onMounted(() => {
diff --git a/frontend/src/pages/crm/companies/(index).vue b/frontend/src/pages/crm/companies/(index).vue
index febd9e46d..38ea3b71c 100644
--- a/frontend/src/pages/crm/companies/(index).vue
+++ b/frontend/src/pages/crm/companies/(index).vue
@@ -252,7 +252,7 @@ watch(currentPage, async (newPage) => {
 })
 
 function navigateToCompany(company: Company, rank: number) {
-  logCompanySearchClick(company, companyStore.searchQuery, rank, 'crm_clients_table')
+  logCompanySearchClick(company, companyStore.searchQuery, rank, 'crm_companies_table')
   router.push({ name: '/crm/companies/[id]', params: { id: company.id } })
 }
 
diff --git a/frontend/src/pages/crm/companies/[id].vue b/frontend/src/pages/crm/companies/[id].vue
index 88a2f7365..df4b91aad 100644
--- a/frontend/src/pages/crm/companies/[id].vue
+++ b/frontend/src/pages/crm/companies/[id].vue
@@ -161,9 +161,21 @@
           <!-- People -->
           <Card>
             <CardHeader>
-              <CardTitle>People</CardTitle>
+              <div class="flex items-center justify-between gap-3">
+                <CardTitle>People</CardTitle>
+                <span class="text-sm text-gray-500">{{ people.length }} linked</span>
+              </div>
             </CardHeader>
-            <CardContent>
+            <CardContent class="space-y-4">
+              <PersonSelector
+                id="company-person"
+                label="Add or link person"
+                :optional="true"
+                :company-id="props.id"
+                :company-name="company.name"
+                placeholder="Select, create, or link a person"
+                @update:selected-person="onCompanyPersonSelected"
+              />
               <div
                 v-if="companyStore.isLoadingPeople"
                 class="flex items-center justify-center py-8"
@@ -177,7 +189,7 @@
               <div v-else class="space-y-3">
                 <div
                   v-for="person in people"
-                  :key="person.id"
+                  :key="person.person_id"
                   class="flex items-start gap-3 p-3 border border-gray-200 rounded-lg"
                 >
                   <UserCircle class="w-5 h-5 text-gray-400 mt-0.5" />
@@ -193,9 +205,18 @@
                     </p>
                     <div class="flex flex-col gap-1 mt-1 text-sm text-gray-600">
                       <span v-if="person.person_email">{{ person.person_email }}</span>
-                      <span v-if="person.phone">{{ person.phone }}</span>
+                      <span v-if="person.primary_phone">{{ person.primary_phone }}</span>
                     </div>
                   </div>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    :data-automation-id="`CompanyDetail-manage-person-${person.person_id}`"
+                    @click="navigateToPerson(person.person_id)"
+                  >
+                    Manage
+                  </Button>
                 </div>
               </div>
             </CardContent>
@@ -205,7 +226,7 @@
             title="Phone Numbers"
             :fixed-company-id="props.id"
             :fixed-company-name="company.name"
-            search-context="crm_client_detail_phone_numbers"
+            search-context="crm_company_detail_phone_numbers"
             @changed="loadPhoneCalls"
           />
 
@@ -406,6 +427,7 @@ import { useCompanyStore } from '@/stores/companyStore'
 import AppLayout from '@/components/AppLayout.vue'
 import PhoneCallTable from '@/components/crm/PhoneCallTable.vue'
 import PhoneNumberManager from '@/components/crm/PhoneNumberManager.vue'
+import PersonSelector from '@/components/PersonSelector.vue'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Badge } from '@/components/ui/badge'
@@ -616,7 +638,7 @@ async function loadCompanyData() {
 
     // Load people
     try {
-      await companyStore.fetchCompanyPersonLinks(props.id)
+      await companyStore.fetchCompanyPeople(props.id)
     } catch (err) {
       console.error('Failed to load people:', err)
       // Don't show error for people, just log it
@@ -651,6 +673,15 @@ function navigateToJob(jobId: string) {
   router.push({ name: '/jobs/[id]/(index)', params: { id: jobId } })
 }
 
+async function onCompanyPersonSelected(person: z.infer<typeof schemas.CompanyPerson> | null) {
+  if (!person) return
+  await companyStore.fetchCompanyPeople(props.id)
+}
+
+function navigateToPerson(personId: string) {
+  router.push({ name: '/crm/people/[id]', params: { id: personId } })
+}
+
 // Lifecycle
 onMounted(() => {
   loadCompanyData()
diff --git a/frontend/src/pages/crm/people/(index).vue b/frontend/src/pages/crm/people/(index).vue
new file mode 100644
index 000000000..b857077ae
--- /dev/null
+++ b/frontend/src/pages/crm/people/(index).vue
@@ -0,0 +1,224 @@
+<template>
+  <AppLayout>
+    <main class="mx-auto w-full max-w-7xl space-y-6 p-4 md:p-8">
+      <header class="flex flex-col gap-4 sm:flex-row sm:items-center sm:justify-between">
+        <div>
+          <h1 class="flex items-center gap-3 text-3xl font-bold text-gray-900">
+            <Users class="h-8 w-8 text-indigo-600" /> People
+          </h1>
+          <p class="mt-1 text-sm text-gray-600">
+            One identity per person, linked to every company they work with.
+          </p>
+        </div>
+        <Button
+          type="button"
+          data-automation-id="PeopleDirectory-create"
+          @click="showCreate = !showCreate"
+        >
+          <UserPlus class="mr-2 h-4 w-4" /> Create or link person
+        </Button>
+      </header>
+
+      <Card v-if="showCreate" data-automation-id="PeopleDirectory-create-panel">
+        <CardHeader>
+          <CardTitle>Create or link a person</CardTitle>
+          <p class="text-sm text-gray-600">
+            Choose the company first. Every new person requires a company link.
+          </p>
+        </CardHeader>
+        <CardContent class="grid gap-4 lg:grid-cols-2">
+          <CompanyLookup
+            id="people-company"
+            v-model="selectedCompanyName"
+            label="Company"
+            :required="true"
+            :search-mode="true"
+            @update:selected-company="selectedCompany = $event"
+          />
+          <PersonSelector
+            id="directory-person"
+            label="Person"
+            :optional="true"
+            :company-id="selectedCompany?.id ?? ''"
+            :company-name="selectedCompany?.name ?? ''"
+            placeholder="Choose a company first"
+            @update:selected-person="personAdded"
+          />
+        </CardContent>
+      </Card>
+
+      <Card>
+        <CardContent class="pt-6">
+          <div class="flex flex-col gap-3 sm:flex-row">
+            <Input
+              v-model="searchInput"
+              placeholder="Search name, email, phone, or company"
+              data-automation-id="PeopleDirectory-search"
+              @keydown.enter.prevent="applySearch"
+            />
+            <Button type="button" variant="outline" @click="applySearch">
+              <Search class="mr-2 h-4 w-4" /> Search
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+
+      <div v-if="loading" class="flex min-h-64 items-center justify-center text-gray-500">
+        <Loader2 class="mr-2 h-6 w-6 animate-spin" /> Loading people…
+      </div>
+      <div v-else-if="error" class="rounded-lg border border-red-200 bg-red-50 p-6 text-red-800">
+        {{ error }}
+      </div>
+      <Card v-else>
+        <CardContent class="p-0">
+          <div class="overflow-x-auto">
+            <table class="w-full text-sm">
+              <thead class="border-b bg-slate-50 text-left text-gray-600">
+                <tr>
+                  <th class="p-4 font-semibold">Person</th>
+                  <th class="p-4 font-semibold">Phone</th>
+                  <th class="p-4 font-semibold">Companies</th>
+                  <th class="p-4 text-right font-semibold">Action</th>
+                </tr>
+              </thead>
+              <tbody>
+                <tr v-if="people.length === 0">
+                  <td colspan="4" class="p-8 text-center text-gray-500">No people found</td>
+                </tr>
+                <tr
+                  v-for="person in people"
+                  :key="person.id"
+                  class="border-b last:border-b-0 hover:bg-slate-50"
+                  :data-automation-id="`PeopleDirectory-row-${person.id}`"
+                >
+                  <td class="p-4">
+                    <p class="font-medium text-gray-900">{{ person.name }}</p>
+                    <p class="text-gray-500">{{ person.email || 'No email' }}</p>
+                  </td>
+                  <td class="p-4 text-gray-700">{{ person.primary_phone || '—' }}</td>
+                  <td class="p-4 text-gray-700">
+                    {{ person.companies.map((company) => company.company_name).join(', ') || '—' }}
+                  </td>
+                  <td class="p-4 text-right">
+                    <Button
+                      type="button"
+                      variant="outline"
+                      size="sm"
+                      :data-automation-id="`PeopleDirectory-open-${person.id}`"
+                      @click="openPerson(person.id)"
+                    >
+                      Manage
+                    </Button>
+                  </td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+          <div class="flex items-center justify-between border-t p-4">
+            <p class="text-sm text-gray-600">{{ count }} people</p>
+            <div class="flex items-center gap-2">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                :disabled="page <= 1"
+                @click="goToPage(page - 1)"
+              >
+                Previous
+              </Button>
+              <span class="text-sm text-gray-600">Page {{ page }} of {{ totalPages || 1 }}</span>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                :disabled="page >= totalPages"
+                @click="goToPage(page + 1)"
+              >
+                Next
+              </Button>
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+    </main>
+  </AppLayout>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { useRouter } from 'vue-router'
+import type { z } from 'zod'
+import { Loader2, Search, UserPlus, Users } from 'lucide-vue-next'
+import { toast } from 'vue-sonner'
+
+import { api } from '@/api/client'
+import { schemas } from '@/api/generated/api'
+import AppLayout from '@/components/AppLayout.vue'
+import CompanyLookup from '@/components/CompanyLookup.vue'
+import PersonSelector from '@/components/PersonSelector.vue'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Input } from '@/components/ui/input'
+
+type PersonSummary = z.infer<typeof schemas.PersonSummary>
+type Company = z.infer<typeof schemas.CompanySearchResult>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
+
+const router = useRouter()
+const people = ref<PersonSummary[]>([])
+const loading = ref(false)
+const error = ref<string | null>(null)
+const page = ref(1)
+const totalPages = ref(0)
+const count = ref(0)
+const query = ref('')
+const searchInput = ref('')
+const showCreate = ref(false)
+const selectedCompany = ref<Company | null>(null)
+const selectedCompanyName = ref('')
+
+async function loadPeople(): Promise<void> {
+  loading.value = true
+  error.value = null
+  try {
+    const response = await api.people_list({
+      queries: { page: page.value, page_size: 50, q: query.value || undefined },
+    })
+    people.value = response.results
+    count.value = response.count
+    totalPages.value = response.total_pages
+    page.value = response.page
+  } catch (err) {
+    people.value = []
+    error.value = err instanceof Error ? err.message : 'Failed to load people'
+    toast.error('Failed to load people')
+  } finally {
+    loading.value = false
+  }
+}
+
+function applySearch(): void {
+  query.value = searchInput.value.trim()
+  page.value = 1
+  void loadPeople()
+}
+
+function goToPage(nextPage: number): void {
+  page.value = nextPage
+  void loadPeople()
+}
+
+function openPerson(personId: string): void {
+  router.push({ name: '/crm/people/[id]', params: { id: personId } })
+}
+
+function personAdded(person: CompanyPerson | null): void {
+  if (!person) return
+  showCreate.value = false
+  selectedCompany.value = null
+  selectedCompanyName.value = ''
+  void loadPeople()
+}
+
+onMounted(loadPeople)
+</script>
diff --git a/frontend/src/pages/crm/people/[id].vue b/frontend/src/pages/crm/people/[id].vue
new file mode 100644
index 000000000..912c88884
--- /dev/null
+++ b/frontend/src/pages/crm/people/[id].vue
@@ -0,0 +1,436 @@
+<template>
+  <AppLayout>
+    <main class="mx-auto w-full max-w-6xl space-y-6 p-4 md:p-8">
+      <header class="flex items-center gap-4">
+        <Button type="button" variant="outline" size="sm" @click="router.push('/crm/people')">
+          <ArrowLeft class="mr-2 h-4 w-4" /> People
+        </Button>
+        <div>
+          <h1 class="text-3xl font-bold text-gray-900">{{ person?.name || 'Person' }}</h1>
+          <p class="text-sm text-gray-600">
+            Manage identity, contact methods, and company relationships.
+          </p>
+        </div>
+      </header>
+
+      <div v-if="loading" class="flex min-h-64 items-center justify-center text-gray-500">
+        <Loader2 class="mr-2 h-6 w-6 animate-spin" /> Loading person…
+      </div>
+      <div v-else-if="error" class="rounded-lg border border-red-200 bg-red-50 p-6 text-red-800">
+        {{ error }}
+      </div>
+
+      <template v-else-if="person">
+        <Card>
+          <CardHeader><CardTitle>Identity</CardTitle></CardHeader>
+          <CardContent class="grid gap-4 md:grid-cols-2">
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">Name</label>
+              <Input v-model="identityName" data-automation-id="PersonDetail-name" />
+            </div>
+            <div>
+              <label class="mb-1 block text-sm font-medium text-gray-700">Email</label>
+              <Input v-model="identityEmail" type="email" data-automation-id="PersonDetail-email" />
+            </div>
+            <div class="md:col-span-2">
+              <Button
+                type="button"
+                :disabled="savingIdentity || !identityName.trim()"
+                data-automation-id="PersonDetail-save-identity"
+                @click="saveIdentity"
+              >
+                Save identity
+              </Button>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader><CardTitle>Contact methods</CardTitle></CardHeader>
+          <CardContent class="space-y-4">
+            <div class="grid gap-3 md:grid-cols-[10rem_1fr_1fr_auto_auto]">
+              <select
+                v-model="methodType"
+                class="rounded-md border border-gray-300 px-3 py-2 text-sm"
+              >
+                <option value="phone">Phone</option>
+                <option value="email">Email</option>
+              </select>
+              <Input
+                v-model="methodValue"
+                placeholder="Phone or email"
+                data-automation-id="PersonDetail-method-value"
+              />
+              <Input v-model="methodLabel" placeholder="Label" />
+              <label class="flex items-center gap-2 rounded-md border px-3 py-2 text-sm">
+                <input v-model="methodPrimary" type="checkbox" /> Primary
+              </label>
+              <div class="flex gap-2">
+                <Button
+                  type="button"
+                  :disabled="savingMethod || !methodValue.trim()"
+                  data-automation-id="PersonDetail-save-method"
+                  @click="saveMethod"
+                >
+                  {{ editingMethodId ? 'Update' : 'Add' }}
+                </Button>
+                <Button
+                  v-if="editingMethodId"
+                  type="button"
+                  variant="outline"
+                  @click="resetMethodForm"
+                  >Cancel</Button
+                >
+              </div>
+            </div>
+            <div class="overflow-x-auto rounded-md border">
+              <table class="w-full text-sm">
+                <thead class="border-b bg-slate-50 text-left">
+                  <tr>
+                    <th class="p-3">Type</th>
+                    <th class="p-3">Value</th>
+                    <th class="p-3">Label</th>
+                    <th class="p-3">Primary</th>
+                    <th class="p-3 text-right">Actions</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr v-if="contactMethods.length === 0">
+                    <td colspan="5" class="p-6 text-center text-gray-500">No contact methods</td>
+                  </tr>
+                  <tr
+                    v-for="method in contactMethods"
+                    :key="method.id"
+                    class="border-b last:border-b-0"
+                  >
+                    <td class="p-3 capitalize">{{ method.method_type }}</td>
+                    <td class="p-3">{{ method.value }}</td>
+                    <td class="p-3">{{ method.label || '—' }}</td>
+                    <td class="p-3">{{ method.is_primary ? 'Yes' : '—' }}</td>
+                    <td class="p-3">
+                      <div class="flex justify-end gap-2">
+                        <Button type="button" variant="ghost" size="sm" @click="editMethod(method)"
+                          >Edit</Button
+                        ><Button
+                          type="button"
+                          variant="ghost"
+                          size="sm"
+                          class="text-red-700"
+                          @click="removeMethod(method.id)"
+                          >Remove</Button
+                        >
+                      </div>
+                    </td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Company links</CardTitle>
+            <p class="text-sm text-gray-600">
+              Active and inactive relationships are retained here.
+            </p>
+          </CardHeader>
+          <CardContent class="space-y-4">
+            <div class="grid gap-3 lg:grid-cols-[1fr_1fr_1fr_auto_auto]">
+              <CompanyLookup
+                id="person-link-company"
+                v-model="linkCompanyName"
+                label="Company"
+                :required="true"
+                :search-mode="true"
+                @update:selected-company="linkCompany = $event"
+              />
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">Position</label
+                ><Input v-model="linkPosition" />
+              </div>
+              <div>
+                <label class="mb-1 block text-sm font-medium text-gray-700">Notes</label
+                ><Input v-model="linkNotes" />
+              </div>
+              <label class="mt-6 flex items-center gap-2 rounded-md border px-3 py-2 text-sm"
+                ><input v-model="linkPrimary" type="checkbox" /> Primary</label
+              >
+              <Button
+                type="button"
+                class="mt-6"
+                :disabled="!editingCompanyId && !linkCompany"
+                data-automation-id="PersonDetail-save-link"
+                @click="saveLink"
+                >{{ editingCompanyId ? 'Update' : 'Add link' }}</Button
+              >
+              <Button
+                v-if="editingCompanyId"
+                type="button"
+                class="mt-6"
+                variant="outline"
+                @click="resetLinkForm"
+              >
+                Cancel
+              </Button>
+            </div>
+            <div class="space-y-3">
+              <div
+                v-for="link in companyLinks"
+                :key="link.company_id"
+                class="flex flex-col gap-3 rounded-lg border p-4 sm:flex-row sm:items-center sm:justify-between"
+                :class="
+                  link.is_active ? 'border-gray-200' : 'border-gray-300 bg-gray-50 opacity-75'
+                "
+                :data-automation-id="`PersonDetail-company-link-${link.company_id}`"
+              >
+                <div>
+                  <div class="flex items-center gap-2">
+                    <p class="font-medium text-gray-900">{{ link.company_name }}</p>
+                    <Badge :variant="link.is_active ? 'default' : 'secondary'">{{
+                      link.is_active ? 'Active' : 'Inactive'
+                    }}</Badge
+                    ><Badge v-if="link.is_primary" variant="outline">Primary</Badge>
+                  </div>
+                  <p class="text-sm text-gray-600">
+                    {{ link.position || 'No position'
+                    }}<span v-if="link.notes"> · {{ link.notes }}</span>
+                  </p>
+                </div>
+                <div class="flex gap-2">
+                  <Button type="button" variant="outline" size="sm" @click="editLink(link)"
+                    >Edit</Button
+                  ><Button
+                    v-if="link.is_active"
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    class="text-red-700"
+                    :data-automation-id="`PersonDetail-remove-link-${link.company_id}`"
+                    @click="removeLink(link.company_id)"
+                    >Remove</Button
+                  ><Button
+                    v-else
+                    type="button"
+                    size="sm"
+                    :data-automation-id="`PersonDetail-restore-link-${link.company_id}`"
+                    @click="restoreLink(link)"
+                    >Restore</Button
+                  ><Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    @click="openCompany(link.company_id)"
+                    >Company</Button
+                  >
+                </div>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </template>
+    </main>
+  </AppLayout>
+</template>
+
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import { useRouter } from 'vue-router'
+import type { z } from 'zod'
+import { ArrowLeft, Loader2 } from 'lucide-vue-next'
+import { toast } from 'vue-sonner'
+
+import { api } from '@/api/client'
+import { schemas } from '@/api/generated/api'
+import AppLayout from '@/components/AppLayout.vue'
+import CompanyLookup from '@/components/CompanyLookup.vue'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import { Input } from '@/components/ui/input'
+import { extractErrorMessage } from '@/utils/error-handler'
+
+const props = defineProps<{ id: string }>()
+type PersonDetail = z.infer<typeof schemas.PersonDetail>
+type ContactMethod = z.infer<typeof schemas.ContactMethod>
+type PersonCompanyLink = z.infer<typeof schemas.PersonCompanyLink>
+type Company = z.infer<typeof schemas.CompanySearchResult>
+type MethodType = z.infer<typeof schemas.ContactMethodTypeEnum>
+
+const router = useRouter()
+const person = ref<PersonDetail | null>(null)
+const contactMethods = ref<ContactMethod[]>([])
+const companyLinks = ref<PersonCompanyLink[]>([])
+const loading = ref(false)
+const error = ref<string | null>(null)
+const savingIdentity = ref(false)
+const identityName = ref('')
+const identityEmail = ref('')
+const savingMethod = ref(false)
+const editingMethodId = ref('')
+const methodType = ref<MethodType>('phone')
+const methodValue = ref('')
+const methodLabel = ref('')
+const methodPrimary = ref(false)
+const editingCompanyId = ref('')
+const linkCompany = ref<Company | null>(null)
+const linkCompanyName = ref('')
+const linkPosition = ref('')
+const linkNotes = ref('')
+const linkPrimary = ref(false)
+
+async function loadPerson(): Promise<void> {
+  loading.value = true
+  error.value = null
+  try {
+    const [detail, methods, links] = await Promise.all([
+      api.people_retrieve({ params: { person_id: props.id } }),
+      api.people_contact_methods_list({ params: { person_id: props.id } }),
+      api.people_company_links_list({ params: { person_id: props.id } }),
+    ])
+    person.value = detail
+    contactMethods.value = methods
+    companyLinks.value = links
+    identityName.value = detail.name
+    identityEmail.value = detail.email || ''
+  } catch (err) {
+    error.value = err instanceof Error ? err.message : 'Failed to load person'
+    toast.error('Failed to load person')
+  } finally {
+    loading.value = false
+  }
+}
+
+async function saveIdentity(): Promise<void> {
+  savingIdentity.value = true
+  try {
+    await api.people_partial_update(
+      { name: identityName.value.trim(), email: identityEmail.value.trim() || null },
+      { params: { person_id: props.id } },
+    )
+    toast.success('Identity updated')
+    await loadPerson()
+  } catch {
+    toast.error('Failed to update identity')
+  } finally {
+    savingIdentity.value = false
+  }
+}
+
+async function saveMethod(): Promise<void> {
+  savingMethod.value = true
+  const body = {
+    method_type: methodType.value,
+    value: methodValue.value.trim(),
+    label: methodLabel.value.trim(),
+    is_primary: methodPrimary.value,
+  }
+  try {
+    if (editingMethodId.value)
+      await api.people_contact_methods_partial_update(body, {
+        params: { person_id: props.id, method_id: editingMethodId.value },
+      })
+    else await api.people_contact_methods_create(body, { params: { person_id: props.id } })
+    toast.success('Contact method saved')
+    resetMethodForm()
+    contactMethods.value = await api.people_contact_methods_list({
+      params: { person_id: props.id },
+    })
+  } catch (err) {
+    toast.error(err instanceof Error ? err.message : 'Failed to save contact method')
+  } finally {
+    savingMethod.value = false
+  }
+}
+
+function editMethod(method: ContactMethod): void {
+  editingMethodId.value = method.id
+  methodType.value = method.method_type
+  methodValue.value = method.value
+  methodLabel.value = method.label || ''
+  methodPrimary.value = Boolean(method.is_primary)
+}
+function resetMethodForm(): void {
+  editingMethodId.value = ''
+  methodType.value = 'phone'
+  methodValue.value = ''
+  methodLabel.value = ''
+  methodPrimary.value = false
+}
+async function removeMethod(methodId: string): Promise<void> {
+  if (!window.confirm('Remove this contact method?')) return
+  try {
+    await api.people_contact_methods_destroy(undefined, {
+      params: { person_id: props.id, method_id: methodId },
+    })
+    contactMethods.value = contactMethods.value.filter((method) => method.id !== methodId)
+    toast.success('Contact method removed')
+  } catch (err) {
+    toast.error(`Contact method not removed: ${extractErrorMessage(err)}`)
+  }
+}
+
+async function saveLink(): Promise<void> {
+  const companyId = editingCompanyId.value || linkCompany.value?.id
+  if (!companyId) return
+  try {
+    await api.people_company_links_update(
+      {
+        position: linkPosition.value.trim() || null,
+        notes: linkNotes.value.trim() || null,
+        is_primary: linkPrimary.value,
+      },
+      { params: { person_id: props.id, company_id: companyId } },
+    )
+    toast.success(editingCompanyId.value ? 'Company link updated' : 'Company linked')
+    resetLinkForm()
+    companyLinks.value = await api.people_company_links_list({ params: { person_id: props.id } })
+  } catch (err) {
+    toast.error(`Company link not saved: ${extractErrorMessage(err)}`)
+  }
+}
+function editLink(link: PersonCompanyLink): void {
+  editingCompanyId.value = link.company_id
+  linkCompanyName.value = link.company_name
+  linkPosition.value = link.position || ''
+  linkNotes.value = link.notes || ''
+  linkPrimary.value = link.is_primary
+}
+function resetLinkForm(): void {
+  editingCompanyId.value = ''
+  linkCompany.value = null
+  linkCompanyName.value = ''
+  linkPosition.value = ''
+  linkNotes.value = ''
+  linkPrimary.value = false
+}
+async function removeLink(companyId: string): Promise<void> {
+  if (!window.confirm('Remove this company link?')) return
+  try {
+    await api.people_company_links_destroy(undefined, {
+      params: { person_id: props.id, company_id: companyId },
+    })
+    companyLinks.value = await api.people_company_links_list({ params: { person_id: props.id } })
+    toast.success('Company link removed')
+  } catch (err) {
+    toast.error(`Company link not removed: ${extractErrorMessage(err)}`)
+  }
+}
+async function restoreLink(link: PersonCompanyLink): Promise<void> {
+  try {
+    await api.people_company_links_update(
+      { position: link.position, notes: link.notes, is_primary: link.is_primary },
+      { params: { person_id: props.id, company_id: link.company_id } },
+    )
+    companyLinks.value = await api.people_company_links_list({ params: { person_id: props.id } })
+    toast.success('Company link restored')
+  } catch (err) {
+    toast.error(`Company link not restored: ${extractErrorMessage(err)}`)
+  }
+}
+function openCompany(companyId: string): void {
+  router.push({ name: '/crm/companies/[id]', params: { id: companyId } })
+}
+
+onMounted(loadPerson)
+</script>
diff --git a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
new file mode 100644
index 000000000..e8560c7df
--- /dev/null
+++ b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
@@ -0,0 +1,62 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/api/client', () => ({ api: { people_list: vi.fn() } }))
+vi.mock('@/components/AppLayout.vue', () => ({ default: { template: '<div><slot /></div>' } }))
+vi.mock('@/components/CompanyLookup.vue', () => ({ default: { template: '<div />' } }))
+vi.mock('@/components/PersonSelector.vue', () => ({ default: { template: '<div />' } }))
+vi.mock('vue-sonner', () => ({ toast: { error: vi.fn() } }))
+
+import { api } from '@/api/client'
+import PeopleDirectory from '@/pages/crm/people/(index).vue'
+
+const response = {
+  results: [
+    {
+      id: '11111111-1111-4111-8111-111111111111',
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      primary_phone: '021 555 0100',
+      companies: [
+        {
+          company_id: '22222222-2222-4222-8222-222222222222',
+          company_name: 'Acme Limited',
+        },
+      ],
+    },
+  ],
+  count: 1,
+  page: 1,
+  page_size: 50,
+  total_pages: 1,
+}
+
+describe('people directory', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(api.people_list).mockResolvedValue(response)
+  })
+
+  it('renders person identities with their companies', async () => {
+    const wrapper = mount(PeopleDirectory)
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Jane Doe')
+    expect(wrapper.text()).toContain('Acme Limited')
+    expect(api.people_list).toHaveBeenCalledWith({
+      queries: { page: 1, page_size: 50, q: undefined },
+    })
+  })
+
+  it('sends search to the paginated people endpoint', async () => {
+    const wrapper = mount(PeopleDirectory)
+    await flushPromises()
+    await wrapper.find('[data-automation-id="PeopleDirectory-search"]').setValue('Jane')
+    await wrapper.find('[data-automation-id="PeopleDirectory-search"]').trigger('keydown.enter')
+    await flushPromises()
+
+    expect(api.people_list).toHaveBeenLastCalledWith({
+      queries: { page: 1, page_size: 50, q: 'Jane' },
+    })
+  })
+})
diff --git a/frontend/src/pages/crm/people/__tests__/person-detail.test.ts b/frontend/src/pages/crm/people/__tests__/person-detail.test.ts
new file mode 100644
index 000000000..59aecc894
--- /dev/null
+++ b/frontend/src/pages/crm/people/__tests__/person-detail.test.ts
@@ -0,0 +1,121 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('@/api/client', () => ({
+  api: {
+    people_retrieve: vi.fn(),
+    people_partial_update: vi.fn(),
+    people_contact_methods_list: vi.fn(),
+    people_contact_methods_create: vi.fn(),
+    people_contact_methods_partial_update: vi.fn(),
+    people_contact_methods_destroy: vi.fn(),
+    people_company_links_list: vi.fn(),
+    people_company_links_update: vi.fn(),
+    people_company_links_destroy: vi.fn(),
+  },
+}))
+vi.mock('@/components/AppLayout.vue', () => ({ default: { template: '<div><slot /></div>' } }))
+vi.mock('@/components/CompanyLookup.vue', () => ({ default: { template: '<div />' } }))
+vi.mock('vue-sonner', () => ({
+  toast: { error: vi.fn(), success: vi.fn() },
+}))
+
+import { api } from '@/api/client'
+import PersonDetailPage from '@/pages/crm/people/[id].vue'
+import { toast } from 'vue-sonner'
+
+const personId = '11111111-1111-4111-8111-111111111111'
+const companyId = '22222222-2222-4222-8222-222222222222'
+const person = {
+  id: personId,
+  name: 'Jane Doe',
+  email: 'jane@example.com',
+  is_active: true,
+  created_at: '2026-01-01T00:00:00Z',
+  updated_at: '2026-01-01T00:00:00Z',
+  primary_phone: '021 555 0100',
+  companies: [{ company_id: companyId, company_name: 'Acme Limited' }],
+  company_links: [],
+}
+const inactiveLink = {
+  company_id: companyId,
+  company_name: 'Acme Limited',
+  position: 'Buyer',
+  notes: null,
+  is_primary: true,
+  is_active: false,
+}
+
+describe('person detail', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.mocked(api.people_retrieve).mockResolvedValue(person)
+    vi.mocked(api.people_contact_methods_list).mockResolvedValue([])
+    vi.mocked(api.people_company_links_list).mockResolvedValue([inactiveLink])
+    vi.mocked(api.people_company_links_update).mockResolvedValue({
+      ...inactiveLink,
+      is_active: true,
+    })
+  })
+
+  it('shows inactive company links and restores them', async () => {
+    const wrapper = mount(PersonDetailPage, { props: { id: personId } })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Inactive')
+    await wrapper
+      .find(`[data-automation-id="PersonDetail-restore-link-${companyId}"]`)
+      .trigger('click')
+    await flushPromises()
+
+    expect(api.people_company_links_update).toHaveBeenCalledWith(
+      { position: 'Buyer', notes: null, is_primary: true },
+      { params: { person_id: personId, company_id: companyId } },
+    )
+  })
+
+  it('updates identity without touching company-link fields', async () => {
+    const wrapper = mount(PersonDetailPage, { props: { id: personId } })
+    await flushPromises()
+    await wrapper.find('[data-automation-id="PersonDetail-name"]').setValue('Jane Smith')
+    await wrapper.find('[data-automation-id="PersonDetail-save-identity"]').trigger('click')
+    await flushPromises()
+
+    expect(api.people_partial_update).toHaveBeenCalledWith(
+      { name: 'Jane Smith', email: 'jane@example.com' },
+      { params: { person_id: personId } },
+    )
+  })
+
+  it('shows blocked-unlink validation and keeps the active link visible', async () => {
+    const activeLink = { ...inactiveLink, is_active: true }
+    vi.mocked(api.people_company_links_list).mockResolvedValue([activeLink])
+    vi.mocked(api.people_company_links_destroy).mockRejectedValue({
+      isAxiosError: true,
+      response: {
+        status: 400,
+        data: {
+          error: 'Removing this link would create a cross-company phone conflict.',
+        },
+      },
+    })
+    vi.stubGlobal(
+      'confirm',
+      vi.fn(() => true),
+    )
+    const wrapper = mount(PersonDetailPage, { props: { id: personId } })
+    await flushPromises()
+
+    await wrapper
+      .find(`[data-automation-id="PersonDetail-remove-link-${companyId}"]`)
+      .trigger('click')
+    await flushPromises()
+
+    expect(toast.error).toHaveBeenCalledWith(
+      'Company link not removed: Removing this link would create a cross-company phone conflict.',
+    )
+    expect(wrapper.text()).toContain('Active')
+    expect(wrapper.text()).not.toContain('Inactive')
+    expect(api.people_company_links_list).toHaveBeenCalledOnce()
+  })
+})
diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index 9d3b88766..bed7f4ad4 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -252,7 +252,7 @@ import { z } from 'zod'
 import { debugLog } from '@/utils/debug'
 
 type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
 import { toast } from 'vue-sonner'
 
 const personSelectorRef = ref<InstanceType<typeof PersonSelector> | null>(null)
@@ -311,7 +311,7 @@ const formData = ref<JobCreateData>({
 const companyDisplayName = ref('')
 
 const selectedCompany = ref<CompanySearchResult | null>(null)
-const selectedPerson = ref<CompanyPersonLink | null>(null)
+const selectedPerson = ref<CompanyPerson | null>(null)
 const personDisplayName = ref('')
 
 const errors = ref<Record<string, string>>({})
@@ -364,11 +364,11 @@ const handleCompanySelection = async (company: CompanySearchResult | null) => {
   }
 }
 
-const updateSelectedPerson = (personLink: CompanyPersonLink | null) => {
+const updateSelectedPerson = (personLink: CompanyPerson | null) => {
   selectedPerson.value = personLink
   if (personLink) {
     // Save the person ID for the API and display name for the UI
-    formData.value.person_id = personLink.person
+    formData.value.person_id = personLink.person_id
     personDisplayName.value = personLink.person_name
   } else {
     formData.value.person_id = null
diff --git a/frontend/src/pages/purchasing/po/[id].vue b/frontend/src/pages/purchasing/po/[id].vue
index 078f721a6..dbd7fa0dd 100644
--- a/frontend/src/pages/purchasing/po/[id].vue
+++ b/frontend/src/pages/purchasing/po/[id].vue
@@ -166,7 +166,7 @@ type Job = z.infer<typeof schemas.JobForPurchasing>
 type AllocationItem = z.infer<typeof schemas.AllocationItem>
 type DeliveryAllocation = z.infer<typeof schemas.DeliveryReceiptAllocationRequest>
 type PurchaseOrderEmailResponse = z.infer<typeof schemas.PurchaseOrderEmailResponse>
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
 type PurchaseOrderEmailResponseWithLegacy = PurchaseOrderEmailResponse & { email?: string }
 type PurchaseOrderStatus = z.infer<typeof schemas.PurchaseOrderDetailStatusEnum>
 
@@ -811,11 +811,11 @@ async function resolveSupplierEmail(): Promise<string | null> {
   }
 
   try {
-    const people = await api.companies_person_links_list({
-      queries: { company_id: supplierId },
+    const people = await api.companies_people_list({
+      params: { company_id: supplierId },
     })
 
-    const peopleArray: CompanyPersonLink[] = Array.isArray(people) ? people : []
+    const peopleArray: CompanyPerson[] = Array.isArray(people) ? people : []
     const primaryPerson = peopleArray.find((person) => person.is_primary && !!person.person_email)
     const fallbackPerson = peopleArray.find((person) => !!person.person_email)
     const resolvedEmail = primaryPerson?.person_email ?? fallbackPerson?.person_email ?? null
diff --git a/frontend/src/stores/__tests__/companyStore.test.ts b/frontend/src/stores/__tests__/companyStore.test.ts
index eb45e2a3e..42bf6e70a 100644
--- a/frontend/src/stores/__tests__/companyStore.test.ts
+++ b/frontend/src/stores/__tests__/companyStore.test.ts
@@ -5,60 +5,55 @@ import { useCompanyStore } from '@/stores/companyStore'
 
 vi.mock('@/api/client', () => ({
   api: {
-    companies_person_links_list: vi.fn(),
+    companies_people_list: vi.fn(),
   },
 }))
 
 const mockedApi = vi.mocked(api)
 
-describe('company store people links', () => {
+describe('company store people', () => {
   beforeEach(() => {
     setActivePinia(createPinia())
     vi.clearAllMocks()
   })
 
-  it('fetchCompanyPersonLinks updates companyPeople as a side effect', async () => {
+  it('fetchCompanyPeople updates companyPeople as a side effect', async () => {
     const store = useCompanyStore()
     const previousCompanyPeople = store.companyPeople
     const people = [
       {
-        id: 'link-1',
-        company: 'company-1',
-        person: 'person-1',
+        person_id: 'person-1',
         person_name: 'Jane Doe',
         person_email: 'jane@example.com',
         position: null,
         is_primary: true,
         notes: null,
-        is_active: true,
-        created_at: '2026-01-01T00:00:00+00:00',
-        updated_at: '2026-01-01T00:00:00+00:00',
-        phone: '+64 21 555 0100',
+        primary_phone: '+64 21 555 0100',
       },
     ]
-    mockedApi.companies_person_links_list.mockResolvedValueOnce(people)
+    mockedApi.companies_people_list.mockResolvedValueOnce(people)
 
-    const result = await store.fetchCompanyPersonLinks('company-1')
+    const result = await store.fetchCompanyPeople('company-1')
 
     expect(result).toBeUndefined()
     expect(store.companyPeople).not.toBe(previousCompanyPeople)
     expect(store.companyPeople['company-1']).toEqual(people)
   })
 
-  it('getCompanyPersonLinks uses cached state and otherwise fetches as a side effect', async () => {
+  it('getCompanyPeople uses cached state and otherwise fetches as a side effect', async () => {
     const store = useCompanyStore()
-    mockedApi.companies_person_links_list.mockResolvedValueOnce([])
+    mockedApi.companies_people_list.mockResolvedValueOnce([])
 
-    const result = await store.getCompanyPersonLinks('company-1')
+    const result = await store.getCompanyPeople('company-1')
 
     expect(result).toBeUndefined()
-    expect(mockedApi.companies_person_links_list).toHaveBeenCalledWith({
-      queries: { company_id: 'company-1' },
+    expect(mockedApi.companies_people_list).toHaveBeenCalledWith({
+      params: { company_id: 'company-1' },
     })
     expect(store.companyPeople['company-1']).toEqual([])
 
-    await store.getCompanyPersonLinks('company-1')
+    await store.getCompanyPeople('company-1')
 
-    expect(mockedApi.companies_person_links_list).toHaveBeenCalledTimes(1)
+    expect(mockedApi.companies_people_list).toHaveBeenCalledTimes(1)
   })
 })
diff --git a/frontend/src/stores/companyStore.ts b/frontend/src/stores/companyStore.ts
index 747ae4ba9..f1c28b1da 100644
--- a/frontend/src/stores/companyStore.ts
+++ b/frontend/src/stores/companyStore.ts
@@ -8,7 +8,7 @@ import type { z } from 'zod'
 type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
 type CompanySearchResponse = z.infer<typeof schemas.CompanySearchResponse>
 type CompanyDetail = z.infer<typeof schemas.CompanyDetailResponse>
-type CompanyPersonLink = z.infer<typeof schemas.CompanyPersonLink>
+type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
 type CompanyJobsResponse = z.infer<typeof schemas.CompanyJobsResponse>
 
 // Type for company jobs - inferred from generated schema
@@ -35,7 +35,7 @@ export const useCompanyStore = defineStore('companies', () => {
 
   // State - company details and related data
   const detailedCompanies = ref<Record<string, CompanyDetail>>({})
-  const companyPeople = ref<Record<string, CompanyPersonLink[]>>({})
+  const companyPeople = ref<Record<string, CompanyPerson[]>>({})
   const companyJobs = ref<Record<string, CompanyJob[]>>({})
   const isLoading = ref(false)
   const isLoadingDetail = ref(false)
@@ -107,12 +107,12 @@ export const useCompanyStore = defineStore('companies', () => {
    * Fetch people for a specific company
    * @param companyId UUID of the company
    */
-  async function fetchCompanyPersonLinks(companyId: string): Promise<void> {
+  async function fetchCompanyPeople(companyId: string): Promise<void> {
     isLoadingPeople.value = true
 
     try {
-      const response = await api.companies_person_links_list({
-        queries: { company_id: companyId },
+      const response = await api.companies_people_list({
+        params: { company_id: companyId },
       })
       companyPeople.value = {
         ...companyPeople.value,
@@ -145,11 +145,11 @@ export const useCompanyStore = defineStore('companies', () => {
    * Get cached company people or fetch if not available
    * @param companyId UUID of the company
    */
-  async function getCompanyPersonLinks(companyId: string): Promise<void> {
+  async function getCompanyPeople(companyId: string): Promise<void> {
     if (companyPeople.value[companyId]) {
       return
     }
-    await fetchCompanyPersonLinks(companyId)
+    await fetchCompanyPeople(companyId)
   }
 
   /**
@@ -225,10 +225,10 @@ export const useCompanyStore = defineStore('companies', () => {
     // Actions
     fetchCompanies,
     fetchCompanyDetail,
-    fetchCompanyPersonLinks,
+    fetchCompanyPeople,
     fetchCompanyJobs,
     getCompanyDetail,
-    getCompanyPersonLinks,
+    getCompanyPeople,
     getCompanyJobs,
     clearCache,
   }
diff --git a/frontend/src/typed-router.d.ts b/frontend/src/typed-router.d.ts
index b4ee8c8fe..32e776607 100644
--- a/frontend/src/typed-router.d.ts
+++ b/frontend/src/typed-router.d.ts
@@ -59,6 +59,20 @@ declare module 'vue-router/auto-routes' {
       { id: ParamValue<false> },
       | never
     >,
+    '/crm/people/(index)': RouteRecordInfo<
+      '/crm/people/(index)',
+      '/crm/people',
+      Record<never, never>,
+      Record<never, never>,
+      | never
+    >,
+    '/crm/people/[id]': RouteRecordInfo<
+      '/crm/people/[id]',
+      '/crm/people/:id',
+      { id: ParamValue<true> },
+      { id: ParamValue<false> },
+      | never
+    >,
     '/jobs/[id]/(index)': RouteRecordInfo<
       '/jobs/[id]/(index)',
       '/jobs/:id',
@@ -334,6 +348,18 @@ declare module 'vue-router/auto-routes' {
       views:
         | never
     }
+    'src/pages/crm/people/(index).vue': {
+      routes:
+        | '/crm/people/(index)'
+      views:
+        | never
+    }
+    'src/pages/crm/people/[id].vue': {
+      routes:
+        | '/crm/people/[id]'
+      views:
+        | never
+    }
     'src/pages/jobs/[id]/(index).vue': {
       routes:
         | '/jobs/[id]/(index)'
diff --git a/frontend/tests/crm/people.spec.ts b/frontend/tests/crm/people.spec.ts
new file mode 100644
index 000000000..7d553ac56
--- /dev/null
+++ b/frontend/tests/crm/people.spec.ts
@@ -0,0 +1,100 @@
+import { expect, test } from '../fixtures/auth'
+import { autoId, waitForCompanyCreateResponse } from '../fixtures/helpers'
+
+async function createCompany(page: Parameters<typeof autoId>[0], companyName: string) {
+  const input = autoId(page, 'CompanyLookup-input')
+  await input.fill(companyName)
+  await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+  await waitForCompanyCreateResponse(page, async () => {
+    await input.press('Control+Enter')
+  })
+  await expect(input).toHaveValue(companyName)
+}
+
+async function createPersonForSelectedCompany(
+  page: Parameters<typeof autoId>[0],
+  name: string,
+  phone: string,
+) {
+  await autoId(page, 'PersonSelector-modal-button').click()
+  await autoId(page, 'PersonSelectionModal-container').waitFor()
+  await autoId(page, 'PersonSelectionModal-name-input').fill(name)
+  await autoId(page, 'PersonSelectionModal-phone-input').fill(phone)
+  await autoId(page, 'PersonSelectionModal-submit').click()
+  await autoId(page, 'PersonSelectionModal-container').waitFor({ state: 'hidden' })
+}
+
+test.describe('people directory and company links', () => {
+  test('creates a company-linked person and manages link lifecycle', async ({
+    authenticatedPage: page,
+  }) => {
+    const suffix = Math.floor(Math.random() * 1_000_000)
+    const companyName = `[TEST] People Company ${suffix}`
+    const personName = `[TEST] People Person ${suffix}`
+
+    await page.goto('/crm/people')
+    await autoId(page, 'PeopleDirectory-create').click()
+    await createCompany(page, companyName)
+    await createPersonForSelectedCompany(page, personName, `0217${String(suffix).padStart(6, '0')}`)
+
+    await autoId(page, 'PeopleDirectory-search').fill(personName)
+    await autoId(page, 'PeopleDirectory-search').press('Enter')
+    const row = page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({
+      hasText: personName,
+    })
+    await expect(row).toContainText(companyName)
+    await row.getByRole('button', { name: 'Manage' }).click()
+
+    const link = page.locator('[data-automation-id^="PersonDetail-company-link-"]').filter({
+      hasText: companyName,
+    })
+    await expect(link).toContainText('Active')
+    const linkAutomationId = await link.getAttribute('data-automation-id')
+    const companyId = linkAutomationId?.replace('PersonDetail-company-link-', '')
+    expect(companyId).toBeTruthy()
+
+    page.once('dialog', (dialog) => dialog.accept())
+    await autoId(page, `PersonDetail-remove-link-${companyId}`).click()
+    await expect(link).toContainText('Inactive')
+    await autoId(page, `PersonDetail-restore-link-${companyId}`).click()
+    await expect(link).toContainText('Active')
+  })
+
+  test('reuses a phone owner across companies instead of creating a duplicate', async ({
+    authenticatedPage: page,
+  }) => {
+    const suffix = Math.floor(Math.random() * 1_000_000)
+    const firstCompany = `[TEST] Phone Owner A ${suffix}`
+    const secondCompany = `[TEST] Phone Owner B ${suffix}`
+    const personName = `[TEST] Shared Person ${suffix}`
+    const phone = `0228${String(suffix).padStart(6, '0')}`
+
+    await page.goto('/crm/people')
+    await autoId(page, 'PeopleDirectory-create').click()
+    await createCompany(page, firstCompany)
+    await createPersonForSelectedCompany(page, personName, phone)
+
+    await autoId(page, 'PeopleDirectory-create').click()
+    await createCompany(page, secondCompany)
+    await autoId(page, 'PersonSelector-modal-button').click()
+    await autoId(page, 'PersonSelectionModal-name-input').fill(`${personName} duplicate`)
+    await autoId(page, 'PersonSelectionModal-phone-input').fill(phone)
+    await autoId(page, 'PersonSelectionModal-submit').click()
+
+    const conflict = autoId(page, 'PersonSelectionModal-phone-conflict')
+    await expect(conflict).toContainText(personName)
+    await page
+      .locator('[data-automation-id^="PersonSelectionModal-link-match-"]')
+      .filter({ hasText: 'Link to this company' })
+      .click()
+    await autoId(page, 'PersonSelectionModal-container').waitFor({ state: 'hidden' })
+
+    await autoId(page, 'PeopleDirectory-search').fill(personName)
+    await autoId(page, 'PeopleDirectory-search').press('Enter')
+    const row = page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({
+      hasText: personName,
+    })
+    await expect(row).toContainText(firstCompany)
+    await expect(row).toContainText(secondCompany)
+  })
+})
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index 19589b8de..e5bb1763c 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -1402,10 +1402,6 @@ apps/company/views/supplier_pickup_address_viewset.py:0: error: Missing type arg
 apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/company/views/supplier_pickup_address_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/company/views/contact_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
-apps/company/views/contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
-apps/company/views/contact_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]
-apps/company/views/contact_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/views/contact_method_viewset.py:0: error: Missing type arguments for generic type "ModelViewSet"  [type-arg]
 apps/company/views/contact_method_viewset.py:0: error: Function is missing a type annotation  [no-untyped-def]
 apps/company/views/contact_method_viewset.py:0: error: Function is missing a return type annotation  [no-untyped-def]

From 0d6e15095ab96c55e9bee083827f6e015907e47f Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 15:03:09 +1200
Subject: [PATCH 27/73] fix: address people management review findings

---
 apps/company/models.py                        |  5 ++-
 apps/company/services/person_service.py       | 42 ++++++++++++-------
 apps/company/tests/test_person_api.py         | 23 ++++++++++
 apps/company/views/person_views.py            | 12 +++++-
 frontend/src/components/PersonSelector.vue    |  2 +
 .../__tests__/usePersonManagement.test.ts     | 34 +++++++++++++++
 .../src/composables/usePersonManagement.ts    |  5 +++
 frontend/src/pages/crm/calls.vue              |  1 +
 8 files changed, 104 insertions(+), 20 deletions(-)

diff --git a/apps/company/models.py b/apps/company/models.py
index 96a85433b..887551080 100644
--- a/apps/company/models.py
+++ b/apps/company/models.py
@@ -388,8 +388,9 @@ def save(
         # If this link is being set as primary, ensure no other links
         # for this company are marked as primary
         if self.is_primary and self.is_active:
-            CompanyPersonLink.objects.filter(
-                company=self.company, is_primary=True, is_active=True
+            db = using or self._state.db or DEFAULT_DB_ALIAS
+            CompanyPersonLink.objects.using(db).filter(
+                company_id=self.company_id, is_primary=True, is_active=True
             ).exclude(id=self.id).update(is_primary=False)
         super().save(
             force_insert=force_insert,
diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index 7d46950d8..1420096d0 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -8,6 +8,7 @@
 from django.db.models import Prefetch, Q, QuerySet
 
 from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.workflow.services.error_persistence import persist_app_error
 
 
 class PersonCompanyLinkData(TypedDict):
@@ -230,16 +231,11 @@ def _schedule_person_phone_rematch(person: Person) -> None:
     transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
 
 
-def create_person_for_company(
-    *, company: Company, data: NewPersonData
+def _create_person_link(
+    *, company: Company, data: NewPersonData, raw_phone: str | None
 ) -> CompanyPersonLink:
-    raw_phone = data.get("phone")
-    if raw_phone:
-        ownership = classify_phone_ownership(company=company, raw_phone=raw_phone)
-        if not ownership["can_create_person"]:
-            raise PersonPhoneConflictError(ownership)
-
     with transaction.atomic():
+        Company.objects.select_for_update().only("id").get(pk=company.pk)
         person = Person.objects.create(
             name=data["name"].strip(),
             email=data.get("email"),
@@ -256,23 +252,37 @@ def create_person_for_company(
             is_primary=data.get("is_primary", False) or not has_active_people,
             is_active=True,
         )
-        if raw_phone:
+        if raw_phone is not None:
             from apps.company.serializers import set_primary_phone
 
-            try:
-                set_primary_phone(person, raw_phone)
-            except DjangoValidationError as exc:
-                ownership = classify_phone_ownership(
-                    company=company, raw_phone=raw_phone
-                )
-                raise PersonPhoneConflictError(ownership) from exc
+            set_primary_phone(person, raw_phone)
         return link
 
 
+def create_person_for_company(
+    *, company: Company, data: NewPersonData
+) -> CompanyPersonLink:
+    raw_phone = data.get("phone")
+    if not raw_phone:
+        return _create_person_link(company=company, data=data, raw_phone=None)
+
+    ownership = classify_phone_ownership(company=company, raw_phone=raw_phone)
+    if not ownership["can_create_person"]:
+        raise PersonPhoneConflictError(ownership)
+
+    try:
+        return _create_person_link(company=company, data=data, raw_phone=raw_phone)
+    except DjangoValidationError as exc:
+        persist_app_error(exc)
+        ownership = classify_phone_ownership(company=company, raw_phone=raw_phone)
+        raise PersonPhoneConflictError(ownership) from exc
+
+
 def put_company_link(
     *, person: Person, company: Company, data: CompanyLinkData
 ) -> CompanyPersonLink:
     with transaction.atomic():
+        Company.objects.select_for_update().only("id").get(pk=company.pk)
         existing = (
             CompanyPersonLink.objects.select_for_update()
             .filter(person=person, company=company)
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index 6b2052884..c61c84680 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -137,6 +137,29 @@ def test_contact_method_patch_cannot_change_its_owner(self) -> None:
         self.assertIsNone(method.company_id)
         self.assertEqual(method.label, "Mobile")
 
+    def test_changing_phone_to_email_rematches_the_old_phone(self) -> None:
+        """Changing method type must clear calls matched to the former phone."""
+        person = self._person(company=self.company_a)
+        method = ContactMethod.objects.create(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 222 3333",
+        )
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay") as rematch:
+            with self.captureOnCommitCallbacks(execute=True):
+                response = self.client.patch(
+                    f"/api/people/{person.id}/contact-methods/{method.id}/",
+                    {
+                        "method_type": ContactMethod.MethodType.EMAIL,
+                        "value": "jane@example.com",
+                    },
+                    format="json",
+                )
+
+        self.assertEqual(response.status_code, 200)
+        rematch.assert_called_once_with(["+64212223333"])
+
     def test_put_reactivates_existing_company_link_without_duplication(self) -> None:
         """Restoring employment must reuse the soft-deleted unique link row."""
         person = self._person()
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
index 68ae28514..3f5a197ae 100644
--- a/apps/company/views/person_views.py
+++ b/apps/company/views/person_views.py
@@ -265,10 +265,18 @@ def patch(self, request: Request, person_id: str, method_id: str) -> Response:
         )
         serializer.is_valid(raise_exception=True)
         old_normalized = method.normalized_value
+        old_method_type = method.method_type
         updated = serializer.save()
+        numbers: set[str] = set()
+        if old_method_type == ContactMethod.MethodType.PHONE:
+            numbers.add(old_normalized)
         if updated.method_type == ContactMethod.MethodType.PHONE:
-            numbers = sorted({old_normalized, updated.normalized_value})
-            transaction.on_commit(lambda: rematch_phone_calls_task.delay(numbers))
+            numbers.add(updated.normalized_value)
+        if numbers:
+            sorted_numbers = sorted(numbers)
+            transaction.on_commit(
+                lambda: rematch_phone_calls_task.delay(sorted_numbers)
+            )
         return Response(ContactMethodSerializer(updated).data)
 
     @extend_schema(responses={204: None})
diff --git a/frontend/src/components/PersonSelector.vue b/frontend/src/components/PersonSelector.vue
index d6e059948..461f9a044 100644
--- a/frontend/src/components/PersonSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -115,6 +115,7 @@ const {
   setSelectedPerson,
   selectExistingPerson: selectFromComposable,
   savePerson,
+  beginCreatePerson,
   createNewPerson,
   linkExistingPerson,
   clearSelection: clearFromComposable,
@@ -156,6 +157,7 @@ const selectExistingPerson = (person: CompanyPerson) => {
 }
 
 const handleSavePerson = async () => {
+  beginCreatePerson()
   debugLog('PersonSelector - handleSavePerson: before save', {
     personForm: personForm.value,
     selectedPerson: selectedPerson.value,
diff --git a/frontend/src/composables/__tests__/usePersonManagement.test.ts b/frontend/src/composables/__tests__/usePersonManagement.test.ts
index 2017d5ceb..6a0a097cc 100644
--- a/frontend/src/composables/__tests__/usePersonManagement.test.ts
+++ b/frontend/src/composables/__tests__/usePersonManagement.test.ts
@@ -160,6 +160,40 @@ describe('usePersonManagement duplicate phone prevention', () => {
     expect(api.companies_people_create).not.toHaveBeenCalled()
   })
 
+  it('clears stale ownership before a fresh save attempt', async () => {
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      status: 'company',
+      normalized_phone: '+6495550100',
+      can_create_person: false,
+      people: [],
+      companies: [{ company_id: otherCompanyId, company_name: 'Other Company' }],
+    })
+    const manager = usePersonManagement()
+    await manager.openModal(companyId, 'Current Company')
+    manager.personForm.value = {
+      ...manager.personForm.value,
+      name: 'Fresh Attempt',
+      phone: '09 555 0100',
+    }
+    await manager.createNewPerson()
+    expect(manager.phoneOwnership.value?.status).toBe('company')
+
+    manager.beginCreatePerson()
+    expect(manager.phoneOwnership.value).toBeNull()
+
+    vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
+      status: 'available',
+      normalized_phone: '+6495550100',
+      can_create_person: true,
+      people: [],
+      companies: [],
+    })
+    vi.mocked(api.companies_people_create).mockRejectedValue(new Error('Network failure'))
+
+    expect(await manager.createNewPerson()).toBe(false)
+    expect(manager.phoneOwnership.value).toBeNull()
+  })
+
   it('allows an explicit separate identity only when the ownership result permits it', async () => {
     vi.mocked(api.companies_people_phone_ownership_create).mockResolvedValue({
       status: 'people',
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
index 2538d4c45..374f6531f 100644
--- a/frontend/src/composables/usePersonManagement.ts
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -52,6 +52,10 @@ export function usePersonManagement() {
 
   const hasPeople = computed(() => people.value.length > 0)
 
+  const beginCreatePerson = () => {
+    phoneOwnership.value = null
+  }
+
   watch(
     () => personForm.value.phone,
     () => {
@@ -405,6 +409,7 @@ export function usePersonManagement() {
     setSelectedPerson,
     selectExistingPerson,
     createNewPerson,
+    beginCreatePerson,
     linkExistingPerson,
     savePerson,
     clearSelection,
diff --git a/frontend/src/pages/crm/calls.vue b/frontend/src/pages/crm/calls.vue
index b528d5aae..b54e3f23a 100644
--- a/frontend/src/pages/crm/calls.vue
+++ b/frontend/src/pages/crm/calls.vue
@@ -351,6 +351,7 @@ watch([activeTab, directionFilter, recordingsOnly], () => {
 watch(selectedCompanyId, (companyId) => {
   if (!companyId) {
     selectedPersonId.value = ''
+    return
   }
   void loadCompanyPeople(companyId)
 })

From f2b63d56018d50570f01714f1af8558b6cf45146 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 16:50:12 +1200
Subject: [PATCH 28/73] chore: batch dependabot dependency updates 2026-07-14
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bundle the open dependabot updates into one branch ahead of a hard test
pass. Backend updates applied via poetry (source of truth) and
requirements.txt regenerated from poetry.lock; frontend via npm.

pip (poetry.lock + requirements.txt):
- cryptography 47.0.0 -> 49.0.0
- django 6.0.4 -> 6.0.7
- msgpack 1.1.2 -> 1.2.1
- pydantic-settings 2.14.0 -> 2.14.2
- pyjwt 2.12.1 -> 2.13.0
- pypdf 6.10.2 -> 6.14.2
- python-multipart 0.0.27 -> 0.0.32
- starlette 1.2.1 -> 1.3.1
- pyproject-api 1.10.0 -> 1.10.1
- mistralai 2.4.9 -> 2.6.0
- cachetools 7.1.1 -> 7.1.4
- pylint 4.0.5 -> 4.0.6, pylint-django 2.7.0 -> 2.8.0

npm (frontend/package.json + package-lock.json):
- eslint 10.4.0 -> 10.7.0
- @typescript-eslint/parser 8.59.4 -> 8.63.0
- @tailwindcss/vite 4.3.1 -> 4.3.2
- lucide-vue-next 0.513.0 -> 1.0.0 (major; type-check + build clean, no icon changes)

Excluded: astroid 4.1.2 (dependabot #444) — no released pylint yet allows
astroid >=4.1 (pylint 4.0.6 caps astroid <4.1.dev0), so it is upstream-blocked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/package-lock.json | 300 ++++++++++++++--------------------
 frontend/package.json      |   8 +-
 poetry.lock                | 322 ++++++++++++++++++-------------------
 requirements.txt           |  28 ++--
 4 files changed, 299 insertions(+), 359 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index 091d60270..d3ebfaed0 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -13,7 +13,7 @@
         "@internationalized/date": "^3.12.2",
         "@kodeglot/vue-calendar": "^1.5.0",
         "@rrweb/record": "^2.0.0-alpha.20",
-        "@tailwindcss/vite": "^4.3.1",
+        "@tailwindcss/vite": "^4.3.2",
         "@tanstack/vue-table": "^8.21.3",
         "@types/event-source-polyfill": "^1.0.5",
         "@types/quill": "^2.0.14",
@@ -33,7 +33,7 @@
         "event-source-polyfill": "^1.0.31",
         "js-cookie": "^3.0.7",
         "lodash-es": "^4.18.1",
-        "lucide-vue-next": "^0.513.0",
+        "lucide-vue-next": "^1.0.0",
         "openapi-zod-client": "^1.18.3",
         "pdf-vue3": "^1.0.12",
         "pinia": "^3.0.1",
@@ -62,7 +62,7 @@
         "@types/js-cookie": "^3.0.6",
         "@types/node": "^25.9.3",
         "@typescript-eslint/eslint-plugin": "^8.59.4",
-        "@typescript-eslint/parser": "^8.59.4",
+        "@typescript-eslint/parser": "^8.63.0",
         "@vitejs/plugin-vue": "^6.0.7",
         "@vue/eslint-config-prettier": "^10.2.0",
         "@vue/eslint-config-typescript": "^14.7.0",
@@ -71,7 +71,7 @@
         "adm-zip": "^0.5.17",
         "codesight": "^1.18.0",
         "dotenv": "^17.4.2",
-        "eslint": "^10.4.0",
+        "eslint": "^10.7.0",
         "eslint-plugin-vue": "~10.8.0",
         "happy-dom": "^20.8.9",
         "jiti": "^2.4.2",
@@ -1361,9 +1361,9 @@
       }
     },
     "node_modules/@eslint/plugin-kit": {
-      "version": "0.7.1",
-      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.1.tgz",
-      "integrity": "sha512-rZAP3aVgB9ds9KOeUSL+zZ21hPmo8dh6fnIFwRQj5EAZl9gzR7wxYbYXYysAM8CTqGmUGyp2S4kUdV17MnGuWQ==",
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.7.2.tgz",
+      "integrity": "sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A==",
       "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
@@ -2994,23 +2994,23 @@
       }
     },
     "node_modules/@tailwindcss/vite": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/vite/-/vite-4.3.1.tgz",
-      "integrity": "sha512-hItDHuIIlEV61R+faXu66s1K36aTurO/Qw0e45Vskz57gXl9pWOT6eg3zmcEui6CZXddbN7zd41bwmvag4JGwQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/vite/-/vite-4.3.2.tgz",
+      "integrity": "sha512-eHpMeX4JXfVNJDEcsouTeCBubJBTcTLigeaw/NTUW6PB5ATKKXdyonnXgTBX2VuRbjz1hjfz6C5XAhr52ImQXA==",
       "license": "MIT",
       "dependencies": {
-        "@tailwindcss/node": "4.3.1",
-        "@tailwindcss/oxide": "4.3.1",
-        "tailwindcss": "4.3.1"
+        "@tailwindcss/node": "4.3.2",
+        "@tailwindcss/oxide": "4.3.2",
+        "tailwindcss": "4.3.2"
       },
       "peerDependencies": {
         "vite": "^5.2.0 || ^6 || ^7 || ^8"
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/node": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.3.1.tgz",
-      "integrity": "sha512-6NDaqRoAMSXD1mr/RXu0HBvNE9a2n5tHPsxu9XHLws8o4Twes5rBM2205SUUiJ9goAtadrN6xTGX0UDEwp/N4A==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/node/-/node-4.3.2.tgz",
+      "integrity": "sha512-yWP/sqEcBLaD8JuA6zNwxoYKr75qxTioYwlRwekj5Jr/I5GXnoJfjetH/psLUIv74cYTH2lBUEzBkinthoYcBg==",
       "license": "MIT",
       "dependencies": {
         "@jridgewell/remapping": "^2.3.5",
@@ -3019,36 +3019,36 @@
         "lightningcss": "1.32.0",
         "magic-string": "^0.30.21",
         "source-map-js": "^1.2.1",
-        "tailwindcss": "4.3.1"
+        "tailwindcss": "4.3.2"
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.3.1.tgz",
-      "integrity": "sha512-yVPyo8RNkabVr3O2EhHEE0Rewu7YKzc1DhIqfL46LKveFrmu9XbDazNOJY7/GRuvw1h6u3utWnR29H/p5JPlgA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide/-/oxide-4.3.2.tgz",
+      "integrity": "sha512-z8ZgnzX8gdNoWLBLqBPoh/sjnxkwvf9ZuWjnO0l0yIzbLa5/9S+eC5QxGZKRobVHIC3/1BoMWjHblqWjcgFgag==",
       "license": "MIT",
       "engines": {
         "node": ">= 20"
       },
       "optionalDependencies": {
-        "@tailwindcss/oxide-android-arm64": "4.3.1",
-        "@tailwindcss/oxide-darwin-arm64": "4.3.1",
-        "@tailwindcss/oxide-darwin-x64": "4.3.1",
-        "@tailwindcss/oxide-freebsd-x64": "4.3.1",
-        "@tailwindcss/oxide-linux-arm-gnueabihf": "4.3.1",
-        "@tailwindcss/oxide-linux-arm64-gnu": "4.3.1",
-        "@tailwindcss/oxide-linux-arm64-musl": "4.3.1",
-        "@tailwindcss/oxide-linux-x64-gnu": "4.3.1",
-        "@tailwindcss/oxide-linux-x64-musl": "4.3.1",
-        "@tailwindcss/oxide-wasm32-wasi": "4.3.1",
-        "@tailwindcss/oxide-win32-arm64-msvc": "4.3.1",
-        "@tailwindcss/oxide-win32-x64-msvc": "4.3.1"
+        "@tailwindcss/oxide-android-arm64": "4.3.2",
+        "@tailwindcss/oxide-darwin-arm64": "4.3.2",
+        "@tailwindcss/oxide-darwin-x64": "4.3.2",
+        "@tailwindcss/oxide-freebsd-x64": "4.3.2",
+        "@tailwindcss/oxide-linux-arm-gnueabihf": "4.3.2",
+        "@tailwindcss/oxide-linux-arm64-gnu": "4.3.2",
+        "@tailwindcss/oxide-linux-arm64-musl": "4.3.2",
+        "@tailwindcss/oxide-linux-x64-gnu": "4.3.2",
+        "@tailwindcss/oxide-linux-x64-musl": "4.3.2",
+        "@tailwindcss/oxide-wasm32-wasi": "4.3.2",
+        "@tailwindcss/oxide-win32-arm64-msvc": "4.3.2",
+        "@tailwindcss/oxide-win32-x64-msvc": "4.3.2"
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-android-arm64": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.3.1.tgz",
-      "integrity": "sha512-SVlyf61g374l5cHyg8x9kf5xmLcOaxvOTsbsqDnSsDJaKOEFZ7GCvi84VAVGpxojYOs1+3K6M0UjXfqPU8vmOQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-android-arm64/-/oxide-android-arm64-4.3.2.tgz",
+      "integrity": "sha512-WHxqIuHpvZ5VtdX6GTl1Ik/Vp2YuN42Et+0CdeaVd/frQ9jAvGmvR8vLT+jk3e8/Q3x8kECB9+R17pgpp2BulA==",
       "cpu": [
         "arm64"
       ],
@@ -3062,9 +3062,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-darwin-arm64": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.3.1.tgz",
-      "integrity": "sha512-hVnWLwv+e/l7c4WKyVtHVrIPvYdqWHjRB3MDIqARynzFtnQg85kmQEFCbV9Ja0VVx4xXTIiDWY60Y7iz/iNoDA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-arm64/-/oxide-darwin-arm64-4.3.2.tgz",
+      "integrity": "sha512-GZypeUY/IDJW3877KeM+O67vbXr3MBnbtEL4aYhNErv/JWZhye2vGSWWG9tB6iiqR2MqRNkY8IOUy4NdSZV26w==",
       "cpu": [
         "arm64"
       ],
@@ -3078,9 +3078,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-darwin-x64": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.3.1.tgz",
-      "integrity": "sha512-Cf7abu0WVgbhU7ANgPUnSAvm7nCvMweusHb8FnaHlLfv/Caq4GYaEZg7ZImzzmjx4lIAfuS8q+eLIS7A7IzxIg==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-darwin-x64/-/oxide-darwin-x64-4.3.2.tgz",
+      "integrity": "sha512-UIIzmefR6KO1sDU7MzRqAxC8iBpft/VhkGjTjnhoS6k7Z3rQ9wEgA1ODSiyH/tcSYssulNm4Ci3hOeK1jH7ccQ==",
       "cpu": [
         "x64"
       ],
@@ -3094,9 +3094,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-freebsd-x64": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.3.1.tgz",
-      "integrity": "sha512-ZZqzX2Y+GXtXXfqSfpJhDm60OoZfvLHLCgm+J7NVqgHHJjG/m9ugZI77RwTsVd4fnBJuCFP6Ae6kTJb71UdS8g==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-freebsd-x64/-/oxide-freebsd-x64-4.3.2.tgz",
+      "integrity": "sha512-GN+uAmcI6DNspnCDwtOAZrTz6oukJnp337qZvxqCGLd3BHBzJpO0ZbTLRvJNdztOeAmTzewewGIMPb0tk2R4WA==",
       "cpu": [
         "x64"
       ],
@@ -3110,9 +3110,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-linux-arm-gnueabihf": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.3.1.tgz",
-      "integrity": "sha512-/Ah/xik0LaMYfv9DZ0S/t4pBlBNYOcqtRwusjgovHkvT8ixueWCLyJjsaF5kQIckjb4IT8Q6K6p/iPmZMixYgg==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm-gnueabihf/-/oxide-linux-arm-gnueabihf-4.3.2.tgz",
+      "integrity": "sha512-4ABn7qSbdHRwTiDiuWNegCyb5+2FJ4vKIKc3DmKrvAFw7MU1Lm11dIkTPwUaFdTzc7IsOpDbqBrlh0x6y36U/w==",
       "cpu": [
         "arm"
       ],
@@ -3126,9 +3126,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-linux-arm64-gnu": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.3.1.tgz",
-      "integrity": "sha512-gqdFoVJlw444GvpnheZLHmvTzSxI/cOUUh2KSNejQjTcYkW062SVD+En0rUgD+QV91bz1XGIGtt1HJd48xUGbQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-gnu/-/oxide-linux-arm64-gnu-4.3.2.tgz",
+      "integrity": "sha512-wDgEIGwoM8w8pufh9LVt1PahDgNdKXrLC2qfAnV3vAmococ9RWbxeAw4pxPttd/TsJfwjyLf90Dg1y9y8I6Emw==",
       "cpu": [
         "arm64"
       ],
@@ -3142,9 +3142,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-linux-arm64-musl": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.3.1.tgz",
-      "integrity": "sha512-Bwv9KwOvE0VKa86xPFif9b9c3Y1NxOV1P0gLti/IYaWEsQYZXDlxfGEtA8mdDZ7SG3wyNXAWYT5SIn3giL57oA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-arm64-musl/-/oxide-linux-arm64-musl-4.3.2.tgz",
+      "integrity": "sha512-J5Nuk0uZQIiMTJj3LEx4sAA9tMFUoXQZFv1J6An+QGYe53HKRJuFDi0rpq/tuouCZeAbOBY3kQ6g8qeD4TUjtA==",
       "cpu": [
         "arm64"
       ],
@@ -3158,9 +3158,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-linux-x64-gnu": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.3.1.tgz",
-      "integrity": "sha512-Ymi8O8T15HYQdOUWUtTI6ldN0neHP85FC+Qz32xTcZ7iJXtem/x8ITev0o1e9e5rkqj4lONZfTRLvkmin1+tKg==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-gnu/-/oxide-linux-x64-gnu-4.3.2.tgz",
+      "integrity": "sha512-kqCZpSKOBEJO4mz7OqWoofBZeXTAwaVGPj0ErAj7CojmhKpWVWVOnrt9dE8odoIraZq4oj3ausM37kXi+Tow8w==",
       "cpu": [
         "x64"
       ],
@@ -3174,9 +3174,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-linux-x64-musl": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.3.1.tgz",
-      "integrity": "sha512-M+P/91qJ6uILLw4k2G93GMDRAXj61SMvFQYt39AqvUqYgExXpLL5aepfns7sj4HiAQeolirQF9E0lzRvdf4zPQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-linux-x64-musl/-/oxide-linux-x64-musl-4.3.2.tgz",
+      "integrity": "sha512-cixpqbh2toJDmkuCRI68nXA8ZxNmdK9Y+9v5h3MC3ZQKy/0BO8AWzlkWyRM7JAFSGBlfig4YVTPsK6MVgqz1uw==",
       "cpu": [
         "x64"
       ],
@@ -3190,9 +3190,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.3.1.tgz",
-      "integrity": "sha512-zsM8uOeqvVGHsAXsJxsT28ttosFahLJKCLOTUBqRAtKnVgGSRitds9T432QiT8b77Yga7JIBkulIRRlJPtYhRA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-wasm32-wasi/-/oxide-wasm32-wasi-4.3.2.tgz",
+      "integrity": "sha512-4ec2Z/LOmRsAgU23CS4xeJfcJlmRg94A/XrbGRCF1gyU/zdDfRLYDVsS+ynSZCmGNxQ1jQriQOKMQeQxBA3Isw==",
       "bundleDependencies": [
         "@napi-rs/wasm-runtime",
         "@emnapi/core",
@@ -3207,9 +3207,9 @@
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "@emnapi/core": "^1.10.0",
-        "@emnapi/runtime": "^1.10.0",
-        "@emnapi/wasi-threads": "^1.2.1",
+        "@emnapi/core": "^1.11.1",
+        "@emnapi/runtime": "^1.11.1",
+        "@emnapi/wasi-threads": "^1.2.2",
         "@napi-rs/wasm-runtime": "^1.1.4",
         "@tybys/wasm-util": "^0.10.2",
         "tslib": "^2.8.1"
@@ -3218,70 +3218,10 @@
         "node": ">=14.0.0"
       }
     },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": {
-      "version": "1.10.0",
-      "inBundle": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "@emnapi/wasi-threads": "1.2.1",
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": {
-      "version": "1.10.0",
-      "inBundle": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": {
-      "version": "1.2.1",
-      "inBundle": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@napi-rs/wasm-runtime": {
-      "version": "1.1.4",
-      "inBundle": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "@tybys/wasm-util": "^0.10.1"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/Brooooooklyn"
-      },
-      "peerDependencies": {
-        "@emnapi/core": "^1.7.1",
-        "@emnapi/runtime": "^1.7.1"
-      }
-    },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@tybys/wasm-util": {
-      "version": "0.10.2",
-      "inBundle": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/tslib": {
-      "version": "2.8.1",
-      "inBundle": true,
-      "license": "0BSD",
-      "optional": true
-    },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-win32-arm64-msvc": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.3.1.tgz",
-      "integrity": "sha512-aiNvSq9BsVk8V513lDKlrCFAgf8qBMPZTpgEhInL+NwQqs97mYmupVMrPrgBBSL8Pv/0zXu9MrMF9rMun1ZeNg==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-arm64-msvc/-/oxide-win32-arm64-msvc-4.3.2.tgz",
+      "integrity": "sha512-Zyr/M0+XcYZu3bZrUytc7TXvrk0ftWfl8gN2MwekNDzhqhKRUucMPSeOzM0o0wH5AWOU49BsKRrfKxI2atCPMQ==",
       "cpu": [
         "arm64"
       ],
@@ -3295,9 +3235,9 @@
       }
     },
     "node_modules/@tailwindcss/vite/node_modules/@tailwindcss/oxide-win32-x64-msvc": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.3.1.tgz",
-      "integrity": "sha512-xDEyu1rg290472FEGaKHnzyDyh5QH+AlWvsU5hMoMtPpzmKlRI0jaYKCgSHDYtaQWZOYbMaduSyCwFwY4n1HmA==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/@tailwindcss/oxide-win32-x64-msvc/-/oxide-win32-x64-msvc-4.3.2.tgz",
+      "integrity": "sha512-QI9BO7KlNZsp2GuO0jwAAj5jCDABOKXRkCk2XuKTSaNEFSdfzqswYVTtCHBNKHLsqyjFyFkqlDiwkNbTYSssMQ==",
       "cpu": [
         "x64"
       ],
@@ -4526,16 +4466,16 @@
       }
     },
     "node_modules/@typescript-eslint/parser": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.59.4.tgz",
-      "integrity": "sha512-zORHqO/tuhxY1zWuTvMUqddRxpiFJ72xVfcNoWpqdLjs6lfPbuQBJuW4pk+49/uBMy7Ssr4bzgjiKmmDB1UbZQ==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.63.0.tgz",
+      "integrity": "sha512-gwh4gvvlaVDKKxyfxMG+Gnu1u9X0OQBwyGLkbwB65dIzBKnxeRiJlNFqlI3zwVhNXJIs6qV7mlFCn/BIajlVig==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/scope-manager": "8.59.4",
-        "@typescript-eslint/types": "8.59.4",
-        "@typescript-eslint/typescript-estree": "8.59.4",
-        "@typescript-eslint/visitor-keys": "8.59.4",
+        "@typescript-eslint/scope-manager": "8.63.0",
+        "@typescript-eslint/types": "8.63.0",
+        "@typescript-eslint/typescript-estree": "8.63.0",
+        "@typescript-eslint/visitor-keys": "8.63.0",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -4551,14 +4491,14 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/project-service": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.59.4.tgz",
-      "integrity": "sha512-Ly00Vu4oAacfDeHp2Zg85ioNG6l8HG+tN1D7J+xTHSxu9y0awYKJ2zH1rFBn8ZSfuGK+7FxK3Cgl3uAz0aZZLg==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.63.0.tgz",
+      "integrity": "sha512-e5dh0/UI0ok53AlZ5wRkXCB32z/f2jUZqPR/ygAw5WYaSw8j9EoJWlS7wQjr/dmOaqWjnPIn2m+HhVPCMWGZVQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/tsconfig-utils": "^8.59.4",
-        "@typescript-eslint/types": "^8.59.4",
+        "@typescript-eslint/tsconfig-utils": "^8.63.0",
+        "@typescript-eslint/types": "^8.63.0",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -4573,14 +4513,14 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/scope-manager": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.59.4.tgz",
-      "integrity": "sha512-mUeR/3H1WrTAddJrwut8OoPjfauaztMQmRwV5fQTUyNVJCLiUXXe4lGEyYIL2oFDpP7UtgbGJXCt72wT0z2S3Q==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.63.0.tgz",
+      "integrity": "sha512-uUyfMWCnDSN8bCpcrY8nGP2BLkQ9Xn0GsipcONcpIDWhwhO4ZSyHvyS14U3X75mzxWxL3I2UZIrenTzdzcJO8A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.59.4",
-        "@typescript-eslint/visitor-keys": "8.59.4"
+        "@typescript-eslint/types": "8.63.0",
+        "@typescript-eslint/visitor-keys": "8.63.0"
       },
       "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -4591,9 +4531,9 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/tsconfig-utils": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.59.4.tgz",
-      "integrity": "sha512-DLCpnKgD4alVxTBSKulK+gU1KCqOgUXfDRDXh2mZgzokQKa/70ax93I2uVO3m/LLvIAtWZIFoiifudmIqAxpMA==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.63.0.tgz",
+      "integrity": "sha512-sUAbkulqBAsncKnbRP3+7CtQFRKicexnj7ZwNC6ddCR7EmrXvjvdCYMJbUIqMd6lwoEriZjwLo08aS5tSjVMHg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4608,9 +4548,9 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/types": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.59.4.tgz",
-      "integrity": "sha512-F1o7WJcCq+bc8dwcO/YsSEOudAH8RDtaOhM6wcAQhcUsFhnWQl81JKy48q1hoxAU0qrzM89+31GYh1515Zde3Q==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.63.0.tgz",
+      "integrity": "sha512-xyLtl9DUBBFrcJS4x2pIqGLH68/tC2uOa4Z7pUteW09D3bXnnXUom4dyPikzWgB7llmIc1zoeI3aoUdC4rPK/Q==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4622,16 +4562,16 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/typescript-estree": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.59.4.tgz",
-      "integrity": "sha512-F+RuOmcDXo4+TPdfd/TCLS3m2nw8gE9XXyZLrA3JBfaA5tz9TtdkyD3YJFmPxulyc2cKbEok/CvFE3MgSLWnag==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.63.0.tgz",
+      "integrity": "sha512-ygBkU+B7ex5UI/gKhaqexWev79uISfIv7XQCRNYO/jmD8rGLPyWLAb3KMRT6nd8Gt9bmUBi9+iX6tBdYfOY81Q==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/project-service": "8.59.4",
-        "@typescript-eslint/tsconfig-utils": "8.59.4",
-        "@typescript-eslint/types": "8.59.4",
-        "@typescript-eslint/visitor-keys": "8.59.4",
+        "@typescript-eslint/project-service": "8.63.0",
+        "@typescript-eslint/tsconfig-utils": "8.63.0",
+        "@typescript-eslint/types": "8.63.0",
+        "@typescript-eslint/visitor-keys": "8.63.0",
         "debug": "^4.4.3",
         "minimatch": "^10.2.2",
         "semver": "^7.7.3",
@@ -4650,13 +4590,13 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/visitor-keys": {
-      "version": "8.59.4",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.59.4.tgz",
-      "integrity": "sha512-U3gxVaDVnuZKhSspW/MzMxE1kq7zOdc072FcSNoqA1I9p8HyKbBFfEHoWckBAMgNMph4MamwS5iTVzFmrnt8TQ==",
+      "version": "8.63.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.63.0.tgz",
+      "integrity": "sha512-UexrHGnGTpbuQHct2ExOc2ZcFbGUS9FOesCxxqdBGcpI1BxYu/LZ6U8Aq6/72XtF/qRBk9nhuGHFJIXXMhPMdw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.59.4",
+        "@typescript-eslint/types": "8.63.0",
         "eslint-visitor-keys": "^5.0.0"
       },
       "engines": {
@@ -4678,9 +4618,9 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/brace-expansion": {
-      "version": "5.0.6",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
-      "integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
+      "version": "5.0.7",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.7.tgz",
+      "integrity": "sha512-7oFy703dxfY3/NLxC1fh2SUCQ0H9rmAY+5EpDVfXjUTTs+HEwR2nYaqLv+GWcTsumwxPfiz6CzCNkwXwBUwqCA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -7755,18 +7695,21 @@
       }
     },
     "node_modules/eslint": {
-      "version": "10.4.0",
-      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.4.0.tgz",
-      "integrity": "sha512-loXy6bWOoP3EP6JA7jo6p5jMpBJmHmsNZM5SFRHLdh1MGOPurMnNBj4ZlAbaqUAaQWbCr7jHV4P7gzAyryZWkQ==",
+      "version": "10.7.0",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.7.0.tgz",
+      "integrity": "sha512-GVTD7s1vdIl6UYvAfriOPeY1Df8LIZjfofLvHwde+erDHGGuHyuM6xoxRxmHiebhYuD2p1vN4wWh0XzPARSGDQ==",
       "dev": true,
       "license": "MIT",
+      "workspaces": [
+        "packages/*"
+      ],
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
         "@eslint/config-array": "^0.23.5",
         "@eslint/config-helpers": "^0.6.0",
         "@eslint/core": "^1.2.1",
-        "@eslint/plugin-kit": "^0.7.1",
+        "@eslint/plugin-kit": "^0.7.2",
         "@humanfs/node": "^0.16.6",
         "@humanwhocodes/module-importer": "^1.0.1",
         "@humanwhocodes/retry": "^0.4.2",
@@ -9478,9 +9421,10 @@
       "license": "ISC"
     },
     "node_modules/lucide-vue-next": {
-      "version": "0.513.0",
-      "resolved": "https://registry.npmjs.org/lucide-vue-next/-/lucide-vue-next-0.513.0.tgz",
-      "integrity": "sha512-/J7DB2WBC+UPcRswOfJFXSWt8r5HTMVu0PRkR6e0+Ozx6kLJZv4m71vbT1DS9RCjj0pfuLskWIslSBeeXmg7BA==",
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/lucide-vue-next/-/lucide-vue-next-1.0.0.tgz",
+      "integrity": "sha512-V6SPvx1IHTj/UY+FrIYWV5faISsPSb8BnWSFDxAtezWKvWc9ZZ40PDrdu1/Qb5vg4lHWr1hs1BAMGVGm6V1Xdg==",
+      "deprecated": "Package deprecated. Please use @lucide/vue instead.",
       "license": "ISC",
       "peerDependencies": {
         "vue": ">=3.0.1"
@@ -12120,9 +12064,9 @@
       }
     },
     "node_modules/tailwindcss": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.1.tgz",
-      "integrity": "sha512-hk+TB1m+K8CYNrP6rjQaq/Y+4Zylwpa87mLYBKCunwnnQ9p+fHb7kmSfGqyEJoxF/O6CDyABWVFEafNSYKll+Q==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.2.tgz",
+      "integrity": "sha512-WtctNNSH8A9jlMIqxzuYumOHU5uGZyRv0Q5svQl+oEPy5w84YpBxdb7MdqyiSPQge5jTJ6zFQLq0PFygdccSBA==",
       "license": "MIT"
     },
     "node_modules/tanu": {
diff --git a/frontend/package.json b/frontend/package.json
index a0a3e950b..b5b3e8611 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -36,7 +36,7 @@
     "@internationalized/date": "^3.12.2",
     "@kodeglot/vue-calendar": "^1.5.0",
     "@rrweb/record": "^2.0.0-alpha.20",
-    "@tailwindcss/vite": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.2",
     "@tanstack/vue-table": "^8.21.3",
     "@types/event-source-polyfill": "^1.0.5",
     "@types/quill": "^2.0.14",
@@ -56,7 +56,7 @@
     "event-source-polyfill": "^1.0.31",
     "js-cookie": "^3.0.7",
     "lodash-es": "^4.18.1",
-    "lucide-vue-next": "^0.513.0",
+    "lucide-vue-next": "^1.0.0",
     "openapi-zod-client": "^1.18.3",
     "pdf-vue3": "^1.0.12",
     "pinia": "^3.0.1",
@@ -85,7 +85,7 @@
     "@types/js-cookie": "^3.0.6",
     "@types/node": "^25.9.3",
     "@typescript-eslint/eslint-plugin": "^8.59.4",
-    "@typescript-eslint/parser": "^8.59.4",
+    "@typescript-eslint/parser": "^8.63.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vue/eslint-config-prettier": "^10.2.0",
     "@vue/eslint-config-typescript": "^14.7.0",
@@ -94,7 +94,7 @@
     "adm-zip": "^0.5.17",
     "codesight": "^1.18.0",
     "dotenv": "^17.4.2",
-    "eslint": "^10.4.0",
+    "eslint": "^10.7.0",
     "eslint-plugin-vue": "~10.8.0",
     "happy-dom": "^20.8.9",
     "jiti": "^2.4.2",
diff --git a/poetry.lock b/poetry.lock
index 352f88b2d..db2c4e0de 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -472,14 +472,14 @@ files = [
 
 [[package]]
 name = "cachetools"
-version = "7.1.1"
+version = "7.1.4"
 description = "Extensible memoizing collections and decorators"
 optional = false
 python-versions = ">=3.10"
 groups = ["dev"]
 files = [
-    {file = "cachetools-7.1.1-py3-none-any.whl", hash = "sha256:0335cd7a0952d2b22327441fb0628139e234c565559eeb91a8a4ac7551c5353d"},
-    {file = "cachetools-7.1.1.tar.gz", hash = "sha256:27bdf856d68fd3c71c26c01b5edc312124ed427524d1ddb31aa2b7746fe20d4b"},
+    {file = "cachetools-7.1.4-py3-none-any.whl", hash = "sha256:323dc4127934744db5b54eb4924482d7edafbf9554e820d1531c2e08c0e4ef54"},
+    {file = "cachetools-7.1.4.tar.gz", hash = "sha256:437f55a4e0c1b01a4f3077cc470e6991d47430970e36fbcb77e2be0df4fc1cd6"},
 ]
 
 [[package]]
@@ -645,7 +645,7 @@ files = [
     {file = "cffi-2.0.0-cp39-cp39-win_amd64.whl", hash = "sha256:b882b3df248017dba09d6b16defe9b5c407fe32fc7c65a9c69798e6175601be9"},
     {file = "cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529"},
 ]
-markers = {main = "platform_python_implementation != \"PyPy\" or os_name == \"nt\" and implementation_name != \"pypy\"", dev = "platform_python_implementation != \"PyPy\""}
+markers = {main = "os_name == \"nt\" and implementation_name != \"pypy\" or platform_python_implementation != \"PyPy\"", dev = "platform_python_implementation != \"PyPy\""}
 
 [package.dependencies]
 pycparser = {version = "*", markers = "implementation_name != \"PyPy\""}
@@ -1051,65 +1051,62 @@ dev = ["polib"]
 
 [[package]]
 name = "cryptography"
-version = "47.0.0"
+version = "49.0.0"
 description = "cryptography is a package which provides cryptographic recipes and primitives to Python developers."
 optional = false
-python-versions = "!=3.9.0,!=3.9.1,>=3.8"
+python-versions = "!=3.9.0,!=3.9.1,>=3.9"
 groups = ["main", "dev"]
 files = [
-    {file = "cryptography-47.0.0-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:160ad728f128972d362e714054f6ba0067cab7fb350c5202a9ae8ae4ce3ef1a0"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b9a8943e359b7615db1a3ba587994618e094ff3d6fa5a390c73d079ce18b3973"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:f5c15764f261394b22aef6b00252f5195f46f2ca300bec57149474e2538b31f8"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:9c59ab0e0fa3a180a5a9c59f3a5abe3ef90d474bc56d7fadfbe80359491b615b"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:34b4358b925a5ea3e14384ca781a2c0ef7ac219b57bb9eacc4457078e2b19f92"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:0024b87d47ae2399165a6bfb20d24888881eeab83ae2566d62467c5ff0030ce7"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:1e47422b5557bb82d3fff997e8d92cff4e28b9789576984f08c248d2b3535d93"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:6f29f36582e6151d9686235e586dd35bb67491f024767d10b842e520dc6a07ac"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:a9b761f012a943b7de0e828843c5688d0de94a0578d44d6c85a1bae32f87791f"},
-    {file = "cryptography-47.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:4e1de79e047e25d6e9f8cea71c86b4a53aced64134f0f003bbcbf3655fd172c8"},
-    {file = "cryptography-47.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:ef6b3634087f18d2155b1e8ce264e5345a753da2c5fa9815e7d41315c90f8318"},
-    {file = "cryptography-47.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:11dbb9f50a0f1bb9757b3d8c27c1101780efb8f0bdecfb12439c22a74d64c001"},
-    {file = "cryptography-47.0.0-cp311-abi3-win32.whl", hash = "sha256:7fda2f02c9015db3f42bb8a22324a454516ed10a8c29ca6ece6cdbb5efe2a203"},
-    {file = "cryptography-47.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:f5c3296dab66202f1b18a91fa266be93d6aa0c2806ea3d67762c69f60adc71aa"},
-    {file = "cryptography-47.0.0-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:be12cb6a204f77ed968bcefe68086eb061695b540a3dd05edac507a3111b25f0"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2ebd84adf0728c039a3be2700289378e1c164afc6748df1a5ed456767bef9ba7"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7f68d6fbc7fbbcfb0939fea72c3b96a9f9a6edfc0e1b1d29778a2066030418b1"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:6651d32eff255423503aa276739da98c30f26c40cbeffcc6048e0d54ef704c0c"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:3fb8fa48075fad7193f2e5496135c6a76ac4b2aa5a38433df0a539296b377829"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:11438c7518132d95f354fa01a4aa2f806d172a061a7bed18cf18cbdacdb204d7"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:8c1a736bbb3288005796c3f7ccb9453360d7fed483b13b9f468aea5171432923"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:f1557695e5c2b86e204f6ce9470497848634100787935ab7adc5397c54abd7ab"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:f9a034b642b960767fb343766ae5ba6ad653f2e890ddd82955aef288ffea8736"},
-    {file = "cryptography-47.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:b1c76fca783aa7698eb21eb14f9c4aa09452248ee54a627d125025a43f83e7a7"},
-    {file = "cryptography-47.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:4f7722c97826770bab8ae92959a2e7b20a5e9e9bf4deae68fd86c3ca457bab52"},
-    {file = "cryptography-47.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:09f6d7bf6724f8db8b32f11eccf23efc8e759924bc5603800335cf8859a3ddbd"},
-    {file = "cryptography-47.0.0-cp314-cp314t-win32.whl", hash = "sha256:6eebcaf0df1d21ce1f90605c9b432dd2c4f4ab665ac29a40d5e3fc68f51b5e63"},
-    {file = "cryptography-47.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:51c9313e90bd1690ec5a75ed047c27c0b8e6c570029712943d6116ef9a90620b"},
-    {file = "cryptography-47.0.0-cp38-abi3-macosx_10_9_universal2.whl", hash = "sha256:14432c8a9bcb37009784f9594a62fae211a2ae9543e96c92b2a8e4c3cd5cd0c4"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:07efe86201817e7d3c18781ca9770bc0db04e1e48c994be384e4602bc38f8f27"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:2b45761c6ec22b7c726d6a829558777e32d0f1c8be7c3f3480f9c912d5ee8a10"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:edd4da498015da5b9f26d38d3bfc2e90257bfa9cbed1f6767c282a0025ae649b"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9af828c0d5a65c70ec729cd7495a4bf1a67ecb66417b8f02ff125ab8a6326a74"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:256d07c78a04d6b276f5df935a9923275f53bd1522f214447fdf365494e2d515"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:5d0e362ff51041b0c0d219cc7d6924d7b8996f57ce5712bdcef71eb3c65a59cc"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:1581aef4219f7ca2849d0250edaa3866212fb74bf5667284f46aa92f9e65c1ca"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:a49a3eb5341b9503fa3000a9a0db033161db90d47285291f53c2a9d2cd1b7f76"},
-    {file = "cryptography-47.0.0-cp38-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2207a498b03275d0051589e326b79d4cf59985c99031b05bb292ac52631c37fe"},
-    {file = "cryptography-47.0.0-cp38-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7a02675e2fabd0c0fc04c868b8781863cbf1967691543c22f5470500ff840b31"},
-    {file = "cryptography-47.0.0-cp38-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:80887c5cbd1774683cb126f0ab4184567f080071d5acf62205acb354b4b753b7"},
-    {file = "cryptography-47.0.0-cp38-abi3-win32.whl", hash = "sha256:ed67ea4e0cfb5faa5bc7ecb6e2b8838f3807a03758eec239d6c21c8769355310"},
-    {file = "cryptography-47.0.0-cp38-abi3-win_amd64.whl", hash = "sha256:835d2d7f47cdc53b3224e90810fb1d36ca94ea29cc1801fb4c1bc43876735769"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:7f1207974a904e005f762869996cf620e9bf79ecb4622f148550bb48e0eb35a7"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:1a405c08857258c11016777e11c02bacbe7ef596faf259305d282272a3a05cbe"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:20fdbe3e38fb67c385d233c89371fa27f9909f6ebca1cecc20c13518dae65475"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:f7db373287273d8af1414cf95dc4118b13ffdc62be521997b0f2b270771fef50"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:9fe6b7c64926c765f9dff301f9c1b867febcda5768868ca084e18589113732ab"},
-    {file = "cryptography-47.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:cffbba3392df0fa8629bb7f43454ee2925059ee158e23c54620b9063912b86c8"},
-    {file = "cryptography-47.0.0.tar.gz", hash = "sha256:9f8e55fe4e63613a5e1cc5819030f27b97742d720203a087802ce4ce9ceb52bb"},
-]
-
-[package.dependencies]
-cffi = {version = ">=2.0.0", markers = "python_full_version >= \"3.9.0\" and platform_python_implementation != \"PyPy\""}
+    {file = "cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68"},
+    {file = "cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9"},
+    {file = "cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f"},
+    {file = "cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459"},
+    {file = "cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e"},
+    {file = "cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866"},
+    {file = "cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8"},
+    {file = "cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3"},
+    {file = "cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27"},
+    {file = "cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61"},
+    {file = "cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8"},
+    {file = "cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36"},
+    {file = "cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e"},
+    {file = "cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b"},
+    {file = "cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:fc1e275c2f1d97b1a6450b8b0ea3ebfa6e087a611c2b26cb2404d48588abab7b"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:c83782480a4a9da4d0feb51950131ba32e12e70813848b3343f6e18c28a66838"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:b39efa323140595abd3ecca8529d321ae50f55f3aa3ba9cc81ea56a6011953d5"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_aarch64.whl", hash = "sha256:b47db11c2c3525083296069b98ac5221907455e989ae0c2e3008bde851921615"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:084ef1af862eb07ec46d25f68689f2102a9fc0e05ce7b80f14f5fe51e4eef0f6"},
+    {file = "cryptography-49.0.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:be9fcb48a55f023493482827d4f459bd263cc20efde64f204b97c123201850c6"},
+    {file = "cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493"},
+]
+
+[package.dependencies]
+cffi = {version = ">=2.0.0", markers = "platform_python_implementation != \"PyPy\""}
 
 [package.extras]
 ssh = ["bcrypt (>=3.1.5)"]
@@ -1245,14 +1242,14 @@ files = [
 
 [[package]]
 name = "django"
-version = "6.0.4"
+version = "6.0.7"
 description = "A high-level Python web framework that encourages rapid development and clean, pragmatic design."
 optional = false
 python-versions = ">=3.12"
 groups = ["main", "dev"]
 files = [
-    {file = "django-6.0.4-py3-none-any.whl", hash = "sha256:14359c809fc16e8f81fd2b59d7d348e4d2d799da6840b10522b6edf7b8afc1da"},
-    {file = "django-6.0.4.tar.gz", hash = "sha256:8cfa2572b3f2768b2e84983cf3c4811877a01edb64e817986ec5d60751c113ac"},
+    {file = "django-6.0.7-py3-none-any.whl", hash = "sha256:a037427c2288443a8c02a1b02295a31c239663aa682bc50b1976afb7cf6a769e"},
+    {file = "django-6.0.7.tar.gz", hash = "sha256:2998503fc083124fb58037084bfa00de323c7c743f05f1b4284e77bff0ab8890"},
 ]
 
 [package.dependencies]
@@ -3679,14 +3676,14 @@ files = [
 
 [[package]]
 name = "mistralai"
-version = "2.4.9"
+version = "2.6.0"
 description = "Python Client SDK for the Mistral AI API."
 optional = false
 python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "mistralai-2.4.9-py3-none-any.whl", hash = "sha256:8e2f8a58697455f2113b4f6d0d1bd28d66d3eb51f94ff24b9d22a21dea531520"},
-    {file = "mistralai-2.4.9.tar.gz", hash = "sha256:9a6465b8bddf825d76cf80ab54d55bb8089fdf5aafc0a7943ae74c825df97939"},
+    {file = "mistralai-2.6.0-py3-none-any.whl", hash = "sha256:4b7202b0cab84ea03f8ff4a933c8cfc615b3057520d9d76467c07aa23939dab2"},
+    {file = "mistralai-2.6.0.tar.gz", hash = "sha256:531a86292ad498fc0fcd6dfcd480a3f4db9e92f558e14ffb22172824831e3a6e"},
 ]
 
 [package.dependencies]
@@ -3713,74 +3710,78 @@ workflow-payload-offloading-s3 = ["aioboto3 (>=12.4.0,<13.0.0)"]
 
 [[package]]
 name = "msgpack"
-version = "1.1.2"
+version = "1.2.1"
 description = "MessagePack serializer"
 optional = false
-python-versions = ">=3.9"
+python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "msgpack-1.1.2-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:0051fffef5a37ca2cd16978ae4f0aef92f164df86823871b5162812bebecd8e2"},
-    {file = "msgpack-1.1.2-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:a605409040f2da88676e9c9e5853b3449ba8011973616189ea5ee55ddbc5bc87"},
-    {file = "msgpack-1.1.2-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8b696e83c9f1532b4af884045ba7f3aa741a63b2bc22617293a2c6a7c645f251"},
-    {file = "msgpack-1.1.2-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:365c0bbe981a27d8932da71af63ef86acc59ed5c01ad929e09a0b88c6294e28a"},
-    {file = "msgpack-1.1.2-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:41d1a5d875680166d3ac5c38573896453bbbea7092936d2e107214daf43b1d4f"},
-    {file = "msgpack-1.1.2-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:354e81bcdebaab427c3df4281187edc765d5d76bfb3a7c125af9da7a27e8458f"},
-    {file = "msgpack-1.1.2-cp310-cp310-win32.whl", hash = "sha256:e64c8d2f5e5d5fda7b842f55dec6133260ea8f53c4257d64494c534f306bf7a9"},
-    {file = "msgpack-1.1.2-cp310-cp310-win_amd64.whl", hash = "sha256:db6192777d943bdaaafb6ba66d44bf65aa0e9c5616fa1d2da9bb08828c6b39aa"},
-    {file = "msgpack-1.1.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:2e86a607e558d22985d856948c12a3fa7b42efad264dca8a3ebbcfa2735d786c"},
-    {file = "msgpack-1.1.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:283ae72fc89da59aa004ba147e8fc2f766647b1251500182fac0350d8af299c0"},
-    {file = "msgpack-1.1.2-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:61c8aa3bd513d87c72ed0b37b53dd5c5a0f58f2ff9f26e1555d3bd7948fb7296"},
-    {file = "msgpack-1.1.2-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:454e29e186285d2ebe65be34629fa0e8605202c60fbc7c4c650ccd41870896ef"},
-    {file = "msgpack-1.1.2-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:7bc8813f88417599564fafa59fd6f95be417179f76b40325b500b3c98409757c"},
-    {file = "msgpack-1.1.2-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:bafca952dc13907bdfdedfc6a5f579bf4f292bdd506fadb38389afa3ac5b208e"},
-    {file = "msgpack-1.1.2-cp311-cp311-win32.whl", hash = "sha256:602b6740e95ffc55bfb078172d279de3773d7b7db1f703b2f1323566b878b90e"},
-    {file = "msgpack-1.1.2-cp311-cp311-win_amd64.whl", hash = "sha256:d198d275222dc54244bf3327eb8cbe00307d220241d9cec4d306d49a44e85f68"},
-    {file = "msgpack-1.1.2-cp311-cp311-win_arm64.whl", hash = "sha256:86f8136dfa5c116365a8a651a7d7484b65b13339731dd6faebb9a0242151c406"},
-    {file = "msgpack-1.1.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:70a0dff9d1f8da25179ffcf880e10cf1aad55fdb63cd59c9a49a1b82290062aa"},
-    {file = "msgpack-1.1.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:446abdd8b94b55c800ac34b102dffd2f6aa0ce643c55dfc017ad89347db3dbdb"},
-    {file = "msgpack-1.1.2-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c63eea553c69ab05b6747901b97d620bb2a690633c77f23feb0c6a947a8a7b8f"},
-    {file = "msgpack-1.1.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:372839311ccf6bdaf39b00b61288e0557916c3729529b301c52c2d88842add42"},
-    {file = "msgpack-1.1.2-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2929af52106ca73fcb28576218476ffbb531a036c2adbcf54a3664de124303e9"},
-    {file = "msgpack-1.1.2-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:be52a8fc79e45b0364210eef5234a7cf8d330836d0a64dfbb878efa903d84620"},
-    {file = "msgpack-1.1.2-cp312-cp312-win32.whl", hash = "sha256:1fff3d825d7859ac888b0fbda39a42d59193543920eda9d9bea44d958a878029"},
-    {file = "msgpack-1.1.2-cp312-cp312-win_amd64.whl", hash = "sha256:1de460f0403172cff81169a30b9a92b260cb809c4cb7e2fc79ae8d0510c78b6b"},
-    {file = "msgpack-1.1.2-cp312-cp312-win_arm64.whl", hash = "sha256:be5980f3ee0e6bd44f3a9e9dea01054f175b50c3e6cdb692bc9424c0bbb8bf69"},
-    {file = "msgpack-1.1.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:4efd7b5979ccb539c221a4c4e16aac1a533efc97f3b759bb5a5ac9f6d10383bf"},
-    {file = "msgpack-1.1.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:42eefe2c3e2af97ed470eec850facbe1b5ad1d6eacdbadc42ec98e7dcf68b4b7"},
-    {file = "msgpack-1.1.2-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1fdf7d83102bf09e7ce3357de96c59b627395352a4024f6e2458501f158bf999"},
-    {file = "msgpack-1.1.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fac4be746328f90caa3cd4bc67e6fe36ca2bf61d5c6eb6d895b6527e3f05071e"},
-    {file = "msgpack-1.1.2-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:fffee09044073e69f2bad787071aeec727183e7580443dfeb8556cbf1978d162"},
-    {file = "msgpack-1.1.2-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:5928604de9b032bc17f5099496417f113c45bc6bc21b5c6920caf34b3c428794"},
-    {file = "msgpack-1.1.2-cp313-cp313-win32.whl", hash = "sha256:a7787d353595c7c7e145e2331abf8b7ff1e6673a6b974ded96e6d4ec09f00c8c"},
-    {file = "msgpack-1.1.2-cp313-cp313-win_amd64.whl", hash = "sha256:a465f0dceb8e13a487e54c07d04ae3ba131c7c5b95e2612596eafde1dccf64a9"},
-    {file = "msgpack-1.1.2-cp313-cp313-win_arm64.whl", hash = "sha256:e69b39f8c0aa5ec24b57737ebee40be647035158f14ed4b40e6f150077e21a84"},
-    {file = "msgpack-1.1.2-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:e23ce8d5f7aa6ea6d2a2b326b4ba46c985dbb204523759984430db7114f8aa00"},
-    {file = "msgpack-1.1.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:6c15b7d74c939ebe620dd8e559384be806204d73b4f9356320632d783d1f7939"},
-    {file = "msgpack-1.1.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:99e2cb7b9031568a2a5c73aa077180f93dd2e95b4f8d3b8e14a73ae94a9e667e"},
-    {file = "msgpack-1.1.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:180759d89a057eab503cf62eeec0aa61c4ea1200dee709f3a8e9397dbb3b6931"},
-    {file = "msgpack-1.1.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:04fb995247a6e83830b62f0b07bf36540c213f6eac8e851166d8d86d83cbd014"},
-    {file = "msgpack-1.1.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8e22ab046fa7ede9e36eeb4cfad44d46450f37bb05d5ec482b02868f451c95e2"},
-    {file = "msgpack-1.1.2-cp314-cp314-win32.whl", hash = "sha256:80a0ff7d4abf5fecb995fcf235d4064b9a9a8a40a3ab80999e6ac1e30b702717"},
-    {file = "msgpack-1.1.2-cp314-cp314-win_amd64.whl", hash = "sha256:9ade919fac6a3e7260b7f64cea89df6bec59104987cbea34d34a2fa15d74310b"},
-    {file = "msgpack-1.1.2-cp314-cp314-win_arm64.whl", hash = "sha256:59415c6076b1e30e563eb732e23b994a61c159cec44deaf584e5cc1dd662f2af"},
-    {file = "msgpack-1.1.2-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:897c478140877e5307760b0ea66e0932738879e7aa68144d9b78ea4c8302a84a"},
-    {file = "msgpack-1.1.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a668204fa43e6d02f89dbe79a30b0d67238d9ec4c5bd8a940fc3a004a47b721b"},
-    {file = "msgpack-1.1.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5559d03930d3aa0f3aacb4c42c776af1a2ace2611871c84a75afe436695e6245"},
-    {file = "msgpack-1.1.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:70c5a7a9fea7f036b716191c29047374c10721c389c21e9ffafad04df8c52c90"},
-    {file = "msgpack-1.1.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:f2cb069d8b981abc72b41aea1c580ce92d57c673ec61af4c500153a626cb9e20"},
-    {file = "msgpack-1.1.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:d62ce1f483f355f61adb5433ebfd8868c5f078d1a52d042b0a998682b4fa8c27"},
-    {file = "msgpack-1.1.2-cp314-cp314t-win32.whl", hash = "sha256:1d1418482b1ee984625d88aa9585db570180c286d942da463533b238b98b812b"},
-    {file = "msgpack-1.1.2-cp314-cp314t-win_amd64.whl", hash = "sha256:5a46bf7e831d09470ad92dff02b8b1ac92175ca36b087f904a0519857c6be3ff"},
-    {file = "msgpack-1.1.2-cp314-cp314t-win_arm64.whl", hash = "sha256:d99ef64f349d5ec3293688e91486c5fdb925ed03807f64d98d205d2713c60b46"},
-    {file = "msgpack-1.1.2-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:ea5405c46e690122a76531ab97a079e184c0daf491e588592d6a23d3e32af99e"},
-    {file = "msgpack-1.1.2-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:9fba231af7a933400238cb357ecccf8ab5d51535ea95d94fc35b7806218ff844"},
-    {file = "msgpack-1.1.2-cp39-cp39-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:a8f6e7d30253714751aa0b0c84ae28948e852ee7fb0524082e6716769124bc23"},
-    {file = "msgpack-1.1.2-cp39-cp39-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:94fd7dc7d8cb0a54432f296f2246bc39474e017204ca6f4ff345941d4ed285a7"},
-    {file = "msgpack-1.1.2-cp39-cp39-musllinux_1_2_aarch64.whl", hash = "sha256:350ad5353a467d9e3b126d8d1b90fe05ad081e2e1cef5753f8c345217c37e7b8"},
-    {file = "msgpack-1.1.2-cp39-cp39-musllinux_1_2_x86_64.whl", hash = "sha256:6bde749afe671dc44893f8d08e83bf475a1a14570d67c4bb5cec5573463c8833"},
-    {file = "msgpack-1.1.2-cp39-cp39-win32.whl", hash = "sha256:ad09b984828d6b7bb52d1d1d0c9be68ad781fa004ca39216c8a1e63c0f34ba3c"},
-    {file = "msgpack-1.1.2-cp39-cp39-win_amd64.whl", hash = "sha256:67016ae8c8965124fdede9d3769528ad8284f14d635337ffa6a713a580f6c030"},
-    {file = "msgpack-1.1.2.tar.gz", hash = "sha256:3b60763c1373dd60f398488069bcdc703cd08a711477b5d480eecc9f9626f47e"},
+    {file = "msgpack-1.2.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:8c7b398c56ff125feae96c2737abfec5595f1fa0aa186df60c56040b8accb95c"},
+    {file = "msgpack-1.2.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:1548006a91aa93c5da81f3bdcebc1a0d10cea2d25969754fbe848da622b2b895"},
+    {file = "msgpack-1.2.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1dabedcd0f23559f3596428c6589c1cd8c6eaed3a0d720795b07b0225d769203"},
+    {file = "msgpack-1.2.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:83efa1c898e0fc5380fc0cabbf75164c52e3b5cbb45973710d75821928380c73"},
+    {file = "msgpack-1.2.1-cp310-cp310-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:01e2dd6c9b19d333a00282330cc8a73d38d8dabc306dc5b42cd668c3ac82e833"},
+    {file = "msgpack-1.2.1-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:350cb813d0af6e65d2f7ef0d729f7ff5be5a8bce03665892f43e5883d4ecc1b8"},
+    {file = "msgpack-1.2.1-cp310-cp310-musllinux_1_2_riscv64.whl", hash = "sha256:ee1d9ed27d0497b848923746cf762ed2e7db24f4be7eec8e5cbe8c766aa707b7"},
+    {file = "msgpack-1.2.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:633727297ed063441fd1cda2288865487f33ad14eeb8831afb5f0c396a62cfce"},
+    {file = "msgpack-1.2.1-cp310-cp310-win32.whl", hash = "sha256:298872ecf9e61950f1c6af4ca969b859ee91783bb920ef6e6172697d0c8aad74"},
+    {file = "msgpack-1.2.1-cp310-cp310-win_amd64.whl", hash = "sha256:2ff164c1b0bcb740b073b99e945234d0212852fa378e44a208c425379140dbeb"},
+    {file = "msgpack-1.2.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:29a3f6e9667868429d8240dfd063ea5ffdc1321c13d783aa23827a38de0dcb22"},
+    {file = "msgpack-1.2.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:aded5bdf32609dc7987a49bbbd15a8ef096193f96dd8bbeb791de729e650acf5"},
+    {file = "msgpack-1.2.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:146ee4e9ce80b365c6d4c47073da9da7bcec473e58194ceee5dd7620ace77e06"},
+    {file = "msgpack-1.2.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a28d076ca7c82b9c8728ad90b7147489449557038bed50e4241eb832395169b4"},
+    {file = "msgpack-1.2.1-cp311-cp311-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7d31c0ac0c640f877804c67cb2bc9f4e23dc2db97e96c2e67fa27d38283b41f8"},
+    {file = "msgpack-1.2.1-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:8ff92d7feeaf5bc26c51495b69e2f99ed97ab79346fb6555f44be7dd2ac6503b"},
+    {file = "msgpack-1.2.1-cp311-cp311-musllinux_1_2_riscv64.whl", hash = "sha256:779197a6513bab3c3632265e3d0f7cb3227e62510841a6f34f1eaa37efbb345e"},
+    {file = "msgpack-1.2.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:67f6dd22fa72a93752643f07889796d62739a13415ee630169a8ce764f86cf9f"},
+    {file = "msgpack-1.2.1-cp311-cp311-win32.whl", hash = "sha256:91054a783328e0ea7954b8771095705c8d2243b814743fbaadf14552c9c52c5d"},
+    {file = "msgpack-1.2.1-cp311-cp311-win_amd64.whl", hash = "sha256:2eda0b7ebb1283a98d3e4492ac933c8af6aff59fd3df1c3ed024f536af4b1dc8"},
+    {file = "msgpack-1.2.1-cp311-cp311-win_arm64.whl", hash = "sha256:6ee967f7c7e1df2890c671ff2ee51a28ded0efc95da3e507176dee881ce36c66"},
+    {file = "msgpack-1.2.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:2ef59c659f289eddf8aa6623823f19fa2f40a4029266889eac7a2505dd210c35"},
+    {file = "msgpack-1.2.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d3567748a5107cb40cdf66a275430c2f87c07777698f4bfd25c35f44d533258c"},
+    {file = "msgpack-1.2.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:60926b75d00c8e816ef98f3034f484a8bc64242d66839cef4cf7e503142316a0"},
+    {file = "msgpack-1.2.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:020e881a764b20d8d7ca1a54fc01b8175519d108e3c3f194fddc200bda95951a"},
+    {file = "msgpack-1.2.1-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:4202c74688ca06591f78cb18988228bd4cca2cc75d57b60008372892d2f1e6e6"},
+    {file = "msgpack-1.2.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8b267ce94efb76fbd1b3373511420074ee3187f0f7811bf394531de13294735a"},
+    {file = "msgpack-1.2.1-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:e4f1d0f8f98ade9634e01fb704a408f9336c0a8f1117b369f5db83dc7551d8b1"},
+    {file = "msgpack-1.2.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:f02cf17a6ca1abe29b5f980644f7551f94d71f2011509b26d8625ce038f0df64"},
+    {file = "msgpack-1.2.1-cp312-cp312-win32.whl", hash = "sha256:0c0d9802354507bcba62af19c17918e3eb437cc25e6f50657d511b5856a77aac"},
+    {file = "msgpack-1.2.1-cp312-cp312-win_amd64.whl", hash = "sha256:5c24aa15d5963051e1a5c62b12c50cd705992502b5ec1f3bece6046f33c9fc24"},
+    {file = "msgpack-1.2.1-cp312-cp312-win_arm64.whl", hash = "sha256:4227224aaec8f7fbcbfbd4272319347b2bb4030366502600f8c45588c5187b07"},
+    {file = "msgpack-1.2.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0a70e3cf2804a300d921bb0940426e35f4e489a23adfb77a808892241db0a064"},
+    {file = "msgpack-1.2.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:491cc39455ca765fad51fb451bf2915eb2cf41192ab5801ce8d67c1d614fe056"},
+    {file = "msgpack-1.2.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f310233ef7fb9c14e201c93639fe5f5260b005f56f0b29048e999c30935596cc"},
+    {file = "msgpack-1.2.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:787c9bebb5833e8f6fc8abca3c0597683d8d87f56a8842b6b89c75a5f3176e2d"},
+    {file = "msgpack-1.2.1-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:dc871b997a9370d855b7394465f2f350e847a5b806dd38dcc9c989e7d87da155"},
+    {file = "msgpack-1.2.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:85f57e960d877f2977f6430896191b04a21f8901b3b4baf2e4604329f4db5402"},
+    {file = "msgpack-1.2.1-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:1233ee2dd0cefba127583de50ea654677277047d238303521db35def3d7b2e7c"},
+    {file = "msgpack-1.2.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:e3dc2feb0876209d9c38aa56cb1de169bd6c4348f1aa48271f241226590993e6"},
+    {file = "msgpack-1.2.1-cp313-cp313-win32.whl", hash = "sha256:6d09badf350af2be9d189184e04e64cf54ad93569ab3d96fca58bd3e84aad707"},
+    {file = "msgpack-1.2.1-cp313-cp313-win_amd64.whl", hash = "sha256:33f14fba63278b714efe6ad07e50ea5f03d91537aa6a1c5f1ceca4cf44013ca9"},
+    {file = "msgpack-1.2.1-cp313-cp313-win_arm64.whl", hash = "sha256:afc5febcd4c99effbc02b528e49d6fd0760b2b7d48c05239e345a5fa6e743d9a"},
+    {file = "msgpack-1.2.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:05f340e47e7e47d2da8db9b53e1bb1d294369e9ef45a747441309f6650b8351d"},
+    {file = "msgpack-1.2.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:810b916696c86ef0deb3b74588480224df4c1b071136c34183e4a2a4284d7ac7"},
+    {file = "msgpack-1.2.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ca0dacff965c47afdc3749a8469d7302a8f801d6a28758d55120d75e66ce6889"},
+    {file = "msgpack-1.2.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0e2bf9280bceb5efca998435904b5d3e9fdbcc11d90dc9df30aec7973252b720"},
+    {file = "msgpack-1.2.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:aa6c4be5d1c02a42b066ca6ddb71adf36432868fdcdb6ee87e634e86e0674190"},
+    {file = "msgpack-1.2.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ec0e675d59150a6269ddc9139087c722292664a37d071a849c05c473350f1f2d"},
+    {file = "msgpack-1.2.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:dd3bfe82d53edfe4b7fc9a7ec9761e23a7a5b1dac22264505af428253c29ed24"},
+    {file = "msgpack-1.2.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5ad5467fc3f68b5468e06c5f788d712e9f8ffc8b0cd1bcb160c105c1ee92dae7"},
+    {file = "msgpack-1.2.1-cp314-cp314-win32.whl", hash = "sha256:98b58bdb89c46190e4609bb36abe17c6d4105ad13f9c5f8f6f64d320f8ced3fb"},
+    {file = "msgpack-1.2.1-cp314-cp314-win_amd64.whl", hash = "sha256:74847557e28ce71bd3c438a447ca90e4b507e997ddbdef8a12a7b283b86c156b"},
+    {file = "msgpack-1.2.1-cp314-cp314-win_arm64.whl", hash = "sha256:b50b727bd652bdc37d950336c848ef20ec54a4cafc38dce19b1cd86ad625d0f7"},
+    {file = "msgpack-1.2.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:8d00f177ca88a77c1cf848d204a38f249751650b601cb6532acc68805d8a8273"},
+    {file = "msgpack-1.2.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5bb9c386f0a329c035ddbab4b72d1028bf9627add8dda41070288563d57ed1b1"},
+    {file = "msgpack-1.2.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:20466cca18c49c7292a8984bc15d65857b171e7264bdcb5f96baf8be238791fc"},
+    {file = "msgpack-1.2.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:196300e7e5d6e74d50f1607ab9c06c4a1484c383cd22defd727902591f7e8dde"},
+    {file = "msgpack-1.2.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:575957e79cd51903a4e8495a242442949641e08f1efd5197b43bebd3ea7682b4"},
+    {file = "msgpack-1.2.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8c2ed1e48cc0f460bf3c7780e7137ff21a4e18433451916f2442c1b21036cd7d"},
+    {file = "msgpack-1.2.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:5f6277e5f783c36786a145e0247fc189a03f35f84b251646e53592d2bc12b355"},
+    {file = "msgpack-1.2.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f9389552ecf4784886345ead0647e4edc96bee37cbab05b75540f542f766c48c"},
+    {file = "msgpack-1.2.1-cp314-cp314t-win32.whl", hash = "sha256:c1c79a604a2969a868a78b6ebd27a887e00c624f14f66b3038e0590cb23332d1"},
+    {file = "msgpack-1.2.1-cp314-cp314t-win_amd64.whl", hash = "sha256:f12038a35fabd52e56a3547bab42401af49a45caa6dd00b34c44de235bc93ee2"},
+    {file = "msgpack-1.2.1-cp314-cp314t-win_arm64.whl", hash = "sha256:0adcf06ffde0777c0e1a9b771a2b1c4226ba1bbf748c8efcc02fcdeca3299107"},
+    {file = "msgpack-1.2.1.tar.gz", hash = "sha256:04c721c2c7448767e9e3f2520a475663d8ee0f09c31890f6d2bd70fd636a9647"},
 ]
 
 [[package]]
@@ -4963,7 +4964,7 @@ files = [
     {file = "pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992"},
     {file = "pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29"},
 ]
-markers = {main = "(platform_python_implementation != \"PyPy\" or os_name == \"nt\" and implementation_name != \"pypy\") and implementation_name != \"PyPy\"", dev = "platform_python_implementation != \"PyPy\" and implementation_name != \"PyPy\""}
+markers = {main = "(os_name == \"nt\" and implementation_name != \"pypy\" or platform_python_implementation != \"PyPy\") and implementation_name != \"PyPy\"", dev = "platform_python_implementation != \"PyPy\" and implementation_name != \"PyPy\""}
 
 [[package]]
 name = "pydantic"
@@ -5122,14 +5123,14 @@ typing-extensions = ">=4.14.1"
 
 [[package]]
 name = "pydantic-settings"
-version = "2.14.0"
+version = "2.14.2"
 description = "Settings management using Pydantic"
 optional = false
 python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "pydantic_settings-2.14.0-py3-none-any.whl", hash = "sha256:fc8d5d692eb7092e43c8647c1c35a3ecd00e040fcf02ed86f4cb5458ca62182e"},
-    {file = "pydantic_settings-2.14.0.tar.gz", hash = "sha256:24285fd4b0e0c06507dd9fdfd331ee23794305352aaec8fc4eb92d4047aeb67d"},
+    {file = "pydantic_settings-2.14.2-py3-none-any.whl", hash = "sha256:a20c97b37910b6550d5ea50fbcc2d4187defe58cd57070b73863d069419c9440"},
+    {file = "pydantic_settings-2.14.2.tar.gz", hash = "sha256:c19dd64b19097f1de80184f0cc7b0272a13ae6e170cbf240a3e27e381ed14a5f"},
 ]
 
 [package.dependencies]
@@ -5174,14 +5175,14 @@ windows-terminal = ["colorama (>=0.4.6)"]
 
 [[package]]
 name = "pyjwt"
-version = "2.12.1"
+version = "2.13.0"
 description = "JSON Web Token implementation in Python"
 optional = false
 python-versions = ">=3.9"
 groups = ["main"]
 files = [
-    {file = "pyjwt-2.12.1-py3-none-any.whl", hash = "sha256:28ca37c070cad8ba8cd9790cd940535d40274d22f80ab87f3ac6a713e6e8454c"},
-    {file = "pyjwt-2.12.1.tar.gz", hash = "sha256:c74a7a2adf861c04d002db713dd85f84beb242228e671280bf709d765b03672b"},
+    {file = "pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728"},
+    {file = "pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423"},
 ]
 
 [package.dependencies]
@@ -5189,20 +5190,17 @@ cryptography = {version = ">=3.4.0", optional = true, markers = "extra == \"cryp
 
 [package.extras]
 crypto = ["cryptography (>=3.4.0)"]
-dev = ["coverage[toml] (==7.10.7)", "cryptography (>=3.4.0)", "pre-commit", "pytest (>=8.4.2,<9.0.0)", "sphinx", "sphinx-rtd-theme", "zope.interface"]
-docs = ["sphinx", "sphinx-rtd-theme", "zope.interface"]
-tests = ["coverage[toml] (==7.10.7)", "pytest (>=8.4.2,<9.0.0)"]
 
 [[package]]
 name = "pylint"
-version = "4.0.5"
+version = "4.0.6"
 description = "python code static checker"
 optional = false
 python-versions = ">=3.10.0"
 groups = ["main", "dev"]
 files = [
-    {file = "pylint-4.0.5-py3-none-any.whl", hash = "sha256:00f51c9b14a3b3ae08cff6b2cdd43f28165c78b165b628692e428fb1f8dc2cf2"},
-    {file = "pylint-4.0.5.tar.gz", hash = "sha256:8cd6a618df75deb013bd7eb98327a95f02a6fb839205a6bbf5456ef96afb317c"},
+    {file = "pylint-4.0.6-py3-none-any.whl", hash = "sha256:d11a0e1fdb7b1cd46ec5d6fc78fee8b95f28695b2d6140e5809925f61e32ea54"},
+    {file = "pylint-4.0.6.tar.gz", hash = "sha256:52f19191bee08bf103f9705ad1a0ece4aa5a0a4ef2bdcbd969375a1e6f6579d5"},
 ]
 
 [package.dependencies]
@@ -5220,13 +5218,14 @@ testutils = ["gitpython (>3)"]
 
 [[package]]
 name = "pylint-django"
-version = "2.7.0"
+version = "2.8.0"
 description = "A Pylint plugin to help Pylint understand the Django web framework"
 optional = false
 python-versions = "<4.0,>=3.9"
 groups = ["main", "dev"]
 files = [
-    {file = "pylint_django-2.7.0-py3-none-any.whl", hash = "sha256:76ef7e7bbbcf7ee86adbb2beac0ffaa7232509a17bf4a488d81467a1bbaa215b"},
+    {file = "pylint_django-2.8.0-py3-none-any.whl", hash = "sha256:706eb2cc8d7692236be9fd033a341042afe3bbbf99df9234a659db931016ef5d"},
+    {file = "pylint_django-2.8.0.tar.gz", hash = "sha256:42accea9098e4a3298b4bfbae0e4da81f909f8bff0deda9485efbd6035a86d6a"},
 ]
 
 [package.dependencies]
@@ -5287,22 +5286,23 @@ diagrams = ["jinja2", "railroad-diagrams"]
 
 [[package]]
 name = "pypdf"
-version = "6.10.2"
+version = "6.14.2"
 description = "A pure-python PDF library capable of splitting, merging, cropping, and transforming PDF files"
 optional = false
 python-versions = ">=3.9"
 groups = ["main"]
 files = [
-    {file = "pypdf-6.10.2-py3-none-any.whl", hash = "sha256:aa53be9826655b51c96741e5d7983ca224d898ac0a77896e64636810517624aa"},
-    {file = "pypdf-6.10.2.tar.gz", hash = "sha256:7d09ce108eff6bf67465d461b6ef352dcb8d84f7a91befc02f904455c6eea11d"},
+    {file = "pypdf-6.14.2-py3-none-any.whl", hash = "sha256:3f07891af76dc002657e04993ab9b4de81de29f9013b9761d0b7968bff12e946"},
+    {file = "pypdf-6.14.2.tar.gz", hash = "sha256:7873f502fe4385e79539b21d872392dc0c4e3714327c15881cbc7fbfd1f95b25"},
 ]
 
 [package.extras]
-crypto = ["cryptography"]
+crypto = ["cryptography (>3.0)"]
 cryptodome = ["PyCryptodome"]
 dev = ["flit", "pip-tools", "pre-commit", "pytest-cov", "pytest-socket", "pytest-timeout", "pytest-xdist", "wheel"]
 docs = ["myst_parser", "sphinx", "sphinx_rtd_theme"]
-full = ["Pillow (>=8.0.0)", "cryptography"]
+fonts = ["fonttools"]
+full = ["Pillow (>=8.0.0)", "cryptography (>3.0)", "fonttools"]
 image = ["Pillow (>=8.0.0)"]
 
 [[package]]
@@ -5339,23 +5339,19 @@ files = [
 
 [[package]]
 name = "pyproject-api"
-version = "1.10.0"
+version = "1.10.1"
 description = "API to interact with the python pyproject.toml based projects"
 optional = false
 python-versions = ">=3.10"
 groups = ["dev"]
 files = [
-    {file = "pyproject_api-1.10.0-py3-none-any.whl", hash = "sha256:8757c41a79c0f4ab71b99abed52b97ecf66bd20b04fa59da43b5840bac105a09"},
-    {file = "pyproject_api-1.10.0.tar.gz", hash = "sha256:40c6f2d82eebdc4afee61c773ed208c04c19db4c4a60d97f8d7be3ebc0bbb330"},
+    {file = "pyproject_api-1.10.1-py3-none-any.whl", hash = "sha256:fa9e6f66c35b5017e909825d8f2b5d5482ea699d7be809d21c03bd1f7317f36a"},
+    {file = "pyproject_api-1.10.1.tar.gz", hash = "sha256:c2b2726bd7aa9217b6c50b621fef5b2ae5def4d55b779c9e0694c15e0a8517ba"},
 ]
 
 [package.dependencies]
 packaging = ">=25"
 
-[package.extras]
-docs = ["furo (>=2025.9.25)", "sphinx-autodoc-typehints (>=3.5.1)"]
-testing = ["covdefaults (>=2.3)", "pytest (>=8.4.2)", "pytest-cov (>=7)", "pytest-mock (>=3.15.1)", "setuptools (>=80.9)"]
-
 [[package]]
 name = "pysocks"
 version = "1.7.1"
@@ -5505,14 +5501,14 @@ Levenshtein = "0.27.3"
 
 [[package]]
 name = "python-multipart"
-version = "0.0.27"
+version = "0.0.32"
 description = "A streaming multipart parser for Python"
 optional = false
 python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "python_multipart-0.0.27-py3-none-any.whl", hash = "sha256:6fccfad17a27334bd0193681b369f476eda3409f17381a2d65aa7df3f7275645"},
-    {file = "python_multipart-0.0.27.tar.gz", hash = "sha256:9870a6a8c5a20a5bf4f07c017bd1489006ff8836cff097b6933355ee2b49b602"},
+    {file = "python_multipart-0.0.32-py3-none-any.whl", hash = "sha256:ff6d3f776f16878c894e52e107296ffc890e913c611b1a4ec6c44e2821fe2e23"},
+    {file = "python_multipart-0.0.32.tar.gz", hash = "sha256:be54b7f3fa167bb83e4fcd936b887b708f4e57fe75911c02aebf53efaf8d938e"},
 ]
 
 [[package]]
@@ -6344,14 +6340,14 @@ uvicorn = ["uvicorn (>=0.34.0)"]
 
 [[package]]
 name = "starlette"
-version = "1.2.1"
+version = "1.3.1"
 description = "The little ASGI library that shines."
 optional = false
 python-versions = ">=3.10"
 groups = ["main"]
 files = [
-    {file = "starlette-1.2.1-py3-none-any.whl", hash = "sha256:4de0082d08c8f6764a85a54cf1120d6939507a19905c7768acad2a9f875d2b89"},
-    {file = "starlette-1.2.1.tar.gz", hash = "sha256:9b9b5ebb992e67d6093741e63c2f59e4f6fff986f81163c087867bd7b924b3f6"},
+    {file = "starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6"},
+    {file = "starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0"},
 ]
 
 [package.dependencies]
@@ -6359,7 +6355,7 @@ anyio = ">=3.6.2,<5"
 typing-extensions = {version = ">=4.10.0", markers = "python_version < \"3.13\""}
 
 [package.extras]
-full = ["httpx (>=0.27.0,<0.29.0)", "itsdangerous", "jinja2", "python-multipart (>=0.0.18)", "pyyaml"]
+full = ["httpx (>=0.27.0,<0.29.0)", "httpx2 (>=2.0.0)", "itsdangerous", "jinja2", "python-multipart (>=0.0.18)", "pyyaml"]
 
 [[package]]
 name = "stone"
diff --git a/requirements.txt b/requirements.txt
index 48ef4377f..ea0bd3690 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -17,10 +17,10 @@ beautifulsoup4==4.14.3 ; python_version >= "3.12" and python_version < "4.0"
 billiard==4.2.4 ; python_version >= "3.12" and python_version < "4.0"
 black==26.5.1 ; python_version >= "3.12" and python_version < "4.0"
 blinker==1.9.0 ; python_version >= "3.12" and python_version < "4.0"
-cachetools==7.1.1 ; python_version >= "3.12" and python_version < "4.0"
+cachetools==7.1.4 ; python_version >= "3.12" and python_version < "4.0"
 celery==5.6.3 ; python_version >= "3.12" and python_version < "4.0"
 certifi==2026.6.17 ; python_version >= "3.12" and python_version < "4.0"
-cffi==2.0.0 ; python_version >= "3.12" and python_version < "4.0" and (platform_python_implementation != "PyPy" or os_name == "nt") and (platform_python_implementation != "PyPy" or implementation_name != "pypy")
+cffi==2.0.0 ; python_version >= "3.12" and python_version < "4.0" and (os_name == "nt" or platform_python_implementation != "PyPy") and (implementation_name != "pypy" or platform_python_implementation != "PyPy")
 cfgv==3.5.0 ; python_version >= "3.12" and python_version < "4.0"
 channels-redis==4.3.0 ; python_version >= "3.12" and python_version < "4.0"
 channels==4.3.2 ; python_version >= "3.12" and python_version < "4.0"
@@ -33,7 +33,7 @@ colorama==0.4.6 ; python_version >= "3.12" and python_version < "4.0"
 concurrent-log-handler==0.9.29 ; python_version >= "3.12" and python_version < "4.0"
 contourpy==1.3.3 ; python_version >= "3.12" and python_version < "4.0"
 cron-descriptor==1.4.5 ; python_version >= "3.12" and python_version < "4.0"
-cryptography==47.0.0 ; python_version >= "3.12" and python_version < "4.0"
+cryptography==49.0.0 ; python_version >= "3.12" and python_version < "4.0"
 cycler==0.12.1 ; python_version >= "3.12" and python_version < "4.0"
 debugpy==1.8.20 ; python_version >= "3.12" and python_version < "4.0"
 deptry==0.25.1 ; python_version >= "3.12" and python_version < "4.0"
@@ -51,7 +51,7 @@ django-solo==2.5.1 ; python_version >= "3.12" and python_version < "4.0"
 django-stubs-ext==6.0.3 ; python_version >= "3.12" and python_version < "4.0"
 django-stubs==6.0.3 ; python_version >= "3.12" and python_version < "4.0"
 django-timezone-field==7.2.1 ; python_version >= "3.12" and python_version < "4.0"
-django==6.0.4 ; python_version >= "3.12" and python_version < "4.0"
+django==6.0.7 ; python_version >= "3.12" and python_version < "4.0"
 djangorestframework-simplejwt==5.5.1 ; python_version >= "3.12" and python_version < "4.0"
 djangorestframework-stubs==3.16.9 ; python_version >= "3.12" and python_version < "4.0"
 djangorestframework==3.17.1 ; python_version >= "3.12" and python_version < "4.0"
@@ -115,8 +115,8 @@ matplotlib==3.10.9 ; python_version >= "3.12" and python_version < "4.0"
 mccabe==0.7.0 ; python_version >= "3.12" and python_version < "4.0"
 mcp==1.27.0 ; python_version >= "3.12" and python_version < "4.0"
 mdurl==0.1.2 ; python_version >= "3.12" and python_version < "3.14"
-mistralai==2.4.9 ; python_version >= "3.12" and python_version < "4.0"
-msgpack==1.1.2 ; python_version >= "3.12" and python_version < "4.0"
+mistralai==2.6.0 ; python_version >= "3.12" and python_version < "4.0"
+msgpack==1.2.1 ; python_version >= "3.12" and python_version < "4.0"
 multidict==6.7.1 ; python_version >= "3.12" and python_version < "3.14"
 mypy-baseline==0.7.4 ; python_version >= "3.12" and python_version < "4.0"
 mypy-extensions==1.1.0 ; python_version >= "3.12" and python_version < "4.0"
@@ -154,19 +154,19 @@ pyasn1==0.6.3 ; python_version >= "3.12" and python_version < "4.0"
 pycodestyle==2.14.0 ; python_version >= "3.12" and python_version < "4.0"
 pycparser==3.0 ; python_version >= "3.12" and python_version < "4.0" and (platform_python_implementation != "PyPy" or os_name == "nt") and (platform_python_implementation != "PyPy" or implementation_name != "pypy" and implementation_name != "PyPy") and implementation_name != "PyPy"
 pydantic-core==2.46.4 ; python_version >= "3.12" and python_version < "4.0"
-pydantic-settings==2.14.0 ; python_version >= "3.12" and python_version < "4.0"
+pydantic-settings==2.14.2 ; python_version >= "3.12" and python_version < "4.0"
 pydantic==2.13.4 ; python_version >= "3.12" and python_version < "4.0"
 pyflakes==3.4.0 ; python_version >= "3.12" and python_version < "4.0"
 pygments==2.20.0 ; python_version >= "3.12" and python_version < "4.0"
-pyjwt==2.12.1 ; python_version >= "3.12" and python_version < "4.0"
-pylint-django==2.7.0 ; python_version >= "3.12" and python_version < "4.0"
+pyjwt==2.13.0 ; python_version >= "3.12" and python_version < "4.0"
+pylint-django==2.8.0 ; python_version >= "3.12" and python_version < "4.0"
 pylint-plugin-utils==0.9.0 ; python_version >= "3.12" and python_version < "4.0"
-pylint==4.0.5 ; python_version >= "3.12" and python_version < "4.0"
+pylint==4.0.6 ; python_version >= "3.12" and python_version < "4.0"
 pyngrok==7.5.1 ; python_version >= "3.12" and python_version < "4.0"
 pyparsing==3.3.2 ; python_version >= "3.12" and python_version < "4.0"
-pypdf==6.10.2 ; python_version >= "3.12" and python_version < "4.0"
+pypdf==6.14.2 ; python_version >= "3.12" and python_version < "4.0"
 pypdfium2==5.7.1 ; python_version >= "3.12" and python_version < "4.0"
-pyproject-api==1.10.0 ; python_version >= "3.12" and python_version < "4.0"
+pyproject-api==1.10.1 ; python_version >= "3.12" and python_version < "4.0"
 pysocks==1.7.1 ; python_version >= "3.12" and python_version < "4.0"
 pytest-django==4.12.0 ; python_version >= "3.12" and python_version < "4.0"
 pytest==9.0.3 ; python_version >= "3.12" and python_version < "4.0"
@@ -176,7 +176,7 @@ python-discovery==1.4.2 ; python_version >= "3.12" and python_version < "4.0"
 python-docx==1.2.0 ; python_version >= "3.12" and python_version < "4.0"
 python-dotenv==1.2.2 ; python_version >= "3.12" and python_version < "4.0"
 python-levenshtein==0.27.3 ; python_version >= "3.12" and python_version < "4.0"
-python-multipart==0.0.27 ; python_version >= "3.12" and python_version < "4.0"
+python-multipart==0.0.32 ; python_version >= "3.12" and python_version < "4.0"
 python-stdnum==2.2 ; python_version >= "3.12" and python_version < "4.0"
 pytokens==0.4.1 ; python_version >= "3.12" and python_version < "4.0"
 pytz==2026.2 ; python_version >= "3.12" and python_version < "4.0"
@@ -201,7 +201,7 @@ sortedcontainers==2.4.0 ; python_version >= "3.12" and python_version < "4.0"
 soupsieve==2.8.4 ; python_version >= "3.12" and python_version < "4.0"
 sqlparse==0.5.5 ; python_version >= "3.12" and python_version < "4.0"
 sse-starlette==3.4.1 ; python_version >= "3.12" and python_version < "4.0"
-starlette==1.2.1 ; python_version >= "3.12" and python_version < "4.0"
+starlette==1.3.1 ; python_version >= "3.12" and python_version < "4.0"
 stone==3.3.1 ; python_version >= "3.12" and python_version < "4.0"
 tabulate==0.10.0 ; python_version >= "3.12" and python_version < "4.0"
 tenacity==9.1.4 ; python_version >= "3.12" and python_version < "4.0"

From acfab099adf59f3e16caf51e68dc8321effc64c3 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 16:59:59 +1200
Subject: [PATCH 29/73] fix: run prod backup from active release

---
 scripts/pull_prod_backup.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/pull_prod_backup.sh b/scripts/pull_prod_backup.sh
index 3c7c4158b..36e1f00de 100755
--- a/scripts/pull_prod_backup.sh
+++ b/scripts/pull_prod_backup.sh
@@ -43,7 +43,7 @@ TMP_PATH="/tmp/$DUMP_NAME"
 echo ">> Generating $DUMP_NAME on $REMOTE_HOST as $INSTANCE_USER..."
 # shellcheck disable=SC2029  # $INSTANCE_USER and $TMP_PATH are meant to expand client-side
 ssh "$REMOTE_USER@$REMOTE_HOST" \
-    "sudo -iu $INSTANCE_USER bash -lc 'python manage.py backport_data_backup --output $TMP_PATH'"
+    "sudo -iu $INSTANCE_USER bash -lc 'cd app && python manage.py backport_data_backup --output $TMP_PATH'"
 
 echo ">> Copying $DUMP_NAME to $LOCAL_DIR/..."
 scp "$REMOTE_USER@$REMOTE_HOST:$TMP_PATH" "$LOCAL_DIR/"

From 27de2a3dae131b021e18c5b0436ac2f1cc77d6a6 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:01:02 +0000
Subject: [PATCH 30/73] chore(deps-dev): bump @typescript-eslint/parser in
 /frontend

Bumps [@typescript-eslint/parser](https://github.com/typescript-eslint/typescript-eslint/tree/HEAD/packages/parser) from 8.63.0 to 8.64.0.
- [Release notes](https://github.com/typescript-eslint/typescript-eslint/releases)
- [Changelog](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/parser/CHANGELOG.md)
- [Commits](https://github.com/typescript-eslint/typescript-eslint/commits/v8.64.0/packages/parser)

---
updated-dependencies:
- dependency-name: "@typescript-eslint/parser"
  dependency-version: 8.63.0
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 frontend/package-lock.json | 70 +++++++++++++++++++-------------------
 frontend/package.json      |  2 +-
 2 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index d3ebfaed0..f3b03313d 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -62,7 +62,7 @@
         "@types/js-cookie": "^3.0.6",
         "@types/node": "^25.9.3",
         "@typescript-eslint/eslint-plugin": "^8.59.4",
-        "@typescript-eslint/parser": "^8.63.0",
+        "@typescript-eslint/parser": "^8.64.0",
         "@vitejs/plugin-vue": "^6.0.7",
         "@vue/eslint-config-prettier": "^10.2.0",
         "@vue/eslint-config-typescript": "^14.7.0",
@@ -4466,16 +4466,16 @@
       }
     },
     "node_modules/@typescript-eslint/parser": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.63.0.tgz",
-      "integrity": "sha512-gwh4gvvlaVDKKxyfxMG+Gnu1u9X0OQBwyGLkbwB65dIzBKnxeRiJlNFqlI3zwVhNXJIs6qV7mlFCn/BIajlVig==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.64.0.tgz",
+      "integrity": "sha512-KA0OshtlcCCXmbfqyZkM5pV3/WNraJf7DkJRLpyrmwPtud57H5BDX7C3k0LPSPxpprfRL+cJDGabF10mvNCoCw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/scope-manager": "8.63.0",
-        "@typescript-eslint/types": "8.63.0",
-        "@typescript-eslint/typescript-estree": "8.63.0",
-        "@typescript-eslint/visitor-keys": "8.63.0",
+        "@typescript-eslint/scope-manager": "8.64.0",
+        "@typescript-eslint/types": "8.64.0",
+        "@typescript-eslint/typescript-estree": "8.64.0",
+        "@typescript-eslint/visitor-keys": "8.64.0",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -4491,14 +4491,14 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/project-service": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.63.0.tgz",
-      "integrity": "sha512-e5dh0/UI0ok53AlZ5wRkXCB32z/f2jUZqPR/ygAw5WYaSw8j9EoJWlS7wQjr/dmOaqWjnPIn2m+HhVPCMWGZVQ==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/project-service/-/project-service-8.64.0.tgz",
+      "integrity": "sha512-tk4WpOJ6IEbGrVHaNmM0YRrwAD3exZlIK3iadQNAxh4YKk6jvUQ4ecq18n+v7+meh+cJ3j+D8nbk8sRKhlwLQg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/tsconfig-utils": "^8.63.0",
-        "@typescript-eslint/types": "^8.63.0",
+        "@typescript-eslint/tsconfig-utils": "^8.64.0",
+        "@typescript-eslint/types": "^8.64.0",
         "debug": "^4.4.3"
       },
       "engines": {
@@ -4513,14 +4513,14 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/scope-manager": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.63.0.tgz",
-      "integrity": "sha512-uUyfMWCnDSN8bCpcrY8nGP2BLkQ9Xn0GsipcONcpIDWhwhO4ZSyHvyS14U3X75mzxWxL3I2UZIrenTzdzcJO8A==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/scope-manager/-/scope-manager-8.64.0.tgz",
+      "integrity": "sha512-CXEaFdYXjSTgKhisNkwCcJwTP8Pl+fmRrEQrri4nm3vU743bALrxzLmq7fHG/7e6a5xO0lDYeURpZmBuhHk54w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.63.0",
-        "@typescript-eslint/visitor-keys": "8.63.0"
+        "@typescript-eslint/types": "8.64.0",
+        "@typescript-eslint/visitor-keys": "8.64.0"
       },
       "engines": {
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
@@ -4531,9 +4531,9 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/tsconfig-utils": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.63.0.tgz",
-      "integrity": "sha512-sUAbkulqBAsncKnbRP3+7CtQFRKicexnj7ZwNC6ddCR7EmrXvjvdCYMJbUIqMd6lwoEriZjwLo08aS5tSjVMHg==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/tsconfig-utils/-/tsconfig-utils-8.64.0.tgz",
+      "integrity": "sha512-2yo8rRNKuzbVWQp5kslhANqZ2uDAeROQHBRZNPu8JDsHmeFNj/XJJhX/FhNUWmkHHvoNsKa6+tHJiig87EzsQw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4548,9 +4548,9 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/types": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.63.0.tgz",
-      "integrity": "sha512-xyLtl9DUBBFrcJS4x2pIqGLH68/tC2uOa4Z7pUteW09D3bXnnXUom4dyPikzWgB7llmIc1zoeI3aoUdC4rPK/Q==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.64.0.tgz",
+      "integrity": "sha512-qjhfuTfLXjA4IOzXvz0rTjT01BqEiIgPoUeMwiEjnaHKJMTNo8rH5pYW1a2L/0Dnux2fPC85AeyJoWaGa8WxTA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4562,16 +4562,16 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/typescript-estree": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.63.0.tgz",
-      "integrity": "sha512-ygBkU+B7ex5UI/gKhaqexWev79uISfIv7XQCRNYO/jmD8rGLPyWLAb3KMRT6nd8Gt9bmUBi9+iX6tBdYfOY81Q==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/typescript-estree/-/typescript-estree-8.64.0.tgz",
+      "integrity": "sha512-Pztpsn1aCE1oWDvDEfUk31nngvvF7vUB5SwHFEaZIFpvw7WJtqUHHL4plBZDA9HfWJJjL13BdG0YrJInTUvoVA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/project-service": "8.63.0",
-        "@typescript-eslint/tsconfig-utils": "8.63.0",
-        "@typescript-eslint/types": "8.63.0",
-        "@typescript-eslint/visitor-keys": "8.63.0",
+        "@typescript-eslint/project-service": "8.64.0",
+        "@typescript-eslint/tsconfig-utils": "8.64.0",
+        "@typescript-eslint/types": "8.64.0",
+        "@typescript-eslint/visitor-keys": "8.64.0",
         "debug": "^4.4.3",
         "minimatch": "^10.2.2",
         "semver": "^7.7.3",
@@ -4590,13 +4590,13 @@
       }
     },
     "node_modules/@typescript-eslint/parser/node_modules/@typescript-eslint/visitor-keys": {
-      "version": "8.63.0",
-      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.63.0.tgz",
-      "integrity": "sha512-UexrHGnGTpbuQHct2ExOc2ZcFbGUS9FOesCxxqdBGcpI1BxYu/LZ6U8Aq6/72XtF/qRBk9nhuGHFJIXXMhPMdw==",
+      "version": "8.64.0",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/visitor-keys/-/visitor-keys-8.64.0.tgz",
+      "integrity": "sha512-mrtuL8Nsn6gi2H4mo5KMTp823M+3Q19Ew/i+Zlikq20tIMm99C3Ez0dCmkWWnxut20esQvTg8aUSEhMcAOXhEw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@typescript-eslint/types": "8.63.0",
+        "@typescript-eslint/types": "8.64.0",
         "eslint-visitor-keys": "^5.0.0"
       },
       "engines": {
diff --git a/frontend/package.json b/frontend/package.json
index b5b3e8611..d247755bb 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -85,7 +85,7 @@
     "@types/js-cookie": "^3.0.6",
     "@types/node": "^25.9.3",
     "@typescript-eslint/eslint-plugin": "^8.59.4",
-    "@typescript-eslint/parser": "^8.63.0",
+    "@typescript-eslint/parser": "^8.64.0",
     "@vitejs/plugin-vue": "^6.0.7",
     "@vue/eslint-config-prettier": "^10.2.0",
     "@vue/eslint-config-typescript": "^14.7.0",

From fb985c97a453de2ce8670d9930b2d95148421704 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:01:32 +0000
Subject: [PATCH 31/73] chore(deps): bump ws

Bumps the npm_and_yarn group with 1 update in the /frontend directory: [ws](https://github.com/websockets/ws).


Updates `ws` from 8.20.1 to 8.21.0
- [Release notes](https://github.com/websockets/ws/releases)
- [Commits](https://github.com/websockets/ws/compare/8.20.1...8.21.0)

---
updated-dependencies:
- dependency-name: ws
  dependency-version: 8.21.0
  dependency-type: indirect
  dependency-group: npm_and_yarn
...

Signed-off-by: dependabot[bot] <support@github.com>
---
 frontend/package-lock.json | 32 ++++++++++++++++----------------
 frontend/package.json      |  4 ++--
 2 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/frontend/package-lock.json b/frontend/package-lock.json
index d3ebfaed0..58a35a733 100644
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
@@ -45,7 +45,7 @@
         "tailwind-merge": "^3.6.0",
         "tailwindcss": "^4.3.0",
         "tw-animate-css": "^1.3.4",
-        "uuid": "^14.0.0",
+        "uuid": "^14.0.1",
         "vaul-vue": "^0.4.1",
         "vee-validate": "^4.15.1",
         "vue": "^3.5.39",
@@ -81,7 +81,7 @@
         "puppeteer": "^25.0.2",
         "tsx": "^4.21.0",
         "typescript": "~6.0.3",
-        "vite": "^8.1.3",
+        "vite": "^8.1.4",
         "vite-plugin-vue-devtools": "^8.1.5",
         "vitepress": "2.0.0-alpha.17",
         "vitest": "^4.1.7",
@@ -12728,9 +12728,9 @@
       "license": "MIT"
     },
     "node_modules/uuid": {
-      "version": "14.0.0",
-      "resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.0.tgz",
-      "integrity": "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg==",
+      "version": "14.0.1",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-14.0.1.tgz",
+      "integrity": "sha512-6ZxzVpzDXDa3bJWaHilVayA+BH/1zmxCJoVgvmqJnid/gPoKHxUrS/aC/T6LGQtNHT+XHG9fXPJB4d+IrU30Ew==",
       "funding": [
         "https://github.com/sponsors/broofa",
         "https://github.com/sponsors/ctavan"
@@ -12908,15 +12908,15 @@
       }
     },
     "node_modules/vite": {
-      "version": "8.1.3",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.1.3.tgz",
-      "integrity": "sha512-Ds+gBRbj0lwRO2Y5hwnUBdxSwlAve9LeRyU4sNnAr0ewW0gWF0n5bgXgUzbgZ49MV9BVUAQUFYVcDUcilUExMA==",
+      "version": "8.1.4",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.1.4.tgz",
+      "integrity": "sha512-bTT9PsdWO+MQMNG9ZXIP/qM9wGh37DFxTV/sPq9cFpHr3w4jkgef032PkAL9jAqhk3Nz8NQw3O8n6/xFkqO4QQ==",
       "license": "MIT",
       "dependencies": {
         "lightningcss": "^1.32.0",
-        "picomatch": "^4.0.4",
+        "picomatch": "^4.0.5",
         "postcss": "^8.5.16",
-        "rolldown": "~1.1.3",
+        "rolldown": "~1.1.4",
         "tinyglobby": "^0.2.17"
       },
       "bin": {
@@ -13379,9 +13379,9 @@
       }
     },
     "node_modules/vite/node_modules/picomatch": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
-      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "version": "4.0.5",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz",
+      "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==",
       "license": "MIT",
       "engines": {
         "node": ">=12"
@@ -14185,9 +14185,9 @@
       "license": "ISC"
     },
     "node_modules/ws": {
-      "version": "8.20.1",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.1.tgz",
-      "integrity": "sha512-It4dO0K5v//JtTXuPkfEOaI3uUN87iYPnqo/ZzqCoG3g8uhA66QUMs/SrM0YK7/NAu+r4LMh/9dq2A7k+rHs+w==",
+      "version": "8.21.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+      "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
       "dev": true,
       "license": "MIT",
       "engines": {
diff --git a/frontend/package.json b/frontend/package.json
index b5b3e8611..2b54ef209 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -68,7 +68,7 @@
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.3.4",
-    "uuid": "^14.0.0",
+    "uuid": "^14.0.1",
     "vaul-vue": "^0.4.1",
     "vee-validate": "^4.15.1",
     "vue": "^3.5.39",
@@ -104,7 +104,7 @@
     "puppeteer": "^25.0.2",
     "tsx": "^4.21.0",
     "typescript": "~6.0.3",
-    "vite": "^8.1.3",
+    "vite": "^8.1.4",
     "vite-plugin-vue-devtools": "^8.1.5",
     "vitepress": "2.0.0-alpha.17",
     "vitest": "^4.1.7",

From cee1017160fb8e101ecb0893f6927fe5ce77d27d Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 17:15:41 +1200
Subject: [PATCH 32/73] fix: exclude private config from prod backups

---
 apps/workflow/services/db_scrubber.py   | 38 +++++++++++++-----
 apps/workflow/tests/test_db_scrubber.py | 51 ++++++++++++++++++++++++-
 2 files changed, 78 insertions(+), 11 deletions(-)

diff --git a/apps/workflow/services/db_scrubber.py b/apps/workflow/services/db_scrubber.py
index ae78ed963..d189fb9ad 100644
--- a/apps/workflow/services/db_scrubber.py
+++ b/apps/workflow/services/db_scrubber.py
@@ -6,9 +6,9 @@
   2. Delete the unlinked accounting records that _filter_unlinked_accounting_records dropped.
   3. Truncate the tables in EXCLUDE_MODELS (minus framework tables).
 
-Anything beyond that is OUT OF SCOPE for this task and must NOT be added without
-a separate ticket — see docs/plans/2026-04-25-pg-dump-backport-refresh-plan.md
-"Strict like-for-like contract".
+It additionally excludes DB-backed external-system credentials introduced
+after the legacy command. A scrubbed backup must never carry configuration that
+could authenticate against production services.
 
 Safety: refuses to run unless settings.DATABASES["scrub"]["NAME"] ends in
 "_scrub" — last line of defence against a misconfigured SCRUB_DB_NAME pointing
@@ -18,7 +18,7 @@
 from collections.abc import Callable
 
 from django.conf import settings
-from django.db import transaction
+from django.db import connections, transaction
 from faker import Faker
 
 from apps.accounting.models import (
@@ -265,14 +265,20 @@ def _delete_unlinked_accounting() -> None:
 # xeropayitem would cascade through Job.default_xero_pay_item and
 # CostLine.xero_pay_item and erase every Job and CostLine in the dump.
 # Pay item names aren't PII; letting prod's set through is harmless.
+_PRIVATE_CONFIG_TABLES = (
+    "workflow_aiprovider",
+    "workflow_xeroapp",
+    "workflow_serviceapikey",
+    "crm_phoneprovidersettings",
+    "quoting_suppliercredential",
+)
+
 _EXCLUDED_TABLES = (
     # In joined-table inheritance, child tables have FKs back to parent.
     # TRUNCATE parent WITH CASCADE will cascade to children. Do NOT include
     # child tables — workflow_xeroerror will be cascaded from workflow_apperror.
     "workflow_apperror",  # Parent; CASCADE will delete xeroerror children
-    "workflow_xeroapp",
-    "workflow_serviceapikey",
-    "quoting_suppliercredential",
+    *_PRIVATE_CONFIG_TABLES,
     "accounts_historicalstaff",
     "process_historicalform",
     "process_historicalformentry",
@@ -282,13 +288,26 @@ def _delete_unlinked_accounting() -> None:
 
 def _truncate_excluded_tables() -> None:
     """Mirror legacy EXCLUDE_MODELS by emptying these tables in the scrub DB."""
-    from django.db import connections
-
     with connections[SCRUB_ALIAS].cursor() as cur:
         for table in _EXCLUDED_TABLES:
             cur.execute(f'TRUNCATE TABLE "{table}" RESTART IDENTITY CASCADE')
 
 
+def _assert_private_config_removed() -> None:
+    """Fail closed if a scrubbed DB still contains external credentials."""
+    remaining: list[str] = []
+    with connections[SCRUB_ALIAS].cursor() as cur:
+        for table in _PRIVATE_CONFIG_TABLES:
+            cur.execute(f'SELECT COUNT(*) FROM "{table}"')
+            count = cur.fetchone()[0]
+            if count:
+                remaining.append(f"{table}={count}")
+    if remaining:
+        raise RuntimeError(
+            "Private configuration remained after scrubbing: " + ", ".join(remaining)
+        )
+
+
 def scrub() -> None:
     """Reproduce the legacy command's PII handling on the scrub DB.
 
@@ -303,6 +322,7 @@ def scrub() -> None:
             _scrub_accounting_contacts()
             _delete_unlinked_accounting()
             _truncate_excluded_tables()
+            _assert_private_config_removed()
     except Exception as exc:
         persist_app_error(exc)
         raise
diff --git a/apps/workflow/tests/test_db_scrubber.py b/apps/workflow/tests/test_db_scrubber.py
index b7c034794..6027a9128 100644
--- a/apps/workflow/tests/test_db_scrubber.py
+++ b/apps/workflow/tests/test_db_scrubber.py
@@ -1,14 +1,20 @@
-"""Unit tests for db_scrubber collision-safe value generation.
+"""Unit tests for production database scrubbing contracts.
 
 The full scrub runs against the ``scrub`` DB alias (a restored prod copy) and is
 not exercised here; these tests pin the novel logic that keeps the scrub from
 aborting on a normalized-value collision.
 """
 
+from unittest.mock import MagicMock, patch
+
 from django.test import SimpleTestCase
 
 from apps.company.models import ContactMethod
-from apps.workflow.services.db_scrubber import _unique_scrub_value
+from apps.workflow.services.db_scrubber import (
+    _PRIVATE_CONFIG_TABLES,
+    _assert_private_config_removed,
+    _unique_scrub_value,
+)
 
 PHONE = ContactMethod.MethodType.PHONE
 
@@ -37,3 +43,44 @@ def test_raises_when_every_attempt_collides(self) -> None:
         _unique_scrub_value(lambda: "021 111 111", PHONE, used)  # seed `used`
         with self.assertRaises(RuntimeError):
             _unique_scrub_value(lambda: "021 111 111", PHONE, used)
+
+
+class PrivateConfigurationScrubTests(SimpleTestCase):
+    def test_external_credentials_are_part_of_the_scrub_contract(self) -> None:
+        self.assertEqual(
+            set(_PRIVATE_CONFIG_TABLES),
+            {
+                "workflow_aiprovider",
+                "workflow_xeroapp",
+                "workflow_serviceapikey",
+                "crm_phoneprovidersettings",
+                "quoting_suppliercredential",
+            },
+        )
+
+    @patch("apps.workflow.services.db_scrubber.connections")
+    def test_private_config_postcondition_accepts_empty_tables(
+        self, connections: MagicMock
+    ) -> None:
+        cursor = connections.__getitem__.return_value.cursor.return_value.__enter__
+        cursor.return_value.fetchone.side_effect = [(0,)] * len(_PRIVATE_CONFIG_TABLES)
+
+        _assert_private_config_removed()
+
+    @patch("apps.workflow.services.db_scrubber.connections")
+    def test_private_config_postcondition_reports_counts_not_values(
+        self, connections: MagicMock
+    ) -> None:
+        cursor = connections.__getitem__.return_value.cursor.return_value.__enter__
+        cursor.return_value.fetchone.side_effect = [
+            (2,) if table == "workflow_aiprovider" else (0,)
+            for table in _PRIVATE_CONFIG_TABLES
+        ]
+
+        with self.assertRaisesRegex(
+            RuntimeError,
+            r"workflow_aiprovider=2",
+        ) as raised:
+            _assert_private_config_removed()
+
+        self.assertNotIn("api_key", str(raised.exception))

From 5bd83ceb83d8c449c5634060b4161010e4d2a7d2 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Tue, 14 Jul 2026 17:28:13 +1200
Subject: [PATCH 33/73] fix: harden production restore rehearsal

---
 apps/workflow/tests/test_backup_scripts.py    |  10 +
 .../tests/test_restore_migration_state.py     |  58 +++++
 .../tests/test_verify_scrubbed_backup.py      | 114 ++++++++++
 docs/restore-prod-to-nonprod.md               | 108 +++++----
 scripts/README.md                             |   2 +
 scripts/pull_prod_backup.sh                   |  45 +++-
 .../capture_pre_migration_state.py            | 108 +++++++++
 .../check_post_migration_state.py             | 209 ++++++++++++++++++
 scripts/verify_scrubbed_backup.py             | 105 +++++++++
 9 files changed, 705 insertions(+), 54 deletions(-)
 create mode 100644 apps/workflow/tests/test_restore_migration_state.py
 create mode 100644 apps/workflow/tests/test_verify_scrubbed_backup.py
 create mode 100644 scripts/restore_checks/capture_pre_migration_state.py
 create mode 100644 scripts/restore_checks/check_post_migration_state.py
 create mode 100644 scripts/verify_scrubbed_backup.py

diff --git a/apps/workflow/tests/test_backup_scripts.py b/apps/workflow/tests/test_backup_scripts.py
index dc646f7e0..69d581169 100644
--- a/apps/workflow/tests/test_backup_scripts.py
+++ b/apps/workflow/tests/test_backup_scripts.py
@@ -11,6 +11,7 @@
 REPO_ROOT = Path(__file__).resolve().parents[3]
 CLEANUP_BACKUPS = REPO_ROOT / "scripts" / "cleanup_backups.py"
 BACKUP_INSTANCE_FILES = REPO_ROOT / "scripts" / "backup_instance_files.sh"
+PULL_PROD_BACKUP = REPO_ROOT / "scripts" / "pull_prod_backup.sh"
 
 
 def load_cleanup_module() -> types.ModuleType:
@@ -23,6 +24,15 @@ def load_cleanup_module() -> types.ModuleType:
 
 
 class BackupScriptTests(SimpleTestCase):
+    def test_prod_pull_verifies_archive_and_cleans_failed_artifacts(self) -> None:
+        content = PULL_PROD_BACKUP.read_text()
+
+        self.assertIn("trap cleanup EXIT", content)
+        self.assertIn("verify_scrubbed_backup.py", content)
+        self.assertIn('rm -f "$LOCAL_PATH"', content)
+        self.assertIn("sha256sum", content)
+        self.assertIn("cd app && python manage.py backport_data_backup", content)
+
     def test_cleanup_copies_remote_before_pruning_expired_backups(self) -> None:
         cleanup = load_cleanup_module()
 
diff --git a/apps/workflow/tests/test_restore_migration_state.py b/apps/workflow/tests/test_restore_migration_state.py
new file mode 100644
index 000000000..1609aa85a
--- /dev/null
+++ b/apps/workflow/tests/test_restore_migration_state.py
@@ -0,0 +1,58 @@
+import importlib.util
+import types
+from pathlib import Path
+from typing import ClassVar
+
+from django.test import TestCase
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+POST_CHECK = REPO_ROOT / "scripts" / "restore_checks" / "check_post_migration_state.py"
+
+
+def load_post_check() -> types.ModuleType:
+    spec = importlib.util.spec_from_file_location(
+        "check_post_migration_state", POST_CHECK
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError("Could not load check_post_migration_state.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class RestoreMigrationStateTests(TestCase):
+    check: ClassVar[types.ModuleType]
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        super().setUpClass()
+        cls.check = load_post_check()
+
+    def counts(self) -> dict[str, int]:
+        return {
+            "companies": 10,
+            "contacts": 8,
+            "contact_methods": 7,
+            "jobs": 20,
+            "calls": 5,
+            "jobs_with_contact": 12,
+            "calls_with_contact": 4,
+        }
+
+    def test_count_comparison_accepts_preservation_and_cleanup(self) -> None:
+        before = self.counts()
+        after = {**before, "contacts": 6, "contact_methods": 5}
+
+        self.assertEqual(self.check.comparison_errors(before, after), [])
+
+    def test_count_comparison_reports_lost_business_references(self) -> None:
+        before = self.counts()
+        after = {**before, "jobs_with_contact": 11}
+
+        self.assertEqual(
+            self.check.comparison_errors(before, after),
+            ["jobs_with_contact: before=12, after=11"],
+        )
+
+    def test_current_test_schema_satisfies_structural_invariants(self) -> None:
+        self.assertEqual(self.check.structural_errors(), [])
diff --git a/apps/workflow/tests/test_verify_scrubbed_backup.py b/apps/workflow/tests/test_verify_scrubbed_backup.py
new file mode 100644
index 000000000..7e396c386
--- /dev/null
+++ b/apps/workflow/tests/test_verify_scrubbed_backup.py
@@ -0,0 +1,114 @@
+import importlib.util
+import subprocess
+import types
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from django.test import SimpleTestCase
+
+SCRIPT = Path(__file__).resolve().parents[3] / "scripts" / "verify_scrubbed_backup.py"
+
+
+def load_verifier() -> types.ModuleType:
+    spec = importlib.util.spec_from_file_location("verify_scrubbed_backup", SCRIPT)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("Could not load verify_scrubbed_backup.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def copy_sql(*rows: str) -> str:
+    body = "\n".join(rows)
+    return f"COPY public.test (id) FROM stdin;\n{body}\n\\.\n"
+
+
+class VerifyScrubbedBackupTests(SimpleTestCase):
+    def setUp(self) -> None:
+        self.verifier = load_verifier()
+        self.archive = Path("scrubbed.dump")
+
+    def completed(
+        self, args: list[str], stdout: str
+    ) -> subprocess.CompletedProcess[str]:
+        return subprocess.CompletedProcess(args, 0, stdout=stdout, stderr="")
+
+    def successful_pg_restore(
+        self, args: list[str], **kwargs: object
+    ) -> subprocess.CompletedProcess[str]:
+        if "--list" in args:
+            return self.completed(args, "; archive list")
+        if "--table=django_migrations" in args:
+            return self.completed(
+                args,
+                copy_sql("1\tclient\t0001_baseline\t2026-07-06 00:00:00+12"),
+            )
+        return self.completed(args, copy_sql())
+
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_accepts_readable_post_squash_archive_without_private_rows(
+        self,
+        run: MagicMock,
+        _is_file: object,
+    ) -> None:
+        run.side_effect = self.successful_pg_restore
+
+        self.verifier.verify_backup(self.archive)
+
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_rejects_private_rows_without_printing_their_contents(
+        self,
+        run: MagicMock,
+        _is_file: object,
+    ) -> None:
+        secret = "do-not-print-this-secret"
+
+        def pg_restore(
+            args: list[str], **kwargs: object
+        ) -> subprocess.CompletedProcess[str]:
+            result = self.successful_pg_restore(args, **kwargs)
+            if "--table=workflow_aiprovider" in args:
+                return self.completed(args, copy_sql(f"1\tGemini\t{secret}"))
+            return result
+
+        run.side_effect = pg_restore
+
+        with self.assertRaisesRegex(
+            RuntimeError,
+            r"workflow_aiprovider=1",
+        ) as raised:
+            self.verifier.verify_backup(self.archive)
+
+        self.assertNotIn(secret, str(raised.exception))
+
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_rejects_pre_squash_archive(self, run: MagicMock, _is_file: object) -> None:
+        def pg_restore(
+            args: list[str], **kwargs: object
+        ) -> subprocess.CompletedProcess[str]:
+            if "--list" in args:
+                return self.completed(args, "; archive list")
+            return self.completed(args, copy_sql())
+
+        run.side_effect = pg_restore
+
+        with self.assertRaisesRegex(RuntimeError, "predates the July migration squash"):
+            self.verifier.verify_backup(self.archive)
+
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_reports_pg_restore_failure_without_stderr_contents(
+        self, run: MagicMock, _is_file: object
+    ) -> None:
+        secret = "pg-restore-secret"
+        run.return_value = subprocess.CompletedProcess(
+            ["pg_restore"], 1, stdout="", stderr=secret
+        )
+
+        with self.assertRaisesRegex(RuntimeError, "exit code 1") as raised:
+            self.verifier.verify_backup(self.archive)
+
+        self.assertNotIn(secret, str(raised.exception))
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index e7a2e2868..62e8473ab 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -21,6 +21,13 @@ Sections must run in the order written. The Connect to Xero OAuth section is a h
   ```bash
   scp prod-server:/path/to/docketworks/restore/scrubbed_<DB_NAME>_<ts>.dump restore/
   ```
+- The fetched archive must pass the credential and migration-ledger verifier:
+  ```bash
+  python scripts/verify_scrubbed_backup.py restore/scrubbed_<DB_NAME>_<ts>.dump
+  ```
+  This fails if the archive is unreadable, predates the July migration squash,
+  or contains DB-backed external-system credentials. Do not restore a failing
+  archive.
 - The dump must be from a prod release at or after the July 2026 migration squash (baseline `*_baseline` migrations). Older dumps carry a `django_migrations` ledger the current graph cannot migrate — restore those under a matching pre-squash checkout instead (see `docs/updating.md`).
 - Celery Beat stopped. Beat ticks against the DB and Xero on a timer; if it fires during the reset/restore it will block `DROP SCHEMA` or race `seed_xero_from_database`. Stop it before Reset Database; the Celery Beat section restarts it. The worker can stay running — it has nothing to do without Beat dispatches.
   - Dev: kill the `Celery Beat` task in its VS Code terminal.
@@ -40,10 +47,12 @@ python -c "import django; print(f'django {django.__version__} from {django.__fil
 **Check `.env` is loaded:**
 
 ```bash
-grep -E "^(DB_NAME|DB_USER|DB_PASSWORD)=" .env
+grep -E "^(DB_NAME|DB_USER|DB_HOST)=" .env
+grep -q '^DB_PASSWORD=.' .env && echo "DB_PASSWORD is set"
 export DB_PASSWORD=$(grep DB_PASSWORD .env | cut -d= -f2)
 export DB_NAME=$(grep DB_NAME .env | cut -d= -f2)
 export DB_USER=$(grep DB_USER .env | cut -d= -f2)
+export DB_HOST=$(grep DB_HOST .env | cut -d= -f2)
 ```
 
 **Must show:**
@@ -51,7 +60,8 @@ export DB_USER=$(grep DB_USER .env | cut -d= -f2)
 ```
 DB_NAME=dw_<client>_<env>
 DB_USER=dw_<client>_<env>
-DB_PASSWORD=your_password
+DB_HOST=/var/run/postgresql
+DB_PASSWORD is set
 ```
 
 Note: If you're using Claude or similar, you need to specify these explicitly on all subsequent command lines rather than use environment variables.
@@ -78,48 +88,23 @@ The scrubbed dump carries schema, data, and `django_migrations` together. `pg_re
 ```bash
 PGPASSWORD="$DB_PASSWORD" pg_restore --no-owner --no-privileges --exit-on-error \
   -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME" \
-  ./restore/scrubbed_<DB_NAME>_<ts>.dump
+  ./restore/scrubbed_<source-db>_<ts>.dump
 ```
 
-**Check:**
+#### Capture Pre-Migration State
 
-```bash
-PGPASSWORD="$DB_PASSWORD" psql -U "$DB_USER" "$DB_NAME" -c "
-SELECT 'job_job' as table_name, COUNT(*) as count FROM job_job
-UNION ALL SELECT 'accounts_staff', COUNT(*) FROM accounts_staff
-UNION ALL SELECT 'company_company', COUNT(*) FROM company_company
-UNION ALL SELECT 'job_costset', COUNT(*) FROM job_costset
-UNION ALL SELECT 'job_costline', COUNT(*) FROM job_costline;
-"
-```
-
-**Expected output (approximate):**
-
-```
-  table_name    | count
-----------------+-------
- job_job         |  1054
- accounts_staff  |    20
- company_company |  3739
- job_costset     |  3162
- job_costline    | 10334
-```
-
-Then smoke-test the Django ORM against the restored data — fail fast here rather than letting a broken ORM surface later in the validator loop:
+The restored dump may use the schema of the production release while the
+checkout contains newer models. Do not run current ORM code against that old
+schema. Capture count-only evidence through raw SQL instead:
 
 ```bash
-python scripts/restore_checks/check_django_orm.py
+python scripts/restore_checks/capture_pre_migration_state.py
 ```
 
-**Expected output:**
-
-```
-Jobs: ~1400
-Staff: ~22
-Companies: ~4800
-Sample job: [any real job name] (#XXXXX)
-Contact: [any real contact name]
-```
+This requires the pre-KAN-278 `client_*` schema, verifies the squashed migration
+ledger, and writes only aggregate counts to
+`restore/pre_migration_state.json`. A missing table, unexpected new-schema
+table, or empty production dataset is a hard stop.
 
 #### Apply Django Migrations
 
@@ -132,10 +117,17 @@ python manage.py migrate
 **Check:**
 
 ```bash
+python scripts/restore_checks/check_post_migration_state.py
+python scripts/restore_checks/check_django_orm.py
 python manage.py showmigrations | grep '\[ \]'
 # Expect no output.
 ```
 
+The post-migration check compares against the captured counts and verifies the
+client→company table cutover, Person/link ownership, job and call references,
+merge structure, and persisted terminology. Any mismatch is a migration
+failure; do not continue.
+
 #### Load Company Defaults Fixture
 
 For demo restores only, this replaces your real company name and logos with the
@@ -147,11 +139,24 @@ instead of the shared repo fixture.
 python manage.py loaddata apps/workflow/fixtures/company_defaults.json
 ```
 
-#### Reload Private Instance Config
+#### Reload Private Configuration
+
+The scrubbed archive contains no DB-backed external-system configuration.
+Restore only configuration owned by this non-production target.
+
+**Local dev:** load the ignored local AI and Xero fixtures. Phone-provider
+configuration intentionally remains absent so local Celery cannot contact the
+production phone system.
 
-The DB reset wiped private DB-backed config. Re-run instance reconfiguration to
-regenerate and load the per-instance private fixtures for AI providers, Xero app
-credentials, and phone-provider settings from the root-owned credentials file:
+```bash
+python manage.py loaddata apps/workflow/fixtures/ai_providers.json
+python manage.py loaddata apps/workflow/fixtures/xero_apps.json
+python scripts/restore_checks/check_xero_app.py
+python manage.py shell -c "from apps.crm.models import PhoneProviderSettings; assert not PhoneProviderSettings.objects.exists(), 'phone provider must be unconfigured on local dev'"
+```
+
+**Server instance:** regenerate and load the instance-owned private fixtures
+from the root-owned credentials file:
 
 ```bash
 sudo scripts/server/instance.sh reconfigure <client> <env>
@@ -350,17 +355,25 @@ ls -lh backups/post_restore_*.sql.gz | tail -1
 
 #### Run Playwright Tests
 
+Before E2E, restart the backend, Celery worker, and Celery Beat with
+`XERO_READONLY=True`. The user starts these long-running services; the agent
+does not. All three processes must use the flag because it is process-scoped.
+
 ```bash
-cd frontend && npx playwright test
+cd frontend
+PATH=/home/corrin/src/docketworks/.venv/bin:$PATH npm run test:e2e
 ```
 
-**Expected:** All tests pass.
+Run in the foreground without a shell timeout or SIGTERM. Global teardown must
+finish so it can restore the database, preserve/reinject the Xero token, remove
+the lock, and run integrity checks. **Expected:** all tests and teardown pass.
 
 ## Cleanup
 
-```bash
-rm -rf restore/
-```
+Retain the source dump, `restore/pre_migration_state.json`, and the verified
+post-restore snapshot through E2E and release verification. After explicit
+operator approval, remove only the named source dump. Never recursively remove
+`restore/`; it also contains E2E recovery artifacts.
 
 ## Troubleshooting
 
@@ -389,8 +402,9 @@ gunzip -c "$LATEST" | PGPASSWORD="$DB_PASSWORD" psql \
 
 ## File Locations
 
-- **Scrubbed dump (consumer-side):** `restore/scrubbed_<DB_NAME>_<ts>.dump`
+- **Scrubbed dump (consumer-side):** `restore/scrubbed_<source-db>_<ts>.dump`
 - **Scrubbed dump (producer-side, on prod):** `<BASE_DIR>/restore/scrubbed_<DB_NAME>_<ts>.dump`
+- **Pre-migration count artifact:** `restore/pre_migration_state.json`
 - **Baseline snapshot:** `backups/post_restore_<TS>.sql.gz`
 
 ## First-time setup (existing instances only)
diff --git a/scripts/README.md b/scripts/README.md
index c232466aa..6d2378f59 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -39,6 +39,8 @@ Run manually for one-off or periodic data tasks:
 
 - **`backup_db.sh`** — Instance-user database backup. Writes daily/monthly dumps plus sibling `.sha` release markers, then runs retention and Google Drive upload through `cleanup_backups.py`. Runs via `backup-db-<instance>.timer`.
 - **`backup_instance_files.sh`** — Instance-user mutable file backup. Incrementally syncs instance-owned files (`phone-recordings`, `session-replays`, `mediafiles`) to Google Drive with 30-day dated remote archive folders for replaced/deleted files. Runs via `backup-files-<instance>.timer`.
+- **`pull_prod_backup.sh`** — Generates a scrubbed backup through the active production release, copies it locally, verifies its migration ledger and absence of private external-system configuration, and removes staging artifacts.
+- **`verify_scrubbed_backup.py`** — Fail-closed verifier for scrubbed custom-format PostgreSQL archives. Reports table row counts only; never emits credential values.
 - **`predeploy_backup.sh`** — Called by `scripts/server/deploy.sh` before each instance is switched to a new release. Stamps the dump with the current release hash so rollback is a (switch release, psql restore) pair. Runnable by hand: `sudo predeploy_backup.sh <instance>`
 - **`predeploy_rollback.sh`** — Restore an instance to the release + data that paired with a given commit hash. Usage: `sudo predeploy_rollback.sh <instance> <8-char-hash>` (interactive confirm; restores the dump into a temporary DB before stopping services and swapping DBs)
 - **`cleanup_backups.py`** — DB backup retention and remote upload. Copies local dumps before pruning, then purges only the matching expired remote names. Legacy `ts_dir` style: keep 24h + daily for a week + monthly beyond. `predeploy_*.sql.gz`: keep 30 days. `daily_*.sql.gz`: keep 14. `monthly_*.sql.gz`: keep 12. Other filenames left alone.
diff --git a/scripts/pull_prod_backup.sh b/scripts/pull_prod_backup.sh
index 36e1f00de..15cbcf17b 100755
--- a/scripts/pull_prod_backup.sh
+++ b/scripts/pull_prod_backup.sh
@@ -39,19 +39,50 @@ fi
 TS="$(date +%Y%m%d_%H%M%S)"
 DUMP_NAME="scrubbed_${INSTANCE_USER}_${TS}.dump"
 TMP_PATH="/tmp/$DUMP_NAME"
+LOCAL_PATH="$LOCAL_DIR/$DUMP_NAME"
+REMOTE_STAGED=false
+LOCAL_COPIED=false
+
+cleanup() {
+    local command_status=$?
+    local cleanup_status=0
+    trap - EXIT
+    set +e
+
+    if [[ "$REMOTE_STAGED" == true ]]; then
+        echo ">> Removing remote staging file..."
+        # Dump is owned by $INSTANCE_USER and /tmp has the sticky bit, so the
+        # delete has to run as the same user that created it.
+        # shellcheck disable=SC2029  # values are meant to expand client-side
+        ssh "$REMOTE_USER@$REMOTE_HOST" "sudo -u $INSTANCE_USER rm -f '$TMP_PATH'"
+        cleanup_status=$?
+    fi
+
+    if [[ $command_status -ne 0 && "$LOCAL_COPIED" == true ]]; then
+        echo ">> Removing failed local backup..." >&2
+        rm -f "$LOCAL_PATH"
+    fi
+
+    if [[ $command_status -ne 0 ]]; then
+        exit "$command_status"
+    fi
+    exit "$cleanup_status"
+}
+
+trap cleanup EXIT
 
 echo ">> Generating $DUMP_NAME on $REMOTE_HOST as $INSTANCE_USER..."
-# shellcheck disable=SC2029  # $INSTANCE_USER and $TMP_PATH are meant to expand client-side
+REMOTE_STAGED=true
+# shellcheck disable=SC2029  # values are meant to expand client-side
 ssh "$REMOTE_USER@$REMOTE_HOST" \
     "sudo -iu $INSTANCE_USER bash -lc 'cd app && python manage.py backport_data_backup --output $TMP_PATH'"
 
 echo ">> Copying $DUMP_NAME to $LOCAL_DIR/..."
+LOCAL_COPIED=true
 scp "$REMOTE_USER@$REMOTE_HOST:$TMP_PATH" "$LOCAL_DIR/"
 
-echo ">> Removing remote staging file..."
-# Dump is owned by $INSTANCE_USER and /tmp has the sticky bit, so the
-# delete has to run as the same user that created it.
-# shellcheck disable=SC2029  # $INSTANCE_USER and $TMP_PATH are meant to expand client-side
-ssh "$REMOTE_USER@$REMOTE_HOST" "sudo -u $INSTANCE_USER rm -f '$TMP_PATH'"
+echo ">> Verifying scrubbed backup..."
+python "$REPO_ROOT/scripts/verify_scrubbed_backup.py" "$LOCAL_PATH"
 
-echo ">> Done: $LOCAL_DIR/$DUMP_NAME"
+echo ">> SHA-256: $(sha256sum "$LOCAL_PATH" | cut -d' ' -f1)"
+echo ">> Done: $LOCAL_PATH"
diff --git a/scripts/restore_checks/capture_pre_migration_state.py b/scripts/restore_checks/capture_pre_migration_state.py
new file mode 100644
index 000000000..cf0fcf309
--- /dev/null
+++ b/scripts/restore_checks/capture_pre_migration_state.py
@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Capture count-only evidence from a restored pre-KAN-278 database."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import TypedDict
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from django.db import connection
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_OUTPUT = REPO_ROOT / "restore" / "pre_migration_state.json"
+
+
+class PreMigrationSnapshot(TypedDict):
+    companies: int
+    contacts: int
+    contact_methods: int
+    jobs: int
+    calls: int
+    jobs_with_contact: int
+    calls_with_contact: int
+
+
+def _scalar(sql: str, params: tuple[str, ...] = ()) -> int:
+    with connection.cursor() as cursor:
+        cursor.execute(sql, params)
+        row = cursor.fetchone()
+    if row is None:
+        raise RuntimeError("Pre-migration query returned no row")
+    return int(row[0])
+
+
+def _table_exists(table: str) -> bool:
+    return bool(_scalar("SELECT to_regclass(%s) IS NOT NULL", (f"public.{table}",)))
+
+
+def capture_snapshot() -> PreMigrationSnapshot:
+    required_tables = (
+        "client_client",
+        "client_clientcontact",
+        "client_clientcontactmethod",
+        "job_job",
+        "crm_phonecallrecord",
+        "django_migrations",
+    )
+    missing = [table for table in required_tables if not _table_exists(table)]
+    if missing:
+        raise RuntimeError(
+            "Restored pre-migration tables are missing: " + ", ".join(missing)
+        )
+    if _table_exists("company_company"):
+        raise RuntimeError(
+            "company_company already exists; expected the pre-KAN-278 client schema"
+        )
+    baseline_count = _scalar(
+        "SELECT COUNT(*) FROM django_migrations WHERE app = %s AND name = %s",
+        ("client", "0001_baseline"),
+    )
+    if baseline_count != 1:
+        raise RuntimeError(
+            "Expected exactly one client.0001_baseline migration ledger row; "
+            f"found {baseline_count}"
+        )
+
+    snapshot: PreMigrationSnapshot = {
+        "companies": _scalar("SELECT COUNT(*) FROM client_client"),
+        "contacts": _scalar("SELECT COUNT(*) FROM client_clientcontact"),
+        "contact_methods": _scalar("SELECT COUNT(*) FROM client_clientcontactmethod"),
+        "jobs": _scalar("SELECT COUNT(*) FROM job_job"),
+        "calls": _scalar("SELECT COUNT(*) FROM crm_phonecallrecord"),
+        "jobs_with_contact": _scalar(
+            "SELECT COUNT(*) FROM job_job WHERE contact_id IS NOT NULL"
+        ),
+        "calls_with_contact": _scalar(
+            "SELECT COUNT(*) FROM crm_phonecallrecord WHERE contact_id IS NOT NULL"
+        ),
+    }
+    if not snapshot["companies"] or not snapshot["jobs"]:
+        raise RuntimeError(
+            "Restored production snapshot must contain companies and jobs"
+        )
+    return snapshot
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) > 2:
+        print(f"Usage: {argv[0]} [output.json]", file=sys.stderr)
+        return 2
+    output = Path(argv[1]) if len(argv) == 2 else DEFAULT_OUTPUT
+    snapshot = capture_snapshot()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(snapshot, indent=2, sort_keys=True) + "\n")
+    print(f"Pre-migration state captured: {output}")
+    for name, count in snapshot.items():
+        print(f"{name}: {count}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/scripts/restore_checks/check_post_migration_state.py b/scripts/restore_checks/check_post_migration_state.py
new file mode 100644
index 000000000..2ad9bedb4
--- /dev/null
+++ b/scripts/restore_checks/check_post_migration_state.py
@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Verify KAN-278 preserved production-shaped data across its schema cutover."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import TypedDict, TypeGuard
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "docketworks.settings")
+
+import django
+
+django.setup()
+
+from django.db import connection
+from django.db.models import Q
+
+from apps.company.models import Company, CompanyPersonLink, ContactMethod, Person
+from apps.crm.models import PhoneCallRecord
+from apps.job.models import Job, JobEvent
+from apps.workflow.models import SearchTelemetryEvent
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_INPUT = REPO_ROOT / "restore" / "pre_migration_state.json"
+
+
+class MigrationCounts(TypedDict):
+    companies: int
+    contacts: int
+    contact_methods: int
+    jobs: int
+    calls: int
+    jobs_with_contact: int
+    calls_with_contact: int
+
+
+COUNT_KEYS = frozenset(MigrationCounts.__annotations__)
+
+
+def _is_migration_counts(value: object) -> TypeGuard[MigrationCounts]:
+    if not isinstance(value, dict) or set(value) != COUNT_KEYS:
+        return False
+    return all(type(value[key]) is int and value[key] >= 0 for key in COUNT_KEYS)
+
+
+def load_snapshot(path: Path) -> MigrationCounts:
+    value: object = json.loads(path.read_text())
+    if not _is_migration_counts(value):
+        raise RuntimeError(f"Invalid pre-migration count artifact: {path}")
+    return value
+
+
+def current_counts() -> MigrationCounts:
+    return {
+        "companies": Company.objects.count(),
+        "contacts": CompanyPersonLink.objects.count(),
+        "contact_methods": ContactMethod.objects.count(),
+        "jobs": Job.objects.count(),
+        "calls": PhoneCallRecord.objects.count(),
+        "jobs_with_contact": Job.objects.exclude(person__isnull=True).count(),
+        "calls_with_contact": PhoneCallRecord.objects.exclude(
+            person__isnull=True
+        ).count(),
+    }
+
+
+def comparison_errors(before: MigrationCounts, after: MigrationCounts) -> list[str]:
+    errors: list[str] = []
+    preserved_counts = (
+        ("companies", before["companies"], after["companies"]),
+        ("jobs", before["jobs"], after["jobs"]),
+        ("calls", before["calls"], after["calls"]),
+        (
+            "jobs_with_contact",
+            before["jobs_with_contact"],
+            after["jobs_with_contact"],
+        ),
+        (
+            "calls_with_contact",
+            before["calls_with_contact"],
+            after["calls_with_contact"],
+        ),
+    )
+    for name, before_count, after_count in preserved_counts:
+        if before_count != after_count:
+            errors.append(f"{name}: before={before_count}, after={after_count}")
+    if after["contacts"] > before["contacts"]:
+        errors.append(
+            "company-person links increased unexpectedly: "
+            f"before={before['contacts']}, after={after['contacts']}"
+        )
+    if after["contact_methods"] > before["contact_methods"]:
+        errors.append(
+            "contact methods increased unexpectedly: "
+            f"before={before['contact_methods']}, after={after['contact_methods']}"
+        )
+    return errors
+
+
+def _table_exists(table: str) -> bool:
+    with connection.cursor() as cursor:
+        cursor.execute("SELECT to_regclass(%s) IS NOT NULL", [f"public.{table}"])
+        row = cursor.fetchone()
+    if row is None:
+        raise RuntimeError("Post-migration schema query returned no row")
+    return bool(row[0])
+
+
+def structural_errors() -> list[str]:
+    errors: list[str] = []
+    required_tables = (
+        "company_company",
+        "company_person",
+        "company_companypersonlink",
+        "company_contactmethod",
+    )
+    old_tables = (
+        "client_client",
+        "client_clientcontact",
+        "client_clientcontactmethod",
+    )
+    for table in required_tables:
+        if not _table_exists(table):
+            errors.append(f"required post-migration table is missing: {table}")
+    for table in old_tables:
+        if _table_exists(table):
+            errors.append(f"legacy table still exists: {table}")
+
+    invalid_owners = ContactMethod.objects.filter(
+        Q(company__isnull=True, person__isnull=True)
+        | Q(company__isnull=False, person__isnull=False)
+    ).count()
+    if invalid_owners:
+        errors.append(f"contact methods with invalid ownership: {invalid_owners}")
+    null_links = CompanyPersonLink.objects.filter(person__isnull=True).count()
+    if null_links:
+        errors.append(f"company-person links without a person: {null_links}")
+    multi_hop_merges = Company.objects.filter(
+        merged_into__merged_into__isnull=False
+    ).count()
+    if multi_hop_merges:
+        errors.append(f"multi-hop company merges: {multi_hop_merges}")
+
+    legacy_event_types = JobEvent.objects.filter(
+        event_type__in=("client_changed", "contact_changed")
+    ).count()
+    if legacy_event_types:
+        errors.append(f"job events with legacy event types: {legacy_event_types}")
+    with connection.cursor() as cursor:
+        cursor.execute("""
+            SELECT COUNT(*)
+            FROM job_jobevent
+            WHERE detail ->> 'field_name' IN ('Client', 'Contact')
+               OR detail @? '$.changes[*] ? (@.field_name == "Client" || @.field_name == "Contact")'
+            """)
+        row = cursor.fetchone()
+    if row is None:
+        raise RuntimeError("Job-event terminology query returned no row")
+    if row[0]:
+        errors.append(f"job events with legacy detail labels: {row[0]}")
+
+    legacy_telemetry = SearchTelemetryEvent.objects.filter(
+        Q(domain="client")
+        | Q(
+            source__in=(
+                "client_lookup",
+                "crm_clients_table",
+                "crm_client_detail_phone_numbers",
+            )
+        )
+    ).count()
+    if legacy_telemetry:
+        errors.append(f"telemetry rows with legacy terminology: {legacy_telemetry}")
+    return errors
+
+
+def verify_post_migration(snapshot: MigrationCounts) -> MigrationCounts:
+    after = current_counts()
+    errors = comparison_errors(snapshot, after) + structural_errors()
+    people = Person.objects.count()
+    if people > snapshot["contacts"]:
+        errors.append(
+            "people increased beyond the legacy contact population: "
+            f"contacts={snapshot['contacts']}, people={people}"
+        )
+    if errors:
+        raise RuntimeError(
+            "Post-migration verification failed:\n- " + "\n- ".join(errors)
+        )
+    return after
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) > 2:
+        print(f"Usage: {argv[0]} [pre_migration_state.json]", file=sys.stderr)
+        return 2
+    source = Path(argv[1]) if len(argv) == 2 else DEFAULT_INPUT
+    before = load_snapshot(source)
+    after = verify_post_migration(before)
+    print("Post-migration production-data invariants passed")
+    for name, count in after.items():
+        print(f"{name}: {count}")
+    print(f"people: {Person.objects.count()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))
diff --git a/scripts/verify_scrubbed_backup.py b/scripts/verify_scrubbed_backup.py
new file mode 100644
index 000000000..911657376
--- /dev/null
+++ b/scripts/verify_scrubbed_backup.py
@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Verify that a production-to-nonprod dump is readable and credential-free."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+PRIVATE_CONFIG_TABLES = (
+    "workflow_aiprovider",
+    "workflow_xeroapp",
+    "workflow_serviceapikey",
+    "crm_phoneprovidersettings",
+    "quoting_suppliercredential",
+)
+
+
+def _pg_restore(archive: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["pg_restore", *args, str(archive)],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    if result.returncode:
+        operation = " ".join(args) or "archive read"
+        raise RuntimeError(
+            f"pg_restore {operation} failed with exit code {result.returncode}"
+        )
+    return result.stdout
+
+
+def _copy_rows(sql: str) -> list[str]:
+    rows: list[str] = []
+    in_copy = False
+    for line in sql.splitlines():
+        if line.startswith("COPY "):
+            in_copy = True
+        elif in_copy and line == r"\.":
+            in_copy = False
+        elif in_copy and not line:
+            pass
+        elif in_copy:
+            rows.append(line)
+        else:
+            pass
+    return rows
+
+
+def _table_rows(archive: Path, table: str) -> list[str]:
+    sql = _pg_restore(archive, "--data-only", f"--table={table}", "--file=-")
+    if "COPY " not in sql:
+        raise RuntimeError(f"Required table data entry is missing: {table}")
+    return _copy_rows(sql)
+
+
+def _has_squashed_baseline(rows: list[str]) -> bool:
+    for row in rows:
+        columns = row.split("\t")
+        if len(columns) < 3:
+            continue
+        app, migration = columns[1:3]
+        if app in {"client", "company"} and migration == "0001_baseline":
+            return True
+    return False
+
+
+def verify_backup(archive: Path) -> None:
+    if not archive.is_file():
+        raise RuntimeError(f"Backup not found: {archive}")
+
+    _pg_restore(archive, "--list")
+    migration_rows = _table_rows(archive, "django_migrations")
+    if not _has_squashed_baseline(migration_rows):
+        raise RuntimeError(
+            "Backup predates the July migration squash: no client/company "
+            "0001_baseline ledger entry"
+        )
+
+    populated: list[str] = []
+    for table in PRIVATE_CONFIG_TABLES:
+        count = len(_table_rows(archive, table))
+        if count:
+            populated.append(f"{table}={count}")
+    if populated:
+        raise RuntimeError(
+            "Backup contains private external-system configuration: "
+            + ", ".join(populated)
+        )
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print(f"Usage: {argv[0]} <scrubbed.dump>", file=sys.stderr)
+        return 2
+
+    archive = Path(argv[1])
+    verify_backup(archive)
+    print(f"Verified scrubbed backup: {archive}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

From a38990fcbf002597df660862e7ee221e0904d82b Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 10:41:38 +1200
Subject: [PATCH 34/73] fix: address restore backup review findings

---
 .../commands/backport_data_backup.py          |   7 +-
 .../management/commands/relabel_client_app.py |   4 +
 apps/workflow/services/db_scrubber.py         |   7 +-
 apps/workflow/tests/test_backup_scripts.py    | 225 +++++++++++++++++-
 apps/workflow/tests/test_db_scrubber.py       |  46 ++++
 .../tests/test_verify_scrubbed_backup.py      |  60 ++++-
 docs/restore-prod-to-nonprod.md               |  28 ++-
 scripts/README.md                             |   2 +-
 scripts/pull_prod_backup.sh                   |   9 +-
 .../capture_pre_migration_state.py            |   7 +-
 .../check_post_migration_state.py             |   7 +-
 scripts/server/deploy.sh                      |   2 +
 scripts/verify_scrubbed_backup.py             |  74 ++++--
 13 files changed, 438 insertions(+), 40 deletions(-)

diff --git a/apps/workflow/management/commands/backport_data_backup.py b/apps/workflow/management/commands/backport_data_backup.py
index 938efcf7a..4132558cc 100644
--- a/apps/workflow/management/commands/backport_data_backup.py
+++ b/apps/workflow/management/commands/backport_data_backup.py
@@ -8,6 +8,7 @@
 from django.conf import settings
 from django.core.management.base import BaseCommand
 
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services import db_scrubber
 from apps.workflow.services.error_persistence import persist_app_error
 
@@ -166,9 +167,11 @@ def handle(self, *args, **options):
             self.stdout.write(
                 self.style.SUCCESS(f"Scrubbed dump written: {scrubbed_dump}")
             )
-        except Exception as exc:
-            persist_app_error(exc)
+        except AlreadyLoggedException:
             raise
+        except Exception as exc:
+            err = persist_app_error(exc)
+            raise AlreadyLoggedException(exc, err.id) from exc
 
     def _run(self, cmd, env=None):
         subprocess.run(cmd, check=True, env=env, capture_output=True, text=True)
diff --git a/apps/workflow/management/commands/relabel_client_app.py b/apps/workflow/management/commands/relabel_client_app.py
index 27ab6d533..2e58139bf 100644
--- a/apps/workflow/management/commands/relabel_client_app.py
+++ b/apps/workflow/management/commands/relabel_client_app.py
@@ -3,6 +3,10 @@
 Runs before `migrate` (deploy.sh calls it for every instance). Idempotent:
 keys off django_migrations rows still recorded under the old label.
 
+TEMPORARY KAN-278: remove this command and its deploy hook after every
+production instance has completed the cutover and produced a verified
+company-schema backup.
+
 The historic pre-squash rows (0001_initial .. 0023_drop_scalar_phone_fields)
 are DELETED rather than relabelled: with the squash's `replaces` lists gone,
 a blanket relabel would strand ("company", "0001_initial")-style ghost rows
diff --git a/apps/workflow/services/db_scrubber.py b/apps/workflow/services/db_scrubber.py
index d189fb9ad..9a93ad4e6 100644
--- a/apps/workflow/services/db_scrubber.py
+++ b/apps/workflow/services/db_scrubber.py
@@ -32,6 +32,7 @@
 from apps.accounts.models import SYSTEM_AUTOMATION_EMAIL, Staff
 from apps.accounts.staff_anonymization import create_staff_profile
 from apps.company.models import Company, ContactMethod, Person
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
 
@@ -323,6 +324,8 @@ def scrub() -> None:
             _delete_unlinked_accounting()
             _truncate_excluded_tables()
             _assert_private_config_removed()
-    except Exception as exc:
-        persist_app_error(exc)
+    except AlreadyLoggedException:
         raise
+    except Exception as exc:
+        err = persist_app_error(exc)
+        raise AlreadyLoggedException(exc, err.id) from exc
diff --git a/apps/workflow/tests/test_backup_scripts.py b/apps/workflow/tests/test_backup_scripts.py
index 69d581169..ab60f6d5c 100644
--- a/apps/workflow/tests/test_backup_scripts.py
+++ b/apps/workflow/tests/test_backup_scripts.py
@@ -1,4 +1,5 @@
 import importlib.util
+import os
 import subprocess
 import sys
 import tempfile
@@ -6,8 +7,12 @@
 from pathlib import Path
 from unittest import mock
 
+from django.core.management import call_command
 from django.test import SimpleTestCase
 
+from apps.workflow.exceptions import AlreadyLoggedException
+from apps.workflow.management.commands.backport_data_backup import Command
+
 REPO_ROOT = Path(__file__).resolve().parents[3]
 CLEANUP_BACKUPS = REPO_ROOT / "scripts" / "cleanup_backups.py"
 BACKUP_INSTANCE_FILES = REPO_ROOT / "scripts" / "backup_instance_files.sh"
@@ -24,14 +29,177 @@ def load_cleanup_module() -> types.ModuleType:
 
 
 class BackupScriptTests(SimpleTestCase):
-    def test_prod_pull_verifies_archive_and_cleans_failed_artifacts(self) -> None:
-        content = PULL_PROD_BACKUP.read_text()
+    def _write_stub(self, directory: Path, name: str, body: str) -> None:
+        path = directory / name
+        path.write_text("#!/usr/bin/env bash\nset -u\n" + body)
+        path.chmod(0o755)
+
+    def _run_prod_pull(
+        self,
+        *,
+        generation_status: int = 0,
+        copy_status: int = 0,
+        verifier_status: int = 0,
+        checksum_status: int = 0,
+        cleanup_status: int = 0,
+    ) -> tuple[subprocess.CompletedProcess[str], list[str], bool]:
+        with tempfile.TemporaryDirectory() as tmp:
+            temp_repo = Path(tmp)
+            scripts_dir = temp_repo / "scripts"
+            restore_dir = temp_repo / "restore"
+            bin_dir = temp_repo / "bin"
+            scripts_dir.mkdir()
+            restore_dir.mkdir()
+            bin_dir.mkdir()
+
+            script = scripts_dir / PULL_PROD_BACKUP.name
+            script.write_text(PULL_PROD_BACKUP.read_text())
+            script.chmod(0o755)
+            event_log = temp_repo / "events.log"
+
+            self._write_stub(bin_dir, "date", 'echo "20260715_120000"\n')
+            self._write_stub(
+                bin_dir,
+                "ssh",
+                """printf 'ssh:%s\\n' "$*" >> "$EVENT_LOG"
+if [[ "$*" == *"backport_data_backup"* ]]; then
+    exit "$GENERATION_STATUS"
+fi
+exit "$CLEANUP_STATUS"
+""",
+            )
+            self._write_stub(
+                bin_dir,
+                "scp",
+                """printf 'scp:%s\\n' "$*" >> "$EVENT_LOG"
+source_path="$1"
+destination="$2"
+filename="${source_path##*/}"
+: > "${destination%/}/$filename"
+exit "$COPY_STATUS"
+""",
+            )
+            self._write_stub(
+                bin_dir,
+                "python",
+                """printf 'verify:%s\\n' "$*" >> "$EVENT_LOG"
+exit "$VERIFIER_STATUS"
+""",
+            )
+            self._write_stub(
+                bin_dir,
+                "sha256sum",
+                """printf 'sha256sum:%s\\n' "$*" >> "$EVENT_LOG"
+if [[ "$CHECKSUM_STATUS" -ne 0 ]]; then
+    exit "$CHECKSUM_STATUS"
+fi
+printf 'abc123  %s\\n' "$1"
+""",
+            )
+
+            environment = {
+                **os.environ,
+                "PATH": f"{bin_dir}:/usr/bin:/bin",
+                "EVENT_LOG": str(event_log),
+                "GENERATION_STATUS": str(generation_status),
+                "COPY_STATUS": str(copy_status),
+                "VERIFIER_STATUS": str(verifier_status),
+                "CHECKSUM_STATUS": str(checksum_status),
+                "CLEANUP_STATUS": str(cleanup_status),
+                "REMOTE_USER": "backup-operator",
+            }
+            result = subprocess.run(
+                [str(script), "prod.example", "dw_msm_prod"],
+                capture_output=True,
+                check=False,
+                env=environment,
+                text=True,
+            )
+            events = event_log.read_text().splitlines()
+            archive_exists = (
+                restore_dir / "scrubbed_dw_msm_prod_20260715_120000.dump"
+            ).exists()
+            return result, events, archive_exists
+
+    def test_prod_pull_success_preserves_verified_archive_and_cleans_remote(
+        self,
+    ) -> None:
+        result, events, archive_exists = self._run_prod_pull()
+
+        self.assertEqual(result.returncode, 0)
+        self.assertTrue(archive_exists)
+        self.assertEqual(
+            [event.split(":", 1)[0] for event in events],
+            ["ssh", "scp", "verify", "sha256sum", "ssh"],
+        )
+        self.assertIn("--allow-legacy-client-baseline", events[2])
+        self.assertIn("backport_data_backup", events[0])
+        self.assertIn("rm -f", events[-1])
+
+    def test_prod_pull_failures_remove_partial_archive_and_preserve_status(
+        self,
+    ) -> None:
+        cases = (
+            ("generation", 41, 0, 0, 0, 41, ["ssh", "ssh"]),
+            ("copy", 0, 42, 0, 0, 42, ["ssh", "scp", "ssh"]),
+            (
+                "verification",
+                0,
+                0,
+                43,
+                0,
+                43,
+                ["ssh", "scp", "verify", "ssh"],
+            ),
+            (
+                "checksum",
+                0,
+                0,
+                0,
+                44,
+                44,
+                ["ssh", "scp", "verify", "sha256sum", "ssh"],
+            ),
+        )
+        for (
+            stage,
+            generation_status,
+            copy_status,
+            verifier_status,
+            checksum_status,
+            expected_status,
+            expected_events,
+        ) in cases:
+            with self.subTest(stage=stage):
+                result, events, archive_exists = self._run_prod_pull(
+                    generation_status=generation_status,
+                    copy_status=copy_status,
+                    verifier_status=verifier_status,
+                    checksum_status=checksum_status,
+                )
+
+                self.assertEqual(result.returncode, expected_status)
+                self.assertFalse(archive_exists)
+                self.assertEqual(
+                    [event.split(":", 1)[0] for event in events], expected_events
+                )
+                self.assertIn("rm -f", events[-1])
+
+    def test_prod_pull_cleanup_failure_is_reported_after_success(self) -> None:
+        result, events, archive_exists = self._run_prod_pull(cleanup_status=45)
+
+        self.assertEqual(result.returncode, 45)
+        self.assertTrue(archive_exists)
+        self.assertIn("rm -f", events[-1])
 
-        self.assertIn("trap cleanup EXIT", content)
-        self.assertIn("verify_scrubbed_backup.py", content)
-        self.assertIn('rm -f "$LOCAL_PATH"', content)
-        self.assertIn("sha256sum", content)
-        self.assertIn("cd app && python manage.py backport_data_backup", content)
+    def test_prod_pull_original_failure_wins_over_cleanup_failure(self) -> None:
+        result, _events, archive_exists = self._run_prod_pull(
+            verifier_status=43,
+            cleanup_status=45,
+        )
+
+        self.assertEqual(result.returncode, 43)
+        self.assertFalse(archive_exists)
 
     def test_cleanup_copies_remote_before_pruning_expired_backups(self) -> None:
         cleanup = load_cleanup_module()
@@ -170,3 +338,46 @@ def test_file_backup_script_is_incremental_and_scoped(self) -> None:
         self.assertIn("ARCHIVE_RETENTION_DAYS=30", content)
         self.assertIn("rclone purge", content)
         self.assertIn("refusing to back up symlinked directory", content)
+
+
+class BackportCommandErrorPersistenceTests(SimpleTestCase):
+    def test_prelogged_scrub_failure_is_not_persisted_again(self) -> None:
+        command = Command()
+        failure = AlreadyLoggedException(RuntimeError("scrub failed"), "error-123")
+        with tempfile.TemporaryDirectory() as tmp:
+            output = Path(tmp) / "backup.dump"
+            with (
+                mock.patch.object(command, "_run"),
+                mock.patch.object(command, "_run_pipe"),
+                mock.patch(
+                    "apps.workflow.management.commands.backport_data_backup.db_scrubber.scrub",
+                    side_effect=failure,
+                ),
+                mock.patch(
+                    "apps.workflow.management.commands.backport_data_backup.persist_app_error"
+                ) as persist_app_error,
+                self.assertRaises(AlreadyLoggedException) as raised,
+            ):
+                call_command(command, output=str(output))
+
+        self.assertIs(raised.exception, failure)
+        persist_app_error.assert_not_called()
+
+    def test_new_command_failure_is_persisted_and_wrapped(self) -> None:
+        command = Command()
+        failure = RuntimeError("backup failed")
+        with tempfile.TemporaryDirectory() as tmp:
+            output = Path(tmp) / "backup.dump"
+            with (
+                mock.patch.object(command, "_run", side_effect=failure),
+                mock.patch(
+                    "apps.workflow.management.commands.backport_data_backup.persist_app_error"
+                ) as persist_app_error,
+                self.assertRaises(AlreadyLoggedException) as raised,
+            ):
+                persist_app_error.return_value.id = "error-456"
+                call_command(command, output=str(output))
+
+        self.assertIs(raised.exception.original, failure)
+        self.assertEqual(raised.exception.app_error_id, "error-456")
+        persist_app_error.assert_called_once_with(failure)
diff --git a/apps/workflow/tests/test_db_scrubber.py b/apps/workflow/tests/test_db_scrubber.py
index 6027a9128..e7514cd67 100644
--- a/apps/workflow/tests/test_db_scrubber.py
+++ b/apps/workflow/tests/test_db_scrubber.py
@@ -10,10 +10,12 @@
 from django.test import SimpleTestCase
 
 from apps.company.models import ContactMethod
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.db_scrubber import (
     _PRIVATE_CONFIG_TABLES,
     _assert_private_config_removed,
     _unique_scrub_value,
+    scrub,
 )
 
 PHONE = ContactMethod.MethodType.PHONE
@@ -84,3 +86,47 @@ def test_private_config_postcondition_reports_counts_not_values(
             _assert_private_config_removed()
 
         self.assertNotIn("api_key", str(raised.exception))
+
+
+class ScrubErrorPersistenceTests(SimpleTestCase):
+    @patch("apps.workflow.services.db_scrubber._assert_scrub_alias_is_safe")
+    @patch("apps.workflow.services.db_scrubber.transaction.atomic")
+    @patch("apps.workflow.services.db_scrubber._scrub_staff")
+    @patch("apps.workflow.services.db_scrubber.persist_app_error")
+    def test_new_failure_is_persisted_and_wrapped_once(
+        self,
+        persist_app_error: MagicMock,
+        scrub_staff: MagicMock,
+        _atomic: MagicMock,
+        _assert_safe: MagicMock,
+    ) -> None:
+        failure = RuntimeError("scrub failed")
+        scrub_staff.side_effect = failure
+        persist_app_error.return_value.id = "error-123"
+
+        with self.assertRaises(AlreadyLoggedException) as raised:
+            scrub()
+
+        self.assertIs(raised.exception.original, failure)
+        self.assertEqual(raised.exception.app_error_id, "error-123")
+        persist_app_error.assert_called_once_with(failure)
+
+    @patch("apps.workflow.services.db_scrubber._assert_scrub_alias_is_safe")
+    @patch("apps.workflow.services.db_scrubber.transaction.atomic")
+    @patch("apps.workflow.services.db_scrubber._scrub_staff")
+    @patch("apps.workflow.services.db_scrubber.persist_app_error")
+    def test_prelogged_failure_passes_through_unchanged(
+        self,
+        persist_app_error: MagicMock,
+        scrub_staff: MagicMock,
+        _atomic: MagicMock,
+        _assert_safe: MagicMock,
+    ) -> None:
+        failure = AlreadyLoggedException(RuntimeError("scrub failed"), "error-123")
+        scrub_staff.side_effect = failure
+
+        with self.assertRaises(AlreadyLoggedException) as raised:
+            scrub()
+
+        self.assertIs(raised.exception, failure)
+        persist_app_error.assert_not_called()
diff --git a/apps/workflow/tests/test_verify_scrubbed_backup.py b/apps/workflow/tests/test_verify_scrubbed_backup.py
index 7e396c386..ec3758cd2 100644
--- a/apps/workflow/tests/test_verify_scrubbed_backup.py
+++ b/apps/workflow/tests/test_verify_scrubbed_backup.py
@@ -36,12 +36,10 @@ def completed(
     def successful_pg_restore(
         self, args: list[str], **kwargs: object
     ) -> subprocess.CompletedProcess[str]:
-        if "--list" in args:
-            return self.completed(args, "; archive list")
         if "--table=django_migrations" in args:
             return self.completed(
                 args,
-                copy_sql("1\tclient\t0001_baseline\t2026-07-06 00:00:00+12"),
+                copy_sql("1\tcompany\t0001_baseline\t2026-07-06 00:00:00+12"),
             )
         return self.completed(args, copy_sql())
 
@@ -56,6 +54,8 @@ def test_accepts_readable_post_squash_archive_without_private_rows(
 
         self.verifier.verify_backup(self.archive)
 
+        self.assertIn("--file=/dev/null", run.call_args_list[0].args[0])
+
     @patch.object(Path, "is_file", return_value=True)
     @patch("subprocess.run")
     def test_rejects_private_rows_without_printing_their_contents(
@@ -89,8 +89,6 @@ def test_rejects_pre_squash_archive(self, run: MagicMock, _is_file: object) -> N
         def pg_restore(
             args: list[str], **kwargs: object
         ) -> subprocess.CompletedProcess[str]:
-            if "--list" in args:
-                return self.completed(args, "; archive list")
             return self.completed(args, copy_sql())
 
         run.side_effect = pg_restore
@@ -98,6 +96,57 @@ def pg_restore(
         with self.assertRaisesRegex(RuntimeError, "predates the July migration squash"):
             self.verifier.verify_backup(self.archive)
 
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_legacy_baseline_requires_temporary_cutover_flag(
+        self, run: MagicMock, _is_file: object
+    ) -> None:
+        def pg_restore(
+            args: list[str], **kwargs: object
+        ) -> subprocess.CompletedProcess[str]:
+            if "--table=django_migrations" in args:
+                return self.completed(
+                    args,
+                    copy_sql("1\tclient\t0001_baseline\t2026-07-06 00:00:00+12"),
+                )
+            return self.completed(args, copy_sql())
+
+        run.side_effect = pg_restore
+
+        with self.assertRaisesRegex(RuntimeError, "temporary pre-KAN-278"):
+            self.verifier.verify_backup(self.archive)
+
+        self.verifier.verify_backup(
+            self.archive,
+            allow_legacy_client_baseline=True,
+        )
+
+    @patch.object(Path, "is_file", return_value=True)
+    @patch("subprocess.run")
+    def test_rejects_mixed_client_and_company_baselines(
+        self, run: MagicMock, _is_file: object
+    ) -> None:
+        def pg_restore(
+            args: list[str], **kwargs: object
+        ) -> subprocess.CompletedProcess[str]:
+            if "--table=django_migrations" in args:
+                return self.completed(
+                    args,
+                    copy_sql(
+                        "1\tclient\t0001_baseline\t2026-07-06 00:00:00+12",
+                        "2\tcompany\t0001_baseline\t2026-07-06 00:01:00+12",
+                    ),
+                )
+            return self.completed(args, copy_sql())
+
+        run.side_effect = pg_restore
+
+        with self.assertRaisesRegex(RuntimeError, "mixed client/company"):
+            self.verifier.verify_backup(
+                self.archive,
+                allow_legacy_client_baseline=True,
+            )
+
     @patch.object(Path, "is_file", return_value=True)
     @patch("subprocess.run")
     def test_reports_pg_restore_failure_without_stderr_contents(
@@ -112,3 +161,4 @@ def test_reports_pg_restore_failure_without_stderr_contents(
             self.verifier.verify_backup(self.archive)
 
         self.assertNotIn(secret, str(raised.exception))
+        self.assertIn("--file=/dev/null", run.call_args.args[0])
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index 62e8473ab..7d302ae79 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -23,11 +23,17 @@ Sections must run in the order written. The Connect to Xero OAuth section is a h
   ```
 - The fetched archive must pass the credential and migration-ledger verifier:
   ```bash
-  python scripts/verify_scrubbed_backup.py restore/scrubbed_<DB_NAME>_<ts>.dump
+  python scripts/verify_scrubbed_backup.py \
+    --allow-legacy-client-baseline \
+    restore/scrubbed_<DB_NAME>_<ts>.dump
   ```
   This fails if the archive is unreadable, predates the July migration squash,
   or contains DB-backed external-system credentials. Do not restore a failing
   archive.
+- **TEMPORARY KAN-278:** `--allow-legacy-client-baseline` exists only while
+  production still uses the pre-cutover `client` app label. Remove this flag and
+  the pre-migration cutover sections below after every production instance has
+  migrated and produced a verified company-schema backup.
 - The dump must be from a prod release at or after the July 2026 migration squash (baseline `*_baseline` migrations). Older dumps carry a `django_migrations` ledger the current graph cannot migrate — restore those under a matching pre-squash checkout instead (see `docs/updating.md`).
 - Celery Beat stopped. Beat ticks against the DB and Xero on a timer; if it fires during the reset/restore it will block `DROP SCHEMA` or race `seed_xero_from_database`. Stop it before Reset Database; the Celery Beat section restarts it. The worker can stay running — it has nothing to do without Beat dispatches.
   - Dev: kill the `Celery Beat` task in its VS Code terminal.
@@ -93,6 +99,10 @@ PGPASSWORD="$DB_PASSWORD" pg_restore --no-owner --no-privileges --exit-on-error
 
 #### Capture Pre-Migration State
 
+**TEMPORARY KAN-278 CUTOVER STEP:** Remove this section after every production
+instance has completed the client-to-company migration and produced a verified
+company-schema backup.
+
 The restored dump may use the schema of the production release while the
 checkout contains newer models. Do not run current ORM code against that old
 schema. Capture count-only evidence through raw SQL instead:
@@ -106,6 +116,20 @@ ledger, and writes only aggregate counts to
 `restore/pre_migration_state.json`. A missing table, unexpected new-schema
 table, or empty production dataset is a hard stop.
 
+#### Relabel the Legacy Client App
+
+**TEMPORARY KAN-278 CUTOVER STEP:** The restored ledger and tables still use the
+legacy `client` app label. Apply the same one-time, idempotent surgery that the
+deployment workflow runs before Django migrations:
+
+```bash
+python manage.py relabel_client_app
+```
+
+This must complete successfully before `migrate`. It keeps the squashed
+baseline, removes obsolete pre-squash ledger rows, and changes the app label and
+table prefixes without creating a second baseline.
+
 #### Apply Django Migrations
 
 `django_migrations` rode along in the dump, so this only runs migrations the dev branch has beyond prod's state. On a fresh prod-aligned checkout it's a no-op.
@@ -361,7 +385,7 @@ does not. All three processes must use the flag because it is process-scoped.
 
 ```bash
 cd frontend
-PATH=/home/corrin/src/docketworks/.venv/bin:$PATH npm run test:e2e
+PATH="$PWD/../.venv/bin:$PATH" npm run test:e2e
 ```
 
 Run in the foreground without a shell timeout or SIGTERM. Global teardown must
diff --git a/scripts/README.md b/scripts/README.md
index 6d2378f59..181b70ba1 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -40,7 +40,7 @@ Run manually for one-off or periodic data tasks:
 - **`backup_db.sh`** — Instance-user database backup. Writes daily/monthly dumps plus sibling `.sha` release markers, then runs retention and Google Drive upload through `cleanup_backups.py`. Runs via `backup-db-<instance>.timer`.
 - **`backup_instance_files.sh`** — Instance-user mutable file backup. Incrementally syncs instance-owned files (`phone-recordings`, `session-replays`, `mediafiles`) to Google Drive with 30-day dated remote archive folders for replaced/deleted files. Runs via `backup-files-<instance>.timer`.
 - **`pull_prod_backup.sh`** — Generates a scrubbed backup through the active production release, copies it locally, verifies its migration ledger and absence of private external-system configuration, and removes staging artifacts.
-- **`verify_scrubbed_backup.py`** — Fail-closed verifier for scrubbed custom-format PostgreSQL archives. Reports table row counts only; never emits credential values.
+- **`verify_scrubbed_backup.py`** — Fail-closed verifier for scrubbed custom-format PostgreSQL archives. Fully reads every archive entry, reports table row counts only, and never emits credential values. Its `--allow-legacy-client-baseline` option is temporary for the KAN-278 production cutover.
 - **`predeploy_backup.sh`** — Called by `scripts/server/deploy.sh` before each instance is switched to a new release. Stamps the dump with the current release hash so rollback is a (switch release, psql restore) pair. Runnable by hand: `sudo predeploy_backup.sh <instance>`
 - **`predeploy_rollback.sh`** — Restore an instance to the release + data that paired with a given commit hash. Usage: `sudo predeploy_rollback.sh <instance> <8-char-hash>` (interactive confirm; restores the dump into a temporary DB before stopping services and swapping DBs)
 - **`cleanup_backups.py`** — DB backup retention and remote upload. Copies local dumps before pruning, then purges only the matching expired remote names. Legacy `ts_dir` style: keep 24h + daily for a week + monthly beyond. `predeploy_*.sql.gz`: keep 30 days. `daily_*.sql.gz`: keep 14. `monthly_*.sql.gz`: keep 12. Other filenames left alone.
diff --git a/scripts/pull_prod_backup.sh b/scripts/pull_prod_backup.sh
index 15cbcf17b..40402d228 100755
--- a/scripts/pull_prod_backup.sh
+++ b/scripts/pull_prod_backup.sh
@@ -82,7 +82,12 @@ LOCAL_COPIED=true
 scp "$REMOTE_USER@$REMOTE_HOST:$TMP_PATH" "$LOCAL_DIR/"
 
 echo ">> Verifying scrubbed backup..."
-python "$REPO_ROOT/scripts/verify_scrubbed_backup.py" "$LOCAL_PATH"
+# TEMPORARY KAN-278: production still emits the legacy client migration label.
+# Remove this flag as soon as every production instance has completed the
+# client-to-company cutover and produced a verified company-schema backup.
+python "$REPO_ROOT/scripts/verify_scrubbed_backup.py" \
+    --allow-legacy-client-baseline "$LOCAL_PATH"
 
-echo ">> SHA-256: $(sha256sum "$LOCAL_PATH" | cut -d' ' -f1)"
+CHECKSUM="$(sha256sum "$LOCAL_PATH" | cut -d' ' -f1)"
+echo ">> SHA-256: $CHECKSUM"
 echo ">> Done: $LOCAL_PATH"
diff --git a/scripts/restore_checks/capture_pre_migration_state.py b/scripts/restore_checks/capture_pre_migration_state.py
index cf0fcf309..f7400d9d4 100644
--- a/scripts/restore_checks/capture_pre_migration_state.py
+++ b/scripts/restore_checks/capture_pre_migration_state.py
@@ -1,5 +1,10 @@
 #!/usr/bin/env python3
-"""Capture count-only evidence from a restored pre-KAN-278 database."""
+"""Capture count-only evidence from a restored pre-KAN-278 database.
+
+TEMPORARY KAN-278: remove this script after every production instance has
+completed the client-to-company cutover and produced a verified company-schema
+backup.
+"""
 
 import json
 import os
diff --git a/scripts/restore_checks/check_post_migration_state.py b/scripts/restore_checks/check_post_migration_state.py
index 2ad9bedb4..92d240ae2 100644
--- a/scripts/restore_checks/check_post_migration_state.py
+++ b/scripts/restore_checks/check_post_migration_state.py
@@ -1,5 +1,10 @@
 #!/usr/bin/env python3
-"""Verify KAN-278 preserved production-shaped data across its schema cutover."""
+"""Verify KAN-278 preserved production-shaped data across its schema cutover.
+
+TEMPORARY KAN-278: remove this script after every production instance has
+completed the client-to-company cutover and produced a verified company-schema
+backup.
+"""
 
 import json
 import os
diff --git a/scripts/server/deploy.sh b/scripts/server/deploy.sh
index 737fad4ba..6b8fc763f 100755
--- a/scripts/server/deploy.sh
+++ b/scripts/server/deploy.sh
@@ -336,6 +336,8 @@ for instance in "${TARGETS[@]}"; do
     switch_instance_release "$instance" "$TARGET_SHA"
     chown -h "$inst_user:$inst_user" "$instance_dir/app"
 
+    # TEMPORARY KAN-278: remove after every production instance has completed
+    # the client-to-company cutover and produced a verified company-schema backup.
     log "  Running relabel_client_app (KAN-278 one-time DB surgery)..."
     if ! "$SCRIPT_DIR/dw-run.sh" "$instance" python manage.py relabel_client_app; then
         log "  ERROR: relabel_client_app failed for $instance — services remain stopped"
diff --git a/scripts/verify_scrubbed_backup.py b/scripts/verify_scrubbed_backup.py
index 911657376..6581740cf 100644
--- a/scripts/verify_scrubbed_backup.py
+++ b/scripts/verify_scrubbed_backup.py
@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import argparse
 import subprocess
 import sys
 from pathlib import Path
@@ -55,28 +56,55 @@ def _table_rows(archive: Path, table: str) -> list[str]:
     return _copy_rows(sql)
 
 
-def _has_squashed_baseline(rows: list[str]) -> bool:
+def _squashed_baseline_apps(rows: list[str]) -> set[str]:
+    found: set[str] = set()
     for row in rows:
         columns = row.split("\t")
         if len(columns) < 3:
             continue
         app, migration = columns[1:3]
         if app in {"client", "company"} and migration == "0001_baseline":
-            return True
-    return False
+            found.add(app)
+    return found
+
+
+def _assert_squashed_baseline(
+    rows: list[str], *, allow_legacy_client_baseline: bool
+) -> None:
+    found = _squashed_baseline_apps(rows)
+    if found == {"company"}:
+        return
+    if found == {"client"} and allow_legacy_client_baseline:
+        return
+    if found == {"client"}:
+        raise RuntimeError(
+            "Backup uses the temporary pre-KAN-278 client migration label; "
+            "pass --allow-legacy-client-baseline only for the controlled "
+            "client-to-company cutover rehearsal"
+        )
+    if found == {"client", "company"}:
+        raise RuntimeError(
+            "Backup has mixed client/company 0001_baseline migration labels"
+        )
+    raise RuntimeError(
+        "Backup predates the July migration squash: no company "
+        "0001_baseline ledger entry"
+    )
 
 
-def verify_backup(archive: Path) -> None:
+def verify_backup(archive: Path, *, allow_legacy_client_baseline: bool = False) -> None:
     if not archive.is_file():
         raise RuntimeError(f"Backup not found: {archive}")
 
-    _pg_restore(archive, "--list")
+    # A catalogue read does not decompress every archive entry. Rendering the
+    # complete restore stream to /dev/null catches corruption anywhere in the
+    # archive without creating or modifying a database.
+    _pg_restore(archive, "--file=/dev/null")
     migration_rows = _table_rows(archive, "django_migrations")
-    if not _has_squashed_baseline(migration_rows):
-        raise RuntimeError(
-            "Backup predates the July migration squash: no client/company "
-            "0001_baseline ledger entry"
-        )
+    _assert_squashed_baseline(
+        migration_rows,
+        allow_legacy_client_baseline=allow_legacy_client_baseline,
+    )
 
     populated: list[str] = []
     for table in PRIVATE_CONFIG_TABLES:
@@ -91,13 +119,25 @@ def verify_backup(archive: Path) -> None:
 
 
 def main(argv: list[str]) -> int:
-    if len(argv) != 2:
-        print(f"Usage: {argv[0]} <scrubbed.dump>", file=sys.stderr)
-        return 2
-
-    archive = Path(argv[1])
-    verify_backup(archive)
-    print(f"Verified scrubbed backup: {archive}")
+    parser = argparse.ArgumentParser(
+        prog=argv[0],
+        description=__doc__,
+    )
+    parser.add_argument(
+        "--allow-legacy-client-baseline",
+        action="store_true",
+        help=(
+            "TEMPORARY KAN-278: accept a pre-cutover client.0001_baseline "
+            "ledger instead of the permanent company baseline"
+        ),
+    )
+    parser.add_argument("archive", type=Path)
+    args = parser.parse_args(argv[1:])
+    verify_backup(
+        args.archive,
+        allow_legacy_client_baseline=args.allow_legacy_client_baseline,
+    )
+    print(f"Verified scrubbed backup: {args.archive}")
     return 0
 
 

From 5a0192614ecef88a711a17a5446e1df9e58ef55d Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 16:38:24 +1200
Subject: [PATCH 35/73] fix: refresh KAN-278 reviewed dedup dataset for
 production drift

A pre-flight migration test (restore of prod backup 584ff0d1 into the hotfix
checkout, then relabel_client_app -> migrate) showed company.0008_apply_reviewed
_duplicate_cleanup aborting: the frozen reviewed-merge dataset no longer matched
production, which had drifted after the dataset was captured.

Two kinds of drift, all confirmed against the current prod snapshot:

Renamed/resolved entities (count-guard failures):
- Company "CASH SALE - IRVING" -> "CASH SALE - IRVING PATCHETT"
- Company "MC ALPINE HUSSMANN" -> "MCALPINE HUSSMANN" (whitespace)
- Person "IRVING"@"CASH SALE - IRVING" -> "IRVING PATCHETT" with email
  herbpatch20@gmail.com @ "CASH SALE - IRVING PATCHETT"
- Person "TIM MOORE" duplicate already resolved; decision dropped

New duplicates that appeared after the freeze (residual-assertion failures),
each human-reviewed 2026-07-15:
- Company "CASH SALE - PINNACLE BUILDS LTD - TOBY FOUNTAIN" -> "Pinnacle Build"
- Company "CASH SALE - YAN - 021809004" -> "Limbrother Ltd" (analyzer flagged
  review; confirmed same customer Yan Lim, yan@limbro.com, phone 021809004)
- Person "Yan" -> "YAN LIM" @ Limbrother Ltd
- Third "SIMON ROSE"@Proclimb row (transposed phone) folded into the existing
  Simon Rose decision (expected_people 2 -> 3)

Verified: re-restore + relabel_client_app + migrate now applies all 21
migrations cleanly through 0008 and the residual assertion; makemigrations
--check reports no drift.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../services/kan278_duplicate_cleanup.py      | 72 ++++++++++++-------
 1 file changed, 47 insertions(+), 25 deletions(-)

diff --git a/apps/company/services/kan278_duplicate_cleanup.py b/apps/company/services/kan278_duplicate_cleanup.py
index 89207359a..6354ddde9 100644
--- a/apps/company/services/kan278_duplicate_cleanup.py
+++ b/apps/company/services/kan278_duplicate_cleanup.py
@@ -546,9 +546,9 @@ class InvalidLinkDecision:
     ),
     CompanyMergeDecision(
         canonical_name="Irving",
-        names=("CASH SALE - IRVING", "CASH SALE -Irving", "Irving"),
+        names=("CASH SALE - IRVING PATCHETT", "CASH SALE -Irving", "Irving"),
         expected_rows=3,
-        evidence="production jobs CASH SALE - IRVING=2, CASH SALE -Irving=1, Irving=0; shared contact irving; shared email herbpatch20@gmail.com; shared phone +6421378335",
+        evidence="production: 'CASH SALE - IRVING' since renamed to 'CASH SALE - IRVING PATCHETT'; shared email herbpatch20@gmail.com; shared phone +6421378335",
     ),
     CompanyMergeDecision(
         canonical_name="Jack Lum and Co Limited",
@@ -672,10 +672,10 @@ class InvalidLinkDecision:
         evidence="production jobs Handro=1, MATERIAL HANDLING SOLUTIONS=1; shared phone +64212892852",
     ),
     CompanyMergeDecision(
-        canonical_name="MC ALPINE HUSSMANN",
-        names=("CASH SALE - MCALPINE HUSSMANN", "MC ALPINE HUSSMANN"),
+        canonical_name="MCALPINE HUSSMANN",
+        names=("CASH SALE - MCALPINE HUSSMANN", "MCALPINE HUSSMANN"),
         expected_rows=2,
-        evidence="production jobs CASH SALE - MCALPINE HUSSMANN=0, MC ALPINE HUSSMANN=5; shared email domain hussmann.com; shared email tim.moore@hussmann.com; shared phone +64272240844",
+        evidence="production: 'MC ALPINE HUSSMANN' since renamed to 'MCALPINE HUSSMANN'; shared email domain hussmann.com; shared email tim.moore@hussmann.com; shared phone +64272240844",
     ),
     CompanyMergeDecision(
         canonical_name="McConnell Dowell Constructors Limited",
@@ -1169,6 +1169,20 @@ class InvalidLinkDecision:
         expected_rows=2,
         evidence="production jobs CASH SALE - YOSHIKI FUJIMOTO=0, Yoshiki Fujimoto=2",
     ),
+    # KAN-278 drift refresh (human-reviewed 2026-07-15): duplicates that appeared
+    # in production after the original dataset was frozen.
+    CompanyMergeDecision(
+        canonical_name="Pinnacle Build",
+        names=("CASH SALE - PINNACLE BUILDS LTD - TOBY FOUNTAIN", "Pinnacle Build"),
+        expected_rows=2,
+        evidence="shared email toby@pinnaclebuildltd.co.nz (contact Toby Fountain); cash-sale alias of 'Pinnacle Build'",
+    ),
+    CompanyMergeDecision(
+        canonical_name="Limbrother Ltd",
+        names=("CASH SALE - YAN - 021809004", "Limbrother Ltd"),
+        expected_rows=2,
+        evidence="cash-sale alias for Yan Lim (yan@limbro.com, phone 021809004) of 'Limbrother Ltd'; analyzer flagged review, human-confirmed merge",
+    ),
 )
 
 REVIEWED_PERSON_MERGES: tuple[PersonMergeDecision, ...] = (
@@ -1797,13 +1811,19 @@ class InvalidLinkDecision:
         evidence="production jobs IAIN MATTHEW=1, IAN MATTHEW=1; shared phone +64274754864",
     ),
     PersonMergeDecision(
-        canonical=PersonSelector("IRVING", None, "CASH SALE - IRVING"),
+        canonical=PersonSelector(
+            "IRVING PATCHETT", "herbpatch20@gmail.com", "CASH SALE - IRVING PATCHETT"
+        ),
         members=(
-            PersonSelector("IRVING", None, "CASH SALE - IRVING"),
+            PersonSelector(
+                "IRVING PATCHETT",
+                "herbpatch20@gmail.com",
+                "CASH SALE - IRVING PATCHETT",
+            ),
             PersonSelector("Irving", None, "CASH SALE -Irving"),
         ),
         expected_people=2,
-        evidence="production jobs IRVING=2, Irving=1; shared phone +6421378335",
+        evidence="production: 'IRVING'@'CASH SALE - IRVING' since renamed to 'IRVING PATCHETT'@'CASH SALE - IRVING PATCHETT' with email herbpatch20@gmail.com; shared phone +6421378335",
     ),
     PersonMergeDecision(
         canonical=PersonSelector("Jason Hu", None, "Free Co Flooring"),
@@ -2369,9 +2389,12 @@ class InvalidLinkDecision:
             PersonSelector(
                 "SIMON ROSE", "simon.rose@proclimb.co.nz", "CASH SALE - SIMON ROSE"
             ),
+            # KAN-278 drift refresh (human-reviewed 2026-07-15): third row at
+            # Proclimb with a transposed phone (+64276442307) appeared after freeze.
+            PersonSelector("SIMON ROSE", "simon.rose@proclimb.co.nz", "Proclimb"),
         ),
-        expected_people=2,
-        evidence="production jobs Simon Rose=1, SIMON ROSE=1; shared email simon.rose@proclimb.co.nz; shared phone +64276642307",
+        expected_people=3,
+        evidence="production jobs Simon Rose=1, SIMON ROSE=1; shared email simon.rose@proclimb.co.nz; shared phone +64276642307 (third row +64276442307, transposed)",
     ),
     PersonMergeDecision(
         canonical=PersonSelector(
@@ -2449,21 +2472,9 @@ class InvalidLinkDecision:
         expected_people=2,
         evidence="production jobs Thomas=1, tom=0; shared phone +64220446045",
     ),
-    PersonMergeDecision(
-        canonical=PersonSelector(
-            "Timothy Moore", "tim.moore@hussmann.com", "MC ALPINE HUSSMANN"
-        ),
-        members=(
-            PersonSelector(
-                "TIM MOORE", "tim.moore@hussmann.com", "CASH SALE - MCALPINE HUSSMANN"
-            ),
-            PersonSelector(
-                "Timothy Moore", "tim.moore@hussmann.com", "MC ALPINE HUSSMANN"
-            ),
-        ),
-        expected_people=2,
-        evidence="production jobs TIM MOORE=2, Timothy Moore=2; shared email tim.moore@hussmann.com; shared phone +64272240844",
-    ),
+    # KAN-278: 'TIM MOORE'@'CASH SALE - MCALPINE HUSSMANN' duplicate already
+    # resolved in production — only a single 'Timothy Moore'@'MCALPINE HUSSMANN'
+    # remains, so there is nothing left to merge.
     PersonMergeDecision(
         canonical=PersonSelector(
             "Toby Andrews", "tobias.andrews@ventia.com", "Ventia NZ Limited"
@@ -2545,6 +2556,17 @@ class InvalidLinkDecision:
         expected_people=2,
         evidence="production jobs ZACH=1, ZACH LINDSAY=1; shared phone +64212216699",
     ),
+    # KAN-278 drift refresh (human-reviewed 2026-07-15): duplicate that appeared
+    # in production after the original dataset was frozen.
+    PersonMergeDecision(
+        canonical=PersonSelector("YAN LIM", "yan@limbro.com", "Limbrother Ltd"),
+        members=(
+            PersonSelector("YAN LIM", "yan@limbro.com", "Limbrother Ltd"),
+            PersonSelector("Yan", "yan@limbro.com", "CASH SALE - YAN - 021809004"),
+        ),
+        expected_people=2,
+        evidence="shared yan@limbro.com; 'Yan' is the cash-sale alias of 'YAN LIM' at Limbrother Ltd",
+    ),
 )
 
 

From afe7634a29f95ea38f57fdaf4d24a080ac30532e Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 16:39:12 +1200
Subject: [PATCH 36/73] docs: note the dw_msm_prod DB role for the hotfix
 checkout

The hotfix checkout repeatedly restores production dumps, which are all owned by
the dw_msm_prod role. Matching that role name locally lets dumps restore verbatim
(no ownership rewriting) and runs the app as the table owner exactly like prod.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/restore-prod-to-hotfix.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/restore-prod-to-hotfix.md b/docs/restore-prod-to-hotfix.md
index 1b53c4b2d..568ef3dfa 100644
--- a/docs/restore-prod-to-hotfix.md
+++ b/docs/restore-prod-to-hotfix.md
@@ -10,6 +10,21 @@ Xero org) is [restore-prod-to-nonprod.md](restore-prod-to-nonprod.md). A hotfix
 restore keeps real production data; the safety concern is different: the copy
 must never **act on** production's external systems.
 
+## Database role
+
+This checkout connects as the **`dw_msm_prod`** role (`.env` `DB_USER`), matching the
+owner recorded in every production dump. Keeping the role name identical to production
+means prod dumps restore **verbatim** — no ownership rewriting — and the app operates as
+the table owner exactly as production does. One-time setup (needs superuser):
+
+```
+sudo -u postgres psql \
+  -c "CREATE ROLE dw_msm_prod LOGIN CREATEDB PASSWORD '<the .env DB_PASSWORD>';"
+```
+
+The DB is owned by this role, so re-restores (drop + recreate `docketworks_prod`) need no
+further superuser access.
+
 ## Mandatory steps when restoring production into this checkout
 
 1. **Back up the production DB.** Take and retain a fresh backup of production

From 4a8dfd5ffd101a86273e5367ce0b8b057bb87ffd Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 17:47:49 +1200
Subject: [PATCH 37/73] docs: tag the psql role-setup block as bash

Review follow-up. Only the fence language changed. The one-off CREATE ROLE
command (password sourced from .env by the operator) is left as-is: it runs once
at checkout setup, not in the daily restore, and hiding the value from shell
history would break unattended UAT/CI restores while adding no real protection
(the same account already reads .env).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/restore-prod-to-hotfix.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/restore-prod-to-hotfix.md b/docs/restore-prod-to-hotfix.md
index 568ef3dfa..4a7547a22 100644
--- a/docs/restore-prod-to-hotfix.md
+++ b/docs/restore-prod-to-hotfix.md
@@ -17,7 +17,7 @@ owner recorded in every production dump. Keeping the role name identical to prod
 means prod dumps restore **verbatim** — no ownership rewriting — and the app operates as
 the table owner exactly as production does. One-time setup (needs superuser):
 
-```
+```bash
 sudo -u postgres psql \
   -c "CREATE ROLE dw_msm_prod LOGIN CREATEDB PASSWORD '<the .env DB_PASSWORD>';"
 ```

From 8c14000249752982d6ffac139d2fb9cb7667cfec Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 18:23:41 +1200
Subject: [PATCH 38/73] chore(xero): drop the dead XeroApp.tenant_id column
 (ADR 0017)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

XeroApp.tenant_id was never the source of truth for the active tenant —
get_tenant_id() resolves from CompanyDefaults.xero_tenant_id and the global
tenant cache, and the token-saver deliberately never wrote the column. It was
kept only as an "informational" field, which ADR 0017 forbids ("no 'for safety'
columns retained"). Remove it and every call site in one PR:

- model: drop the field (+ migration 0010_remove_xeroapp_tenant_id)
- serializer: drop tenant_id from fields / read_only_fields
- active_app.wipe_tokens_and_quota: stop nulling the (now absent) column; the
  global tenant cache is still cleared
- auth._make_token_saver: trim the docstring paragraph that justified the column
- tests: drop the tenant_id setup kwargs and assertions

Verified against restored prod data: get_tenant_id() still resolves the MSM
tenant (75e57cfd…) with the column gone; makemigrations --check clean;
test_xero_app_api green (18 tests).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/workflow/api/xero/active_app.py            |  1 -
 apps/workflow/api/xero/auth.py                  | 12 +++---------
 .../migrations/0010_remove_xeroapp_tenant_id.py | 17 +++++++++++++++++
 apps/workflow/models/xero_app.py                |  1 -
 apps/workflow/serializers.py                    |  2 --
 apps/workflow/tests/test_xero_app_api.py        |  5 -----
 frontend/schema.yml                             | 10 ----------
 frontend/src/api/generated/api.ts               |  6 ++----
 8 files changed, 22 insertions(+), 32 deletions(-)
 create mode 100644 apps/workflow/migrations/0010_remove_xeroapp_tenant_id.py

diff --git a/apps/workflow/api/xero/active_app.py b/apps/workflow/api/xero/active_app.py
index 13719dbb1..d9215a1f3 100644
--- a/apps/workflow/api/xero/active_app.py
+++ b/apps/workflow/api/xero/active_app.py
@@ -116,7 +116,6 @@ def wipe_tokens_and_quota(app: XeroApp) -> None:
     from Xero's perspective; old tokens and quota state are invalid).
     """
     XeroApp.objects.filter(id=app.id).update(
-        tenant_id=None,
         token_type=None,
         access_token=None,
         refresh_token=None,
diff --git a/apps/workflow/api/xero/auth.py b/apps/workflow/api/xero/auth.py
index c008d9b80..70c482045 100644
--- a/apps/workflow/api/xero/auth.py
+++ b/apps/workflow/api/xero/auth.py
@@ -145,15 +145,9 @@ def _make_token_saver(app_id) -> Callable[[Dict[str, Any]], None]:
     here, NOT to whichever row is currently active. This is what makes
     credential swaps safe under concurrent refreshes.
 
-    The saver writes tokens only — never tenant_id. tenant_id is per-app
-    and a connections lookup needs an ApiClient; the only ApiClient
-    available here is the global ``api_client`` proxy, which resolves to
-    the currently active row, not necessarily ``app_id``. Writing the
-    proxy's tenant onto ``app_id``'s row would corrupt the row→tenant
-    binding the moment ``app_id`` isn't the active one (e.g. a refresh
-    in flight when an operator swaps active apps). XeroApp.tenant_id is
-    informational; live calls read CompanyDefaults.xero_tenant_id and the
-    global TENANT_ID_CACHE_KEY, not this column.
+    The saver writes token fields only. The active tenant lives on
+    CompanyDefaults.xero_tenant_id and the global TENANT_ID_CACHE_KEY —
+    resolved per call by get_tenant_id(), never stored on the app row.
     """
 
     def _save(token: Dict[str, Any]) -> None:
diff --git a/apps/workflow/migrations/0010_remove_xeroapp_tenant_id.py b/apps/workflow/migrations/0010_remove_xeroapp_tenant_id.py
new file mode 100644
index 000000000..bf78e4346
--- /dev/null
+++ b/apps/workflow/migrations/0010_remove_xeroapp_tenant_id.py
@@ -0,0 +1,17 @@
+# Generated by Django 6.0.4 on 2026-07-15 06:19
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("workflow", "0009_rename_remaining_crm_telemetry_sources"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="xeroapp",
+            name="tenant_id",
+        ),
+    ]
diff --git a/apps/workflow/models/xero_app.py b/apps/workflow/models/xero_app.py
index 07099b791..380b6b3b7 100644
--- a/apps/workflow/models/xero_app.py
+++ b/apps/workflow/models/xero_app.py
@@ -31,7 +31,6 @@ class XeroApp(models.Model):
 
     is_active = models.BooleanField(default=False)
 
-    tenant_id = models.CharField(max_length=100, null=True, blank=True)
     token_type = models.CharField(max_length=50, null=True, blank=True)
     access_token = models.TextField(null=True, blank=True)
     refresh_token = models.TextField(null=True, blank=True)
diff --git a/apps/workflow/serializers.py b/apps/workflow/serializers.py
index 65a773da2..84ffe9ca7 100644
--- a/apps/workflow/serializers.py
+++ b/apps/workflow/serializers.py
@@ -119,7 +119,6 @@ class Meta:
             "webhook_key",
             "is_active",
             "has_tokens",
-            "tenant_id",
             "day_remaining",
             "minute_remaining",
             "snapshot_at",
@@ -131,7 +130,6 @@ class Meta:
             "id",
             "is_active",
             "has_tokens",
-            "tenant_id",
             "day_remaining",
             "minute_remaining",
             "snapshot_at",
diff --git a/apps/workflow/tests/test_xero_app_api.py b/apps/workflow/tests/test_xero_app_api.py
index a9e93c0f2..65ef55f22 100644
--- a/apps/workflow/tests/test_xero_app_api.py
+++ b/apps/workflow/tests/test_xero_app_api.py
@@ -79,7 +79,6 @@ def test_list_returns_safe_fields_only(self):
             is_active=True,
             access_token="SECRET-DO-NOT-LEAK",
             refresh_token="ALSO-SECRET",
-            tenant_id="tenant-a",
             expires_at=expires,
             day_remaining=4321,
             minute_remaining=55,
@@ -94,7 +93,6 @@ def test_list_returns_safe_fields_only(self):
         self.assertEqual(row["client_id"], "c-a")
         self.assertTrue(row["is_active"])
         self.assertTrue(row["has_tokens"])
-        self.assertEqual(row["tenant_id"], "tenant-a")
         self.assertEqual(row["day_remaining"], 4321)
         self.assertEqual(row["minute_remaining"], 55)
         # Forbidden surface — none of these may appear in the response:
@@ -195,7 +193,6 @@ def test_patch_label_only_does_not_wipe_tokens(self):
             client_id="c-a",
             access_token="aaa",
             refresh_token="rrr",
-            tenant_id="t",
             expires_at=expires,
             day_remaining=42,
         )
@@ -215,7 +212,6 @@ def test_patch_client_id_wipes_tokens_and_quota(self):
             client_id="c-a",
             access_token="aaa",
             refresh_token="rrr",
-            tenant_id="t",
             expires_at=expires,
             day_remaining=42,
             minute_remaining=10,
@@ -231,7 +227,6 @@ def test_patch_client_id_wipes_tokens_and_quota(self):
         self.assertEqual(row.client_id, "c-a-new")
         self.assertIsNone(row.access_token)
         self.assertIsNone(row.refresh_token)
-        self.assertIsNone(row.tenant_id)
         self.assertIsNone(row.day_remaining)
         self.assertIsNone(row.snapshot_at)
 
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 4968bcf2d..b09a2283a 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -23538,10 +23538,6 @@ components:
         has_tokens:
           type: boolean
           readOnly: true
-        tenant_id:
-          type: string
-          readOnly: true
-          nullable: true
         day_remaining:
           type: integer
           readOnly: true
@@ -23580,7 +23576,6 @@ components:
         - minute_remaining
         - redirect_uri
         - snapshot_at
-        - tenant_id
         - updated_at
     XeroAppConfig:
       type: object
@@ -23623,10 +23618,6 @@ components:
         has_tokens:
           type: boolean
           readOnly: true
-        tenant_id:
-          type: string
-          readOnly: true
-          nullable: true
         day_remaining:
           type: integer
           readOnly: true
@@ -23665,7 +23656,6 @@ components:
         - minute_remaining
         - redirect_uri
         - snapshot_at
-        - tenant_id
         - updated_at
     XeroAppCreateRequest:
       type: object
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index 0388ee89f..defad838d 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -2557,15 +2557,15 @@ const CompanyLinkWriteRequest = z
 const PersonContactMethodWriteRequest = z.object({
   method_type: ContactMethodTypeEnum,
   value: z.string().min(1).max(255),
-  label: z.string().optional().default(''),
   is_primary: z.boolean().optional().default(false),
+  label: z.string().optional().default(''),
 })
 const PatchedPersonContactMethodWriteRequest = z
   .object({
     method_type: ContactMethodTypeEnum,
     value: z.string().min(1).max(255),
-    label: z.string().default(''),
     is_primary: z.boolean().default(false),
+    label: z.string().default(''),
   })
   .partial()
 const CategoriesResponse = z.object({
@@ -3550,7 +3550,6 @@ const XeroApp = z.object({
   redirect_uri: z.string().max(512),
   is_active: z.boolean(),
   has_tokens: z.boolean(),
-  tenant_id: z.string().nullable(),
   day_remaining: z.number().int().nullable(),
   minute_remaining: z.number().int().nullable(),
   snapshot_at: z.string().datetime({ offset: true }).nullable(),
@@ -3572,7 +3571,6 @@ const XeroAppCreate = z.object({
   redirect_uri: z.string().max(512),
   is_active: z.boolean(),
   has_tokens: z.boolean(),
-  tenant_id: z.string().nullable(),
   day_remaining: z.number().int().nullable(),
   minute_remaining: z.number().int().nullable(),
   snapshot_at: z.string().datetime({ offset: true }).nullable(),

From 02a136e01956e0d4a37d5149ba976cbedda1fdcc Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 18:46:30 +1200
Subject: [PATCH 39/73] test(xero): drop remaining XeroApp.tenant_id refs in
 test_xero_app_active

Stragglers from the column removal that only surfaced when running this module
(the earlier commit ran test_xero_app_api only): _row(tenant_id=...) kwargs and
the wipe-assertion list entry. Completes the ADR-0017 removal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/workflow/tests/test_xero_app_active.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/apps/workflow/tests/test_xero_app_active.py b/apps/workflow/tests/test_xero_app_active.py
index 34a75e96f..e0a030118 100644
--- a/apps/workflow/tests/test_xero_app_active.py
+++ b/apps/workflow/tests/test_xero_app_active.py
@@ -186,7 +186,6 @@ def test_wipes_token_and_quota_fields(self) -> None:
 
         row = _row(
             client_id="a1",
-            tenant_id="t",
             access_token="aaa",
             refresh_token="rrr",
             token_type="Bearer",
@@ -200,7 +199,6 @@ def test_wipes_token_and_quota_fields(self) -> None:
         wipe_tokens_and_quota(row)
         row.refresh_from_db()
         for field in [
-            "tenant_id",
             "access_token",
             "refresh_token",
             "token_type",
@@ -222,7 +220,7 @@ def test_wipe_invalidates_tenant_id_cache(self) -> None:
         from apps.workflow.api.xero.active_app import wipe_tokens_and_quota
         from apps.workflow.api.xero.constants import TENANT_ID_CACHE_KEY
 
-        row = _row(client_id="a1", tenant_id="t-1")
+        row = _row(client_id="a1")
         cache.set(TENANT_ID_CACHE_KEY, "stale-tenant")
         wipe_tokens_and_quota(row)
         self.assertIsNone(cache.get(TENANT_ID_CACHE_KEY))

From 46a31cd45d39a7c7211c8f3914f768747de8a75d Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 18:47:15 +1200
Subject: [PATCH 40/73] refactor(xero): drop dead connections fallback from
 get_tenant_id (ADR 0015)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

get_tenant_id() reached get_tenant_id_from_connections() only in the else of
`if company_defaults.xero_tenant_id`, and that function raises immediately when
CompanyDefaults.xero_tenant_id is empty — so the branch made a live /connections
call and then always raised, never returning a tenant. Replace it with a direct
persisted raise. Resolution is now cache -> CompanyDefaults.xero_tenant_id ->
error: a cache plus one source of truth, no read-side fallback (ADR 0015).

get_tenant_id_from_connections() is kept (still used by xero_sync_service).
Verified: get_tenant_id() still resolves the live tenant; 72 xero tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/workflow/api/xero/auth.py | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/apps/workflow/api/xero/auth.py b/apps/workflow/api/xero/auth.py
index 70c482045..0d7e660db 100644
--- a/apps/workflow/api/xero/auth.py
+++ b/apps/workflow/api/xero/auth.py
@@ -364,8 +364,11 @@ def exchange_code_for_token(
 
 
 def get_tenant_id() -> str:
-    """Retrieve the tenant ID, refreshing the token or fetching from Xero
-    connections if needed."""
+    """Return the active Xero tenant ID (cached in TENANT_ID_CACHE_KEY).
+
+    Source of truth is CompanyDefaults.xero_tenant_id; the cache only avoids
+    re-reading it. An unset value is a configuration error, not a fallback case.
+    """
     tenant_id = cache.get(TENANT_ID_CACHE_KEY)
 
     payload = get_valid_token()
@@ -379,20 +382,15 @@ def get_tenant_id() -> str:
         return tenant_id
 
     company_defaults = CompanyDefaults.get_solo()
-    if company_defaults.xero_tenant_id:
-        tenant_id = company_defaults.xero_tenant_id
-        cache.set(TENANT_ID_CACHE_KEY, tenant_id)
-        logger.info("Xero tenant ID resolved from CompanyDefaults and cached")
-        return tenant_id
-
-    try:
-        tenant_id = get_tenant_id_from_connections()
-        cache.set(TENANT_ID_CACHE_KEY, tenant_id)
-        logger.info("Xero tenant ID resolved from Xero connections and cached")
-    except AlreadyLoggedException:
-        raise
-    except Exception as exc:
+    if not company_defaults.xero_tenant_id:
+        exc = RuntimeError(
+            "No Xero tenant ID configured in company defaults. "
+            "Please set this up first."
+        )
         err = persist_app_error(exc)
         raise AlreadyLoggedException(exc, err.id) from exc
 
+    tenant_id = company_defaults.xero_tenant_id
+    cache.set(TENANT_ID_CACHE_KEY, tenant_id)
+    logger.info("Xero tenant ID resolved from CompanyDefaults and cached")
     return tenant_id

From 1867418d34de7f2f20c97a27940ec721af614d7c Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 18:59:50 +1200
Subject: [PATCH 41/73] docs: fix stale docketworks_prod checkout paths in
 restore-prod-to-hotfix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hotfix checkout is `~/src/docketworks_hotfix` (matches the .env storage
roots and the docketworks-msm-hotfix domain); the doc still referenced the old
`~/src/docketworks_prod` directory name from before the rename. Update the four
path references (intro + MEDIA_ROOT/PHONE_RECORDING/SESSION_REPLAY targets).
The `docketworks_prod` DB name is unchanged — that is the database, not the dir.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/restore-prod-to-hotfix.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/restore-prod-to-hotfix.md b/docs/restore-prod-to-hotfix.md
index 4a7547a22..795f4a185 100644
--- a/docs/restore-prod-to-hotfix.md
+++ b/docs/restore-prod-to-hotfix.md
@@ -1,6 +1,6 @@
 # Restore Production to the Hotfix Checkout
 
-This checkout (`~/src/docketworks_prod`) is the MSM **hotfix environment**: its
+This checkout (`~/src/docketworks_hotfix`) is the MSM **hotfix environment**: its
 database is refreshed by restoring the production DB into it, it is served via
 the `docketworks-msm-hotfix` ngrok domain, and the E2E suite runs here to verify
 prod hotfixes.
@@ -48,10 +48,10 @@ further superuser access.
    `session-replays/`.
 
    Source: `/opt/docketworks/instances/msm-prod/` on MSM. Targets:
-   `MEDIA_ROOT=/home/corrin/src/docketworks_prod/mediafiles`,
-   `PHONE_RECORDING_STORAGE_ROOT=/home/corrin/src/docketworks_prod/.local/phone-recordings`,
+   `MEDIA_ROOT=/home/corrin/src/docketworks_hotfix/mediafiles`,
+   `PHONE_RECORDING_STORAGE_ROOT=/home/corrin/src/docketworks_hotfix/.local/phone-recordings`,
    and
-   `SESSION_REPLAY_STORAGE_ROOT=/home/corrin/src/docketworks_prod/.local/session-replays`.
+   `SESSION_REPLAY_STORAGE_ROOT=/home/corrin/src/docketworks_hotfix/.local/session-replays`.
    Do not point any of these at `~/src/docketworks`. Verify representative
    DB-backed files, especially logos and phone recordings, before running E2E.
 

From 7ce06fecd439701950a02049cb59db45def44882 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 20:50:48 +1200
Subject: [PATCH 42/73] fix(crm): pass route param as prop on People detail
 page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The People detail route (`/crm/people/:id`) was missing the
`<route lang="json">{"props": true}</route>` SFC block that its sibling
`crm/companies/[id].vue` has. Without it, unplugin-vue-router did not pass
the `:id` route param to `[id].vue`'s `defineProps<{ id: string }>()`, so
`props.id` was `undefined`. The page then called `/api/people/undefined/`
(+ contact-methods, company-links), all 404 — "Failed to load person" and
the company link never rendered.

The list, `openPerson`, and the router were all correct: the browser
navigated to `/crm/people/<uuid>`; only `props.id` was undefined (Vue warned
"Missing required prop: id"). Adding the `<route>` block, mirroring the
companies page, wires the param through.

Verified: `frontend/tests/crm/people.spec.ts` — both tests pass (was failing
test 1 at the company-link assertion + 3 console 404s).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/pages/crm/people/[id].vue | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/frontend/src/pages/crm/people/[id].vue b/frontend/src/pages/crm/people/[id].vue
index 912c88884..1097bf6d1 100644
--- a/frontend/src/pages/crm/people/[id].vue
+++ b/frontend/src/pages/crm/people/[id].vue
@@ -233,6 +233,12 @@
   </AppLayout>
 </template>
 
+<route lang="json">
+{
+  "props": true
+}
+</route>
+
 <script setup lang="ts">
 import { onMounted, ref } from 'vue'
 import { useRouter } from 'vue-router'

From ce3b7a877abaeda48003eadf1ba2dc1ad4c0cf66 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Wed, 15 Jul 2026 21:07:31 +1200
Subject: [PATCH 43/73] fix(e2e): stop teardown reading the dropped
 XeroApp.tenant_id column
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The E2E global-teardown saves the live Xero token before the DB restore and
re-injects it after, so the connection stays live (the backup's token is stale).
Its SELECT/UPDATE against `workflow_xeroapp` still listed `tenant_id`, which
commit 8c140002 dropped (migration 0010_remove_xeroapp_tenant_id, ADR 0017). The
SELECT therefore errored ("column does not exist"), was swallowed by a catch that
mislabelled it "table may not exist yet", and left `xeroAppTokenRow` null — so
the token was never saved and never re-injected. The restore brought back the
backup's (likely expired) token, silently breaking the preservation this block
exists to provide.

`tenant_id` on `workflow_xeroapp` was the dead/fake column: never the source of
truth (get_tenant_id resolves from CompanyDefaults.xero_tenant_id) and never
written. The real tenant lives in CompanyDefaults.xero_tenant_id, which is in the
backup and restored intact — the tenant doesn't change mid-run, so it needs no
active preservation. Only the token, which refreshes mid-run, does.

- Drop `tenant_id` from the token SELECT and the re-inject UPDATE.
- Surface the real error in the catch instead of the misleading "table may not
  exist yet" message, so a future schema change isn't misdiagnosed (ADR 0028).

Verified: E2E teardown now logs "Saving current active Xero app token..." with no
warning, then "Active Xero app token restored." and "Database restored
successfully." (previously the restore line never appeared).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/tests/scripts/global-teardown.ts | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/frontend/tests/scripts/global-teardown.ts b/frontend/tests/scripts/global-teardown.ts
index a74d0a03b..48ee00106 100644
--- a/frontend/tests/scripts/global-teardown.ts
+++ b/frontend/tests/scripts/global-teardown.ts
@@ -100,7 +100,7 @@ function restoreDatabase(lockContents: string) {
       dbConfig,
       `SELECT row_to_json(t)
        FROM (
-         SELECT id, tenant_id, token_type, access_token, refresh_token, expires_at, scope
+         SELECT id, token_type, access_token, refresh_token, expires_at, scope
          FROM workflow_xeroapp
          WHERE is_active = true
            AND access_token IS NOT NULL
@@ -111,8 +111,8 @@ function restoreDatabase(lockContents: string) {
     if (xeroAppTokenRow) {
       fs.writeFileSync(xeroTokenFile, xeroAppTokenRow, 'utf8')
     }
-  } catch {
-    console.warn('[db] Could not read active Xero app token (table may not exist yet). Skipping.')
+  } catch (e) {
+    console.warn('[db] Could not read active Xero app token:', (e as Error).message)
   }
 
   // Let in-flight Celery/Xero work finish against the dirty test DB before
@@ -187,8 +187,7 @@ function restoreDatabase(lockContents: string) {
       runPsql(
         dbConfig,
         `UPDATE workflow_xeroapp
-         SET tenant_id = ${sqlNullableString(token.tenant_id)},
-             token_type = ${sqlString(token.token_type)},
+         SET token_type = ${sqlString(token.token_type)},
              access_token = ${sqlString(token.access_token)},
              refresh_token = ${sqlString(token.refresh_token)},
              expires_at = ${sqlString(token.expires_at)},

From 0c082a1735fc57b48abf6df29e843c81c629376c Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 10:34:47 +1200
Subject: [PATCH 44/73] fix(e2e): pin lazily-discovered heavy deps in
 optimizeDeps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

E2E runs against the Vite dev server. Routes are lazy-loaded via
file-based vue-router, so Vite's cold-start dep scanner never crawls
into route components and first discovers heavy libs (quill, pdf-vue3,
etc.) on first navigation to /jobs/:id. Discovering a new dep mid-run
triggers a full-page reload ("new dependencies optimized"), which
aborts the client-side router.push and times out the job-create
redirect in createTestJob (submitJobAndWaitForCreatedJob).

Pin those deps in optimizeDeps.include so they're bundled at cold
start and never re-optimized mid-session. Dev/test only — production
serves a static build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/vite.config.ts | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index ab2694bbd..587fd1b4e 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -75,6 +75,22 @@ export default defineConfig(({ mode }) => {
         vue: 'vue/dist/vue.esm-bundler.js',
       },
     },
+    optimizeDeps: {
+      // Routes are lazy-loaded (file-based vue-router), so Vite's cold-start
+      // dep scanner never crawls into them and first discovers these heavy
+      // libs on first navigation. A mid-run re-optimize forces a full page
+      // reload that aborts the client-side router.push and flakes E2E (the
+      // job-create redirect times out). Pin them so they're bundled at cold
+      // start. Dev/test only — production serves a static build.
+      include: [
+        'quill', // dynamic import in RichTextEditor (job settings tab)
+        'pdf-vue3', // WorkshopPdfViewer / JobPdfDialog
+        '@tanstack/vue-table',
+        'sortablejs',
+        'dompurify',
+        '@kodeglot/vue-calendar',
+      ],
+    },
     server: {
       host: '0.0.0.0',
       allowedHosts,

From e6a387472ef8fc1b120433b3b682775152acade9 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 11:16:35 +1200
Subject: [PATCH 45/73] chore(scripts): add pull_prod_files.sh to restore
 instance files to hotfix

A prod DB restore into the hotfix checkout brings file paths but not the
files, so DB-referenced media and recordings 404 until the bytes are copied
over (restore-prod-to-hotfix.md step 4). This was documented but had no
script -- the file-side gap opposite pull_prod_backup.sh (DB) and the
restore-side inverse of backup_instance_files.sh (which pushes the same dirs
to Drive).

pull_prod_files.sh incrementally rsyncs the identical set -- mediafiles,
phone-recordings, session-replays -- from a prod instance into the local
storage roots read from .env, escalating to the instance user on the far
side via `sudo -iu` (same pattern as pull_prod_backup.sh) since the files
are instance-user-owned. rsync keeps re-runs cheap: only new/changed files
move.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 scripts/README.md          |  2 ++
 scripts/pull_prod_files.sh | 66 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100755 scripts/pull_prod_files.sh

diff --git a/scripts/README.md b/scripts/README.md
index 181b70ba1..dfeec76c2 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -40,6 +40,8 @@ Run manually for one-off or periodic data tasks:
 - **`backup_db.sh`** — Instance-user database backup. Writes daily/monthly dumps plus sibling `.sha` release markers, then runs retention and Google Drive upload through `cleanup_backups.py`. Runs via `backup-db-<instance>.timer`.
 - **`backup_instance_files.sh`** — Instance-user mutable file backup. Incrementally syncs instance-owned files (`phone-recordings`, `session-replays`, `mediafiles`) to Google Drive with 30-day dated remote archive folders for replaced/deleted files. Runs via `backup-files-<instance>.timer`.
 - **`pull_prod_backup.sh`** — Generates a scrubbed backup through the active production release, copies it locally, verifies its migration ledger and absence of private external-system configuration, and removes staging artifacts.
+- **`pull_prod_files.sh`** — File-side companion to `pull_prod_backup.sh`: incrementally rsyncs a prod instance's `mediafiles`, `phone-recordings`, and `session-replays` (the same set `backup_instance_files.sh` pushes to Drive) into this checkout's local storage roots from `.env`. Files are instance-user-owned, so the remote rsync escalates via `sudo -iu <instance-user>`. A DB restore brings file paths but not the files (see [`docs/restore-prod-to-hotfix.md`](../docs/restore-prod-to-hotfix.md) step 4). Usage: `scripts/pull_prod_files.sh [host] [instance-user]` (defaults: `MSM dw_msm_prod`).
+- **`pull_prod_recordings.sh`** — Incrementally rsyncs a production instance's `phone-recordings/` and `session-replays/` into this checkout's local storage roots (from `.env`). Files are instance-user-owned, so the remote rsync escalates via `sudo -iu <instance-user>`. Complements a DB restore, which brings file paths but not the files (see [`docs/restore-prod-to-hotfix.md`](../docs/restore-prod-to-hotfix.md) step 4). Usage: `scripts/pull_prod_recordings.sh [host] [instance-user]` (defaults: `MSM dw_msm_prod`).
 - **`verify_scrubbed_backup.py`** — Fail-closed verifier for scrubbed custom-format PostgreSQL archives. Fully reads every archive entry, reports table row counts only, and never emits credential values. Its `--allow-legacy-client-baseline` option is temporary for the KAN-278 production cutover.
 - **`predeploy_backup.sh`** — Called by `scripts/server/deploy.sh` before each instance is switched to a new release. Stamps the dump with the current release hash so rollback is a (switch release, psql restore) pair. Runnable by hand: `sudo predeploy_backup.sh <instance>`
 - **`predeploy_rollback.sh`** — Restore an instance to the release + data that paired with a given commit hash. Usage: `sudo predeploy_rollback.sh <instance> <8-char-hash>` (interactive confirm; restores the dump into a temporary DB before stopping services and swapping DBs)
diff --git a/scripts/pull_prod_files.sh b/scripts/pull_prod_files.sh
new file mode 100755
index 000000000..298ce9200
--- /dev/null
+++ b/scripts/pull_prod_files.sh
@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Pull a production instance's mutable file directories into this checkout's
+# local storage roots. This is the file-side companion to pull_prod_backup.sh
+# (which pulls the DB) and the restore-side inverse of backup_instance_files.sh
+# (which pushes the same dirs to Google Drive); it covers the identical set:
+# mediafiles, phone-recordings, session-replays.
+#
+# A prod DB restore (docs/restore-prod-to-hotfix.md step 4) brings file *paths*,
+# not the files, so DB-referenced media/recordings 404 until the bytes are
+# copied over. Production stores them under the instance user's home
+# (/opt/docketworks/instances/<instance>/), owned by <instance-user> and
+# unreadable by the SSH login user -- so rsync runs on the far side as the
+# instance user via `sudo -iu`, the same escalation as pull_prod_backup.sh.
+# rsync is incremental: re-runs copy only new or changed files.
+#
+# Usage:
+#   scripts/pull_prod_files.sh [host] [instance-user]
+#
+# Args (both optional; defaults target MSM production):
+#   host           SSH target (ssh-config alias or hostname).  Default: MSM
+#   instance-user  Unix user owning the instance files remotely.  Default: dw_msm_prod
+#
+# Env:
+#   REMOTE_USER  SSH login user on <host>.  Defaults to the local $USER.
+#   MEDIA_ROOT / PHONE_RECORDING_STORAGE_ROOT / SESSION_REPLAY_STORAGE_ROOT
+#               Local destinations, read from ./.env when unset.
+
+set -euo pipefail
+
+REMOTE_HOST="${1:-MSM}"
+INSTANCE_USER="${2:-dw_msm_prod}"
+REMOTE_USER="${REMOTE_USER:-$USER}"
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Read KEY=value from the repo .env, stripping optional surrounding quotes.
+env_val() {
+    local key="$1"
+    [[ -f "$REPO_ROOT/.env" ]] || return 0
+    sed -n "s/^${key}=//p" "$REPO_ROOT/.env" | tail -1 \
+        | sed -e 's/^"//' -e 's/"$//' -e "s/^'//" -e "s/'\$//"
+}
+
+# Remote subdir (relative to the instance user's home) -> local destination.
+declare -A DESTS=(
+    [mediafiles]="$(env_val MEDIA_ROOT)"
+    [phone-recordings]="$(env_val PHONE_RECORDING_STORAGE_ROOT)"
+    [session-replays]="$(env_val SESSION_REPLAY_STORAGE_ROOT)"
+)
+
+echo ">> Pulling instance files from $REMOTE_USER@$REMOTE_HOST (owned by $INSTANCE_USER)"
+for subdir in mediafiles phone-recordings session-replays; do
+    dest="${DESTS[$subdir]}"
+    if [[ -z "$dest" ]]; then
+        echo "Error: no local destination configured for $subdir (missing .env entry)" >&2
+        exit 1
+    fi
+    echo ">> Syncing $subdir -> $dest"
+    mkdir -p "$dest"
+    rsync -ah --stats \
+        -e ssh \
+        --rsync-path="sudo -iu $INSTANCE_USER rsync" \
+        "$REMOTE_USER@$REMOTE_HOST:$subdir/" \
+        "$dest/"
+done
+echo ">> Done."

From 85463fe37ca9f1f34cefade030ea4c7c5f9ae1b0 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 11:18:32 +1200
Subject: [PATCH 46/73] docs(restore): point step 4 at pull_prod_files.sh

The manual file-copy step now has a script; reference it instead of
describing the copy by hand.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/restore-prod-to-hotfix.md | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/docs/restore-prod-to-hotfix.md b/docs/restore-prod-to-hotfix.md
index 795f4a185..f2f205e62 100644
--- a/docs/restore-prod-to-hotfix.md
+++ b/docs/restore-prod-to-hotfix.md
@@ -43,17 +43,21 @@ further superuser access.
 
 4. **Restore production-owned files referenced by the DB.** The DB restore
    brings file paths, not the files. Copy the mutable production instance
-   directories into this checkout before testing anything that renders files.
-   This includes at least `mediafiles/`, `phone-recordings/`, and
-   `session-replays/`.
+   directories into this checkout before testing anything that renders files:
+   `mediafiles/`, `phone-recordings/`, and `session-replays/`.
 
-   Source: `/opt/docketworks/instances/msm-prod/` on MSM. Targets:
-   `MEDIA_ROOT=/home/corrin/src/docketworks_hotfix/mediafiles`,
-   `PHONE_RECORDING_STORAGE_ROOT=/home/corrin/src/docketworks_hotfix/.local/phone-recordings`,
-   and
-   `SESSION_REPLAY_STORAGE_ROOT=/home/corrin/src/docketworks_hotfix/.local/session-replays`.
-   Do not point any of these at `~/src/docketworks`. Verify representative
-   DB-backed files, especially logos and phone recordings, before running E2E.
+   Run `scripts/pull_prod_files.sh` (defaults to `MSM dw_msm_prod`). It
+   incrementally rsyncs those three dirs from the instance user's home
+   (`/opt/docketworks/instances/msm-prod/` on MSM) into the local storage roots
+   read from `.env` — `MEDIA_ROOT`, `PHONE_RECORDING_STORAGE_ROOT`, and
+   `SESSION_REPLAY_STORAGE_ROOT`. The files are instance-user-owned, so the
+   remote rsync escalates via `sudo -iu dw_msm_prod`. Re-runs copy only
+   new/changed files, so it is cheap to run after every DB restore.
+
+   Keep those `.env` roots inside this checkout (`.local/...` and
+   `mediafiles/`); never point them at `~/src/docketworks`. Verify
+   representative DB-backed files, especially logos and phone recordings,
+   before running E2E.
 
 5. **Run the hotfix processes with `XERO_READONLY=True`** so that even a
    reconnected Xero cannot write to MSM's real organisation. This is

From 5d86101decf3f1f012263aa802c06d5815db1177 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 11:18:47 +1200
Subject: [PATCH 47/73] fix: apply Xero sales branding theme

---
 apps/workflow/__init__.py                     |   2 +
 apps/workflow/accounting/provider.py          |   5 +
 apps/workflow/accounting/types.py             |  11 +
 apps/workflow/accounting/xero/provider.py     |  46 +++-
 apps/workflow/fixtures/company_defaults.json  |   1 +
 .../fixtures/company_defaults_prospect.json   |   1 +
 apps/workflow/management/commands/xero.py     |  48 +++-
 ...nydefaults_xero_sales_branding_theme_id.py |  27 +++
 apps/workflow/models/company_defaults.py      |  10 +
 apps/workflow/models/settings_metadata.py     |   7 +-
 apps/workflow/serializers.py                  |  10 +
 .../tests/test_company_defaults_api.py        |  28 +++
 .../tests/test_company_defaults_schema.py     |  21 ++
 .../tests/test_localdate_regression.py        |  25 +-
 .../tests/test_xero_branding_themes.py        | 223 ++++++++++++++++++
 .../workflow/tests/test_xero_setup_command.py | 130 ++++++++++
 apps/workflow/urls.py                         |   5 +
 apps/workflow/views/xero/__init__.py          |   2 +
 apps/workflow/views/xero/xero_base_manager.py |   9 +
 apps/workflow/views/xero/xero_helpers.py      |  19 +-
 .../views/xero/xero_invoice_manager.py        |  25 +-
 .../workflow/views/xero/xero_quote_manager.py |  25 +-
 apps/workflow/views/xero/xero_view.py         |  43 ++++
 docs/client_onboarding.md                     |  14 ++
 docs/instance-setup-demo.md                   |   5 +
 docs/instance-setup-production.md             |   8 +-
 docs/restore-prod-to-nonprod.md               |   9 +-
 docs/server_setup.md                          |   8 +-
 docs/urls/workflow.md                         |   1 +
 frontend/schema.yml                           |  82 +++++++
 frontend/src/api/generated/api.ts             |  49 +++-
 frontend/src/components/SectionForm.vue       |  86 +++++++
 .../components/__tests__/SectionForm.test.ts  | 156 ++++++++++--
 frontend/tests/company-defaults.spec.ts       |  58 +++++
 mypy-baseline.txt                             |  10 -
 35 files changed, 1150 insertions(+), 59 deletions(-)
 create mode 100644 apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
 create mode 100644 apps/workflow/tests/test_xero_branding_themes.py

diff --git a/apps/workflow/__init__.py b/apps/workflow/__init__.py
index 07f6bf557..a76b6b2c7 100644
--- a/apps/workflow/__init__.py
+++ b/apps/workflow/__init__.py
@@ -61,6 +61,7 @@
             XeroAppCreateSerializer,
             XeroAppSerializer,
             XeroAuthenticationErrorResponseSerializer,
+            XeroBrandingThemeSerializer,
             XeroDocumentErrorResponseSerializer,
             XeroDocumentSuccessResponseSerializer,
             XeroErrorDetailResponseSerializer,
@@ -138,6 +139,7 @@
     "XeroAppCreateSerializer",
     "XeroAppSerializer",
     "XeroAuthenticationErrorResponseSerializer",
+    "XeroBrandingThemeSerializer",
     "XeroDocumentErrorResponseSerializer",
     "XeroDocumentSuccessResponseSerializer",
     "XeroErrorDetailResponseSerializer",
diff --git a/apps/workflow/accounting/provider.py b/apps/workflow/accounting/provider.py
index 77efd0469..d203975a5 100644
--- a/apps/workflow/accounting/provider.py
+++ b/apps/workflow/accounting/provider.py
@@ -14,6 +14,7 @@
     from .types import (
         ContactResult,
         DocumentResult,
+        DocumentTheme,
         InvoicePayload,
         POPayload,
         QuotePayload,
@@ -75,6 +76,10 @@ def search_contact_by_name(self, name: str) -> ContactResult | None:
 
     # --- Documents ---
 
+    def list_document_themes(self) -> list[DocumentTheme]:
+        """List selectable document themes from the accounting system."""
+        ...
+
     def create_invoice(self, payload: InvoicePayload) -> DocumentResult:
         """Create an invoice in the accounting system."""
         ...
diff --git a/apps/workflow/accounting/types.py b/apps/workflow/accounting/types.py
index e872706d3..d62f05063 100644
--- a/apps/workflow/accounting/types.py
+++ b/apps/workflow/accounting/types.py
@@ -6,6 +6,15 @@
 from decimal import Decimal
 
 
+@dataclass(frozen=True)
+class DocumentTheme:
+    """A selectable document presentation theme from an accounting provider."""
+
+    external_id: str
+    name: str
+    is_default: bool
+
+
 @dataclass
 class DocumentLineItem:
     """A single line item on an invoice, quote, or purchase order."""
@@ -26,6 +35,7 @@ class InvoicePayload:
     line_items: list[DocumentLineItem]
     date: date
     due_date: date
+    document_theme_external_id: str
     currency_code: str = "NZD"
     reference: str | None = None
     url: str | None = None
@@ -42,6 +52,7 @@ class QuotePayload:
     line_items: list[DocumentLineItem]
     date: date
     expiry_date: date
+    document_theme_external_id: str
     currency_code: str = "NZD"
     reference: str | None = None
     status: str = "DRAFT"
diff --git a/apps/workflow/accounting/xero/provider.py b/apps/workflow/accounting/xero/provider.py
index f63237356..d36ff60d0 100644
--- a/apps/workflow/accounting/xero/provider.py
+++ b/apps/workflow/accounting/xero/provider.py
@@ -5,17 +5,22 @@
 import logging
 from datetime import datetime
 from typing import TYPE_CHECKING
+from uuid import UUID
 
 from apps.workflow.accounting.registry import register_provider
 from apps.workflow.api.xero.transforms import process_xero_data
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.error_persistence import persist_app_error
 
 if TYPE_CHECKING:
+    from xero_python.accounting import AccountingApi
+
     from apps.company.models import Company
     from apps.job.models import Job
     from apps.workflow.accounting.types import (
         ContactResult,
         DocumentResult,
+        DocumentTheme,
         InvoicePayload,
         POPayload,
         QuotePayload,
@@ -33,7 +38,7 @@ class XeroAccountingProvider:
     # --- Shared helpers (DRY) ---
 
     @staticmethod
-    def _get_api():
+    def _get_api() -> tuple[AccountingApi, str]:
         from xero_python.accounting import AccountingApi
 
         from apps.workflow.api.xero.auth import api_client, get_tenant_id
@@ -171,6 +176,43 @@ def search_contact_by_name(self, name: str) -> ContactResult | None:
 
     # --- Documents ---
 
+    def list_document_themes(self) -> list[DocumentTheme]:
+        from apps.workflow.accounting.types import DocumentTheme
+
+        try:
+            api, tenant_id = self._get_api()
+            response = api.get_branding_themes(tenant_id)
+            ranked_themes: list[tuple[int, DocumentTheme]] = []
+
+            for theme in response.branding_themes:
+                if not isinstance(theme.branding_theme_id, str):
+                    raise ValueError("Xero branding theme is missing its identifier")
+                if not isinstance(theme.name, str) or not theme.name:
+                    raise ValueError("Xero branding theme is missing its name")
+                if not isinstance(theme.sort_order, int):
+                    raise ValueError(
+                        f"Xero branding theme {theme.name} is missing its sort order"
+                    )
+
+                external_id = str(UUID(theme.branding_theme_id))
+                ranked_themes.append(
+                    (
+                        theme.sort_order,
+                        DocumentTheme(
+                            external_id=external_id,
+                            name=theme.name,
+                            is_default=theme.sort_order == 0,
+                        ),
+                    )
+                )
+
+            return [theme for _sort_order, theme in sorted(ranked_themes)]
+        except AlreadyLoggedException:
+            raise
+        except Exception as exc:
+            err = persist_app_error(exc)
+            raise AlreadyLoggedException(exc, err.id) from exc
+
     def create_invoice(self, payload: InvoicePayload) -> DocumentResult:
         from xero_python.accounting.models import Contact, Invoice
 
@@ -192,6 +234,7 @@ def create_invoice(self, payload: InvoicePayload) -> DocumentResult:
                 status=payload.status,
                 reference=payload.reference,
                 url=payload.url,
+                branding_theme_id=payload.document_theme_external_id,
             )
 
             response = api.create_invoices(
@@ -262,6 +305,7 @@ def create_quote(self, payload: QuotePayload) -> DocumentResult:
                 currency_code=payload.currency_code,
                 status=payload.status,
                 reference=payload.reference,
+                branding_theme_id=payload.document_theme_external_id,
             )
 
             response = api.create_quotes(
diff --git a/apps/workflow/fixtures/company_defaults.json b/apps/workflow/fixtures/company_defaults.json
index aea4ab0a0..e9007ac1d 100644
--- a/apps/workflow/fixtures/company_defaults.json
+++ b/apps/workflow/fixtures/company_defaults.json
@@ -44,6 +44,7 @@
       "accounting_provider": "xero",
       "xero_tenant_id": null,
       "xero_shortcode": null,
+      "xero_sales_branding_theme_id": null,
       "enable_xero_sync": false,
       "xero_automated_day_floor": 100,
       "job_delta_soft_fail": true,
diff --git a/apps/workflow/fixtures/company_defaults_prospect.json b/apps/workflow/fixtures/company_defaults_prospect.json
index 7069382ba..ba9a0c9d8 100644
--- a/apps/workflow/fixtures/company_defaults_prospect.json
+++ b/apps/workflow/fixtures/company_defaults_prospect.json
@@ -44,6 +44,7 @@
       "accounting_provider": "xero",
       "xero_tenant_id": null,
       "xero_shortcode": null,
+      "xero_sales_branding_theme_id": null,
       "enable_xero_sync": false,
       "xero_automated_day_floor": 100,
       "job_delta_soft_fail": true,
diff --git a/apps/workflow/management/commands/xero.py b/apps/workflow/management/commands/xero.py
index 427cddd25..fdac5e26a 100644
--- a/apps/workflow/management/commands/xero.py
+++ b/apps/workflow/management/commands/xero.py
@@ -1,4 +1,5 @@
 import datetime
+from uuid import UUID
 
 import requests
 from django.core.cache import cache
@@ -12,6 +13,8 @@
 
 from apps.accounts.models import Staff
 from apps.timesheet.services import PayrollEmployeeSyncService
+from apps.workflow.accounting.registry import get_provider
+from apps.workflow.accounting.types import DocumentTheme
 from apps.workflow.api.xero.auth import api_client, get_tenant_id, get_valid_token
 from apps.workflow.api.xero.payroll import (
     get_earnings_rates,
@@ -73,7 +76,10 @@ def add_arguments(self, parser):
         parser.add_argument(
             "--setup",
             action="store_true",
-            help="Configure Xero tenant ID, shortcode, and payroll calendar",
+            help=(
+                "Configure Xero tenant ID, shortcode, sales branding theme, "
+                "and payroll calendar"
+            ),
         )
         parser.add_argument(
             "--no-set",
@@ -426,8 +432,29 @@ def _ensure_demo_xero_items_exist(self, calendar_name: str, tenant_id: str) -> N
                     )
                 )
 
+    @staticmethod
+    def _resolve_sales_branding_theme(configured_id: UUID | None) -> DocumentTheme:
+        """Preserve a live selection or choose the connected tenant's default."""
+        themes = get_provider().list_document_themes()
+        default_themes = [theme for theme in themes if theme.is_default]
+        if len(default_themes) != 1:
+            raise CommandError(
+                "Xero must return exactly one default branding theme; "
+                f"received {len(default_themes)} from {len(themes)} themes."
+            )
+
+        if configured_id is not None:
+            configured_theme = next(
+                (theme for theme in themes if theme.external_id == str(configured_id)),
+                None,
+            )
+            if configured_theme is not None:
+                return configured_theme
+
+        return default_themes[0]
+
     def run_setup(self):
-        """Configure Xero tenant ID, shortcode, and payroll calendar."""
+        """Configure Xero tenant, theme, shortcode, and payroll calendar."""
         self.stdout.write("Setting up Xero connection...")
 
         # Step 1: Get connected organisations
@@ -495,7 +522,12 @@ def run_setup(self):
 
         shortcode = org_response.organisations[0].short_code
 
-        # Step 5: Fetch payroll calendar ID
+        # Step 5: Select a live sales branding theme for this tenant
+        sales_branding_theme = self._resolve_sales_branding_theme(
+            company.xero_sales_branding_theme_id
+        )
+
+        # Step 6: Fetch payroll calendar ID
         calendar_name = company.xero_payroll_calendar_name
         if not calendar_name:
             self.stdout.write(
@@ -521,14 +553,22 @@ def run_setup(self):
                 return
             payroll_calendar_id = matching_calendar["id"]
 
-        # Step 6: Save to CompanyDefaults
+        # Step 7: Save to CompanyDefaults
         company.xero_tenant_id = tenant_id
         company.xero_shortcode = shortcode
+        company.xero_sales_branding_theme_id = sales_branding_theme.external_id
         company.xero_payroll_calendar_id = payroll_calendar_id
         company.save()
 
         self.stdout.write(self.style.SUCCESS(f"Tenant ID: {tenant_id}"))
         self.stdout.write(self.style.SUCCESS(f"Shortcode: {shortcode}"))
+        self.stdout.write(
+            self.style.SUCCESS(
+                "Sales Branding Theme: "
+                f"{sales_branding_theme.name} "
+                f"({sales_branding_theme.external_id})"
+            )
+        )
         if payroll_calendar_id:
             self.stdout.write(
                 self.style.SUCCESS(
diff --git a/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
new file mode 100644
index 000000000..6aa4596cb
--- /dev/null
+++ b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
@@ -0,0 +1,27 @@
+# Generated by Django 5.2.4 on 2026-07-16 00:00
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("workflow", "0010_remove_xeroapp_tenant_id"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="companydefaults",
+            name="xero_sales_branding_theme_id",
+            field=models.UUIDField(
+                blank=True,
+                help_text=(
+                    "Branding theme applied to every quote and sales invoice "
+                    "created in Xero. Select a theme containing the required "
+                    "terms and conditions; document creation is blocked until "
+                    "one is selected."
+                ),
+                null=True,
+                verbose_name="Xero sales branding theme",
+            ),
+        ),
+    ]
diff --git a/apps/workflow/models/company_defaults.py b/apps/workflow/models/company_defaults.py
index 567a75d54..70cdce47e 100644
--- a/apps/workflow/models/company_defaults.py
+++ b/apps/workflow/models/company_defaults.py
@@ -125,6 +125,16 @@ class CompanyDefaults(SingletonModel):
         blank=True,
         help_text="Xero organisation shortcode for deep linking (e.g., '!8-5Xl')",
     )
+    xero_sales_branding_theme_id = models.UUIDField(
+        null=True,
+        blank=True,
+        verbose_name="Xero sales branding theme",
+        help_text=(
+            "Branding theme applied to every quote and sales invoice created in "
+            "Xero. Select a theme containing the required terms and conditions; "
+            "document creation is blocked until one is selected."
+        ),
+    )
     enable_xero_sync = models.BooleanField(
         default=True,
         help_text="Gate for Xero sync. Defaults True (prod). Dev fixture sets False; seed_xero_from_database sets True after prod IDs are cleared.",
diff --git a/apps/workflow/models/settings_metadata.py b/apps/workflow/models/settings_metadata.py
index 2b6b59b95..0637d43ca 100644
--- a/apps/workflow/models/settings_metadata.py
+++ b/apps/workflow/models/settings_metadata.py
@@ -141,6 +141,7 @@ def get_section_info(cls, key: str) -> tuple[str, str, int] | None:
     "accounting_provider": "xero",
     "xero_tenant_id": "xero",
     "xero_shortcode": "xero",
+    "xero_sales_branding_theme_id": "xero",
     "enable_xero_sync": "xero",
     "xero_automated_day_floor": "xero",
     "xero_payroll_calendar_name": "xero",
@@ -192,7 +193,11 @@ def get_field_metadata(
     else:
         label = field_name.replace("_", " ").title()
 
-    ui_type = get_ui_type_for_field(field)
+    ui_type = (
+        "xero_branding_theme"
+        if field_name == "xero_sales_branding_theme_id"
+        else get_ui_type_for_field(field)
+    )
     return {
         "key": field_name,
         "label": label,
diff --git a/apps/workflow/serializers.py b/apps/workflow/serializers.py
index 84ffe9ca7..d52346c03 100644
--- a/apps/workflow/serializers.py
+++ b/apps/workflow/serializers.py
@@ -2,6 +2,8 @@
 
 from rest_framework import serializers
 
+from apps.workflow.accounting.types import DocumentTheme
+
 # Existing models used in this serializer module
 from .models import (
     AIProvider,
@@ -643,3 +645,11 @@ class GroupedErrorResolveResponseSerializer(serializers.Serializer):
     """Response body for grouped resolve/unresolve endpoints."""
 
     updated = serializers.IntegerField()
+
+
+class XeroBrandingThemeSerializer(serializers.Serializer[DocumentTheme]):
+    """A Xero branding theme available for sales documents."""
+
+    branding_theme_id = serializers.UUIDField(source="external_id")
+    name = serializers.CharField()
+    is_default = serializers.BooleanField()
diff --git a/apps/workflow/tests/test_company_defaults_api.py b/apps/workflow/tests/test_company_defaults_api.py
index 28859f61c..08970a506 100644
--- a/apps/workflow/tests/test_company_defaults_api.py
+++ b/apps/workflow/tests/test_company_defaults_api.py
@@ -1,3 +1,5 @@
+import uuid
+
 from django.db import connection
 from django.test.utils import CaptureQueriesContext
 from rest_framework import status
@@ -51,3 +53,29 @@ def test_patch_canonicalizes_blank_optional_urls_to_null(self):
         self.assertIsNone(company_defaults.master_quote_template_url)
         self.assertIsNone(company_defaults.gdrive_quotes_folder_url)
         self.assertIsNone(company_defaults.company_url)
+
+    def test_patch_persists_and_clears_xero_sales_branding_theme(self) -> None:
+        """Admins can operate the required Xero document theme setting."""
+        theme_id = uuid.uuid4()
+        client = APIClient()
+        client.force_authenticate(user=self.test_staff)
+
+        response = client.patch(
+            "/api/company-defaults/",
+            {"xero_sales_branding_theme_id": str(theme_id)},
+            format="json",
+        )
+        payload = response.json()
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertEqual(payload["xero_sales_branding_theme_id"], str(theme_id))
+
+        response = client.patch(
+            "/api/company-defaults/",
+            {"xero_sales_branding_theme_id": None},
+            format="json",
+        )
+        payload = response.json()
+
+        self.assertEqual(response.status_code, status.HTTP_200_OK)
+        self.assertIsNone(payload["xero_sales_branding_theme_id"])
diff --git a/apps/workflow/tests/test_company_defaults_schema.py b/apps/workflow/tests/test_company_defaults_schema.py
index 62c6af3e9..79b510188 100644
--- a/apps/workflow/tests/test_company_defaults_schema.py
+++ b/apps/workflow/tests/test_company_defaults_schema.py
@@ -222,3 +222,24 @@ def test_company_section_has_company_name(self):
 
         field_keys = [f["key"] for f in company_section["fields"]]
         self.assertIn("company_name", field_keys)
+
+    def test_xero_section_exposes_sales_branding_theme_selector(self) -> None:
+        """The theme is operable through Company Settings, not hidden config."""
+        client = APIClient()
+        client.force_authenticate(user=self.staff)
+        response = client.get("/api/company-defaults/schema/")
+        payload = response.json()
+
+        xero_section = next(
+            section for section in payload["sections"] if section["key"] == "xero"
+        )
+        theme_field = next(
+            field
+            for field in xero_section["fields"]
+            if field["key"] == "xero_sales_branding_theme_id"
+        )
+
+        self.assertEqual(theme_field["type"], "xero_branding_theme")
+        self.assertEqual(theme_field["label"], "Xero Sales Branding Theme")
+        self.assertFalse(theme_field["read_only"])
+        self.assertIn("terms and conditions", theme_field["help_text"])
diff --git a/apps/workflow/tests/test_localdate_regression.py b/apps/workflow/tests/test_localdate_regression.py
index 1c1382ded..73670ce23 100644
--- a/apps/workflow/tests/test_localdate_regression.py
+++ b/apps/workflow/tests/test_localdate_regression.py
@@ -23,6 +23,7 @@
 FROZEN_UTC_MOMENT = "2026-04-27T23:30:00Z"
 NZ_DATE = datetime.date(2026, 4, 28)
 UTC_DATE = datetime.date(2026, 4, 27)
+DOCUMENT_THEME_ID = "00000000-0000-0000-0000-000000000286"
 
 
 def _make_client(name="Localdate Test Company"):
@@ -239,7 +240,9 @@ def test_build_payload_uses_nz_local_date(self):
             freeze_time(FROZEN_UTC_MOMENT),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         self.assertEqual(payload.date, NZ_DATE)
 
@@ -251,7 +254,9 @@ def test_account_customer_due_date_is_20th_of_next_month(self):
             freeze_time(FROZEN_UTC_MOMENT),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         # NZ "today" is 2026-04-28; 20th of next month = 2026-05-20.
         self.assertEqual(payload.due_date, datetime.date(2026, 5, 20))
@@ -264,7 +269,9 @@ def test_cash_customer_due_date_is_same_day(self):
             freeze_time(FROZEN_UTC_MOMENT),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         self.assertEqual(payload.due_date, NZ_DATE)
         self.assertEqual(payload.date, payload.due_date)
@@ -282,7 +289,9 @@ def test_account_customer_due_date_at_31_day_month_boundary(self):
             freeze_time("2026-05-01T00:00:00Z"),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         self.assertEqual(payload.date, datetime.date(2026, 5, 1))
         self.assertEqual(payload.due_date, datetime.date(2026, 6, 20))
@@ -296,7 +305,9 @@ def test_account_customer_due_date_rolls_over_year_in_december(self):
             freeze_time("2026-12-14T13:00:00Z"),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         # NZDT is UTC+13 in December, so 2026-12-14 13:00 UTC = 2026-12-15 02:00 NZDT.
         self.assertEqual(payload.date, datetime.date(2026, 12, 15))
@@ -322,7 +333,9 @@ def test_build_payload_uses_nz_local_date(self):
             freeze_time(FROZEN_UTC_MOMENT),
             patch.object(manager, "get_line_items", return_value=[]),
         ):
-            payload = manager.build_payload()
+            payload = manager.build_payload(
+                document_theme_external_id=DOCUMENT_THEME_ID
+            )
 
         self.assertEqual(payload.date, NZ_DATE)
 
diff --git a/apps/workflow/tests/test_xero_branding_themes.py b/apps/workflow/tests/test_xero_branding_themes.py
new file mode 100644
index 000000000..3fbe43264
--- /dev/null
+++ b/apps/workflow/tests/test_xero_branding_themes.py
@@ -0,0 +1,223 @@
+import uuid
+from datetime import date
+from decimal import Decimal
+from types import SimpleNamespace
+from unittest.mock import Mock, patch
+
+from django.utils import timezone
+from rest_framework.test import APIClient
+
+from apps.company.models import Company
+from apps.job.models import Job
+from apps.testing import BaseTestCase
+from apps.workflow.accounting.types import (
+    DocumentLineItem,
+    DocumentTheme,
+    InvoicePayload,
+    QuotePayload,
+)
+from apps.workflow.accounting.xero.provider import XeroAccountingProvider
+from apps.workflow.models import CompanyDefaults
+from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
+from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
+from apps.workflow.views.xero.xero_view import XeroAuthenticationResult
+
+THEME_ID = "11111111-2222-3333-4444-555555555555"
+
+
+class XeroBrandingThemeProviderTests(BaseTestCase):
+    """Xero receives the exact theme selected by the DocketWorks operator."""
+
+    @patch("apps.workflow.accounting.xero.provider.process_xero_data", return_value={})
+    @patch.object(XeroAccountingProvider, "_get_api")
+    def test_invoice_create_payload_includes_branding_theme_id(
+        self, mock_get_api: Mock, _mock_process: Mock
+    ) -> None:
+        api = Mock()
+        api.create_invoices.return_value = (
+            SimpleNamespace(
+                invoices=[
+                    SimpleNamespace(
+                        invoice_id=uuid.uuid4(), invoice_number="INV-THEME-1"
+                    )
+                ]
+            ),
+            200,
+            {},
+        )
+        mock_get_api.return_value = (api, "tenant-id")
+
+        payload = InvoicePayload(
+            client_external_id=str(uuid.uuid4()),
+            company_name="Theme Test Company",
+            line_items=[
+                DocumentLineItem(
+                    description="Theme test",
+                    quantity=Decimal("1"),
+                    unit_amount=Decimal("100"),
+                )
+            ],
+            date=date(2026, 7, 16),
+            due_date=date(2026, 7, 16),
+            document_theme_external_id=THEME_ID,
+        )
+
+        result = XeroAccountingProvider().create_invoice(payload)
+
+        self.assertTrue(result.success)
+        sent = api.create_invoices.call_args.kwargs["invoices"]["Invoices"][0]
+        self.assertEqual(sent["BrandingThemeID"], THEME_ID)
+        self.assertEqual(sent["Contact"]["ContactID"], payload.client_external_id)
+
+    @patch("apps.workflow.accounting.xero.provider.process_xero_data", return_value={})
+    @patch.object(XeroAccountingProvider, "_get_api")
+    def test_quote_create_payload_includes_branding_theme_without_terms(
+        self, mock_get_api: Mock, _mock_process: Mock
+    ) -> None:
+        api = Mock()
+        api.create_quotes.return_value = (
+            SimpleNamespace(
+                quotes=[
+                    SimpleNamespace(quote_id=uuid.uuid4(), quote_number="QU-THEME-1")
+                ]
+            ),
+            200,
+            {},
+        )
+        mock_get_api.return_value = (api, "tenant-id")
+
+        payload = QuotePayload(
+            client_external_id=str(uuid.uuid4()),
+            company_name="Theme Test Company",
+            line_items=[
+                DocumentLineItem(
+                    description="Theme test",
+                    quantity=Decimal("1"),
+                    unit_amount=Decimal("100"),
+                )
+            ],
+            date=date(2026, 7, 16),
+            expiry_date=date(2026, 8, 15),
+            document_theme_external_id=THEME_ID,
+        )
+
+        result = XeroAccountingProvider().create_quote(payload)
+
+        self.assertTrue(result.success)
+        sent = api.create_quotes.call_args.kwargs["quotes"]["Quotes"][0]
+        self.assertEqual(sent["BrandingThemeID"], THEME_ID)
+        self.assertNotIn("Terms", sent)
+
+    @patch.object(XeroAccountingProvider, "_get_api")
+    def test_list_document_themes_preserves_xero_order_and_default(
+        self, mock_get_api: Mock
+    ) -> None:
+        api = Mock()
+        api.get_branding_themes.return_value = SimpleNamespace(
+            branding_themes=[
+                SimpleNamespace(
+                    branding_theme_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+                    name="Secondary",
+                    sort_order=2,
+                ),
+                SimpleNamespace(
+                    branding_theme_id="bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
+                    name="Sales Terms",
+                    sort_order=0,
+                ),
+            ]
+        )
+        mock_get_api.return_value = (api, "tenant-id")
+
+        themes = XeroAccountingProvider().list_document_themes()
+
+        self.assertEqual([theme.name for theme in themes], ["Sales Terms", "Secondary"])
+        self.assertTrue(themes[0].is_default)
+        self.assertFalse(themes[1].is_default)
+
+
+class XeroBrandingThemeConfigurationTests(BaseTestCase):
+    """No Xero document is created when its required theme is unconfigured."""
+
+    def setUp(self) -> None:
+        defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_sales_branding_theme_id=None
+        )
+        CompanyDefaults.clear_cache()
+
+        self.company = Company.objects.create(
+            name="Missing Theme Company",
+            xero_contact_id=str(uuid.uuid4()),
+            xero_last_modified=timezone.now(),
+        )
+        self.job = Job(
+            company=self.company,
+            name="Missing Theme Job",
+            pricing_methodology="fixed_price",
+        )
+        self.job.save(staff=self.test_staff)
+
+    def test_invoice_creation_stops_before_provider_write(self) -> None:
+        manager = XeroInvoiceManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+
+        result = manager.create_document(total_amount=Decimal("100"))
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["status"], 400)
+        self.assertEqual(result["error_type"], "configuration_error")
+        self.assertIn("Select a Xero sales branding theme", result["error"])
+        manager.provider.create_invoice.assert_not_called()
+
+    def test_quote_creation_stops_before_provider_write(self) -> None:
+        manager = XeroQuoteManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+
+        result = manager.create_document()
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["status"], 400)
+        self.assertEqual(result["error_type"], "configuration_error")
+        self.assertIn("Select a Xero sales branding theme", result["error"])
+        manager.provider.create_quote.assert_not_called()
+
+
+class XeroBrandingThemeAPITests(BaseTestCase):
+    """Office staff can populate the settings selector from live Xero themes."""
+
+    def setUp(self) -> None:
+        self.test_staff.is_office_staff = True
+        self.test_staff.save(update_fields=["is_office_staff"])
+        self.client = APIClient()
+        self.client.force_authenticate(user=self.test_staff)
+
+    @patch("apps.workflow.views.xero.xero_view.get_provider")
+    @patch("apps.workflow.views.xero.xero_view.ensure_xero_authentication")
+    def test_list_branding_themes_returns_selector_contract(
+        self, mock_auth: Mock, mock_get_provider: Mock
+    ) -> None:
+        mock_auth.return_value = XeroAuthenticationResult()
+        provider = Mock()
+        provider.list_document_themes.return_value = [
+            DocumentTheme(external_id=THEME_ID, name="Sales Terms", is_default=True)
+        ]
+        mock_get_provider.return_value = provider
+
+        response = self.client.get("/api/xero/branding-themes/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(
+            response.json(),
+            [
+                {
+                    "branding_theme_id": THEME_ID,
+                    "name": "Sales Terms",
+                    "is_default": True,
+                }
+            ],
+        )
diff --git a/apps/workflow/tests/test_xero_setup_command.py b/apps/workflow/tests/test_xero_setup_command.py
index 4abd69aa2..11c93392e 100644
--- a/apps/workflow/tests/test_xero_setup_command.py
+++ b/apps/workflow/tests/test_xero_setup_command.py
@@ -1,10 +1,14 @@
+import json
 from decimal import Decimal
+from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
+from uuid import UUID
 
 from django.core.management.base import CommandError
 from django.test import TestCase
 
+from apps.workflow.accounting.types import DocumentTheme
 from apps.workflow.management.commands.xero import Command
 from apps.workflow.models import XeroPayItem
 
@@ -171,6 +175,7 @@ def test_skips_destination_items_that_already_exist_by_name(
 
 
 class RunSetupTests(TestCase):
+    @patch("apps.workflow.management.commands.xero.get_provider")
     @patch("apps.workflow.management.commands.xero.cache.set")
     @patch("apps.workflow.management.commands.xero.get_payroll_calendars")
     @patch("apps.workflow.management.commands.xero.AccountingApi")
@@ -183,11 +188,13 @@ def test_run_setup_always_calls_demo_item_provisioning(
         mock_accounting_api_cls,
         mock_get_payroll_calendars,
         _mock_cache_set,
+        mock_get_provider,
     ):
         company = SimpleNamespace(
             xero_tenant_id=None,
             xero_payroll_calendar_name="Weekly Testing",
             xero_shortcode=None,
+            xero_sales_branding_theme_id=None,
             xero_payroll_calendar_id=None,
             save=Mock(),
         )
@@ -205,6 +212,13 @@ def test_run_setup_always_calls_demo_item_provisioning(
         mock_get_payroll_calendars.return_value = [
             {"name": "Weekly Testing", "id": "calendar-123"}
         ]
+        mock_get_provider.return_value.list_document_themes.return_value = [
+            DocumentTheme(
+                external_id="11111111-2222-3333-4444-555555555555",
+                name="Standard",
+                is_default=True,
+            )
+        ]
 
         cmd = Command()
         cmd._ensure_demo_xero_items_exist = Mock()
@@ -214,8 +228,124 @@ def test_run_setup_always_calls_demo_item_provisioning(
         cmd._ensure_demo_xero_items_exist.assert_called_once_with(
             "Weekly Testing", "tenant-123"
         )
+        self.assertEqual(
+            company.xero_sales_branding_theme_id,
+            "11111111-2222-3333-4444-555555555555",
+        )
+
+    @patch("apps.workflow.management.commands.xero.get_provider")
+    def test_resolve_sales_branding_theme_selects_default_when_unconfigured(
+        self, mock_get_provider: Mock
+    ) -> None:
+        default_theme = DocumentTheme(
+            external_id="11111111-2222-3333-4444-555555555555",
+            name="Standard",
+            is_default=True,
+        )
+        mock_get_provider.return_value.list_document_themes.return_value = [
+            DocumentTheme(
+                external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+                name="Custom",
+                is_default=False,
+            ),
+            default_theme,
+        ]
+        selected = Command._resolve_sales_branding_theme(None)
+
+        self.assertEqual(selected, default_theme)
+
+    @patch("apps.workflow.management.commands.xero.get_provider")
+    def test_resolve_sales_branding_theme_preserves_live_custom_selection(
+        self, mock_get_provider: Mock
+    ) -> None:
+        custom_theme = DocumentTheme(
+            external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+            name="Terms",
+            is_default=False,
+        )
+        mock_get_provider.return_value.list_document_themes.return_value = [
+            DocumentTheme(
+                external_id="11111111-2222-3333-4444-555555555555",
+                name="Standard",
+                is_default=True,
+            ),
+            custom_theme,
+        ]
+        selected = Command._resolve_sales_branding_theme(UUID(custom_theme.external_id))
+
+        self.assertEqual(selected, custom_theme)
+
+    @patch("apps.workflow.management.commands.xero.get_provider")
+    def test_resolve_sales_branding_theme_replaces_stale_tenant_selection(
+        self, mock_get_provider: Mock
+    ) -> None:
+        default_theme = DocumentTheme(
+            external_id="11111111-2222-3333-4444-555555555555",
+            name="Standard",
+            is_default=True,
+        )
+        mock_get_provider.return_value.list_document_themes.return_value = [
+            default_theme
+        ]
+        stale_theme_id = UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
+
+        selected = Command._resolve_sales_branding_theme(stale_theme_id)
+
+        self.assertEqual(selected, default_theme)
+
+    @patch("apps.workflow.management.commands.xero.get_provider")
+    def test_resolve_sales_branding_theme_requires_one_default(
+        self, mock_get_provider: Mock
+    ) -> None:
+        custom_theme = DocumentTheme(
+            external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+            name="Custom",
+            is_default=False,
+        )
+        default_themes = [
+            DocumentTheme(
+                external_id="11111111-2222-3333-4444-555555555555",
+                name="Default One",
+                is_default=True,
+            ),
+            DocumentTheme(
+                external_id="66666666-7777-8888-9999-000000000000",
+                name="Default Two",
+                is_default=True,
+            ),
+        ]
+
+        for themes in ([custom_theme], default_themes):
+            with self.subTest(default_count=sum(theme.is_default for theme in themes)):
+                mock_get_provider.return_value.list_document_themes.return_value = (
+                    themes
+                )
+                with self.assertRaisesMessage(
+                    CommandError,
+                    "Xero must return exactly one default branding theme",
+                ):
+                    Command._resolve_sales_branding_theme(None)
 
     def test_removed_create_missing_xero_items_flag_is_rejected(self):
         parser = Command().create_parser("manage.py", "xero")
         with self.assertRaises(CommandError):
             parser.parse_args(["--setup", "--create-missing-xero-items"])
+
+
+class CompanyDefaultsBrandingThemeFixtureTests(TestCase):
+    def test_shared_fixtures_do_not_ship_tenant_specific_theme_ids(self) -> None:
+        fixture_dir = Path(__file__).parents[1] / "fixtures"
+
+        for fixture_name in (
+            "company_defaults.json",
+            "company_defaults_prospect.json",
+        ):
+            fixture = json.loads((fixture_dir / fixture_name).read_text())
+            company_defaults_records = [
+                item for item in fixture if item["model"] == "workflow.companydefaults"
+            ]
+            self.assertEqual(len(company_defaults_records), 1, fixture_name)
+            self.assertIsNone(
+                company_defaults_records[0]["fields"]["xero_sales_branding_theme_id"],
+                fixture_name,
+            )
diff --git a/apps/workflow/urls.py b/apps/workflow/urls.py
index f954dfb1b..23d5783f1 100644
--- a/apps/workflow/urls.py
+++ b/apps/workflow/urls.py
@@ -104,6 +104,11 @@
         xero_view.stream_xero_sync,
         name="stream_xero_sync",
     ),
+    path(
+        "xero/branding-themes/",
+        xero_view.list_xero_branding_themes,
+        name="xero_branding_themes_list",
+    ),
     path(
         "xero/create_invoice/<uuid:job_id>",
         xero_view.create_xero_invoice,
diff --git a/apps/workflow/views/xero/__init__.py b/apps/workflow/views/xero/__init__.py
index 3183f5727..937eb8503 100644
--- a/apps/workflow/views/xero/__init__.py
+++ b/apps/workflow/views/xero/__init__.py
@@ -21,6 +21,7 @@
     ensure_xero_authentication,
     generate_xero_sync_events,
     get_xero_sync_info,
+    list_xero_branding_themes,
     refresh_xero_data,
     refresh_xero_token,
     start_xero_sync,
@@ -68,6 +69,7 @@
     "format_date",
     "generate_xero_sync_events",
     "get_xero_sync_info",
+    "list_xero_branding_themes",
     "parse_xero_api_error_message",
     "refresh_xero_data",
     "refresh_xero_token",
diff --git a/apps/workflow/views/xero/xero_base_manager.py b/apps/workflow/views/xero/xero_base_manager.py
index 45ed13b99..a2f1d130e 100644
--- a/apps/workflow/views/xero/xero_base_manager.py
+++ b/apps/workflow/views/xero/xero_base_manager.py
@@ -8,6 +8,7 @@
 # Import models used in type hints or logic
 from apps.job.models import Job
 from apps.workflow.accounting.registry import get_provider
+from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
 
 logger = logging.getLogger("xero")
@@ -93,6 +94,14 @@ def _get_account_code(self, account_name: str = "Sales") -> str | None:
         """
         return self.provider.get_account_code(account_name)
 
+    @staticmethod
+    def get_xero_sales_branding_theme_id() -> str | None:
+        """Return the configured Xero theme used for sales documents."""
+        theme_id = CompanyDefaults.get_solo().xero_sales_branding_theme_id
+        if theme_id is None:
+            return None
+        return str(theme_id)
+
     def validate_company(self):
         """
         Ensures the company exists and is synced with Xero.
diff --git a/apps/workflow/views/xero/xero_helpers.py b/apps/workflow/views/xero/xero_helpers.py
index 61978a1f2..03649ff67 100644
--- a/apps/workflow/views/xero/xero_helpers.py
+++ b/apps/workflow/views/xero/xero_helpers.py
@@ -1,6 +1,5 @@
 # workflow/views/xero_helpers.py
 import json
-import re
 from datetime import date
 from typing import Any, Dict, List, Optional
 
@@ -31,16 +30,20 @@ def convert_to_pascal_case(obj):
     Recursively converts dictionary keys from snake_case to PascalCase.
     Handles keys starting with an underscore.
     """
+
+    def convert_key(key: str) -> str:
+        leading_underscore = key.startswith("_")
+        source = key[1:] if leading_underscore else key
+        converted = "".join(
+            "ID" if part == "id" else part[:1].upper() + part[1:]
+            for part in source.split("_")
+        )
+        return f"_{converted}" if leading_underscore else converted
+
     if isinstance(obj, dict):
         new_dict = {}
         for key, value in obj.items():
-            # Handle potential leading underscores before converting
-            if key.startswith("_"):
-                pascal_key = "_" + re.sub(
-                    r"(?:^|_)(.)", lambda x: x.group(1).upper(), key[1:]
-                )
-            else:
-                pascal_key = re.sub(r"(?:^|_)(.)", lambda x: x.group(1).upper(), key)
+            pascal_key = convert_key(key)
             new_dict[pascal_key] = convert_to_pascal_case(value)
         return new_dict
     elif isinstance(obj, list):
diff --git a/apps/workflow/views/xero/xero_invoice_manager.py b/apps/workflow/views/xero/xero_invoice_manager.py
index 9cf09f562..d1686fe15 100644
--- a/apps/workflow/views/xero/xero_invoice_manager.py
+++ b/apps/workflow/views/xero/xero_invoice_manager.py
@@ -142,7 +142,12 @@ def _compute_invoice_dates(self) -> tuple[date, date]:
             due_date = invoice_date
         return invoice_date, due_date
 
-    def build_payload(self, total_amount: Decimal | None = None) -> InvoicePayload:
+    def build_payload(
+        self,
+        total_amount: Decimal | None = None,
+        *,
+        document_theme_external_id: str,
+    ) -> InvoicePayload:
         """Build a provider-agnostic invoice payload from the job and company."""
         if not self.job:
             raise ValueError("Job is required to build invoice payload.")
@@ -156,6 +161,7 @@ def build_payload(self, total_amount: Decimal | None = None) -> InvoicePayload:
             line_items=line_items,
             date=invoice_date,
             due_date=due_date,
+            document_theme_external_id=document_theme_external_id,
             reference=(
                 self.job.order_number
                 if hasattr(self.job, "order_number") and self.job.order_number
@@ -207,7 +213,22 @@ def create_document(
             if not self.state_valid_for_xero():
                 raise ValueError("Document is not in a valid state for submission.")
 
-            payload = self.build_payload(total_amount)
+            document_theme_external_id = self.get_xero_sales_branding_theme_id()
+            if document_theme_external_id is None:
+                return {
+                    "success": False,
+                    "error": (
+                        "Select a Xero sales branding theme in Company Settings "
+                        "before creating an invoice."
+                    ),
+                    "error_type": "configuration_error",
+                    "status": 400,
+                }
+
+            payload = self.build_payload(
+                total_amount,
+                document_theme_external_id=document_theme_external_id,
+            )
             result = self.provider.create_invoice(payload)
 
             if not result.success:
diff --git a/apps/workflow/views/xero/xero_quote_manager.py b/apps/workflow/views/xero/xero_quote_manager.py
index 310c0fb9c..bb05743aa 100644
--- a/apps/workflow/views/xero/xero_quote_manager.py
+++ b/apps/workflow/views/xero/xero_quote_manager.py
@@ -127,7 +127,12 @@ def get_line_items(self, breakdown: bool = True) -> list[DocumentLineItem]:
                 )
             ]
 
-    def build_payload(self, breakdown: bool = True) -> QuotePayload:
+    def build_payload(
+        self,
+        breakdown: bool = True,
+        *,
+        document_theme_external_id: str,
+    ) -> QuotePayload:
         """Build a provider-agnostic quote payload from the job and company."""
         if not self.job:
             raise ValueError("Job is required to build quote payload.")
@@ -141,6 +146,7 @@ def build_payload(self, breakdown: bool = True) -> QuotePayload:
             line_items=line_items,
             date=today,
             expiry_date=today + timedelta(days=30),
+            document_theme_external_id=document_theme_external_id,
             reference=(
                 self.job.order_number
                 if hasattr(self.job, "order_number") and self.job.order_number
@@ -161,7 +167,22 @@ def create_document(self, breakdown: bool = True):
             if not self.state_valid_for_xero():
                 raise ValueError("Document is not in a valid state for submission.")
 
-            payload = self.build_payload(breakdown=breakdown)
+            document_theme_external_id = self.get_xero_sales_branding_theme_id()
+            if document_theme_external_id is None:
+                return {
+                    "success": False,
+                    "error": (
+                        "Select a Xero sales branding theme in Company Settings "
+                        "before creating a quote."
+                    ),
+                    "error_type": "configuration_error",
+                    "status": 400,
+                }
+
+            payload = self.build_payload(
+                breakdown=breakdown,
+                document_theme_external_id=document_theme_external_id,
+            )
             result = self.provider.create_quote(payload)
 
             if not result.success:
diff --git a/apps/workflow/views/xero/xero_view.py b/apps/workflow/views/xero/xero_view.py
index b7dc2cdf2..f3e3f145e 100644
--- a/apps/workflow/views/xero/xero_view.py
+++ b/apps/workflow/views/xero/xero_view.py
@@ -41,6 +41,7 @@
 from apps.job.models import Job
 from apps.job.permissions import IsOfficeStaff
 from apps.purchasing.models import PurchaseOrder
+from apps.workflow.accounting.registry import get_provider
 from apps.workflow.api.pagination import FiftyPerPagePagination
 from apps.workflow.api.xero.active_app import (
     NoActiveXeroApp,
@@ -62,6 +63,7 @@
 from apps.workflow.models import XeroError, XeroPayItem
 from apps.workflow.serializers import (
     XeroAuthenticationErrorResponseSerializer,
+    XeroBrandingThemeSerializer,
     XeroDocumentErrorResponseSerializer,
     XeroDocumentSuccessResponseSerializer,
     XeroErrorSerializer,
@@ -415,6 +417,46 @@ def ensure_xero_authentication() -> XeroAuthenticationResult:
     return XeroAuthenticationResult(tenant_id=tenant_id)
 
 
+@extend_schema(
+    operation_id="xero_branding_themes_list",
+    tags=["Xero"],
+    request=None,
+    responses={
+        200: XeroBrandingThemeSerializer(many=True),
+        401: XeroAuthenticationErrorResponseSerializer,
+        500: XeroDocumentErrorResponseSerializer,
+    },
+    description="Lists Xero branding themes available for quotes and sales invoices.",
+)
+@api_view(["GET"])
+@permission_classes([IsAuthenticated, IsOfficeStaff])
+def list_xero_branding_themes(request: Request) -> Response:
+    """Return selectable document themes from the connected Xero organisation."""
+    auth_result = ensure_xero_authentication()
+    if auth_result.error_data is not None:
+        return Response(auth_result.error_data, status=auth_result.status_code)
+
+    try:
+        themes = get_provider().list_document_themes()
+        serialized_themes = [
+            XeroBrandingThemeSerializer(theme).data for theme in themes
+        ]
+        return Response(serialized_themes, status=status.HTTP_200_OK)
+    except AlreadyLoggedException as exc:
+        return Response(
+            _build_xero_error_payload(exc),
+            status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
+    except Exception as exc:
+        try:
+            persist_and_raise(exc, user_id=str(request.user.id))
+        except AlreadyLoggedException as logged_exc:
+            return Response(
+                _build_xero_error_payload(logged_exc),
+                status=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            )
+
+
 @csrf_exempt
 @extend_schema(
     tags=["Xero"],
@@ -956,6 +998,7 @@ def delete_xero_purchase_order(
             error_data = _build_xero_error_payload(logged_exc)
             messages.error(request, f"An unexpected error occurred: {str(exc)}")
             return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
+        raise AssertionError("persist_and_raise returned without raising")
 
 
 @extend_schema(
diff --git a/docs/client_onboarding.md b/docs/client_onboarding.md
index 400fb4543..991c10352 100644
--- a/docs/client_onboarding.md
+++ b/docs/client_onboarding.md
@@ -89,6 +89,14 @@ The client needs a Xero subscription. DocketWorks handles jobs and delegates inv
 - Create a contact named "[Company Name] Shop" (e.g., "Morris Sheetmetal Shop")
 - Used for leave, admin time, training, etc.
 
+**Sales Branding Theme** (Settings > Invoice settings):
+- Ensure one branding theme contains the terms and conditions required on both
+  quotes and invoices
+- Prefer making that theme the Xero default; DocketWorks imports the default
+  during `xero --setup`
+- If another theme must remain the Xero default, select the terms-bearing theme
+  later in DocketWorks Company Settings
+
 ### 2b. You create the Xero Developer App
 
 1. Go to https://developer.xero.com/app/manage
@@ -238,6 +246,10 @@ Once the instance is running:
    python manage.py start_xero_sync
    ```
 
+`xero --setup` imports the connected organisation's real default sales branding
+theme. It preserves a previously selected theme when that theme still exists in
+the connected organisation.
+
 ### 7b. Company Settings
 
 In Admin > Settings, configure:
@@ -249,6 +261,8 @@ In Admin > Settings, configure:
 - Starting job/PO numbers and PO prefix
 - Google Drive folder IDs (Shared Drive, How We Work, SOPs, Reference Library)
 - Quote template ID and quotes folder ID (if applicable)
+- Xero sales branding theme (confirm the selected theme contains the required
+  quote and invoice terms)
 - KPI thresholds (optional, can be tuned later)
 
 ### 7c. Create Shop Jobs
diff --git a/docs/instance-setup-demo.md b/docs/instance-setup-demo.md
index c78ba5b9e..fc52d9128 100644
--- a/docs/instance-setup-demo.md
+++ b/docs/instance-setup-demo.md
@@ -86,6 +86,10 @@ Upload logos: Admin > Settings > Company > Logo and Logo Wide.
 scripts/server/dw-run.sh <client>-uat python manage.py xero --setup
 ```
 
+`xero --setup` stores the Demo Company's real default sales branding theme. In
+Admin > Settings, change it to a terms-bearing theme if the default is not the
+theme the prospect should see.
+
 **Note:** `xero --setup` creates the "Weekly Testing" payroll calendar in the Demo Company if it's missing (a weekly calendar anchored to a **Monday** — Docketworks payroll posting requires Mon→Sun periods). If you ever create one by hand instead (Payroll > Settings > Payroll Calendars), its period **must start on a Monday**; `xero --setup` fails loudly if the calendar it just created came back on any other day.
 
 ## Step 6: Sync Xero Data
@@ -129,6 +133,7 @@ scripts/server/dw-run.sh <client>-uat python manage.py start_xero_sync
 - [ ] Shop jobs visible on Kanban board
 - [ ] Admin > Xero shows "Connected"
 - [ ] Can create a new job and add time/materials
+- [ ] A DocketWorks quote and invoice use the selected Xero branding theme
 - [ ] Create a test timesheet entry
 
 ## Login Credentials
diff --git a/docs/instance-setup-production.md b/docs/instance-setup-production.md
index 9f347a20f..146092063 100644
--- a/docs/instance-setup-production.md
+++ b/docs/instance-setup-production.md
@@ -64,7 +64,9 @@ existence check and doesn't read tokens.)
 scripts/server/dw-run.sh <client>-prod python manage.py xero --setup
 ```
 
-Sets xero_tenant_id, xero_shortcode, and xero_payroll_calendar_id.
+Sets `xero_tenant_id`, `xero_shortcode`, `xero_payroll_calendar_id`, and the
+connected organisation's real default sales branding theme. A valid existing
+custom theme selection is preserved.
 
 **Requires:** The payroll calendar must already exist in Xero (created during client onboarding Phase 2a).
 
@@ -79,6 +81,8 @@ In Admin > Settings, set all values collected in Phase 1 of client_onboarding.md
 - Shop client name (must match the Xero contact from Phase 2a)
 - Google Drive folder IDs (Shared Drive, How We Work, SOPs, Reference Library)
 - Quote template ID and quotes folder ID (if applicable)
+- Xero sales branding theme — select the terms-bearing theme if it is not the
+  Xero default imported by `xero --setup`
 
 Upload logos: Admin > Settings > Company > Logo and Logo Wide.
 
@@ -149,6 +153,8 @@ scripts/server/dw-run.sh <client>-prod python manage.py start_xero_sync
 - [ ] Shop jobs visible on Kanban board
 - [ ] Create a test timesheet entry
 - [ ] Admin > Xero shows "Connected" status
+- [ ] A quote created from DocketWorks shows the required terms in its Xero PDF
+- [ ] An invoice created from DocketWorks shows the required terms in its Xero PDF
 - [ ] Password reset email works (test with a staff member)
 
 ## Post-Setup
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index 7d302ae79..cd77a3915 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -241,7 +241,9 @@ python manage.py xero --setup
 Configures all required Xero settings in CompanyDefaults:
 1. Sets `xero_tenant_id` from connected organisation
 2. Sets `xero_shortcode` for deep linking
-3. Looks up payroll calendar by name and sets `xero_payroll_calendar_id`
+3. Preserves a live sales branding theme selection or replaces a restored,
+   cross-tenant ID with the destination organisation's real default theme
+4. Looks up payroll calendar by name and sets `xero_payroll_calendar_id`
 
 **Expected output:**
 
@@ -249,6 +251,7 @@ Configures all required Xero settings in CompanyDefaults:
 Using organisation: [Tenant Name]
 Tenant ID: [tenant-id-uuid]
 Shortcode: [shortcode]
+Sales Branding Theme: [theme name] ([theme-uuid])
 Payroll Calendar: Weekly Testing ([calendar-uuid])
 Xero setup complete.
 ```
@@ -350,6 +353,10 @@ python scripts/restore_checks/test_kanban_api.py
 API working: 174 active jobs, 23 archived
 ```
 
+Open one recreated quote and one recreated invoice in Xero and confirm their
+PDFs use the selected destination branding theme and contain the required
+terms. A successful API seed alone does not verify document presentation.
+
 #### Snapshot Verified Database
 
 The DB is now in a known-good state: loaded from prod, migrated, fixtures applied, Xero synced, validators and smoke tests green. Capture this state as a baseline so the Playwright run — or any later test run — can be recovered from it without re-running this entire runbook.
diff --git a/docs/server_setup.md b/docs/server_setup.md
index 52f2f8ae3..53f70ac26 100644
--- a/docs/server_setup.md
+++ b/docs/server_setup.md
@@ -213,6 +213,10 @@ For a prospect trying DocketWorks with their own Xero:
    scripts/server/dw-run.sh <name> python manage.py start_xero_sync --entity accounts
    ```
 
+   `xero --setup` stores the connected organisation's real default sales
+   branding theme. In Admin > Settings, select the terms-bearing theme if the
+   organisation uses a different theme for customer documents.
+
 5. **Import staff from Xero**
 
    ```bash
@@ -226,7 +230,9 @@ For a prospect trying DocketWorks with their own Xero:
    This pulls employees from Xero Payroll and creates Staff records with their
    wage rates and working hours. All imported staff get `password_needs_reset=True`.
 
-6. **Verify** — log in as admin, check Staff list, mark office staff via admin UI
+6. **Verify** — log in as admin, check Staff list, mark office staff via admin
+   UI, then create a quote and invoice and confirm their Xero PDFs contain the
+   required terms
 
 ---
 
diff --git a/docs/urls/workflow.md b/docs/urls/workflow.md
index 72280d343..723c652a0 100644
--- a/docs/urls/workflow.md
+++ b/docs/urls/workflow.md
@@ -66,6 +66,7 @@
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
 | `/xero/authenticate/` | `xero_view.xero_authenticate` | `api_xero_authenticate` | Xero Authentication (Step 1: Redirect user to Xero OAuth2 login) |
+| `/xero/branding-themes/` | `xero_view.list_xero_branding_themes` | `xero_branding_themes_list` | Return selectable document themes from the connected Xero organisation. |
 | `/xero/create_invoice/<uuid:job_id>/` | `xero_view.create_xero_invoice` | `create_invoice` | Creates an Invoice in Xero for a given job. |
 | `/xero/create_purchase_order/<uuid:purchase_order_id>/` | `xero_view.create_xero_purchase_order` | `create_xero_purchase_order` | Creates or updates a Purchase Order in Xero for a given purchase order. |
 | `/xero/create_quote/<uuid:job_id>/` | `xero_view.create_xero_quote` | `create_quote` | Creates a quote in Xero for a given job. |
diff --git a/frontend/schema.yml b/frontend/schema.yml
index b09a2283a..0dac15b0c 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -9377,6 +9377,35 @@ paths:
               schema:
                 $ref: '#/components/schemas/GroupedErrorResolveResponse'
           description: ''
+  /api/xero/branding-themes/:
+    get:
+      operationId: xero_branding_themes_list
+      description: Lists Xero branding themes available for quotes and sales invoices.
+      tags:
+        - Xero
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/XeroBrandingTheme'
+          description: ''
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/XeroAuthenticationErrorResponse'
+          description: ''
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/XeroDocumentErrorResponse'
+          description: ''
   /api/xero/create_invoice/{job_id}:
     post:
       operationId: xero_create_invoice_create
@@ -10587,6 +10616,14 @@ components:
           nullable: true
           description: Xero organisation shortcode for deep linking (e.g., '!8-5Xl')
           maxLength: 20
+        xero_sales_branding_theme_id:
+          type: string
+          format: uuid
+          nullable: true
+          title: Xero sales branding theme
+          description: Branding theme applied to every quote and sales invoice created
+            in Xero. Select a theme containing the required terms and conditions;
+            document creation is blocked until one is selected.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -10963,6 +11000,14 @@ components:
           nullable: true
           description: Xero organisation shortcode for deep linking (e.g., '!8-5Xl')
           maxLength: 20
+        xero_sales_branding_theme_id:
+          type: string
+          format: uuid
+          nullable: true
+          title: Xero sales branding theme
+          description: Branding theme applied to every quote and sales invoice created
+            in Xero. Select a theme containing the required terms and conditions;
+            document creation is blocked until one is selected.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -16757,6 +16802,14 @@ components:
           nullable: true
           description: Xero organisation shortcode for deep linking (e.g., '!8-5Xl')
           maxLength: 20
+        xero_sales_branding_theme_id:
+          type: string
+          format: uuid
+          nullable: true
+          title: Xero sales branding theme
+          description: Branding theme applied to every quote and sales invoice created
+            in Xero. Select a theme containing the required terms and conditions;
+            document creation is blocked until one is selected.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -23733,6 +23786,35 @@ components:
         - client_id
         - label
         - redirect_uri
+    XeroAuthenticationErrorResponse:
+      type: object
+      description: Serializer for Xero authentication error responses.
+      properties:
+        success:
+          type: boolean
+          default: false
+        redirect_to_auth:
+          type: boolean
+          default: true
+        message:
+          type: string
+      required:
+        - message
+    XeroBrandingTheme:
+      type: object
+      description: A Xero branding theme available for sales documents.
+      properties:
+        branding_theme_id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        is_default:
+          type: boolean
+      required:
+        - branding_theme_id
+        - is_default
+        - name
     XeroDocumentErrorResponse:
       type: object
       description: Standardized serializer for a failed Xero document operation.
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index defad838d..b87b3b20e 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -927,6 +927,7 @@ const CompanyDefaults = z.object({
   accounting_provider: z.string().max(20).optional(),
   xero_tenant_id: z.string().max(100).nullish(),
   xero_shortcode: z.string().max(20).nullish(),
+  xero_sales_branding_theme_id: z.string().uuid().nullish(),
   enable_xero_sync: z.boolean().optional(),
   xero_automated_day_floor: z.number().int().gte(0).lte(2147483647).optional(),
   xero_payroll_calendar_name: z.string().max(100).optional(),
@@ -991,6 +992,7 @@ const CompanyDefaultsRequest = z.object({
   accounting_provider: z.string().min(1).max(20).optional(),
   xero_tenant_id: z.string().max(100).nullish(),
   xero_shortcode: z.string().max(20).nullish(),
+  xero_sales_branding_theme_id: z.string().uuid().nullish(),
   enable_xero_sync: z.boolean().optional(),
   xero_automated_day_floor: z.number().int().gte(0).lte(2147483647).optional(),
   xero_payroll_calendar_name: z.string().min(1).max(100).optional(),
@@ -1054,6 +1056,7 @@ const PatchedCompanyDefaultsRequest = z
     accounting_provider: z.string().min(1).max(20),
     xero_tenant_id: z.string().max(100).nullable(),
     xero_shortcode: z.string().max(20).nullable(),
+    xero_sales_branding_theme_id: z.string().uuid().nullable(),
     enable_xero_sync: z.boolean(),
     xero_automated_day_floor: z.number().int().gte(0).lte(2147483647),
     xero_payroll_calendar_name: z.string().min(1).max(100),
@@ -3632,6 +3635,23 @@ const PaginatedXeroErrorList = z.object({
   previous: z.string().url().nullish(),
   results: z.array(XeroError),
 })
+const XeroBrandingTheme = z.object({
+  branding_theme_id: z.string().uuid(),
+  name: z.string(),
+  is_default: z.boolean(),
+})
+const XeroAuthenticationErrorResponse = z.object({
+  success: z.boolean().optional().default(false),
+  redirect_to_auth: z.boolean().optional().default(true),
+  message: z.string(),
+})
+const XeroDocumentErrorResponse = z.object({
+  success: z.boolean().optional().default(false),
+  error: z.string(),
+  messages: z.array(z.string()).optional(),
+  error_type: z.string().optional(),
+  redirect_to_auth: z.boolean().optional(),
+})
 const XeroInvoiceCreateModeEnum = z.enum([
   'invoice_full',
   'invoice_costs_to_date',
@@ -3653,13 +3673,6 @@ const XeroDocumentSuccessResponse = z.object({
   total_incl_tax: z.number().gt(-10000000000).lt(10000000000).optional(),
   action: z.string().optional(),
 })
-const XeroDocumentErrorResponse = z.object({
-  success: z.boolean().optional().default(false),
-  error: z.string(),
-  messages: z.array(z.string()).optional(),
-  error_type: z.string().optional(),
-  redirect_to_auth: z.boolean().optional(),
-})
 const XeroQuoteCreateRequest = z.object({ breakdown: z.boolean() })
 const XeroPingResponse = z.object({
   connected: z.boolean(),
@@ -4126,10 +4139,12 @@ export const schemas = {
   XeroPayItem,
   XeroError,
   PaginatedXeroErrorList,
+  XeroBrandingTheme,
+  XeroAuthenticationErrorResponse,
+  XeroDocumentErrorResponse,
   XeroInvoiceCreateModeEnum,
   XeroInvoiceCreateRequest,
   XeroDocumentSuccessResponse,
-  XeroDocumentErrorResponse,
   XeroQuoteCreateRequest,
   XeroPingResponse,
   XeroSyncStartResponse,
@@ -10624,6 +10639,24 @@ Endpoint: /api/xero/errors/&lt;id&gt;/`,
     ],
     response: z.object({ updated: z.number().int() }),
   },
+  {
+    method: 'get',
+    path: '/api/xero/branding-themes/',
+    alias: 'xero_branding_themes_list',
+    description: `Lists Xero branding themes available for quotes and sales invoices.`,
+    requestFormat: 'json',
+    response: z.array(XeroBrandingTheme),
+    errors: [
+      {
+        status: 401,
+        schema: XeroAuthenticationErrorResponse,
+      },
+      {
+        status: 500,
+        schema: XeroDocumentErrorResponse,
+      },
+    ],
+  },
   {
     method: 'post',
     path: '/api/xero/create_invoice/:job_id',
diff --git a/frontend/src/components/SectionForm.vue b/frontend/src/components/SectionForm.vue
index 98adb3808..94c9668d2 100644
--- a/frontend/src/components/SectionForm.vue
+++ b/frontend/src/components/SectionForm.vue
@@ -99,6 +99,41 @@
           </option>
         </select>
 
+        <div v-else-if="field.type === 'xero_branding_theme'" class="flex flex-col gap-1">
+          <select
+            :value="brandingThemeValue(field.key)"
+            class="h-9 text-sm rounded-md border border-input bg-background px-3 py-1"
+            :class="{
+              'bg-gray-100 cursor-not-allowed':
+                field.readOnly || brandingThemesLoading || brandingThemesError,
+            }"
+            :data-automation-id="`SectionForm-${section}-field-${field.key}`"
+            :disabled="field.readOnly || brandingThemesLoading || brandingThemesError !== null"
+            @change="onBrandingThemeChange(field.key, $event)"
+          >
+            <option value="">
+              {{ brandingThemesLoading ? 'Loading Xero branding themes…' : 'No theme selected' }}
+            </option>
+            <option v-if="unavailableBrandingThemeId" :value="unavailableBrandingThemeId">
+              Unavailable theme ({{ unavailableBrandingThemeId }})
+            </option>
+            <option
+              v-for="theme in brandingThemes"
+              :key="theme.branding_theme_id"
+              :value="theme.branding_theme_id"
+            >
+              {{ theme.name }}{{ theme.is_default ? ' (Xero default)' : '' }}
+            </option>
+          </select>
+          <p
+            v-if="brandingThemesError"
+            class="text-xs text-red-600"
+            :data-automation-id="`SectionForm-${section}-field-${field.key}-error`"
+          >
+            {{ brandingThemesError }}
+          </p>
+        </div>
+
         <Textarea
           v-else-if="field.type === 'textarea'"
           v-model="localForm[field.key] as string | undefined"
@@ -213,11 +248,16 @@ const FIELD_COL_SPAN_OVERRIDES: Record<string, 2> = {
   gdrive_reference_library_folder_id: 2,
   xero_tenant_id: 2,
   xero_payroll_calendar_id: 2,
+  xero_sales_branding_theme_id: 2,
 }
 
 const logoErrors = ref<Record<string, string>>({})
 const companyOptions = ref<CompanyOption[]>([])
 const companyOptionsLoading = ref(false)
+const brandingThemes = ref<Awaited<ReturnType<typeof api.xero_branding_themes_list>>>([])
+const brandingThemesLoading = ref(false)
+const brandingThemesError = ref<string | null>(null)
+const brandingThemesLoadAttempted = ref(false)
 
 const LOGO_ASPECT_RULES: Record<
   string,
@@ -475,6 +515,42 @@ async function loadCompanyOptions() {
   }
 }
 
+async function loadBrandingThemes() {
+  brandingThemesLoadAttempted.value = true
+  brandingThemesLoading.value = true
+  brandingThemesError.value = null
+  try {
+    brandingThemes.value = await api.xero_branding_themes_list()
+  } catch (e) {
+    console.error('Xero branding themes load failed:', e)
+    brandingThemesError.value =
+      'Could not load branding themes from Xero. Check the Xero connection and try again.'
+    toast.error('Failed to load Xero branding themes')
+  } finally {
+    brandingThemesLoading.value = false
+  }
+}
+
+function brandingThemeValue(fieldKey: string): string {
+  const value = localForm.value[fieldKey]
+  return typeof value === 'string' ? value : ''
+}
+
+const unavailableBrandingThemeId = computed(() => {
+  const configuredId = brandingThemeValue('xero_sales_branding_theme_id')
+  if (!configuredId) return null
+  const isAvailable = brandingThemes.value.some((theme) => theme.branding_theme_id === configuredId)
+  return isAvailable ? null : configuredId
+})
+
+function onBrandingThemeChange(fieldKey: string, event: Event) {
+  const value = (event.target as HTMLSelectElement).value
+  localForm.value = {
+    ...localForm.value,
+    [fieldKey]: value || null,
+  }
+}
+
 watch(
   sectionFields,
   (fields) => {
@@ -491,6 +567,16 @@ watch(
   { immediate: true },
 )
 
+watch(
+  sectionFields,
+  (fields) => {
+    if (!fields.some((field) => field.type === 'xero_branding_theme')) return
+    if (brandingThemesLoadAttempted.value) return
+    void loadBrandingThemes()
+  },
+  { immediate: true },
+)
+
 function normalizeUrl(url: string): string {
   if (!url) return url
   if (/^https?:\/\//i.test(url)) return url
diff --git a/frontend/src/components/__tests__/SectionForm.test.ts b/frontend/src/components/__tests__/SectionForm.test.ts
index 3f18dc173..803a2c6b5 100644
--- a/frontend/src/components/__tests__/SectionForm.test.ts
+++ b/frontend/src/components/__tests__/SectionForm.test.ts
@@ -1,32 +1,32 @@
 import { flushPromises, mount } from '@vue/test-utils'
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import SectionForm from '@/components/SectionForm.vue'
 
-const { companiesAllList } = vi.hoisted(() => ({
+const { companiesAllList, xeroBrandingThemesList, settingsFields, toastError } = vi.hoisted(() => ({
   companiesAllList: vi.fn(),
+  xeroBrandingThemesList: vi.fn(),
+  settingsFields: [] as Array<Record<string, unknown>>,
+  toastError: vi.fn(),
 }))
 
 vi.mock('@/api/client', () => ({
   api: {
     companies_all_list: companiesAllList,
+    xero_branding_themes_list: xeroBrandingThemesList,
+  },
+}))
+
+vi.mock('vue-sonner', () => ({
+  toast: {
+    error: toastError,
+    success: vi.fn(),
   },
 }))
 
 vi.mock('@/composables/useSettingsSchema', () => ({
   useSettingsSchema: () => ({
-    getFieldsForSection: () => [
-      {
-        key: 'shop_company',
-        label: 'Shop Company',
-        type: 'company',
-        required: true,
-        help_text: 'Internal company used for tracking shop work.',
-        section: 'setup',
-        icon: 'span',
-        readOnly: false,
-      },
-    ],
+    getFieldsForSection: () => settingsFields,
     getSpecialHandler: () => undefined,
   }),
   REMOVED_SETTING_KEYS: new Set<string>(),
@@ -34,6 +34,20 @@ vi.mock('@/composables/useSettingsSchema', () => ({
 }))
 
 describe('SectionForm', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    settingsFields.splice(0, settingsFields.length, {
+      key: 'shop_company',
+      label: 'Shop Company',
+      type: 'company',
+      required: true,
+      help_text: 'Internal company used for tracking shop work.',
+      section: 'setup',
+      icon: 'span',
+      readOnly: false,
+    })
+  })
+
   it('renders company fields as a selector backed by generated company data', async () => {
     companiesAllList.mockResolvedValue([
       { id: '00000000-0000-0000-0000-000000000001', name: 'Demo Company Shop' },
@@ -91,4 +105,118 @@ describe('SectionForm', () => {
     // The edit must be emitted, never applied in place to the prop object.
     expect(modelValue.shop_company).toBe('00000000-0000-0000-0000-000000000001')
   })
+
+  it('loads Xero branding themes, identifies the default, and clears to null', async () => {
+    settingsFields.splice(0, settingsFields.length, {
+      key: 'xero_sales_branding_theme_id',
+      label: 'Sales Branding Theme',
+      type: 'xero_branding_theme',
+      required: false,
+      help_text: 'Branding theme used for sales documents.',
+      section: 'xero',
+      icon: 'span',
+      readOnly: false,
+    })
+    xeroBrandingThemesList.mockResolvedValue([
+      {
+        branding_theme_id: '22222222-2222-2222-2222-222222222222',
+        name: 'Standard',
+        is_default: true,
+      },
+      {
+        branding_theme_id: '33333333-3333-3333-3333-333333333333',
+        name: 'Terms Footer',
+        is_default: false,
+      },
+    ])
+
+    const wrapper = mount(SectionForm, {
+      props: {
+        section: 'xero',
+        modelValue: { xero_sales_branding_theme_id: null },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.get(
+      '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
+    )
+    expect(selector.element.tagName).toBe('SELECT')
+    expect(selector.text()).toContain('Standard (Xero default)')
+    expect(selector.text()).toContain('Terms Footer')
+    expect(selector.element.closest('label')?.className).toContain('md:col-span-2')
+
+    await selector.setValue('33333333-3333-3333-3333-333333333333')
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
+      { xero_sales_branding_theme_id: '33333333-3333-3333-3333-333333333333' },
+    ])
+
+    await selector.setValue('')
+    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
+      { xero_sales_branding_theme_id: null },
+    ])
+  })
+
+  it('preserves a configured branding theme that Xero no longer returns', async () => {
+    settingsFields.splice(0, settingsFields.length, {
+      key: 'xero_sales_branding_theme_id',
+      label: 'Sales Branding Theme',
+      type: 'xero_branding_theme',
+      required: false,
+      help_text: '',
+      section: 'xero',
+      icon: 'span',
+      readOnly: false,
+    })
+    xeroBrandingThemesList.mockResolvedValue([])
+    const unavailableId = '44444444-4444-4444-4444-444444444444'
+
+    const wrapper = mount(SectionForm, {
+      props: {
+        section: 'xero',
+        modelValue: { xero_sales_branding_theme_id: unavailableId },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.get(
+      '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
+    )
+    expect((selector.element as HTMLSelectElement).value).toBe(unavailableId)
+    expect(selector.text()).toContain(`Unavailable theme (${unavailableId})`)
+  })
+
+  it('disables the branding theme selector and explains a Xero loading failure', async () => {
+    settingsFields.splice(0, settingsFields.length, {
+      key: 'xero_sales_branding_theme_id',
+      label: 'Sales Branding Theme',
+      type: 'xero_branding_theme',
+      required: false,
+      help_text: '',
+      section: 'xero',
+      icon: 'span',
+      readOnly: false,
+    })
+    xeroBrandingThemesList.mockRejectedValue(new Error('Xero unavailable'))
+    vi.spyOn(console, 'error').mockImplementation(() => undefined)
+
+    const wrapper = mount(SectionForm, {
+      props: {
+        section: 'xero',
+        modelValue: { xero_sales_branding_theme_id: null },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.get(
+      '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
+    )
+    expect((selector.element as HTMLSelectElement).disabled).toBe(true)
+    expect(
+      wrapper
+        .get('[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id-error"]')
+        .text(),
+    ).toContain('Could not load branding themes from Xero')
+    expect(toastError).toHaveBeenCalledWith('Failed to load Xero branding themes')
+  })
 })
diff --git a/frontend/tests/company-defaults.spec.ts b/frontend/tests/company-defaults.spec.ts
index abfc73f75..e61cc3471 100644
--- a/frontend/tests/company-defaults.spec.ts
+++ b/frontend/tests/company-defaults.spec.ts
@@ -91,3 +91,61 @@ test('test company defaults edit and save', async ({ authenticatedPage: page })
 
   console.log(`Restored company email to: ${originalValue}`)
 })
+
+test('test Xero sales branding theme save, reload, and restore', async ({
+  authenticatedPage: page,
+}) => {
+  await page.goto('/admin/company/xero')
+
+  const selector = page.locator(
+    '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
+  )
+  await expect(selector).toBeVisible({ timeout: 15000 })
+  await expect(selector).toBeEnabled({ timeout: 15000 })
+
+  const originalValue = await selector.inputValue()
+  const availableThemeIds = await selector
+    .locator('option')
+    .evaluateAll((options) =>
+      options
+        .filter(
+          (option) => option.value !== '' && !option.textContent?.startsWith('Unavailable theme'),
+        )
+        .map((option) => option.value),
+    )
+  test.skip(availableThemeIds.length === 0, 'The connected Xero tenant has no branding themes')
+
+  const differentThemeId = availableThemeIds.find((id) => id !== originalValue)
+  const testValue = differentThemeId ?? ''
+  let changed = false
+
+  try {
+    await selector.selectOption(testValue)
+    changed = testValue !== originalValue
+    await expect(
+      page.locator('[data-automation-id="AdminCompanySectionView-save-button"]'),
+    ).toBeEnabled()
+    await page.click('[data-automation-id="AdminCompanySectionView-save-button"]')
+    await expect(
+      page.locator('[data-automation-id="AdminCompanySectionView-save-button"]'),
+    ).toBeDisabled({ timeout: 10000 })
+
+    await page.reload()
+    await expect(selector).toBeVisible({ timeout: 15000 })
+    await expect(selector).toHaveValue(testValue)
+  } finally {
+    if (changed) {
+      await page.goto('/admin/company/xero')
+      await expect(selector).toBeEnabled({ timeout: 15000 })
+      if ((await selector.inputValue()) !== originalValue) {
+        await selector.selectOption(originalValue)
+        await page.click('[data-automation-id="AdminCompanySectionView-save-button"]')
+        await expect(
+          page.locator('[data-automation-id="AdminCompanySectionView-save-button"]'),
+        ).toBeDisabled({ timeout: 10000 })
+        await page.reload()
+        await expect(selector).toHaveValue(originalValue)
+      }
+    }
+  }
+})
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index e5bb1763c..cd156694e 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -3796,41 +3796,31 @@ apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for g
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "create_company_contact_in_xero" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "sync_company_to_xero" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_build_line_items" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_build_line_items" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "process_xero_data" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_build_line_items" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_to_xero_payload" of "XeroAccountingProvider" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Returning Any from function declared to return "DocumentResult"  [no-any-return]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_make_error_result" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "_get_api" of "XeroAccountingProvider" in typed context  [no-untyped-call]
-apps/workflow/accounting/xero/provider.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/accounting/xero/provider.py:0: error: Call to untyped function "synchronise_xero_data" in typed context  [no-untyped-call]
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/accounting/xero/provider.py:0: error: Missing type arguments for generic type "dict"  [type-arg]

From 8fbc820504616cbc143a99b549c84530c0eaed1e Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 12:35:50 +1200
Subject: [PATCH 48/73] fix: initialise Xero branding theme automatically

---
 .../accounting/document_theme_service.py      |  65 +++++
 apps/workflow/management/commands/xero.py     |  44 ++-
 ...nydefaults_xero_sales_branding_theme_id.py |   5 +-
 apps/workflow/models/company_defaults.py      |   3 +-
 .../tests/test_xero_branding_themes.py        | 250 +++++++++++++++++-
 .../workflow/tests/test_xero_setup_command.py | 119 ++-------
 apps/workflow/views/xero/xero_base_manager.py |  21 +-
 .../views/xero/xero_invoice_manager.py        |   7 +-
 .../workflow/views/xero/xero_quote_manager.py |   7 +-
 docs/client_onboarding.md                     |  10 +-
 docs/instance-setup-demo.md                   |   6 +-
 docs/instance-setup-production.md             |   6 +-
 docs/restore-prod-to-nonprod.md               |   3 +-
 docs/server_setup.md                          |  10 +-
 frontend/schema.yml                           |   9 +-
 frontend/src/components/SectionForm.vue       |  50 +++-
 .../components/__tests__/SectionForm.test.ts  |  50 +++-
 frontend/tests/company-defaults.spec.ts       |  13 +-
 18 files changed, 494 insertions(+), 184 deletions(-)
 create mode 100644 apps/workflow/accounting/document_theme_service.py

diff --git a/apps/workflow/accounting/document_theme_service.py b/apps/workflow/accounting/document_theme_service.py
new file mode 100644
index 000000000..0e803886b
--- /dev/null
+++ b/apps/workflow/accounting/document_theme_service.py
@@ -0,0 +1,65 @@
+"""Selection and persistence of the sales document branding theme."""
+
+from uuid import UUID
+
+from apps.workflow.accounting.provider import AccountingProvider
+from apps.workflow.accounting.types import DocumentTheme
+from apps.workflow.models.company_defaults import CompanyDefaults
+
+
+def resolve_and_persist_sales_branding_theme(
+    provider: AccountingProvider,
+    company_defaults: CompanyDefaults,
+) -> DocumentTheme | None:
+    """Preserve a live selection or persist the provider's first theme.
+
+    Providers return themes in their preferred order. The Xero provider orders
+    them by Xero's ``SortOrder``, so its first item is the valid unattended
+    starting point for an installation that has not selected a theme yet.
+    """
+    themes = provider.list_document_themes()
+    if not themes:
+        return None
+
+    configured_id = company_defaults.xero_sales_branding_theme_id
+    selected_theme = next(
+        (
+            theme
+            for theme in themes
+            if configured_id is not None and theme.external_id == str(configured_id)
+        ),
+        themes[0],
+    )
+    selected_id = UUID(selected_theme.external_id)
+
+    if configured_id == selected_id:
+        return selected_theme
+
+    updated = CompanyDefaults.objects.filter(
+        pk=company_defaults.pk,
+        xero_sales_branding_theme_id=configured_id,
+    ).update(xero_sales_branding_theme_id=selected_id)
+    CompanyDefaults.clear_cache()
+
+    if updated == 1:
+        company_defaults.xero_sales_branding_theme_id = selected_id
+        return selected_theme
+
+    current_id = CompanyDefaults.objects.values_list(
+        "xero_sales_branding_theme_id", flat=True
+    ).get(pk=company_defaults.pk)
+    current_theme = next(
+        (
+            theme
+            for theme in themes
+            if current_id is not None and theme.external_id == str(current_id)
+        ),
+        None,
+    )
+    if current_theme is None:
+        raise ValueError(
+            "The Xero sales branding theme changed while it was being configured."
+        )
+
+    company_defaults.xero_sales_branding_theme_id = current_id
+    return current_theme
diff --git a/apps/workflow/management/commands/xero.py b/apps/workflow/management/commands/xero.py
index fdac5e26a..3559793a5 100644
--- a/apps/workflow/management/commands/xero.py
+++ b/apps/workflow/management/commands/xero.py
@@ -1,5 +1,4 @@
 import datetime
-from uuid import UUID
 
 import requests
 from django.core.cache import cache
@@ -13,8 +12,10 @@
 
 from apps.accounts.models import Staff
 from apps.timesheet.services import PayrollEmployeeSyncService
+from apps.workflow.accounting.document_theme_service import (
+    resolve_and_persist_sales_branding_theme,
+)
 from apps.workflow.accounting.registry import get_provider
-from apps.workflow.accounting.types import DocumentTheme
 from apps.workflow.api.xero.auth import api_client, get_tenant_id, get_valid_token
 from apps.workflow.api.xero.payroll import (
     get_earnings_rates,
@@ -432,27 +433,6 @@ def _ensure_demo_xero_items_exist(self, calendar_name: str, tenant_id: str) -> N
                     )
                 )
 
-    @staticmethod
-    def _resolve_sales_branding_theme(configured_id: UUID | None) -> DocumentTheme:
-        """Preserve a live selection or choose the connected tenant's default."""
-        themes = get_provider().list_document_themes()
-        default_themes = [theme for theme in themes if theme.is_default]
-        if len(default_themes) != 1:
-            raise CommandError(
-                "Xero must return exactly one default branding theme; "
-                f"received {len(default_themes)} from {len(themes)} themes."
-            )
-
-        if configured_id is not None:
-            configured_theme = next(
-                (theme for theme in themes if theme.external_id == str(configured_id)),
-                None,
-            )
-            if configured_theme is not None:
-                return configured_theme
-
-        return default_themes[0]
-
     def run_setup(self):
         """Configure Xero tenant, theme, shortcode, and payroll calendar."""
         self.stdout.write("Setting up Xero connection...")
@@ -523,9 +503,14 @@ def run_setup(self):
         shortcode = org_response.organisations[0].short_code
 
         # Step 5: Select a live sales branding theme for this tenant
-        sales_branding_theme = self._resolve_sales_branding_theme(
-            company.xero_sales_branding_theme_id
+        sales_branding_theme = resolve_and_persist_sales_branding_theme(
+            get_provider(), company
         )
+        if sales_branding_theme is None:
+            raise CommandError(
+                "Xero returned no branding themes. Create a branding theme in "
+                "Xero before running setup."
+            )
 
         # Step 6: Fetch payroll calendar ID
         calendar_name = company.xero_payroll_calendar_name
@@ -554,11 +539,14 @@ def run_setup(self):
             payroll_calendar_id = matching_calendar["id"]
 
         # Step 7: Save to CompanyDefaults
-        company.xero_tenant_id = tenant_id
         company.xero_shortcode = shortcode
-        company.xero_sales_branding_theme_id = sales_branding_theme.external_id
         company.xero_payroll_calendar_id = payroll_calendar_id
-        company.save()
+        company.save(
+            update_fields=[
+                "xero_shortcode",
+                "xero_payroll_calendar_id",
+            ]
+        )
 
         self.stdout.write(self.style.SUCCESS(f"Tenant ID: {tenant_id}"))
         self.stdout.write(self.style.SUCCESS(f"Shortcode: {shortcode}"))
diff --git a/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
index 6aa4596cb..8e707a010 100644
--- a/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
+++ b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
@@ -17,8 +17,9 @@ class Migration(migrations.Migration):
                 help_text=(
                     "Branding theme applied to every quote and sales invoice "
                     "created in Xero. Select a theme containing the required "
-                    "terms and conditions; document creation is blocked until "
-                    "one is selected."
+                    "terms and conditions; if unset, the first Xero theme is "
+                    "selected automatically when the next sales document is "
+                    "created."
                 ),
                 null=True,
                 verbose_name="Xero sales branding theme",
diff --git a/apps/workflow/models/company_defaults.py b/apps/workflow/models/company_defaults.py
index 70cdce47e..af13a15cd 100644
--- a/apps/workflow/models/company_defaults.py
+++ b/apps/workflow/models/company_defaults.py
@@ -132,7 +132,8 @@ class CompanyDefaults(SingletonModel):
         help_text=(
             "Branding theme applied to every quote and sales invoice created in "
             "Xero. Select a theme containing the required terms and conditions; "
-            "document creation is blocked until one is selected."
+            "if unset, the first Xero theme is selected automatically when the "
+            "next sales document is created."
         ),
     )
     enable_xero_sync = models.BooleanField(
diff --git a/apps/workflow/tests/test_xero_branding_themes.py b/apps/workflow/tests/test_xero_branding_themes.py
index 3fbe43264..968b93ac3 100644
--- a/apps/workflow/tests/test_xero_branding_themes.py
+++ b/apps/workflow/tests/test_xero_branding_themes.py
@@ -10,13 +10,18 @@
 from apps.company.models import Company
 from apps.job.models import Job
 from apps.testing import BaseTestCase
+from apps.workflow.accounting.document_theme_service import (
+    resolve_and_persist_sales_branding_theme,
+)
 from apps.workflow.accounting.types import (
     DocumentLineItem,
+    DocumentResult,
     DocumentTheme,
     InvoicePayload,
     QuotePayload,
 )
 from apps.workflow.accounting.xero.provider import XeroAccountingProvider
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
@@ -137,7 +142,7 @@ def test_list_document_themes_preserves_xero_order_and_default(
 
 
 class XeroBrandingThemeConfigurationTests(BaseTestCase):
-    """No Xero document is created when its required theme is unconfigured."""
+    """An upgraded installation configures its theme before its first write."""
 
     def setUp(self) -> None:
         defaults = CompanyDefaults.get_solo()
@@ -158,34 +163,267 @@ def setUp(self) -> None:
         )
         self.job.save(staff=self.test_staff)
 
-    def test_invoice_creation_stops_before_provider_write(self) -> None:
+    def test_invoice_creation_initialises_first_theme_before_provider_write(
+        self,
+    ) -> None:
+        """A deployment-only upgrade must not require an operator setup command."""
+        manager = XeroInvoiceManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+        manager.provider.list_document_themes.return_value = [
+            DocumentTheme(
+                external_id=THEME_ID,
+                name="First Xero theme",
+                is_default=False,
+            ),
+            DocumentTheme(
+                external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+                name="Later default-labelled theme",
+                is_default=True,
+            ),
+        ]
+        payload = InvoicePayload(
+            client_external_id=str(uuid.uuid4()),
+            company_name=self.company.name,
+            line_items=[],
+            date=date(2026, 7, 16),
+            due_date=date(2026, 7, 16),
+            document_theme_external_id=THEME_ID,
+        )
+        manager.provider.create_invoice.return_value = DocumentResult(
+            success=False,
+            error="Stop after observing the outbound payload",
+            status_code=400,
+        )
+
+        with patch.object(manager, "build_payload", return_value=payload) as build:
+            result = manager.create_document(total_amount=Decimal("100"))
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["status"], 400)
+        build.assert_called_once_with(
+            Decimal("100"), document_theme_external_id=THEME_ID
+        )
+        manager.provider.create_invoice.assert_called_once_with(payload)
+        self.assertEqual(
+            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
+            uuid.UUID(THEME_ID),
+        )
+
+    def test_quote_creation_initialises_first_theme_before_provider_write(self) -> None:
+        """Quote creation shares the unattended upgrade path with invoices."""
+        manager = XeroQuoteManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+        manager.provider.list_document_themes.return_value = [
+            DocumentTheme(
+                external_id=THEME_ID,
+                name="First Xero theme",
+                is_default=True,
+            )
+        ]
+        payload = QuotePayload(
+            client_external_id=str(uuid.uuid4()),
+            company_name=self.company.name,
+            line_items=[],
+            date=date(2026, 7, 16),
+            expiry_date=date(2026, 8, 15),
+            document_theme_external_id=THEME_ID,
+        )
+        manager.provider.create_quote.return_value = DocumentResult(
+            success=False,
+            error="Stop after observing the outbound payload",
+            status_code=400,
+        )
+
+        with patch.object(manager, "build_payload", return_value=payload) as build:
+            result = manager.create_document()
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["status"], 400)
+        build.assert_called_once_with(
+            breakdown=True, document_theme_external_id=THEME_ID
+        )
+        manager.provider.create_quote.assert_called_once_with(payload)
+        self.assertEqual(
+            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
+            uuid.UUID(THEME_ID),
+        )
+
+    def test_invoice_creation_stops_when_xero_has_no_themes(self) -> None:
+        """An empty Xero configuration must fail before the invoice write."""
         manager = XeroInvoiceManager(
             company=self.company, job=self.job, staff=self.test_staff
         )
         manager.provider = Mock()
+        manager.provider.list_document_themes.return_value = []
 
-        result = manager.create_document(total_amount=Decimal("100"))
+        result = manager.create_document()
 
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Select a Xero sales branding theme", result["error"])
+        self.assertIn("Xero returned no branding themes", result["error"])
         manager.provider.create_invoice.assert_not_called()
 
-    def test_quote_creation_stops_before_provider_write(self) -> None:
+    def test_quote_creation_stops_when_xero_has_no_themes(self) -> None:
+        """An empty Xero configuration must fail before the quote write."""
         manager = XeroQuoteManager(
             company=self.company, job=self.job, staff=self.test_staff
         )
         manager.provider = Mock()
+        manager.provider.list_document_themes.return_value = []
 
         result = manager.create_document()
 
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Select a Xero sales branding theme", result["error"])
+        self.assertIn("Xero returned no branding themes", result["error"])
         manager.provider.create_quote.assert_not_called()
 
+    def test_configured_theme_does_not_add_a_xero_read(self) -> None:
+        """Normal document creation must not spend quota revalidating stable config."""
+        configured_id = uuid.UUID(THEME_ID)
+        defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_sales_branding_theme_id=configured_id
+        )
+        CompanyDefaults.clear_cache()
+        manager = XeroQuoteManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+
+        selected_id = manager.get_xero_sales_branding_theme_id()
+
+        self.assertEqual(selected_id, THEME_ID)
+        manager.provider.list_document_themes.assert_not_called()
+
+    def test_prelogged_theme_lookup_failure_is_not_persisted_twice(self) -> None:
+        """The first-use read must preserve the provider's AppError identity."""
+        manager = XeroQuoteManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        manager.provider = Mock()
+        prelogged = AlreadyLoggedException(
+            RuntimeError("Xero theme lookup failed"), "app-error-123"
+        )
+        manager.provider.list_document_themes.side_effect = prelogged
+
+        with self.assertRaises(AlreadyLoggedException) as raised:
+            manager.create_document()
+
+        self.assertIs(raised.exception, prelogged)
+        manager.provider.create_quote.assert_not_called()
+
+
+class SalesBrandingThemeResolutionTests(BaseTestCase):
+    """Setup and first-use initialization share one strict selection contract."""
+
+    def setUp(self) -> None:
+        self.defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
+            xero_sales_branding_theme_id=None,
+            po_prefix="UNCHANGED-",
+        )
+        CompanyDefaults.clear_cache()
+        self.defaults = CompanyDefaults.get_solo()
+        self.provider = Mock()
+
+    def test_unset_configuration_selects_first_theme_and_is_idempotent(self) -> None:
+        """A refactor must not reintroduce default-count checks or broad saves."""
+        first_theme = DocumentTheme(
+            external_id=THEME_ID,
+            name="First by Xero sort order",
+            is_default=False,
+        )
+        self.provider.list_document_themes.return_value = [
+            first_theme,
+            DocumentTheme(
+                external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
+                name="Also valid",
+                is_default=False,
+            ),
+        ]
+
+        first_result = resolve_and_persist_sales_branding_theme(
+            self.provider, self.defaults
+        )
+        second_result = resolve_and_persist_sales_branding_theme(
+            self.provider, self.defaults
+        )
+        self.defaults.refresh_from_db()
+
+        self.assertEqual(first_result, first_theme)
+        self.assertEqual(second_result, first_theme)
+        self.assertEqual(
+            self.defaults.xero_sales_branding_theme_id, uuid.UUID(THEME_ID)
+        )
+        self.assertEqual(self.defaults.po_prefix, "UNCHANGED-")
+
+    def test_live_custom_selection_is_preserved(self) -> None:
+        """Running setup again must not replace an operator's live custom theme."""
+        custom_id = uuid.UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
+        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
+            xero_sales_branding_theme_id=custom_id
+        )
+        CompanyDefaults.clear_cache()
+        self.defaults = CompanyDefaults.get_solo()
+        custom_theme = DocumentTheme(
+            external_id=str(custom_id), name="Terms", is_default=False
+        )
+        self.provider.list_document_themes.return_value = [
+            DocumentTheme(external_id=THEME_ID, name="Standard", is_default=True),
+            custom_theme,
+        ]
+
+        selected = resolve_and_persist_sales_branding_theme(
+            self.provider, self.defaults
+        )
+
+        self.assertEqual(selected, custom_theme)
+        self.assertEqual(
+            CompanyDefaults.get_solo().xero_sales_branding_theme_id, custom_id
+        )
+
+    def test_stale_selection_is_replaced_by_first_live_theme(self) -> None:
+        """A restored cross-tenant UUID must not leak into new Xero documents."""
+        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
+            xero_sales_branding_theme_id=uuid.UUID(
+                "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+            )
+        )
+        CompanyDefaults.clear_cache()
+        self.defaults = CompanyDefaults.get_solo()
+        first_theme = DocumentTheme(
+            external_id=THEME_ID, name="Destination theme", is_default=True
+        )
+        self.provider.list_document_themes.return_value = [first_theme]
+
+        selected = resolve_and_persist_sales_branding_theme(
+            self.provider, self.defaults
+        )
+
+        self.assertEqual(selected, first_theme)
+        self.assertEqual(
+            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
+            uuid.UUID(THEME_ID),
+        )
+
+    def test_empty_theme_list_leaves_configuration_unset(self) -> None:
+        """No arbitrary UUID may be invented when the connected tenant has no theme."""
+        self.provider.list_document_themes.return_value = []
+
+        selected = resolve_and_persist_sales_branding_theme(
+            self.provider, self.defaults
+        )
+
+        self.assertIsNone(selected)
+        self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
+
 
 class XeroBrandingThemeAPITests(BaseTestCase):
     """Office staff can populate the settings selector from live Xero themes."""
diff --git a/apps/workflow/tests/test_xero_setup_command.py b/apps/workflow/tests/test_xero_setup_command.py
index 11c93392e..554584700 100644
--- a/apps/workflow/tests/test_xero_setup_command.py
+++ b/apps/workflow/tests/test_xero_setup_command.py
@@ -3,7 +3,6 @@
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
-from uuid import UUID
 
 from django.core.management.base import CommandError
 from django.test import TestCase
@@ -175,6 +174,10 @@ def test_skips_destination_items_that_already_exist_by_name(
 
 
 class RunSetupTests(TestCase):
+    @patch(
+        "apps.workflow.management.commands.xero."
+        "resolve_and_persist_sales_branding_theme"
+    )
     @patch("apps.workflow.management.commands.xero.get_provider")
     @patch("apps.workflow.management.commands.xero.cache.set")
     @patch("apps.workflow.management.commands.xero.get_payroll_calendars")
@@ -189,6 +192,7 @@ def test_run_setup_always_calls_demo_item_provisioning(
         mock_get_payroll_calendars,
         _mock_cache_set,
         mock_get_provider,
+        mock_resolve_theme,
     ):
         company = SimpleNamespace(
             xero_tenant_id=None,
@@ -212,13 +216,12 @@ def test_run_setup_always_calls_demo_item_provisioning(
         mock_get_payroll_calendars.return_value = [
             {"name": "Weekly Testing", "id": "calendar-123"}
         ]
-        mock_get_provider.return_value.list_document_themes.return_value = [
-            DocumentTheme(
-                external_id="11111111-2222-3333-4444-555555555555",
-                name="Standard",
-                is_default=True,
-            )
-        ]
+        selected_theme = DocumentTheme(
+            external_id="11111111-2222-3333-4444-555555555555",
+            name="Standard",
+            is_default=True,
+        )
+        mock_resolve_theme.return_value = selected_theme
 
         cmd = Command()
         cmd._ensure_demo_xero_items_exist = Mock()
@@ -228,103 +231,13 @@ def test_run_setup_always_calls_demo_item_provisioning(
         cmd._ensure_demo_xero_items_exist.assert_called_once_with(
             "Weekly Testing", "tenant-123"
         )
-        self.assertEqual(
-            company.xero_sales_branding_theme_id,
-            "11111111-2222-3333-4444-555555555555",
-        )
-
-    @patch("apps.workflow.management.commands.xero.get_provider")
-    def test_resolve_sales_branding_theme_selects_default_when_unconfigured(
-        self, mock_get_provider: Mock
-    ) -> None:
-        default_theme = DocumentTheme(
-            external_id="11111111-2222-3333-4444-555555555555",
-            name="Standard",
-            is_default=True,
-        )
-        mock_get_provider.return_value.list_document_themes.return_value = [
-            DocumentTheme(
-                external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
-                name="Custom",
-                is_default=False,
-            ),
-            default_theme,
-        ]
-        selected = Command._resolve_sales_branding_theme(None)
-
-        self.assertEqual(selected, default_theme)
-
-    @patch("apps.workflow.management.commands.xero.get_provider")
-    def test_resolve_sales_branding_theme_preserves_live_custom_selection(
-        self, mock_get_provider: Mock
-    ) -> None:
-        custom_theme = DocumentTheme(
-            external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
-            name="Terms",
-            is_default=False,
-        )
-        mock_get_provider.return_value.list_document_themes.return_value = [
-            DocumentTheme(
-                external_id="11111111-2222-3333-4444-555555555555",
-                name="Standard",
-                is_default=True,
-            ),
-            custom_theme,
-        ]
-        selected = Command._resolve_sales_branding_theme(UUID(custom_theme.external_id))
-
-        self.assertEqual(selected, custom_theme)
-
-    @patch("apps.workflow.management.commands.xero.get_provider")
-    def test_resolve_sales_branding_theme_replaces_stale_tenant_selection(
-        self, mock_get_provider: Mock
-    ) -> None:
-        default_theme = DocumentTheme(
-            external_id="11111111-2222-3333-4444-555555555555",
-            name="Standard",
-            is_default=True,
+        mock_resolve_theme.assert_called_once_with(
+            mock_get_provider.return_value, company
         )
-        mock_get_provider.return_value.list_document_themes.return_value = [
-            default_theme
-        ]
-        stale_theme_id = UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
-
-        selected = Command._resolve_sales_branding_theme(stale_theme_id)
-
-        self.assertEqual(selected, default_theme)
-
-    @patch("apps.workflow.management.commands.xero.get_provider")
-    def test_resolve_sales_branding_theme_requires_one_default(
-        self, mock_get_provider: Mock
-    ) -> None:
-        custom_theme = DocumentTheme(
-            external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
-            name="Custom",
-            is_default=False,
+        self.assertEqual(
+            company.save.call_args_list[-1].kwargs["update_fields"],
+            ["xero_shortcode", "xero_payroll_calendar_id"],
         )
-        default_themes = [
-            DocumentTheme(
-                external_id="11111111-2222-3333-4444-555555555555",
-                name="Default One",
-                is_default=True,
-            ),
-            DocumentTheme(
-                external_id="66666666-7777-8888-9999-000000000000",
-                name="Default Two",
-                is_default=True,
-            ),
-        ]
-
-        for themes in ([custom_theme], default_themes):
-            with self.subTest(default_count=sum(theme.is_default for theme in themes)):
-                mock_get_provider.return_value.list_document_themes.return_value = (
-                    themes
-                )
-                with self.assertRaisesMessage(
-                    CommandError,
-                    "Xero must return exactly one default branding theme",
-                ):
-                    Command._resolve_sales_branding_theme(None)
 
     def test_removed_create_missing_xero_items_flag_is_rejected(self):
         parser = Command().create_parser("manage.py", "xero")
diff --git a/apps/workflow/views/xero/xero_base_manager.py b/apps/workflow/views/xero/xero_base_manager.py
index a2f1d130e..186534a67 100644
--- a/apps/workflow/views/xero/xero_base_manager.py
+++ b/apps/workflow/views/xero/xero_base_manager.py
@@ -7,6 +7,9 @@
 
 # Import models used in type hints or logic
 from apps.job.models import Job
+from apps.workflow.accounting.document_theme_service import (
+    resolve_and_persist_sales_branding_theme,
+)
 from apps.workflow.accounting.registry import get_provider
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
@@ -94,13 +97,19 @@ def _get_account_code(self, account_name: str = "Sales") -> str | None:
         """
         return self.provider.get_account_code(account_name)
 
-    @staticmethod
-    def get_xero_sales_branding_theme_id() -> str | None:
-        """Return the configured Xero theme used for sales documents."""
-        theme_id = CompanyDefaults.get_solo().xero_sales_branding_theme_id
-        if theme_id is None:
+    def get_xero_sales_branding_theme_id(self) -> str | None:
+        """Return or initialise the Xero theme used for sales documents."""
+        company_defaults = CompanyDefaults.get_solo()
+        theme_id = company_defaults.xero_sales_branding_theme_id
+        if theme_id is not None:
+            return str(theme_id)
+
+        theme = resolve_and_persist_sales_branding_theme(
+            self.provider, company_defaults
+        )
+        if theme is None:
             return None
-        return str(theme_id)
+        return theme.external_id
 
     def validate_company(self):
         """
diff --git a/apps/workflow/views/xero/xero_invoice_manager.py b/apps/workflow/views/xero/xero_invoice_manager.py
index d1686fe15..77bee5ddb 100644
--- a/apps/workflow/views/xero/xero_invoice_manager.py
+++ b/apps/workflow/views/xero/xero_invoice_manager.py
@@ -16,6 +16,7 @@
 from apps.job.models.costing import CostSet
 from apps.job.services.workshop_pdf_service import create_workshop_pdf
 from apps.workflow.accounting.types import DocumentLineItem, InvoicePayload
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.error_persistence import persist_app_error
 
 # Import base class and helpers
@@ -218,8 +219,8 @@ def create_document(
                 return {
                     "success": False,
                     "error": (
-                        "Select a Xero sales branding theme in Company Settings "
-                        "before creating an invoice."
+                        "Xero returned no branding themes. Create a branding "
+                        "theme in Xero before creating an invoice."
                     ),
                     "error_type": "configuration_error",
                     "status": 400,
@@ -324,6 +325,8 @@ def create_document(
                 result_dict["messages"] = messages_list
             return result_dict
 
+        except AlreadyLoggedException:
+            raise
         except Exception as exc:
             persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
diff --git a/apps/workflow/views/xero/xero_quote_manager.py b/apps/workflow/views/xero/xero_quote_manager.py
index bb05743aa..6c1aac429 100644
--- a/apps/workflow/views/xero/xero_quote_manager.py
+++ b/apps/workflow/views/xero/xero_quote_manager.py
@@ -17,6 +17,7 @@
 from apps.accounting.models import Quote
 from apps.job.models.costing import CostSet
 from apps.workflow.accounting.types import DocumentLineItem, QuotePayload
+from apps.workflow.exceptions import AlreadyLoggedException
 from apps.workflow.services.error_persistence import persist_app_error
 
 # Import base class and helpers
@@ -172,8 +173,8 @@ def create_document(self, breakdown: bool = True):
                 return {
                     "success": False,
                     "error": (
-                        "Select a Xero sales branding theme in Company Settings "
-                        "before creating a quote."
+                        "Xero returned no branding themes. Create a branding "
+                        "theme in Xero before creating a quote."
                     ),
                     "error_type": "configuration_error",
                     "status": 400,
@@ -240,6 +241,8 @@ def create_document(self, breakdown: bool = True):
                 "online_url": result.online_url,
             }
 
+        except AlreadyLoggedException:
+            raise
         except Exception as exc:
             persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
diff --git a/docs/client_onboarding.md b/docs/client_onboarding.md
index 991c10352..5ed2eee3c 100644
--- a/docs/client_onboarding.md
+++ b/docs/client_onboarding.md
@@ -92,8 +92,8 @@ The client needs a Xero subscription. DocketWorks handles jobs and delegates inv
 **Sales Branding Theme** (Settings > Invoice settings):
 - Ensure one branding theme contains the terms and conditions required on both
   quotes and invoices
-- Prefer making that theme the Xero default; DocketWorks imports the default
-  during `xero --setup`
+- Prefer making that theme first in Xero's branding-theme order; DocketWorks
+  imports the first theme during `xero --setup`
 - If another theme must remain the Xero default, select the terms-bearing theme
   later in DocketWorks Company Settings
 
@@ -246,9 +246,9 @@ Once the instance is running:
    python manage.py start_xero_sync
    ```
 
-`xero --setup` imports the connected organisation's real default sales branding
-theme. It preserves a previously selected theme when that theme still exists in
-the connected organisation.
+`xero --setup` imports the first sales branding theme returned in the connected
+organisation's Xero order. It preserves a previously selected theme when that
+theme still exists in the connected organisation.
 
 ### 7b. Company Settings
 
diff --git a/docs/instance-setup-demo.md b/docs/instance-setup-demo.md
index fc52d9128..4affd4dc6 100644
--- a/docs/instance-setup-demo.md
+++ b/docs/instance-setup-demo.md
@@ -86,9 +86,9 @@ Upload logos: Admin > Settings > Company > Logo and Logo Wide.
 scripts/server/dw-run.sh <client>-uat python manage.py xero --setup
 ```
 
-`xero --setup` stores the Demo Company's real default sales branding theme. In
-Admin > Settings, change it to a terms-bearing theme if the default is not the
-theme the prospect should see.
+`xero --setup` stores the first sales branding theme in the Demo Company's Xero
+order. In Admin > Settings, change it to a terms-bearing theme if the selected
+theme is not the one the prospect should see.
 
 **Note:** `xero --setup` creates the "Weekly Testing" payroll calendar in the Demo Company if it's missing (a weekly calendar anchored to a **Monday** — Docketworks payroll posting requires Mon→Sun periods). If you ever create one by hand instead (Payroll > Settings > Payroll Calendars), its period **must start on a Monday**; `xero --setup` fails loudly if the calendar it just created came back on any other day.
 
diff --git a/docs/instance-setup-production.md b/docs/instance-setup-production.md
index 146092063..12f1f7e64 100644
--- a/docs/instance-setup-production.md
+++ b/docs/instance-setup-production.md
@@ -65,8 +65,8 @@ scripts/server/dw-run.sh <client>-prod python manage.py xero --setup
 ```
 
 Sets `xero_tenant_id`, `xero_shortcode`, `xero_payroll_calendar_id`, and the
-connected organisation's real default sales branding theme. A valid existing
-custom theme selection is preserved.
+first sales branding theme in the connected organisation's Xero order. A valid
+existing custom theme selection is preserved.
 
 **Requires:** The payroll calendar must already exist in Xero (created during client onboarding Phase 2a).
 
@@ -82,7 +82,7 @@ In Admin > Settings, set all values collected in Phase 1 of client_onboarding.md
 - Google Drive folder IDs (Shared Drive, How We Work, SOPs, Reference Library)
 - Quote template ID and quotes folder ID (if applicable)
 - Xero sales branding theme — select the terms-bearing theme if it is not the
-  Xero default imported by `xero --setup`
+  first theme imported by `xero --setup`
 
 Upload logos: Admin > Settings > Company > Logo and Logo Wide.
 
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index cd77a3915..0ce2be794 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -242,7 +242,8 @@ Configures all required Xero settings in CompanyDefaults:
 1. Sets `xero_tenant_id` from connected organisation
 2. Sets `xero_shortcode` for deep linking
 3. Preserves a live sales branding theme selection or replaces a restored,
-   cross-tenant ID with the destination organisation's real default theme
+   cross-tenant ID with the first theme in the destination organisation's Xero
+   order
 4. Looks up payroll calendar by name and sets `xero_payroll_calendar_id`
 
 **Expected output:**
diff --git a/docs/server_setup.md b/docs/server_setup.md
index 53f70ac26..85f07d15b 100644
--- a/docs/server_setup.md
+++ b/docs/server_setup.md
@@ -213,9 +213,13 @@ For a prospect trying DocketWorks with their own Xero:
    scripts/server/dw-run.sh <name> python manage.py start_xero_sync --entity accounts
    ```
 
-   `xero --setup` stores the connected organisation's real default sales
-   branding theme. In Admin > Settings, select the terms-bearing theme if the
-   organisation uses a different theme for customer documents.
+   `xero --setup` stores the first sales branding theme in the connected
+   organisation's Xero order. In Admin > Settings, select the terms-bearing
+   theme if the organisation uses a different theme for customer documents.
+
+   Existing installations that receive the branding-theme schema migration do
+   not need to rerun setup: their first new quote or invoice selects and stores
+   that same first Xero theme automatically.
 
 5. **Import staff from Xero**
 
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 0dac15b0c..63041b0b6 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -10623,7 +10623,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            document creation is blocked until one is selected.
+            if unset, the first Xero theme is selected automatically when the next
+            sales document is created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -11007,7 +11008,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            document creation is blocked until one is selected.
+            if unset, the first Xero theme is selected automatically when the next
+            sales document is created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -16809,7 +16811,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            document creation is blocked until one is selected.
+            if unset, the first Xero theme is selected automatically when the next
+            sales document is created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
diff --git a/frontend/src/components/SectionForm.vue b/frontend/src/components/SectionForm.vue
index 94c9668d2..a63bff9c1 100644
--- a/frontend/src/components/SectionForm.vue
+++ b/frontend/src/components/SectionForm.vue
@@ -105,14 +105,22 @@
             class="h-9 text-sm rounded-md border border-input bg-background px-3 py-1"
             :class="{
               'bg-gray-100 cursor-not-allowed':
-                field.readOnly || brandingThemesLoading || brandingThemesError,
+                field.readOnly ||
+                brandingThemesLoading ||
+                brandingThemesError ||
+                brandingThemesUnavailable,
             }"
             :data-automation-id="`SectionForm-${section}-field-${field.key}`"
-            :disabled="field.readOnly || brandingThemesLoading || brandingThemesError !== null"
+            :disabled="
+              field.readOnly ||
+              brandingThemesLoading ||
+              brandingThemesError !== null ||
+              brandingThemesUnavailable
+            "
             @change="onBrandingThemeChange(field.key, $event)"
           >
-            <option value="">
-              {{ brandingThemesLoading ? 'Loading Xero branding themes…' : 'No theme selected' }}
+            <option v-if="showBrandingThemePlaceholder" value="" disabled>
+              {{ brandingThemePlaceholder }}
             </option>
             <option v-if="unavailableBrandingThemeId" :value="unavailableBrandingThemeId">
               Unavailable theme ({{ unavailableBrandingThemeId }})
@@ -132,6 +140,13 @@
           >
             {{ brandingThemesError }}
           </p>
+          <p
+            v-else-if="brandingThemesUnavailable"
+            class="text-xs text-amber-700"
+            :data-automation-id="`SectionForm-${section}-field-${field.key}-empty`"
+          >
+            No branding themes are available in the connected Xero organisation.
+          </p>
         </div>
 
         <Textarea
@@ -258,6 +273,13 @@ const brandingThemes = ref<Awaited<ReturnType<typeof api.xero_branding_themes_li
 const brandingThemesLoading = ref(false)
 const brandingThemesError = ref<string | null>(null)
 const brandingThemesLoadAttempted = ref(false)
+const brandingThemesUnavailable = computed(
+  () =>
+    brandingThemesLoadAttempted.value &&
+    !brandingThemesLoading.value &&
+    brandingThemesError.value === null &&
+    brandingThemes.value.length === 0,
+)
 
 const LOGO_ASPECT_RULES: Record<
   string,
@@ -536,6 +558,23 @@ function brandingThemeValue(fieldKey: string): string {
   return typeof value === 'string' ? value : ''
 }
 
+const showBrandingThemePlaceholder = computed(
+  () =>
+    brandingThemesLoading.value ||
+    brandingThemesUnavailable.value ||
+    brandingThemeValue('xero_sales_branding_theme_id') === '',
+)
+
+const brandingThemePlaceholder = computed(() => {
+  if (brandingThemesLoading.value) return 'Loading Xero branding themes…'
+  if (brandingThemesUnavailable.value) return 'No Xero branding themes available'
+  const automaticTheme = brandingThemes.value[0]
+  if (automaticTheme) {
+    return `Not configured — first document will use ${automaticTheme.name}`
+  }
+  return 'Not configured — first document will select a Xero branding theme'
+})
+
 const unavailableBrandingThemeId = computed(() => {
   const configuredId = brandingThemeValue('xero_sales_branding_theme_id')
   if (!configuredId) return null
@@ -545,9 +584,10 @@ const unavailableBrandingThemeId = computed(() => {
 
 function onBrandingThemeChange(fieldKey: string, event: Event) {
   const value = (event.target as HTMLSelectElement).value
+  if (!value) return
   localForm.value = {
     ...localForm.value,
-    [fieldKey]: value || null,
+    [fieldKey]: value,
   }
 }
 
diff --git a/frontend/src/components/__tests__/SectionForm.test.ts b/frontend/src/components/__tests__/SectionForm.test.ts
index 803a2c6b5..3cf5dc971 100644
--- a/frontend/src/components/__tests__/SectionForm.test.ts
+++ b/frontend/src/components/__tests__/SectionForm.test.ts
@@ -106,7 +106,7 @@ describe('SectionForm', () => {
     expect(modelValue.shop_company).toBe('00000000-0000-0000-0000-000000000001')
   })
 
-  it('loads Xero branding themes, identifies the default, and clears to null', async () => {
+  it('shows automatic initialization and allows selecting a live Xero branding theme', async () => {
     settingsFields.splice(0, settingsFields.length, {
       key: 'xero_sales_branding_theme_id',
       label: 'Sales Branding Theme',
@@ -144,17 +144,14 @@ describe('SectionForm', () => {
     expect(selector.element.tagName).toBe('SELECT')
     expect(selector.text()).toContain('Standard (Xero default)')
     expect(selector.text()).toContain('Terms Footer')
+    expect(selector.text()).toContain('Not configured — first document will use Standard')
+    expect(selector.find('option[value=""]').attributes('disabled')).toBeDefined()
     expect(selector.element.closest('label')?.className).toContain('md:col-span-2')
 
     await selector.setValue('33333333-3333-3333-3333-333333333333')
     expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
       { xero_sales_branding_theme_id: '33333333-3333-3333-3333-333333333333' },
     ])
-
-    await selector.setValue('')
-    expect(wrapper.emitted('update:modelValue')?.at(-1)).toEqual([
-      { xero_sales_branding_theme_id: null },
-    ])
   })
 
   it('preserves a configured branding theme that Xero no longer returns', async () => {
@@ -168,7 +165,13 @@ describe('SectionForm', () => {
       icon: 'span',
       readOnly: false,
     })
-    xeroBrandingThemesList.mockResolvedValue([])
+    xeroBrandingThemesList.mockResolvedValue([
+      {
+        branding_theme_id: '22222222-2222-2222-2222-222222222222',
+        name: 'Current Default',
+        is_default: true,
+      },
+    ])
     const unavailableId = '44444444-4444-4444-4444-444444444444'
 
     const wrapper = mount(SectionForm, {
@@ -184,6 +187,39 @@ describe('SectionForm', () => {
     )
     expect((selector.element as HTMLSelectElement).value).toBe(unavailableId)
     expect(selector.text()).toContain(`Unavailable theme (${unavailableId})`)
+    expect((selector.element as HTMLSelectElement).disabled).toBe(false)
+  })
+
+  it('disables the selector when Xero returns no branding themes', async () => {
+    settingsFields.splice(0, settingsFields.length, {
+      key: 'xero_sales_branding_theme_id',
+      label: 'Sales Branding Theme',
+      type: 'xero_branding_theme',
+      required: false,
+      help_text: '',
+      section: 'xero',
+      icon: 'span',
+      readOnly: false,
+    })
+    xeroBrandingThemesList.mockResolvedValue([])
+
+    const wrapper = mount(SectionForm, {
+      props: {
+        section: 'xero',
+        modelValue: { xero_sales_branding_theme_id: null },
+      },
+    })
+    await flushPromises()
+
+    const selector = wrapper.get(
+      '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
+    )
+    expect((selector.element as HTMLSelectElement).disabled).toBe(true)
+    expect(
+      wrapper
+        .get('[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id-empty"]')
+        .text(),
+    ).toContain('No branding themes are available')
   })
 
   it('disables the branding theme selector and explains a Xero loading failure', async () => {
diff --git a/frontend/tests/company-defaults.spec.ts b/frontend/tests/company-defaults.spec.ts
index e61cc3471..ad09715dd 100644
--- a/frontend/tests/company-defaults.spec.ts
+++ b/frontend/tests/company-defaults.spec.ts
@@ -116,12 +116,15 @@ test('test Xero sales branding theme save, reload, and restore', async ({
   test.skip(availableThemeIds.length === 0, 'The connected Xero tenant has no branding themes')
 
   const differentThemeId = availableThemeIds.find((id) => id !== originalValue)
-  const testValue = differentThemeId ?? ''
-  let changed = false
+  const testValue = originalValue === '' ? availableThemeIds[0] : differentThemeId
+  test.skip(
+    testValue === undefined,
+    'The connected Xero tenant has no alternative branding theme to exercise',
+  )
+  if (testValue === undefined) return
 
   try {
     await selector.selectOption(testValue)
-    changed = testValue !== originalValue
     await expect(
       page.locator('[data-automation-id="AdminCompanySectionView-save-button"]'),
     ).toBeEnabled()
@@ -134,7 +137,9 @@ test('test Xero sales branding theme save, reload, and restore', async ({
     await expect(selector).toBeVisible({ timeout: 15000 })
     await expect(selector).toHaveValue(testValue)
   } finally {
-    if (changed) {
+    // A null starting value is an unattended-install state. Selecting the first
+    // live theme legitimately initializes it, so never deliberately restore null.
+    if (originalValue !== '') {
       await page.goto('/admin/company/xero')
       await expect(selector).toBeEnabled({ timeout: 15000 })
       if ((await selector.inputValue()) !== originalValue) {

From 889647d966f5caba09db31b4c84b4c4ba57b24cc Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 14:49:24 +1200
Subject: [PATCH 49/73] fix: configure Xero branding theme during migration

---
 .../accounting/document_theme_service.py      |  48 +--
 apps/workflow/management/commands/xero.py     |   9 +-
 ...nydefaults_xero_sales_branding_theme_id.py |  46 ++-
 apps/workflow/models/company_defaults.py      |   4 +-
 .../tests/test_xero_branding_themes.py        | 302 ++++++++----------
 .../workflow/tests/test_xero_setup_command.py |  18 +-
 apps/workflow/views/xero/xero_base_manager.py |  21 +-
 .../views/xero/xero_invoice_manager.py        |   5 +-
 .../workflow/views/xero/xero_quote_manager.py |   5 +-
 docs/restore-prod-to-nonprod.md               |   4 +
 docs/server_setup.md                          |   7 +-
 frontend/schema.yml                           |  12 +-
 frontend/src/components/SectionForm.vue       |   6 +-
 .../components/__tests__/SectionForm.test.ts  |   4 +-
 frontend/tests/company-defaults.spec.ts       |   4 +-
 15 files changed, 229 insertions(+), 266 deletions(-)

diff --git a/apps/workflow/accounting/document_theme_service.py b/apps/workflow/accounting/document_theme_service.py
index 0e803886b..3dad89dec 100644
--- a/apps/workflow/accounting/document_theme_service.py
+++ b/apps/workflow/accounting/document_theme_service.py
@@ -1,28 +1,25 @@
-"""Selection and persistence of the sales document branding theme."""
+"""Selection of the sales document branding theme."""
 
 from uuid import UUID
 
 from apps.workflow.accounting.provider import AccountingProvider
 from apps.workflow.accounting.types import DocumentTheme
-from apps.workflow.models.company_defaults import CompanyDefaults
 
 
-def resolve_and_persist_sales_branding_theme(
+def resolve_sales_branding_theme(
     provider: AccountingProvider,
-    company_defaults: CompanyDefaults,
+    configured_id: UUID | None,
 ) -> DocumentTheme | None:
-    """Preserve a live selection or persist the provider's first theme.
+    """Preserve a live selection or return the provider's first theme.
 
     Providers return themes in their preferred order. The Xero provider orders
-    them by Xero's ``SortOrder``, so its first item is the valid unattended
-    starting point for an installation that has not selected a theme yet.
+    them by Xero's ``SortOrder``.
     """
     themes = provider.list_document_themes()
     if not themes:
         return None
 
-    configured_id = company_defaults.xero_sales_branding_theme_id
-    selected_theme = next(
+    return next(
         (
             theme
             for theme in themes
@@ -30,36 +27,3 @@ def resolve_and_persist_sales_branding_theme(
         ),
         themes[0],
     )
-    selected_id = UUID(selected_theme.external_id)
-
-    if configured_id == selected_id:
-        return selected_theme
-
-    updated = CompanyDefaults.objects.filter(
-        pk=company_defaults.pk,
-        xero_sales_branding_theme_id=configured_id,
-    ).update(xero_sales_branding_theme_id=selected_id)
-    CompanyDefaults.clear_cache()
-
-    if updated == 1:
-        company_defaults.xero_sales_branding_theme_id = selected_id
-        return selected_theme
-
-    current_id = CompanyDefaults.objects.values_list(
-        "xero_sales_branding_theme_id", flat=True
-    ).get(pk=company_defaults.pk)
-    current_theme = next(
-        (
-            theme
-            for theme in themes
-            if current_id is not None and theme.external_id == str(current_id)
-        ),
-        None,
-    )
-    if current_theme is None:
-        raise ValueError(
-            "The Xero sales branding theme changed while it was being configured."
-        )
-
-    company_defaults.xero_sales_branding_theme_id = current_id
-    return current_theme
diff --git a/apps/workflow/management/commands/xero.py b/apps/workflow/management/commands/xero.py
index 3559793a5..06db25c6d 100644
--- a/apps/workflow/management/commands/xero.py
+++ b/apps/workflow/management/commands/xero.py
@@ -1,4 +1,5 @@
 import datetime
+from uuid import UUID
 
 import requests
 from django.core.cache import cache
@@ -13,7 +14,7 @@
 from apps.accounts.models import Staff
 from apps.timesheet.services import PayrollEmployeeSyncService
 from apps.workflow.accounting.document_theme_service import (
-    resolve_and_persist_sales_branding_theme,
+    resolve_sales_branding_theme,
 )
 from apps.workflow.accounting.registry import get_provider
 from apps.workflow.api.xero.auth import api_client, get_tenant_id, get_valid_token
@@ -503,8 +504,8 @@ def run_setup(self):
         shortcode = org_response.organisations[0].short_code
 
         # Step 5: Select a live sales branding theme for this tenant
-        sales_branding_theme = resolve_and_persist_sales_branding_theme(
-            get_provider(), company
+        sales_branding_theme = resolve_sales_branding_theme(
+            get_provider(), company.xero_sales_branding_theme_id
         )
         if sales_branding_theme is None:
             raise CommandError(
@@ -540,10 +541,12 @@ def run_setup(self):
 
         # Step 7: Save to CompanyDefaults
         company.xero_shortcode = shortcode
+        company.xero_sales_branding_theme_id = UUID(sales_branding_theme.external_id)
         company.xero_payroll_calendar_id = payroll_calendar_id
         company.save(
             update_fields=[
                 "xero_shortcode",
+                "xero_sales_branding_theme_id",
                 "xero_payroll_calendar_id",
             ]
         )
diff --git a/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
index 8e707a010..9d03c45a3 100644
--- a/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
+++ b/apps/workflow/migrations/0011_companydefaults_xero_sales_branding_theme_id.py
@@ -1,8 +1,45 @@
 # Generated by Django 5.2.4 on 2026-07-16 00:00
 
+from uuid import UUID
+
 from django.db import migrations, models
 
 
+def populate_connected_install_theme(apps, _schema_editor):
+    """Backfill connected installs; setup handles unconnected installations."""
+    CompanyDefaults = apps.get_model("workflow", "CompanyDefaults")
+    XeroApp = apps.get_model("workflow", "XeroApp")
+
+    company_defaults = CompanyDefaults.objects.first()
+    if company_defaults is None or company_defaults.xero_tenant_id is None:
+        return
+
+    has_usable_oauth = (
+        XeroApp.objects.filter(is_active=True)
+        .exclude(refresh_token__isnull=True)
+        .exclude(refresh_token="")
+        .exists()
+    )
+    if not has_usable_oauth:
+        return
+
+    from apps.workflow.accounting.document_theme_service import (
+        resolve_sales_branding_theme,
+    )
+    from apps.workflow.accounting.registry import get_provider
+
+    selected_theme = resolve_sales_branding_theme(get_provider(), None)
+    if selected_theme is None:
+        raise RuntimeError(
+            "Xero returned no branding themes while configuring the sales "
+            "branding theme migration."
+        )
+
+    CompanyDefaults.objects.filter(pk=company_defaults.pk).update(
+        xero_sales_branding_theme_id=UUID(selected_theme.external_id)
+    )
+
+
 class Migration(migrations.Migration):
     dependencies = [
         ("workflow", "0010_remove_xeroapp_tenant_id"),
@@ -17,12 +54,15 @@ class Migration(migrations.Migration):
                 help_text=(
                     "Branding theme applied to every quote and sales invoice "
                     "created in Xero. Select a theme containing the required "
-                    "terms and conditions; if unset, the first Xero theme is "
-                    "selected automatically when the next sales document is "
-                    "created."
+                    "terms and conditions; it is configured during Xero setup "
+                    "and required before sales documents can be created."
                 ),
                 null=True,
                 verbose_name="Xero sales branding theme",
             ),
         ),
+        migrations.RunPython(
+            populate_connected_install_theme,
+            migrations.RunPython.noop,
+        ),
     ]
diff --git a/apps/workflow/models/company_defaults.py b/apps/workflow/models/company_defaults.py
index af13a15cd..6b03ba5d5 100644
--- a/apps/workflow/models/company_defaults.py
+++ b/apps/workflow/models/company_defaults.py
@@ -132,8 +132,8 @@ class CompanyDefaults(SingletonModel):
         help_text=(
             "Branding theme applied to every quote and sales invoice created in "
             "Xero. Select a theme containing the required terms and conditions; "
-            "if unset, the first Xero theme is selected automatically when the "
-            "next sales document is created."
+            "it is configured during Xero setup and required before sales "
+            "documents can be created."
         ),
     )
     enable_xero_sync = models.BooleanField(
diff --git a/apps/workflow/tests/test_xero_branding_themes.py b/apps/workflow/tests/test_xero_branding_themes.py
index 968b93ac3..bfc3530df 100644
--- a/apps/workflow/tests/test_xero_branding_themes.py
+++ b/apps/workflow/tests/test_xero_branding_themes.py
@@ -1,9 +1,11 @@
 import uuid
 from datetime import date
 from decimal import Decimal
+from importlib import import_module
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
 
+from django.apps import apps as django_apps
 from django.utils import timezone
 from rest_framework.test import APIClient
 
@@ -11,18 +13,16 @@
 from apps.job.models import Job
 from apps.testing import BaseTestCase
 from apps.workflow.accounting.document_theme_service import (
-    resolve_and_persist_sales_branding_theme,
+    resolve_sales_branding_theme,
 )
 from apps.workflow.accounting.types import (
     DocumentLineItem,
-    DocumentResult,
     DocumentTheme,
     InvoicePayload,
     QuotePayload,
 )
 from apps.workflow.accounting.xero.provider import XeroAccountingProvider
-from apps.workflow.exceptions import AlreadyLoggedException
-from apps.workflow.models import CompanyDefaults
+from apps.workflow.models import CompanyDefaults, XeroApp
 from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
 from apps.workflow.views.xero.xero_view import XeroAuthenticationResult
@@ -142,7 +142,7 @@ def test_list_document_themes_preserves_xero_order_and_default(
 
 
 class XeroBrandingThemeConfigurationTests(BaseTestCase):
-    """An upgraded installation configures its theme before its first write."""
+    """Document creation consumes configuration without changing it."""
 
     def setUp(self) -> None:
         defaults = CompanyDefaults.get_solo()
@@ -163,126 +163,39 @@ def setUp(self) -> None:
         )
         self.job.save(staff=self.test_staff)
 
-    def test_invoice_creation_initialises_first_theme_before_provider_write(
-        self,
-    ) -> None:
-        """A deployment-only upgrade must not require an operator setup command."""
-        manager = XeroInvoiceManager(
-            company=self.company, job=self.job, staff=self.test_staff
-        )
-        manager.provider = Mock()
-        manager.provider.list_document_themes.return_value = [
-            DocumentTheme(
-                external_id=THEME_ID,
-                name="First Xero theme",
-                is_default=False,
-            ),
-            DocumentTheme(
-                external_id="aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
-                name="Later default-labelled theme",
-                is_default=True,
-            ),
-        ]
-        payload = InvoicePayload(
-            client_external_id=str(uuid.uuid4()),
-            company_name=self.company.name,
-            line_items=[],
-            date=date(2026, 7, 16),
-            due_date=date(2026, 7, 16),
-            document_theme_external_id=THEME_ID,
-        )
-        manager.provider.create_invoice.return_value = DocumentResult(
-            success=False,
-            error="Stop after observing the outbound payload",
-            status_code=400,
-        )
-
-        with patch.object(manager, "build_payload", return_value=payload) as build:
-            result = manager.create_document(total_amount=Decimal("100"))
-
-        self.assertFalse(result["success"])
-        self.assertEqual(result["status"], 400)
-        build.assert_called_once_with(
-            Decimal("100"), document_theme_external_id=THEME_ID
-        )
-        manager.provider.create_invoice.assert_called_once_with(payload)
-        self.assertEqual(
-            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
-            uuid.UUID(THEME_ID),
-        )
-
-    def test_quote_creation_initialises_first_theme_before_provider_write(self) -> None:
-        """Quote creation shares the unattended upgrade path with invoices."""
-        manager = XeroQuoteManager(
-            company=self.company, job=self.job, staff=self.test_staff
-        )
-        manager.provider = Mock()
-        manager.provider.list_document_themes.return_value = [
-            DocumentTheme(
-                external_id=THEME_ID,
-                name="First Xero theme",
-                is_default=True,
-            )
-        ]
-        payload = QuotePayload(
-            client_external_id=str(uuid.uuid4()),
-            company_name=self.company.name,
-            line_items=[],
-            date=date(2026, 7, 16),
-            expiry_date=date(2026, 8, 15),
-            document_theme_external_id=THEME_ID,
-        )
-        manager.provider.create_quote.return_value = DocumentResult(
-            success=False,
-            error="Stop after observing the outbound payload",
-            status_code=400,
-        )
-
-        with patch.object(manager, "build_payload", return_value=payload) as build:
-            result = manager.create_document()
-
-        self.assertFalse(result["success"])
-        self.assertEqual(result["status"], 400)
-        build.assert_called_once_with(
-            breakdown=True, document_theme_external_id=THEME_ID
-        )
-        manager.provider.create_quote.assert_called_once_with(payload)
-        self.assertEqual(
-            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
-            uuid.UUID(THEME_ID),
-        )
-
-    def test_invoice_creation_stops_when_xero_has_no_themes(self) -> None:
-        """An empty Xero configuration must fail before the invoice write."""
+    def test_invoice_creation_stops_when_theme_is_unconfigured(self) -> None:
+        """An incomplete Xero setup must fail before any invoice API request."""
         manager = XeroInvoiceManager(
             company=self.company, job=self.job, staff=self.test_staff
         )
         manager.provider = Mock()
-        manager.provider.list_document_themes.return_value = []
 
-        result = manager.create_document()
+        result = manager.create_document(total_amount=Decimal("100"))
 
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Xero returned no branding themes", result["error"])
+        self.assertIn("Configure the Xero sales branding theme", result["error"])
+        manager.provider.list_document_themes.assert_not_called()
         manager.provider.create_invoice.assert_not_called()
+        self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
 
-    def test_quote_creation_stops_when_xero_has_no_themes(self) -> None:
-        """An empty Xero configuration must fail before the quote write."""
+    def test_quote_creation_stops_when_theme_is_unconfigured(self) -> None:
+        """An incomplete Xero setup must fail before any quote API request."""
         manager = XeroQuoteManager(
             company=self.company, job=self.job, staff=self.test_staff
         )
         manager.provider = Mock()
-        manager.provider.list_document_themes.return_value = []
 
         result = manager.create_document()
 
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Xero returned no branding themes", result["error"])
+        self.assertIn("Configure the Xero sales branding theme", result["error"])
+        manager.provider.list_document_themes.assert_not_called()
         manager.provider.create_quote.assert_not_called()
+        self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
 
     def test_configured_theme_does_not_add_a_xero_read(self) -> None:
         """Normal document creation must not spend quota revalidating stable config."""
@@ -302,39 +215,15 @@ def test_configured_theme_does_not_add_a_xero_read(self) -> None:
         self.assertEqual(selected_id, THEME_ID)
         manager.provider.list_document_themes.assert_not_called()
 
-    def test_prelogged_theme_lookup_failure_is_not_persisted_twice(self) -> None:
-        """The first-use read must preserve the provider's AppError identity."""
-        manager = XeroQuoteManager(
-            company=self.company, job=self.job, staff=self.test_staff
-        )
-        manager.provider = Mock()
-        prelogged = AlreadyLoggedException(
-            RuntimeError("Xero theme lookup failed"), "app-error-123"
-        )
-        manager.provider.list_document_themes.side_effect = prelogged
-
-        with self.assertRaises(AlreadyLoggedException) as raised:
-            manager.create_document()
-
-        self.assertIs(raised.exception, prelogged)
-        manager.provider.create_quote.assert_not_called()
-
 
 class SalesBrandingThemeResolutionTests(BaseTestCase):
-    """Setup and first-use initialization share one strict selection contract."""
+    """Migration and setup share one provider-order selection contract."""
 
     def setUp(self) -> None:
-        self.defaults = CompanyDefaults.get_solo()
-        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
-            xero_sales_branding_theme_id=None,
-            po_prefix="UNCHANGED-",
-        )
-        CompanyDefaults.clear_cache()
-        self.defaults = CompanyDefaults.get_solo()
         self.provider = Mock()
 
-    def test_unset_configuration_selects_first_theme_and_is_idempotent(self) -> None:
-        """A refactor must not reintroduce default-count checks or broad saves."""
+    def test_unset_configuration_selects_first_theme(self) -> None:
+        """Multiple valid themes must not reintroduce a unique-default requirement."""
         first_theme = DocumentTheme(
             external_id=THEME_ID,
             name="First by Xero sort order",
@@ -349,29 +238,13 @@ def test_unset_configuration_selects_first_theme_and_is_idempotent(self) -> None
             ),
         ]
 
-        first_result = resolve_and_persist_sales_branding_theme(
-            self.provider, self.defaults
-        )
-        second_result = resolve_and_persist_sales_branding_theme(
-            self.provider, self.defaults
-        )
-        self.defaults.refresh_from_db()
+        selected = resolve_sales_branding_theme(self.provider, None)
 
-        self.assertEqual(first_result, first_theme)
-        self.assertEqual(second_result, first_theme)
-        self.assertEqual(
-            self.defaults.xero_sales_branding_theme_id, uuid.UUID(THEME_ID)
-        )
-        self.assertEqual(self.defaults.po_prefix, "UNCHANGED-")
+        self.assertEqual(selected, first_theme)
 
     def test_live_custom_selection_is_preserved(self) -> None:
         """Running setup again must not replace an operator's live custom theme."""
         custom_id = uuid.UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
-        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
-            xero_sales_branding_theme_id=custom_id
-        )
-        CompanyDefaults.clear_cache()
-        self.defaults = CompanyDefaults.get_solo()
         custom_theme = DocumentTheme(
             external_id=str(custom_id), name="Terms", is_default=False
         )
@@ -380,49 +253,134 @@ def test_live_custom_selection_is_preserved(self) -> None:
             custom_theme,
         ]
 
-        selected = resolve_and_persist_sales_branding_theme(
-            self.provider, self.defaults
-        )
+        selected = resolve_sales_branding_theme(self.provider, custom_id)
 
         self.assertEqual(selected, custom_theme)
-        self.assertEqual(
-            CompanyDefaults.get_solo().xero_sales_branding_theme_id, custom_id
-        )
 
     def test_stale_selection_is_replaced_by_first_live_theme(self) -> None:
         """A restored cross-tenant UUID must not leak into new Xero documents."""
-        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
-            xero_sales_branding_theme_id=uuid.UUID(
-                "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
-            )
-        )
-        CompanyDefaults.clear_cache()
-        self.defaults = CompanyDefaults.get_solo()
+        stale_id = uuid.UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
         first_theme = DocumentTheme(
             external_id=THEME_ID, name="Destination theme", is_default=True
         )
         self.provider.list_document_themes.return_value = [first_theme]
 
-        selected = resolve_and_persist_sales_branding_theme(
-            self.provider, self.defaults
-        )
+        selected = resolve_sales_branding_theme(self.provider, stale_id)
 
         self.assertEqual(selected, first_theme)
-        self.assertEqual(
-            CompanyDefaults.get_solo().xero_sales_branding_theme_id,
-            uuid.UUID(THEME_ID),
-        )
 
     def test_empty_theme_list_leaves_configuration_unset(self) -> None:
         """No arbitrary UUID may be invented when the connected tenant has no theme."""
         self.provider.list_document_themes.return_value = []
 
-        selected = resolve_and_persist_sales_branding_theme(
-            self.provider, self.defaults
-        )
+        selected = resolve_sales_branding_theme(self.provider, None)
 
         self.assertIsNone(selected)
-        self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
+
+
+class SalesBrandingThemeMigrationTests(BaseTestCase):
+    """The data migration configures only genuinely connected installations."""
+
+    def setUp(self) -> None:
+        self.defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(
+            xero_tenant_id="tenant-123",
+            xero_sales_branding_theme_id=None,
+            po_prefix="UNCHANGED-",
+        )
+        CompanyDefaults.clear_cache()
+        XeroApp.objects.create(
+            label="Migration test",
+            client_id="migration-client-id",
+            client_secret="migration-client-secret",
+            redirect_uri="https://example.test/xero/callback/",
+            is_active=True,
+            refresh_token="migration-refresh-token",
+        )
+        self.migration = import_module(
+            "apps.workflow.migrations."
+            "0011_companydefaults_xero_sales_branding_theme_id"
+        )
+
+    @patch("apps.workflow.accounting.registry.get_provider")
+    @patch(
+        "apps.workflow.accounting.document_theme_service."
+        "resolve_sales_branding_theme"
+    )
+    def test_connected_install_is_backfilled_without_broad_save(
+        self,
+        mock_resolve_theme: Mock,
+        mock_get_provider: Mock,
+    ) -> None:
+        """Existing deployments must be ready before services restart."""
+        selected_theme = DocumentTheme(
+            external_id=THEME_ID,
+            name="First Xero theme",
+            is_default=True,
+        )
+        mock_resolve_theme.return_value = selected_theme
+
+        self.migration.populate_connected_install_theme(django_apps, Mock())
+        self.defaults.refresh_from_db()
+
+        mock_resolve_theme.assert_called_once_with(mock_get_provider.return_value, None)
+        self.assertEqual(
+            self.defaults.xero_sales_branding_theme_id,
+            uuid.UUID(THEME_ID),
+        )
+        self.assertEqual(self.defaults.po_prefix, "UNCHANGED-")
+
+    @patch(
+        "apps.workflow.accounting.document_theme_service."
+        "resolve_sales_branding_theme"
+    )
+    def test_unconnected_install_is_left_for_xero_setup(
+        self, mock_resolve_theme: Mock
+    ) -> None:
+        """Fresh and scrubbed installs have no durable OAuth token at migrate time."""
+        XeroApp.objects.filter(is_active=True).update(refresh_token=None)
+
+        self.migration.populate_connected_install_theme(django_apps, Mock())
+        self.defaults.refresh_from_db()
+
+        mock_resolve_theme.assert_not_called()
+        self.assertIsNone(self.defaults.xero_sales_branding_theme_id)
+
+    @patch(
+        "apps.workflow.accounting.document_theme_service."
+        "resolve_sales_branding_theme"
+    )
+    def test_install_without_tenant_is_left_for_xero_setup(
+        self, mock_resolve_theme: Mock
+    ) -> None:
+        """The migration must not contact Xero before onboarding chooses a tenant."""
+        CompanyDefaults.objects.filter(pk=self.defaults.pk).update(xero_tenant_id=None)
+
+        self.migration.populate_connected_install_theme(django_apps, Mock())
+
+        mock_resolve_theme.assert_not_called()
+
+    @patch("apps.workflow.accounting.registry.get_provider")
+    @patch(
+        "apps.workflow.accounting.document_theme_service."
+        "resolve_sales_branding_theme"
+    )
+    def test_connected_install_without_themes_fails_migration(
+        self,
+        mock_resolve_theme: Mock,
+        _mock_get_provider: Mock,
+    ) -> None:
+        """A connected deployment must not restart with incomplete configuration."""
+        mock_resolve_theme.return_value = None
+
+        with self.assertRaisesRegex(RuntimeError, "returned no branding themes"):
+            self.migration.populate_connected_install_theme(django_apps, Mock())
+
+        self.assertIsNone(
+            CompanyDefaults.objects.values_list(
+                "xero_sales_branding_theme_id", flat=True
+            ).get(pk=self.defaults.pk)
+        )
 
 
 class XeroBrandingThemeAPITests(BaseTestCase):
diff --git a/apps/workflow/tests/test_xero_setup_command.py b/apps/workflow/tests/test_xero_setup_command.py
index 554584700..8e33923b6 100644
--- a/apps/workflow/tests/test_xero_setup_command.py
+++ b/apps/workflow/tests/test_xero_setup_command.py
@@ -3,6 +3,7 @@
 from pathlib import Path
 from types import SimpleNamespace
 from unittest.mock import Mock, patch
+from uuid import UUID
 
 from django.core.management.base import CommandError
 from django.test import TestCase
@@ -174,10 +175,7 @@ def test_skips_destination_items_that_already_exist_by_name(
 
 
 class RunSetupTests(TestCase):
-    @patch(
-        "apps.workflow.management.commands.xero."
-        "resolve_and_persist_sales_branding_theme"
-    )
+    @patch("apps.workflow.management.commands.xero.resolve_sales_branding_theme")
     @patch("apps.workflow.management.commands.xero.get_provider")
     @patch("apps.workflow.management.commands.xero.cache.set")
     @patch("apps.workflow.management.commands.xero.get_payroll_calendars")
@@ -231,12 +229,18 @@ def test_run_setup_always_calls_demo_item_provisioning(
         cmd._ensure_demo_xero_items_exist.assert_called_once_with(
             "Weekly Testing", "tenant-123"
         )
-        mock_resolve_theme.assert_called_once_with(
-            mock_get_provider.return_value, company
+        mock_resolve_theme.assert_called_once_with(mock_get_provider.return_value, None)
+        self.assertEqual(
+            company.xero_sales_branding_theme_id,
+            UUID(selected_theme.external_id),
         )
         self.assertEqual(
             company.save.call_args_list[-1].kwargs["update_fields"],
-            ["xero_shortcode", "xero_payroll_calendar_id"],
+            [
+                "xero_shortcode",
+                "xero_sales_branding_theme_id",
+                "xero_payroll_calendar_id",
+            ],
         )
 
     def test_removed_create_missing_xero_items_flag_is_rejected(self):
diff --git a/apps/workflow/views/xero/xero_base_manager.py b/apps/workflow/views/xero/xero_base_manager.py
index 186534a67..a2f1d130e 100644
--- a/apps/workflow/views/xero/xero_base_manager.py
+++ b/apps/workflow/views/xero/xero_base_manager.py
@@ -7,9 +7,6 @@
 
 # Import models used in type hints or logic
 from apps.job.models import Job
-from apps.workflow.accounting.document_theme_service import (
-    resolve_and_persist_sales_branding_theme,
-)
 from apps.workflow.accounting.registry import get_provider
 from apps.workflow.models import CompanyDefaults
 from apps.workflow.services.error_persistence import persist_app_error
@@ -97,19 +94,13 @@ def _get_account_code(self, account_name: str = "Sales") -> str | None:
         """
         return self.provider.get_account_code(account_name)
 
-    def get_xero_sales_branding_theme_id(self) -> str | None:
-        """Return or initialise the Xero theme used for sales documents."""
-        company_defaults = CompanyDefaults.get_solo()
-        theme_id = company_defaults.xero_sales_branding_theme_id
-        if theme_id is not None:
-            return str(theme_id)
-
-        theme = resolve_and_persist_sales_branding_theme(
-            self.provider, company_defaults
-        )
-        if theme is None:
+    @staticmethod
+    def get_xero_sales_branding_theme_id() -> str | None:
+        """Return the configured Xero theme used for sales documents."""
+        theme_id = CompanyDefaults.get_solo().xero_sales_branding_theme_id
+        if theme_id is None:
             return None
-        return theme.external_id
+        return str(theme_id)
 
     def validate_company(self):
         """
diff --git a/apps/workflow/views/xero/xero_invoice_manager.py b/apps/workflow/views/xero/xero_invoice_manager.py
index 77bee5ddb..3a81e55b6 100644
--- a/apps/workflow/views/xero/xero_invoice_manager.py
+++ b/apps/workflow/views/xero/xero_invoice_manager.py
@@ -219,8 +219,9 @@ def create_document(
                 return {
                     "success": False,
                     "error": (
-                        "Xero returned no branding themes. Create a branding "
-                        "theme in Xero before creating an invoice."
+                        "Configure the Xero sales branding theme by running Xero "
+                        "setup or selecting it in Company Settings before "
+                        "creating an invoice."
                     ),
                     "error_type": "configuration_error",
                     "status": 400,
diff --git a/apps/workflow/views/xero/xero_quote_manager.py b/apps/workflow/views/xero/xero_quote_manager.py
index 6c1aac429..d03664290 100644
--- a/apps/workflow/views/xero/xero_quote_manager.py
+++ b/apps/workflow/views/xero/xero_quote_manager.py
@@ -173,8 +173,9 @@ def create_document(self, breakdown: bool = True):
                 return {
                     "success": False,
                     "error": (
-                        "Xero returned no branding themes. Create a branding "
-                        "theme in Xero before creating a quote."
+                        "Configure the Xero sales branding theme by running Xero "
+                        "setup or selecting it in Company Settings before "
+                        "creating a quote."
                     ),
                     "error_type": "configuration_error",
                     "status": 400,
diff --git a/docs/restore-prod-to-nonprod.md b/docs/restore-prod-to-nonprod.md
index 0ce2be794..bb287b033 100644
--- a/docs/restore-prod-to-nonprod.md
+++ b/docs/restore-prod-to-nonprod.md
@@ -152,6 +152,10 @@ client→company table cutover, Person/link ownership, job and call references,
 merge structure, and persisted terminology. Any mismatch is a migration
 failure; do not continue.
 
+The branding-theme migration deliberately skips a scrubbed restore because its
+Xero OAuth tokens have been removed. The destination theme is populated later
+by the required `xero --setup` step after destination OAuth is connected.
+
 #### Load Company Defaults Fixture
 
 For demo restores only, this replaces your real company name and logos with the
diff --git a/docs/server_setup.md b/docs/server_setup.md
index 85f07d15b..fe4b13fef 100644
--- a/docs/server_setup.md
+++ b/docs/server_setup.md
@@ -217,9 +217,10 @@ For a prospect trying DocketWorks with their own Xero:
    organisation's Xero order. In Admin > Settings, select the terms-bearing
    theme if the organisation uses a different theme for customer documents.
 
-   Existing installations that receive the branding-theme schema migration do
-   not need to rerun setup: their first new quote or invoice selects and stores
-   that same first Xero theme automatically.
+   Existing connected installations do not need to rerun setup when they
+   receive the branding-theme migration: the migration selects and stores the
+   first live Xero theme before services restart. If Xero is unavailable, the
+   migration fails and the deployment must be retried.
 
 5. **Import staff from Xero**
 
diff --git a/frontend/schema.yml b/frontend/schema.yml
index 63041b0b6..d9b4eb343 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -10623,8 +10623,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            if unset, the first Xero theme is selected automatically when the next
-            sales document is created.
+            it is configured during Xero setup and required before sales documents
+            can be created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -11008,8 +11008,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            if unset, the first Xero theme is selected automatically when the next
-            sales document is created.
+            it is configured during Xero setup and required before sales documents
+            can be created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
@@ -16811,8 +16811,8 @@ components:
           title: Xero sales branding theme
           description: Branding theme applied to every quote and sales invoice created
             in Xero. Select a theme containing the required terms and conditions;
-            if unset, the first Xero theme is selected automatically when the next
-            sales document is created.
+            it is configured during Xero setup and required before sales documents
+            can be created.
         enable_xero_sync:
           type: boolean
           description: Gate for Xero sync. Defaults True (prod). Dev fixture sets
diff --git a/frontend/src/components/SectionForm.vue b/frontend/src/components/SectionForm.vue
index a63bff9c1..810d159b5 100644
--- a/frontend/src/components/SectionForm.vue
+++ b/frontend/src/components/SectionForm.vue
@@ -568,11 +568,7 @@ const showBrandingThemePlaceholder = computed(
 const brandingThemePlaceholder = computed(() => {
   if (brandingThemesLoading.value) return 'Loading Xero branding themes…'
   if (brandingThemesUnavailable.value) return 'No Xero branding themes available'
-  const automaticTheme = brandingThemes.value[0]
-  if (automaticTheme) {
-    return `Not configured — first document will use ${automaticTheme.name}`
-  }
-  return 'Not configured — first document will select a Xero branding theme'
+  return 'Xero setup incomplete — select a branding theme'
 })
 
 const unavailableBrandingThemeId = computed(() => {
diff --git a/frontend/src/components/__tests__/SectionForm.test.ts b/frontend/src/components/__tests__/SectionForm.test.ts
index 3cf5dc971..f1dc12adc 100644
--- a/frontend/src/components/__tests__/SectionForm.test.ts
+++ b/frontend/src/components/__tests__/SectionForm.test.ts
@@ -106,7 +106,7 @@ describe('SectionForm', () => {
     expect(modelValue.shop_company).toBe('00000000-0000-0000-0000-000000000001')
   })
 
-  it('shows automatic initialization and allows selecting a live Xero branding theme', async () => {
+  it('shows incomplete Xero setup and allows selecting a live branding theme', async () => {
     settingsFields.splice(0, settingsFields.length, {
       key: 'xero_sales_branding_theme_id',
       label: 'Sales Branding Theme',
@@ -144,7 +144,7 @@ describe('SectionForm', () => {
     expect(selector.element.tagName).toBe('SELECT')
     expect(selector.text()).toContain('Standard (Xero default)')
     expect(selector.text()).toContain('Terms Footer')
-    expect(selector.text()).toContain('Not configured — first document will use Standard')
+    expect(selector.text()).toContain('Xero setup incomplete — select a branding theme')
     expect(selector.find('option[value=""]').attributes('disabled')).toBeDefined()
     expect(selector.element.closest('label')?.className).toContain('md:col-span-2')
 
diff --git a/frontend/tests/company-defaults.spec.ts b/frontend/tests/company-defaults.spec.ts
index ad09715dd..226ef284e 100644
--- a/frontend/tests/company-defaults.spec.ts
+++ b/frontend/tests/company-defaults.spec.ts
@@ -137,8 +137,8 @@ test('test Xero sales branding theme save, reload, and restore', async ({
     await expect(selector).toBeVisible({ timeout: 15000 })
     await expect(selector).toHaveValue(testValue)
   } finally {
-    // A null starting value is an unattended-install state. Selecting the first
-    // live theme legitimately initializes it, so never deliberately restore null.
+    // Null means Xero setup is incomplete. Selecting the first live theme
+    // completes setup, so never deliberately restore the invalid null state.
     if (originalValue !== '') {
       await page.goto('/admin/company/xero')
       await expect(selector).toBeEnabled({ timeout: 15000 })

From 74dff61e7e1612569a5fb762575bde3bb8624660 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 11:32:13 +1200
Subject: [PATCH 50/73] fix(jobs): stop masking job-create errors as timeouts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

create.vue's submit catch swallowed every create-or-navigate failure by
stashing form state to localStorage and calling window.location.reload().
The reload aborted the in-flight navigation and dropped the user on a blank
create page with no error surfaced — a real failure presenting as an E2E
timeout (see crm/phone-call-job-link flake). The four diagnostic statements
after the reload were dead code.

Split submit into two phases:
- create: on failure, toast extractErrorMessage(error) and let the user
  retry (no reload, no permanent-disable state).
- navigate: the job already exists, so a router.push rejection is reported
  as "created but the page did not open", never as a creation failure.

Drop the localStorage round-trip and hasCreationError flag (the flag
permanently disabled the submit button with no reload to reset it). onMounted
no longer restores from localStorage — without a reload the in-memory form
state already persists, so it just resets to a clean form.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/pages/jobs/create.vue | 106 +++++++++++++----------------
 1 file changed, 46 insertions(+), 60 deletions(-)

diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index bed7f4ad4..b644071e9 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -201,10 +201,9 @@
               </button>
               <button
                 type="submit"
-                :disabled="isSubmitting || !canSubmit || hasCreationError"
+                :disabled="isSubmitting || !canSubmit"
                 data-automation-id="JobCreateView-submit"
                 class="px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
-                :class="{ 'bg-red-600 hover:bg-red-700': hasCreationError }"
               >
                 <span v-if="isSubmitting" class="flex items-center">
                   <svg
@@ -250,6 +249,7 @@ import { jobService, type JobCreateData } from '@/services/job.service'
 import { schemas } from '@/api/generated/api'
 import { z } from 'zod'
 import { debugLog } from '@/utils/debug'
+import { extractErrorMessage, createErrorToast, logError } from '@/utils/error-handler'
 
 type CompanySearchResult = z.infer<typeof schemas.CompanySearchResult>
 type CompanyPerson = z.infer<typeof schemas.CompanyPerson>
@@ -316,7 +316,6 @@ const personDisplayName = ref('')
 
 const errors = ref<Record<string, string>>({})
 const isSubmitting = ref(false)
-const hasCreationError = ref(false)
 
 const handleCompanySelection = async (company: CompanySearchResult | null) => {
   debugLog('JobCreateView - handleCompanySelection:', {
@@ -460,36 +459,44 @@ const handleSubmit = async () => {
   toast.info('Creating job…', { id: 'create-job' })
   debugLog('FormData: ', formData.value)
 
+  // Step 1: create the job. A failure here means no job exists — surface it and let the user retry.
+  let result: Awaited<ReturnType<typeof jobService.createJob>>
   try {
-    const result = await jobService.createJob(formData.value)
-
-    if (result.success && result.job_id) {
-      toast.success('Job created!')
-      toast.dismiss('create-job')
-
-      // Redirect to quote tab for fixed price jobs, estimate to t&m jobs
-      const defaultTab = formData.value.pricing_methodology === 'fixed_price' ? 'quote' : 'estimate'
-      await router.push({
-        name: '/jobs/[id]/(index)',
-        params: { id: result.job_id },
-        query: { new: 'true', tab: defaultTab },
-      })
-    } else {
-      throw new Error(result.message || 'Failed to create job')
-    }
+    result = await jobService.createJob(formData.value)
   } catch (error: unknown) {
-    const errorMessage = (error as Error).message || String(error)
-    // Save form data and error state in localStorage, then reload the page
-    localStorage.setItem('jobCreationFormData', JSON.stringify(formData.value))
-    localStorage.setItem('hasJobCreationError', 'true')
-    localStorage.setItem('jobCreationErrorMessage', errorMessage)
-    localStorage.setItem('selectedCompany', JSON.stringify(selectedCompany.value))
-
-    window.location.reload()
-    debugLog('Job creation error:', error)
     toast.dismiss('create-job')
+    logError('job creation', error)
+    toast.error(extractErrorMessage(error), createErrorToast())
+    isSubmitting.value = false
+    return
+  }
+
+  if (!result.success || !result.job_id) {
+    toast.dismiss('create-job')
+    toast.error(result.message || 'Failed to create job', createErrorToast())
+    isSubmitting.value = false
+    return
+  }
+
+  toast.success('Job created!')
+  toast.dismiss('create-job')
 
-    hasCreationError.value = true
+  // Step 2: navigate to the new job. The job already exists — a navigation failure must NOT
+  // read as a creation failure, and must never silently reload (which is what masked the real
+  // error as an E2E timeout).
+  const defaultTab = formData.value.pricing_methodology === 'fixed_price' ? 'quote' : 'estimate'
+  try {
+    await router.push({
+      name: '/jobs/[id]/(index)',
+      params: { id: result.job_id },
+      query: { new: 'true', tab: defaultTab },
+    })
+  } catch (error: unknown) {
+    logError('navigate to created job', error)
+    toast.error(
+      `Job #${result.job_number} was created but the page did not open — find it on the jobs list.`,
+      createErrorToast(),
+    )
     isSubmitting.value = false
   }
 }
@@ -499,36 +506,15 @@ watch(formData.value, () => {
 })
 
 onMounted(() => {
-  const hasError = localStorage.getItem('hasJobCreationError') === 'true'
-  const errorMessage = localStorage.getItem('jobCreationErrorMessage') || 'Unknown error'
-  const storedFormData = localStorage.getItem('jobCreationFormData')
-
-  if (hasError) {
-    formData.value = storedFormData ? JSON.parse(storedFormData) : formData.value
-    selectedCompany.value = localStorage.getItem('selectedCompany')
-      ? JSON.parse(localStorage.getItem('selectedCompany') as string)
-      : null
-    handleCompanySelection(selectedCompany.value)
-    localStorage.removeItem('jobCreationFormData')
-    localStorage.removeItem('hasJobCreationError')
-    localStorage.removeItem('selectedCompany')
-    toast.error('Previous job creation failed', {
-      description: `Page reloaded and state saved. Original error: ${errorMessage}`,
-      dismissible: true,
-    })
-    debugLog('Restored form data after error:', formData.value)
-    debugLog('Restored selected company after error:', selectedCompany.value)
-  } else {
-    formData.value.name = ''
-    formData.value.company_id = ''
-    companyDisplayName.value = ''
-    formData.value.description = ''
-    formData.value.order_number = ''
-    formData.value.notes = ''
-    formData.value.person_id = null
-    formData.value.estimated_materials = 0
-    formData.value.estimated_time = 0
-    formData.value.pricing_methodology = 'time_materials'
-  }
+  formData.value.name = ''
+  formData.value.company_id = ''
+  companyDisplayName.value = ''
+  formData.value.description = ''
+  formData.value.order_number = ''
+  formData.value.notes = ''
+  formData.value.person_id = null
+  formData.value.estimated_materials = 0
+  formData.value.estimated_time = 0
+  formData.value.pricing_methodology = 'time_materials'
 })
 </script>

From eecbdb13f17794b20023b879f65ccf3fd436529c Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 15:22:56 +1200
Subject: [PATCH 51/73] fix(jobs): stop sending display-only person_name in job
 delta
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Changing a job's company cleared the linked person and the autosave delta
included person_name, which the backend correctly rejects with 400
"Unsupported field 'person_name' in delta payload" — person_name is derived
from job.person.name (read_only) and has no writable target. The rejected
save meant waitForAutosave never resolved, surfacing as a 120s E2E timeout
(edit-job-settings › change company) rather than a visible error.

person_name legitimately blanks the displayed person via the optimistic
patch. The bug is only that the two wire-payload builders forwarded it to the
delta. Fix each at source:
- useJobHeaderAutosave saveAdapter: drop person_name from allowedHeaderKeys
  and the company-change re-add; only person_id (the writable field) clears
  the person. Remove the now-dead person_name before-value branch.
- JobSettingsTab saveAdapter: skip display-only keys when building the
  partial payload.

The optimistic display path is untouched, and the backend's strict rejection
remains the loud safety net for any future regression. Adds a regression test
asserting a company-change save omits person_name from the wire.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/job/JobSettingsTab.vue     |   2 +
 .../JobSettingsTab.companyChange.test.ts      | 184 ++++++++++++++++++
 .../src/composables/useJobHeaderAutosave.ts   |   5 -
 3 files changed, 186 insertions(+), 5 deletions(-)
 create mode 100644 frontend/src/components/job/__tests__/JobSettingsTab.companyChange.test.ts

diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index b0604f7c5..dd6ac95a8 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -1283,8 +1283,10 @@ const autosave = createJobAutosave({
         return v
       }
 
+      const DISPLAY_ONLY_JOB_FIELDS = new Set(['person_name'])
       const partialPayload: Record<string, unknown> = {}
       for (const [k, v] of Object.entries(patch)) {
+        if (DISPLAY_ONLY_JOB_FIELDS.has(k)) continue
         partialPayload[k] = normalise(k, v)
       }
 
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.companyChange.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.companyChange.test.ts
new file mode 100644
index 000000000..3ca3f98a6
--- /dev/null
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.companyChange.test.ts
@@ -0,0 +1,184 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mount, flushPromises } from '@vue/test-utils'
+import { defineComponent, h } from 'vue'
+
+const { capturedConfig, updateJobHeaderPartial } = vi.hoisted(() => ({
+  capturedConfig: {
+    value: null as { saveAdapter: (patch: Record<string, unknown>) => unknown } | null,
+  },
+  updateJobHeaderPartial: vi.fn(),
+}))
+
+vi.mock('@/composables/useJobAutosave', () => ({
+  createJobAutosave: (config: { saveAdapter: (patch: Record<string, unknown>) => unknown }) => {
+    capturedConfig.value = config
+    return {
+      queueChange: vi.fn(),
+      queueChanges: vi.fn(),
+      flush: vi.fn(),
+      cancel: vi.fn(),
+      isSaving: { value: false },
+      lastSavedAt: { value: null },
+      error: { value: null },
+      pendingKeys: { value: new Set() },
+      inFlightToken: { value: 0 },
+      hasPending: () => false,
+      getPendingPatch: () => ({}),
+      onBeforeUnloadBind: vi.fn(),
+      onBeforeUnloadUnbind: vi.fn(),
+      onVisibilityBind: vi.fn(),
+      onVisibilityUnbind: vi.fn(),
+      onRouteLeaveBind: vi.fn(() => vi.fn()),
+      clearStatus: vi.fn(),
+    }
+  },
+}))
+
+vi.mock('@/stores/jobs', () => ({
+  useJobsStore: () => ({
+    headersById: {},
+    conflictReloadAtById: {},
+    loadBasicInfo: vi.fn().mockResolvedValue({
+      description: '',
+      delivery_date: '',
+      order_number: '',
+      notes: '',
+    }),
+    getJobById: vi.fn(() => null),
+    getBasicInfoById: vi.fn(() => null),
+    updateDetailedJob: vi.fn(),
+    updateJobHeader: vi.fn(),
+    patchHeader: vi.fn(),
+  }),
+}))
+
+vi.mock('@/api/client', () => ({
+  api: {
+    job_jobs_header_retrieve: vi.fn().mockResolvedValue({
+      job_id: 'job-1',
+      job_number: 101,
+      name: 'Job',
+      company_id: 'company-1',
+      company_name: 'Company One',
+      person_id: 'person-1',
+      person_name: 'Alice',
+      status: 'in_progress',
+      pricing_methodology: 'time_materials',
+      speed_quality_tradeoff: 'normal',
+      fully_invoiced: false,
+      quoted: false,
+      quote_acceptance_date: null,
+      paid: false,
+      price_cap: null,
+      default_xero_pay_item_id: null,
+      default_xero_pay_item_name: null,
+      rdti_type: null,
+      is_urgent: false,
+    }),
+    workflow_xero_pay_items_list: vi.fn().mockResolvedValue([]),
+    companies_jobs_person_retrieve: vi.fn().mockResolvedValue({ id: null, name: null }),
+  },
+}))
+
+vi.mock('@/services/job.service', () => ({
+  jobService: {
+    getStatusChoices: vi.fn().mockResolvedValue({ statuses: { in_progress: 'In Progress' } }),
+    getJobLabourRates: vi.fn().mockResolvedValue([]),
+    updateJobHeaderPartial,
+  },
+}))
+
+vi.mock('vue-router', () => ({
+  useRouter: () => ({ beforeEach: vi.fn(() => vi.fn()) }),
+}))
+
+vi.mock('@/composables/useSaveFeedback', () => ({
+  useSaveFeedback: () => ({
+    pending: vi.fn(),
+    saving: vi.fn(),
+    saved: vi.fn(),
+    error: vi.fn(),
+    clear: vi.fn(),
+  }),
+}))
+
+vi.mock('@/composables/useConcurrencyEvents', () => ({
+  onConcurrencyRetry: vi.fn(() => vi.fn()),
+}))
+
+vi.mock('vue-sonner', () => ({
+  toast: { error: vi.fn(), success: vi.fn() },
+}))
+
+vi.mock('@/utils/debug', () => ({
+  debugLog: vi.fn(),
+}))
+
+import JobSettingsTab from '../JobSettingsTab.vue'
+
+const passthrough = defineComponent({
+  name: 'PassthroughStub',
+  setup(_, { slots }) {
+    return () => h('div', slots.default?.())
+  },
+})
+
+describe('JobSettingsTab company-change autosave', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    updateJobHeaderPartial.mockResolvedValue({
+      success: true,
+      data: {
+        data: {
+          job: {
+            id: 'job-1',
+            company_id: 'company-2',
+            company_name: 'Company Two',
+            person_id: null,
+            person_name: null,
+          },
+        },
+      },
+    })
+  })
+
+  it('never sends person_name on the wire when the company changes', async () => {
+    mount(JobSettingsTab, {
+      props: {
+        jobId: 'job-1',
+        jobNumber: '101',
+        pricingMethodology: 'time_materials',
+        quoted: false,
+        fullyInvoiced: false,
+      },
+      global: {
+        stubs: {
+          Card: passthrough,
+          CardHeader: passthrough,
+          CardTitle: passthrough,
+          CardDescription: passthrough,
+          CardContent: passthrough,
+          RichTextEditor: { template: '<div />' },
+          CompanyLookup: { template: '<div />' },
+          PersonSelector: { template: '<div />' },
+          CreateCompanyModal: { template: '<div />' },
+        },
+      },
+    })
+    await flushPromises()
+
+    expect(capturedConfig.value).not.toBeNull()
+
+    await capturedConfig.value!.saveAdapter({
+      company_id: 'company-2',
+      company_name: 'Company Two',
+      person_id: null,
+      person_name: null,
+    })
+
+    expect(updateJobHeaderPartial).toHaveBeenCalledTimes(1)
+    const payload = updateJobHeaderPartial.mock.calls[0][1] as Record<string, unknown>
+    expect(payload).toMatchObject({ company_id: 'company-2', person_id: null })
+    expect(Object.keys(payload)).not.toContain('person_name')
+  })
+})
diff --git a/frontend/src/composables/useJobHeaderAutosave.ts b/frontend/src/composables/useJobHeaderAutosave.ts
index 3300b75f7..d3c14404f 100644
--- a/frontend/src/composables/useJobHeaderAutosave.ts
+++ b/frontend/src/composables/useJobHeaderAutosave.ts
@@ -147,7 +147,6 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
               'company_id',
               'company_name',
               'person_id',
-              'person_name',
               'job_status',
               'pricing_methodology',
               'quoted',
@@ -172,7 +171,6 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
 
             if ('company_id' in (filteredPatch as Partial<Job>)) {
               payloadJob.person_id = null
-              payloadJob.person_name = null
             }
 
             const fields = Object.keys(payloadJob)
@@ -212,9 +210,6 @@ export function useJobHeaderAutosave(headerRef: Ref<JobHeaderResponse | null>) {
                 case 'person_id':
                   beforeValues[field] = detail?.job?.person_id ?? null
                   break
-                case 'person_name':
-                  beforeValues[field] = detail?.job?.person_name ?? null
-                  break
                 default:
                   beforeValues[field] = detail?.job
                     ? (detail.job as Record<string, unknown>)[field]

From c343e0bfae95d48c11b89b2e36dd772f59a6cbda Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 15:57:15 +1200
Subject: [PATCH 52/73] fix(jobs): block duplicate submit after create succeeds
 but nav fails

Once jobService.createJob returns 201 the job exists. If the subsequent
router.push rejects, the catch reset isSubmitting=false; with the form
untouched canSubmit stayed true, so the submit button re-enabled and a second
click created a duplicate job.

Latch a jobCreated guard on creation success and add it to the submit button's
disable binding, so re-submit is blocked regardless of navigation outcome. The
create-failure resets are untouched (retry there is correct); the guard latches
on success only, so it never blocks a legitimate retry.

Addresses CodeRabbit review on PR #465.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/pages/jobs/create.vue | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index b644071e9..f40314441 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -201,7 +201,7 @@
               </button>
               <button
                 type="submit"
-                :disabled="isSubmitting || !canSubmit"
+                :disabled="isSubmitting || !canSubmit || jobCreated"
                 data-automation-id="JobCreateView-submit"
                 class="px-6 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed transition-colors"
               >
@@ -316,6 +316,7 @@ const personDisplayName = ref('')
 
 const errors = ref<Record<string, string>>({})
 const isSubmitting = ref(false)
+const jobCreated = ref(false)
 
 const handleCompanySelection = async (company: CompanySearchResult | null) => {
   debugLog('JobCreateView - handleCompanySelection:', {
@@ -478,6 +479,7 @@ const handleSubmit = async () => {
     return
   }
 
+  jobCreated.value = true
   toast.success('Job created!')
   toast.dismiss('create-job')
 

From 7ddb211818d318f5c9d7052369fc8dc31619341c Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 16:03:28 +1200
Subject: [PATCH 53/73] fix(jobs): handle resolved router.push navigation
 failures on create
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

router.push resolves with a NavigationFailure (aborted/cancelled/duplicated)
rather than rejecting, so the catch-only handling missed those cases: the flow
fell through with isSubmitting stuck true and no error toast — a navigation
failure masquerading as a hung spinner.

Inspect the resolved result with isNavigationFailure() and route it, alongside
the existing catch for thrown errors, through one reportNavFailure handler
(log, toast, reset isSubmitting). Genuine success still falls through to unmount.

Addresses CodeRabbit review on PR #465.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/pages/jobs/create.vue | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/frontend/src/pages/jobs/create.vue b/frontend/src/pages/jobs/create.vue
index f40314441..979234835 100644
--- a/frontend/src/pages/jobs/create.vue
+++ b/frontend/src/pages/jobs/create.vue
@@ -240,7 +240,7 @@
 
 <script setup lang="ts">
 import { ref, computed, onMounted, nextTick, watch } from 'vue'
-import { useRouter } from 'vue-router'
+import { isNavigationFailure, useRouter } from 'vue-router'
 import AppLayout from '@/components/AppLayout.vue'
 import CompanyLookup from '@/components/CompanyLookup.vue'
 import PersonSelector from '@/components/PersonSelector.vue'
@@ -487,19 +487,25 @@ const handleSubmit = async () => {
   // read as a creation failure, and must never silently reload (which is what masked the real
   // error as an E2E timeout).
   const defaultTab = formData.value.pricing_methodology === 'fixed_price' ? 'quote' : 'estimate'
+  const reportNavFailure = (cause: unknown) => {
+    logError('navigate to created job', cause)
+    toast.error(
+      `Job #${result.job_number} was created but the page did not open — find it on the jobs list.`,
+      createErrorToast(),
+    )
+    isSubmitting.value = false
+  }
   try {
-    await router.push({
+    const failure = await router.push({
       name: '/jobs/[id]/(index)',
       params: { id: result.job_id },
       query: { new: 'true', tab: defaultTab },
     })
+    if (isNavigationFailure(failure)) {
+      reportNavFailure(failure)
+    }
   } catch (error: unknown) {
-    logError('navigate to created job', error)
-    toast.error(
-      `Job #${result.job_number} was created but the page did not open — find it on the jobs list.`,
-      createErrorToast(),
-    )
-    isSubmitting.value = false
+    reportNavFailure(error)
   }
 }
 

From cf9553f82dca58aabb7dd70a2bf6de8d8f3b9739 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 16:28:54 +1200
Subject: [PATCH 54/73] fix(jobs): drop redundant job-person fetch that 404s
 after company change
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

JobSettingsTab's load watcher called GET /api/companies/jobs/{id}/person/
unconditionally, but consumed only .id/.name — both already present on the
JobHeaderResponse it was reacting to (person_id/person_name). When a company
change clears the person, that endpoint 404s (it raises when job.person is
None); Chromium auto-logs the failed load, tripping the E2E rule-30 guard even
though the app catches the 404. The fetch was vestigial (predates the header
carrying person fields).

Read person_id/person_name straight from the header instead, matching the
save/retry paths. No request -> no 404 -> the read-side 404 fallback goes too.

Also completes the useJobsStore mock (patchHeader) in the labourRate and urgent
JobSettingsTab tests; the person block previously swallowed the missing-mock
error inside its try/catch, which this change removes.

Retiring the endpoint itself is a tracked follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../src/components/job/JobSettingsTab.vue     | 49 ++++---------------
 .../JobSettingsTab.labourRate.test.ts         |  1 +
 .../__tests__/JobSettingsTab.urgent.test.ts   |  1 +
 3 files changed, 11 insertions(+), 40 deletions(-)

diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index dd6ac95a8..7f82c2e93 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -845,47 +845,16 @@ watch(
       person_name: localJobData.value.person_name ?? null,
     }
 
-    // Load person information using the job person endpoint
-    // IMPORTANT: Do NOT trigger autosave here - this is just loading initial data
-    try {
-      const personResponse = await api.companies_jobs_person_retrieve({
-        params: { job_id: newJobData.job_id },
+    localJobData.value.person_id = newJobData.person_id ?? null
+    localJobData.value.person_name = newJobData.person_name ?? null
+    personDisplayValue.value = newJobData.person_name ?? ''
+    serverBaseline.value.person_id = newJobData.person_id ?? null
+    serverBaseline.value.person_name = newJobData.person_name ?? null
+    if (newJobData.job_id) {
+      jobsStore.patchHeader(newJobData.job_id, {
+        person_id: newJobData.person_id ?? null,
+        person_name: newJobData.person_name ?? null,
       })
-      if (personResponse) {
-        // The response is a single person object
-        localJobData.value.person_id = personResponse.id
-        localJobData.value.person_name = personResponse.name
-        personDisplayValue.value = personResponse.name || ''
-        serverBaseline.value.person_id = personResponse.id ?? null
-        serverBaseline.value.person_name = personResponse.name ?? null
-        if (newJobData.job_id) {
-          jobsStore.patchHeader(newJobData.job_id, {
-            person_id: personResponse.id ?? null,
-            person_name: personResponse.name ?? null,
-          })
-        }
-      }
-    } catch (error: unknown) {
-      // Handle 404 when no person is associated with the job - simply ignore
-      const axiosError = error as { response?: { status?: number } }
-      if (axiosError?.response?.status === 404) {
-        debugLog('No person associated with this job - ignoring 404')
-        localJobData.value.person_id = null
-        localJobData.value.person_name = null
-        personDisplayValue.value = ''
-        serverBaseline.value.person_id = null
-        serverBaseline.value.person_name = null
-        if (newJobData.job_id) {
-          jobsStore.patchHeader(newJobData.job_id, {
-            person_id: null,
-            person_name: null,
-          })
-        }
-      } else {
-        console.error('Failed to load person information:', error)
-        toast.error('Failed to load person information')
-        personDisplayValue.value = ''
-      }
     }
 
     await nextTick()
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
index a74b3529f..c36477793 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.labourRate.test.ts
@@ -44,6 +44,7 @@ vi.mock('@/stores/jobs', () => ({
     getBasicInfoById: vi.fn(() => null),
     updateDetailedJob: vi.fn(),
     updateJobHeader: vi.fn(),
+    patchHeader: vi.fn(),
   }),
 }))
 
diff --git a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
index da7b5e2aa..489d43122 100644
--- a/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
+++ b/frontend/src/components/job/__tests__/JobSettingsTab.urgent.test.ts
@@ -42,6 +42,7 @@ vi.mock('@/stores/jobs', () => ({
     getBasicInfoById: vi.fn(() => null),
     updateDetailedJob: vi.fn(),
     updateJobHeader: vi.fn(),
+    patchHeader: vi.fn(),
   }),
 }))
 

From 3882ca537abbc0769ad651199791cec002e0dd3e Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 16:53:30 +1200
Subject: [PATCH 55/73] fix(crm): stop stale people-list fetch clobbering a
 newer search
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

loadPeople() applied every response unconditionally, so concurrent calls
raced: creating a person triggers an unfiltered refetch, and searching
triggers a filtered one. When the slower unfiltered response resolved last it
overwrote the filtered search result, hiding the just-created person — a
timing-dependent flake (E2E crm/people › link lifecycle).

Add a monotonic request token so only the most recently started loadPeople
applies its response; stale responses are dropped regardless of resolution
order. Adds a regression test resolving the two calls out of order.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/pages/crm/people/(index).vue     |  7 ++-
 .../people/__tests__/people-directory.test.ts | 43 +++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/frontend/src/pages/crm/people/(index).vue b/frontend/src/pages/crm/people/(index).vue
index b857077ae..3927fbb31 100644
--- a/frontend/src/pages/crm/people/(index).vue
+++ b/frontend/src/pages/crm/people/(index).vue
@@ -177,23 +177,28 @@ const showCreate = ref(false)
 const selectedCompany = ref<Company | null>(null)
 const selectedCompanyName = ref('')
 
+let loadRequestSeq = 0
+
 async function loadPeople(): Promise<void> {
+  const seq = ++loadRequestSeq
   loading.value = true
   error.value = null
   try {
     const response = await api.people_list({
       queries: { page: page.value, page_size: 50, q: query.value || undefined },
     })
+    if (seq !== loadRequestSeq) return
     people.value = response.results
     count.value = response.count
     totalPages.value = response.total_pages
     page.value = response.page
   } catch (err) {
+    if (seq !== loadRequestSeq) return
     people.value = []
     error.value = err instanceof Error ? err.message : 'Failed to load people'
     toast.error('Failed to load people')
   } finally {
-    loading.value = false
+    if (seq === loadRequestSeq) loading.value = false
   }
 }
 
diff --git a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
index e8560c7df..61c8b699c 100644
--- a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
+++ b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
@@ -59,4 +59,47 @@ describe('people directory', () => {
       queries: { page: 1, page_size: 50, q: 'Jane' },
     })
   })
+
+  it('ignores a stale unfiltered response that resolves after a newer search', async () => {
+    const searchResponse = {
+      results: [
+        {
+          id: '33333333-3333-4333-8333-333333333333',
+          name: 'Bob Searched',
+          email: 'bob@example.com',
+          primary_phone: '021 555 0200',
+          companies: [
+            { company_id: '44444444-4444-4444-8444-444444444444', company_name: 'Search Co' },
+          ],
+        },
+      ],
+      count: 1,
+      page: 1,
+      page_size: 50,
+      total_pages: 1,
+    }
+
+    function defer<T>() {
+      let resolve!: (value: T) => void
+      const promise = new Promise<T>((r) => (resolve = r))
+      return { promise, resolve }
+    }
+    const full = defer<typeof response>()
+    const search = defer<typeof response>()
+    vi.mocked(api.people_list).mockImplementation((opts) =>
+      opts.queries?.q === undefined ? full.promise : search.promise,
+    )
+
+    const wrapper = mount(PeopleDirectory)
+    await wrapper.find('[data-automation-id="PeopleDirectory-search"]').setValue('Bob')
+    await wrapper.find('[data-automation-id="PeopleDirectory-search"]').trigger('keydown.enter')
+
+    search.resolve(searchResponse)
+    await flushPromises()
+    full.resolve(response)
+    await flushPromises()
+
+    expect(wrapper.text()).toContain('Bob Searched')
+    expect(wrapper.text()).not.toContain('Jane Doe')
+  })
 })

From 1f0360cf4b0b1a198ed19bd8dc23b28be25d3c27 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 17:10:34 +1200
Subject: [PATCH 56/73] refactor(jobs): immutable ref updates in settings-tab
 person hydration

Replace direct property mutation of localJobData/serverBaseline with spread
replacements, per the frontend immutable-update convention (rules 8-9).
personDisplayValue stays a direct primitive assignment.

Addresses CodeRabbit review on PR #465.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 frontend/src/components/job/JobSettingsTab.vue | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/frontend/src/components/job/JobSettingsTab.vue b/frontend/src/components/job/JobSettingsTab.vue
index 7f82c2e93..6baa03bcd 100644
--- a/frontend/src/components/job/JobSettingsTab.vue
+++ b/frontend/src/components/job/JobSettingsTab.vue
@@ -845,11 +845,17 @@ watch(
       person_name: localJobData.value.person_name ?? null,
     }
 
-    localJobData.value.person_id = newJobData.person_id ?? null
-    localJobData.value.person_name = newJobData.person_name ?? null
+    localJobData.value = {
+      ...localJobData.value,
+      person_id: newJobData.person_id ?? null,
+      person_name: newJobData.person_name ?? null,
+    }
     personDisplayValue.value = newJobData.person_name ?? ''
-    serverBaseline.value.person_id = newJobData.person_id ?? null
-    serverBaseline.value.person_name = newJobData.person_name ?? null
+    serverBaseline.value = {
+      ...serverBaseline.value,
+      person_id: newJobData.person_id ?? null,
+      person_name: newJobData.person_name ?? null,
+    }
     if (newJobData.job_id) {
       jobsStore.patchHeader(newJobData.job_id, {
         person_id: newJobData.person_id ?? null,

From 913cd92777e76bfbec169304ad5b1513eb389b4b Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:03:56 +1200
Subject: [PATCH 57/73] fix(crm): restore person edit + delete/archive in the
 Select-Person modal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first-class people cutover replaced ContactSelectionModal with
PersonSelectionModal and silently dropped the per-person Edit (pencil) and
Delete (trash) hover actions, the delete-confirmation overlay, the edit-mode
form, and the composable's edit/delete methods — a regression vs production.

Restore them, adapting production's copy (contact->person, client->company):
- usePersonManagement: startEditPerson/cancelEdit/updatePerson (change-detected
  across the identity, company-link, and phone contact-method endpoints) plus
  deletePerson (unlink, surfacing the backend 400 phone-conflict detail).
- PersonSelectionModal: Edit/Delete hover buttons, delete-confirm overlay, amber
  editing state, edit-mode title/label; new props/emits + automation ids.
- PersonSelector: wire emits, prod-aligned toasts.
- person_service.remove_company_link: archive the Person (is_active=False) when
  its last active company link is removed, so no searchable orphans remain.

Also institutionalise the gate that would have caught this: a "No feature
removal" rule in CLAUDE.md requiring a Feature Parity Inventory before any
rewrite/cutover, plus a docs/plans/_template.md scaffold.

Tests: backend sole-company-archive case; modal edit/delete unit tests; e2e
edit + delete flows on the job-settings person selector.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                                     |   4 +
 apps/company/services/person_service.py       |   5 +
 apps/company/tests/test_person_api.py         |  15 ++
 docs/plans/_template.md                       |  31 +++
 .../src/components/PersonSelectionModal.vue   | 104 +++++++++-
 frontend/src/components/PersonSelector.vue    |  43 +++++
 ...PersonSelectionModal.phoneConflict.test.ts |  86 +++++++++
 .../src/composables/usePersonManagement.ts    | 181 ++++++++++++++++++
 frontend/tests/job/edit-job-settings.spec.ts  | 149 ++++++++++++++
 9 files changed, 614 insertions(+), 4 deletions(-)
 create mode 100644 docs/plans/_template.md

diff --git a/CLAUDE.md b/CLAUDE.md
index e8acea722..fdd93400e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,6 +25,10 @@ Examples:
 - If asked whether a bug is fixed, verify the behavior that matters to the user, not only that a unit test passed.
 - If asked to review a proposal, assess whether it solves the problem and what risks remain, not only whether the text is internally consistent.
 
+## No feature removal
+
+Replacing or rewriting any component, page, model, or endpoint requires a **Feature Parity Inventory** first: enumerate every capability the old version exposed (buttons, actions, fields, shortcuts, edge cases — sourced from its template/emits, its tests, E2E specs, ADRs) with a keep/drop/defer decision for each. Default is keep; dropping a feature needs explicit user sign-off. A silently dropped capability is a release-blocking regression. Plans for such work must carry the inventory as a section (see the template in `docs/plans/`).
+
 ## Tokens are precious
 
 Every single line in CLAUDE.md will make agents worse at unrelated tasks.  Every single word must have significant lasting benefit or it must not be added.  Do not repeat yourself, do not add lines even if you screw up, if it is unlikely a similar screw up will happen again.  Always give the most general fix, to increase the likelihood the guidence is future-directed.
diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index 1420096d0..ca4e7b2c8 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -353,4 +353,9 @@ def remove_company_link(*, person: Person, company: Company) -> None:
         link.is_active = False
         link.is_primary = False
         link.save(update_fields=["is_active", "is_primary", "updated_at"])
+        if not projected_company_ids and person.is_active:
+            # Removing the person's last active company link archives the person
+            # so they no longer surface in people search as an orphan.
+            person.is_active = False
+            person.save(update_fields=["is_active", "updated_at"])
         _schedule_person_phone_rematch(person)
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index c61c84680..bdf3dec03 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -197,9 +197,24 @@ def test_removing_link_preserves_person_and_other_company(self) -> None:
 
         self.assertEqual(response.status_code, 204)
         self.assertTrue(Person.objects.filter(id=person.id).exists())
+        person.refresh_from_db()
+        self.assertTrue(person.is_active)
         other.refresh_from_db()
         self.assertTrue(other.is_active)
 
+    def test_removing_last_link_archives_person(self) -> None:
+        """Unlinking a person's only employer archives the now-orphaned identity."""
+        person = self._person(company=self.company_a)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        self.assertEqual(response.status_code, 204)
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
     def test_removing_link_is_blocked_when_phone_would_cross_companies(self) -> None:
         """Relationship edits must not create the duplicate-phone problem they manage."""
         person = self._person(company=self.company_a)
diff --git a/docs/plans/_template.md b/docs/plans/_template.md
new file mode 100644
index 000000000..827f637a9
--- /dev/null
+++ b/docs/plans/_template.md
@@ -0,0 +1,31 @@
+# Title
+
+## Context
+
+Why this change is being made — the problem or need it addresses, what prompted it, and the intended outcome.
+
+## Feature Parity Inventory
+
+**Required for any work that replaces or rewrites an existing component, page, model, or endpoint. Delete this
+section only if the change adds net-new behaviour that replaces nothing.**
+
+Enumerate every capability the OLD version exposed (buttons, actions, fields, shortcuts, edge cases — sourced
+from its template/emits, its tests, E2E specs, ADRs). One row per capability. Default decision is **keep**;
+**drop** requires explicit user sign-off; **defer** requires a ticket.
+
+| Old capability | New location | Status (keep / drop+signoff / defer) |
+|---|---|---|
+| … | … | … |
+
+## Approach
+
+The recommended implementation. Name the critical files to be modified. For a pattern repeated across many
+files, describe it once with a few representative paths.
+
+## Files to modify
+
+- …
+
+## Verification
+
+How to test end-to-end: run the code / drive the real flow, plus the tests to run.
diff --git a/frontend/src/components/PersonSelectionModal.vue b/frontend/src/components/PersonSelectionModal.vue
index 03095ea9c..24e7a404b 100644
--- a/frontend/src/components/PersonSelectionModal.vue
+++ b/frontend/src/components/PersonSelectionModal.vue
@@ -81,6 +81,48 @@
         >
           <!-- Existing People Section -->
           <div class="people-section flex-1 min-h-0 flex flex-col relative">
+            <!-- Delete Confirmation Overlay -->
+            <div
+              v-if="showDeleteConfirm"
+              class="absolute inset-0 bg-white/95 z-30 flex items-center justify-center rounded-lg"
+            >
+              <div class="text-center p-6 max-w-sm">
+                <div
+                  class="w-12 h-12 rounded-full bg-red-100 flex items-center justify-center mx-auto mb-4"
+                >
+                  <AlertTriangle class="w-6 h-6 text-red-600" />
+                </div>
+                <h4 class="text-lg font-semibold text-gray-900 mb-2">Delete Person?</h4>
+                <p class="text-sm text-gray-600 mb-4">
+                  Are you sure you want to remove
+                  <strong>{{ personToDelete?.person_name }}</strong
+                  >? The person will be marked as inactive.
+                </p>
+                <p
+                  v-if="personToDelete?.is_primary"
+                  class="text-sm text-amber-600 font-medium mb-4"
+                >
+                  This is the primary person for this company.
+                </p>
+                <div class="flex gap-3 justify-center">
+                  <button
+                    class="px-4 py-2 text-sm font-medium text-gray-700 bg-white border border-gray-300 rounded-md hover:bg-gray-50"
+                    data-automation-id="PersonSelectionModal-cancel-delete"
+                    @click="cancelDelete"
+                  >
+                    Cancel
+                  </button>
+                  <button
+                    class="px-4 py-2 text-sm font-medium text-white bg-red-600 rounded-md hover:bg-red-700"
+                    data-automation-id="PersonSelectionModal-confirm-delete"
+                    @click="executeDelete"
+                  >
+                    Delete
+                  </button>
+                </div>
+              </div>
+            </div>
+
             <div v-if="isLoading" class="flex-1 flex items-center justify-center">
               <div class="text-center">
                 <div
@@ -109,7 +151,11 @@
                       :class="{
                         'ring-2 ring-blue-500 bg-blue-50 border-blue-500 shadow-md mt-1':
                           selectedPerson?.person_id === person.person_id,
-                        'hover:bg-gray-50': selectedPerson?.person_id !== person.person_id,
+                        'ring-2 ring-amber-500 bg-amber-50 border-amber-500':
+                          editingPerson?.person_id === person.person_id,
+                        'hover:bg-gray-50':
+                          selectedPerson?.person_id !== person.person_id &&
+                          editingPerson?.person_id !== person.person_id,
                       }"
                       @click="selectPerson(person)"
                     >
@@ -180,6 +226,22 @@
                         >
                           Select
                         </button>
+                        <button
+                          class="p-1.5 text-xs font-medium bg-gray-600 text-white rounded-md shadow-sm hover:bg-gray-700 transition-colors"
+                          data-automation-id="PersonSelectionModal-edit-button"
+                          @click.stop="emit('edit-person', person)"
+                          title="Edit person"
+                        >
+                          <PencilLine class="w-3.5 h-3.5" />
+                        </button>
+                        <button
+                          class="p-1.5 text-xs font-medium bg-red-600 text-white rounded-md shadow-sm hover:bg-red-700 transition-colors"
+                          data-automation-id="PersonSelectionModal-delete-button"
+                          @click.stop="confirmDeletePerson(person)"
+                          title="Delete person"
+                        >
+                          <Trash2 class="w-3.5 h-3.5" />
+                        </button>
                       </div>
                     </div>
                   </div>
@@ -201,7 +263,17 @@
             class="create-person-section w-full xl:w-80 2xl:w-96 flex-shrink-0 border-t xl:border-t-0 xl:border-l border-gray-200 pt-4 xl:pt-0 xl:pl-6"
           >
             <div class="flex items-center justify-between mb-4">
-              <h4 class="section-title text-sm font-semibold text-gray-900">Create New Person</h4>
+              <h4 class="section-title text-sm font-semibold text-gray-900">
+                {{ isEditing ? 'Edit Person' : 'Create New Person' }}
+              </h4>
+              <button
+                v-if="isEditing"
+                type="button"
+                class="text-xs text-gray-500 hover:text-gray-700 underline"
+                @click="emit('cancel-edit')"
+              >
+                Cancel edit
+              </button>
             </div>
 
             <div class="space-y-4">
@@ -295,7 +367,7 @@
             @click="handleSave"
             :disabled="isLoading || !localPersonForm.name.trim()"
           >
-            {{ isLoading ? 'Saving...' : 'Create Person' }}
+            {{ isLoading ? 'Saving...' : isEditing ? 'Update Person' : 'Create Person' }}
           </button>
         </DialogFooter>
       </div>
@@ -305,7 +377,7 @@
 
 <script setup lang="ts">
 import { ref, watch, reactive } from 'vue'
-import { Users } from 'lucide-vue-next'
+import { Users, PencilLine, Trash2, AlertTriangle } from 'lucide-vue-next'
 import { schemas } from '../api/generated/api'
 import { z } from 'zod'
 import type { PersonFormData } from '@/composables/usePersonManagement'
@@ -332,6 +404,8 @@ const props = defineProps<{
   isLoading: boolean
   personForm: PersonFormData
   phoneOwnership: PhoneOwnership | null
+  editingPerson: CompanyPerson | null
+  isEditing: boolean
 }>()
 const emit = defineEmits<{
   close: []
@@ -340,6 +414,9 @@ const emit = defineEmits<{
   'link-person': [person: PhonePersonMatch]
   'create-separate-person': []
   'update:personForm': [personForm: PersonFormData]
+  'edit-person': [person: CompanyPerson]
+  'delete-person': [person: CompanyPerson]
+  'cancel-edit': []
 }>()
 
 const nameError = ref('')
@@ -389,6 +466,25 @@ const selectPerson = (person: CompanyPerson) => {
   emit('select-person', person)
 }
 
+// Delete confirmation state
+const personToDelete = ref<CompanyPerson | null>(null)
+const showDeleteConfirm = ref(false)
+
+const confirmDeletePerson = (person: CompanyPerson) => {
+  personToDelete.value = person
+  showDeleteConfirm.value = true
+}
+
+const cancelDelete = () => {
+  personToDelete.value = null
+  showDeleteConfirm.value = false
+}
+
+const executeDelete = () => {
+  if (personToDelete.value) emit('delete-person', personToDelete.value)
+  cancelDelete()
+}
+
 const matchAction = (match: PhonePersonMatch): string => {
   const link = match.company_links.find((item) => item.company_id === props.companyId)
   if (link?.is_active) return 'Select person'
diff --git a/frontend/src/components/PersonSelector.vue b/frontend/src/components/PersonSelector.vue
index 461f9a044..b43237048 100644
--- a/frontend/src/components/PersonSelector.vue
+++ b/frontend/src/components/PersonSelector.vue
@@ -54,12 +54,17 @@
     :is-loading="isLoading"
     :person-form="personForm"
     :phone-ownership="phoneOwnership"
+    :editing-person="editingPerson"
+    :is-editing="isEditing"
     @close="closeModal"
     @select-person="selectExistingPerson"
     @save-person="handleSavePerson"
     @link-person="handleLinkPerson"
     @create-separate-person="handleCreateSeparatePerson"
     @update:person-form="updatePersonForm"
+    @edit-person="handleEditPerson"
+    @delete-person="handleDeletePerson"
+    @cancel-edit="cancelEdit"
   />
 </template>
 
@@ -121,6 +126,13 @@ const {
   clearSelection: clearFromComposable,
   findPrimaryPerson,
   activePeople,
+  editingPerson,
+  isEditing,
+  startEditPerson,
+  cancelEdit,
+  updatePerson,
+  deletePerson,
+  deleteErrorDetail,
 } = usePersonManagement()
 
 const suppressEmit = ref(false)
@@ -171,6 +183,21 @@ const handleSavePerson = async () => {
     return
   }
 
+  if (isEditing.value) {
+    toast.info('Updating person...', { id: 'save-person' })
+    const success = await updatePerson()
+    toast.dismiss('save-person')
+    if (success) {
+      toast.success('Person updated successfully!', {
+        dismissible: true,
+        position: 'top-left',
+      })
+    } else {
+      toast.error('Failed to update person. Please check the form and try again.')
+    }
+    return
+  }
+
   toast.info('Creating person...', { id: 'save-person' })
   const success = await savePerson()
 
@@ -192,6 +219,22 @@ const handleSavePerson = async () => {
   }
 }
 
+const handleEditPerson = (person: CompanyPerson) => {
+  debugLog('PersonSelector - handleEditPerson:', person)
+  startEditPerson(person)
+}
+
+const handleDeletePerson = async (person: CompanyPerson) => {
+  toast.info('Deleting person...', { id: 'delete-person' })
+  const ok = await deletePerson(person)
+  toast.dismiss('delete-person')
+  if (ok) {
+    toast.success('Person removed successfully')
+  } else {
+    toast.error(deleteErrorDetail.value || 'Failed to remove person. Please try again.')
+  }
+}
+
 const handleLinkPerson = async (person: PhonePersonMatch) => {
   toast.info('Linking existing person...', { id: 'save-person' })
   const success = await linkExistingPerson(person)
diff --git a/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts b/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
index 7121deb65..c7d2aa518 100644
--- a/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
+++ b/frontend/src/components/__tests__/PersonSelectionModal.phoneConflict.test.ts
@@ -76,6 +76,8 @@ describe('PersonSelectionModal phone ownership choices', () => {
             },
           ],
         },
+        editingPerson: null,
+        isEditing: false,
       },
       global: { stubs: dialogStubs },
     })
@@ -110,6 +112,8 @@ describe('PersonSelectionModal phone ownership choices', () => {
             },
           ],
         },
+        editingPerson: null,
+        isEditing: false,
       },
       global: { stubs: dialogStubs },
     })
@@ -123,3 +127,85 @@ describe('PersonSelectionModal phone ownership choices', () => {
     ).toBe(false)
   })
 })
+
+const person = {
+  person_id: '66666666-6666-4666-8666-666666666666',
+  person_name: 'Edit Target',
+  person_email: 'edit@example.com',
+  primary_phone: '021 555 0199',
+  position: 'Manager',
+  is_primary: true,
+  notes: '',
+}
+
+const mountWithPerson = () =>
+  mount(PersonSelectionModal, {
+    props: {
+      isOpen: true,
+      companyId,
+      companyName: 'Current Company',
+      people: [person],
+      selectedPerson: null,
+      isLoading: false,
+      personForm: form,
+      phoneOwnership: null,
+      editingPerson: null,
+      isEditing: false,
+    },
+    global: { stubs: dialogStubs },
+  })
+
+describe('PersonSelectionModal edit and delete actions', () => {
+  it('emits edit-person when the edit button is clicked', async () => {
+    const wrapper = mountWithPerson()
+
+    await wrapper.find('[data-automation-id="PersonSelectionModal-edit-button"]').trigger('click')
+
+    const edits = wrapper.emitted('edit-person')
+    expect(edits).toBeTruthy()
+    expect((edits![0][0] as { person_id: string }).person_id).toBe(person.person_id)
+  })
+
+  it('opens the confirm overlay and emits delete-person on confirm', async () => {
+    const wrapper = mountWithPerson()
+
+    expect(
+      wrapper.find('[data-automation-id="PersonSelectionModal-confirm-delete"]').exists(),
+    ).toBe(false)
+
+    await wrapper.find('[data-automation-id="PersonSelectionModal-delete-button"]').trigger('click')
+
+    expect(wrapper.text()).toContain('Delete Person?')
+    expect(
+      wrapper.find('[data-automation-id="PersonSelectionModal-confirm-delete"]').exists(),
+    ).toBe(true)
+
+    await wrapper
+      .find('[data-automation-id="PersonSelectionModal-confirm-delete"]')
+      .trigger('click')
+
+    const deletes = wrapper.emitted('delete-person')
+    expect(deletes).toBeTruthy()
+    expect((deletes![0][0] as { person_id: string }).person_id).toBe(person.person_id)
+  })
+
+  it('shows the primary warning in the confirm overlay for a primary person', async () => {
+    const wrapper = mountWithPerson()
+
+    await wrapper.find('[data-automation-id="PersonSelectionModal-delete-button"]').trigger('click')
+
+    expect(wrapper.text()).toContain('This is the primary person for this company.')
+  })
+
+  it('closes the confirm overlay without emitting on cancel', async () => {
+    const wrapper = mountWithPerson()
+
+    await wrapper.find('[data-automation-id="PersonSelectionModal-delete-button"]').trigger('click')
+    await wrapper.find('[data-automation-id="PersonSelectionModal-cancel-delete"]').trigger('click')
+
+    expect(
+      wrapper.find('[data-automation-id="PersonSelectionModal-confirm-delete"]').exists(),
+    ).toBe(false)
+    expect(wrapper.emitted('delete-person')).toBeFalsy()
+  })
+})
diff --git a/frontend/src/composables/usePersonManagement.ts b/frontend/src/composables/usePersonManagement.ts
index 374f6531f..4cb4316b6 100644
--- a/frontend/src/composables/usePersonManagement.ts
+++ b/frontend/src/composables/usePersonManagement.ts
@@ -48,6 +48,10 @@ export function usePersonManagement() {
   })
 
   // Edit mode state
+  const editingPerson = ref<CompanyPerson | null>(null)
+  const isEditing = computed(() => editingPerson.value !== null)
+  const deleteErrorDetail = ref<string | null>(null)
+
   const activePeople = computed(() => people.value)
 
   const hasPeople = computed(() => people.value.length > 0)
@@ -319,6 +323,176 @@ export function usePersonManagement() {
     }
   }
 
+  /**
+   * Enters edit mode for a person, populating the form from the list item
+   */
+  const startEditPerson = (person: CompanyPerson) => {
+    editingPerson.value = person
+    personForm.value = {
+      name: person.person_name,
+      position: person.position || '',
+      email: person.person_email || '',
+      phone: person.primary_phone || '',
+      notes: person.notes || '',
+      is_primary: person.is_primary || false,
+    }
+  }
+
+  /**
+   * Cancels the current edit operation and resets the form
+   */
+  const cancelEdit = () => {
+    editingPerson.value = null
+    resetPersonForm()
+  }
+
+  /**
+   * Updates the person being edited, calling only the endpoints whose fields changed
+   *
+   * @returns Promise<boolean> - True if the update succeeded, false otherwise
+   */
+  const updatePerson = async (): Promise<boolean> => {
+    const original = editingPerson.value
+    if (!original) {
+      debugLog('Cannot update person without an editing target')
+      return false
+    }
+    if (!personForm.value.name.trim()) {
+      debugLog('Person name is required')
+      return false
+    }
+    if (!currentCompanyId.value) {
+      debugLog('Cannot update person without company ID')
+      return false
+    }
+
+    isLoading.value = true
+    try {
+      const personId = original.person_id
+      const trimmedName = personForm.value.name.trim()
+      const trimmedEmail = personForm.value.email?.trim() || ''
+      const trimmedPosition = personForm.value.position?.trim() || ''
+      const trimmedNotes = personForm.value.notes?.trim() || ''
+      const trimmedPhone = personForm.value.phone?.trim() || ''
+      const isPrimary = personForm.value.is_primary
+
+      const identityChanged =
+        trimmedName !== original.person_name || trimmedEmail !== (original.person_email ?? '')
+      if (identityChanged) {
+        await api.people_partial_update(
+          { name: trimmedName, email: trimmedEmail || null },
+          { params: { person_id: personId } },
+        )
+      }
+
+      const linkChanged =
+        trimmedPosition !== (original.position ?? '') ||
+        trimmedNotes !== (original.notes ?? '') ||
+        isPrimary !== (original.is_primary ?? false)
+      if (linkChanged) {
+        await api.people_company_links_update(
+          {
+            position: trimmedPosition || null,
+            notes: trimmedNotes || null,
+            is_primary: isPrimary,
+          },
+          { params: { person_id: personId, company_id: currentCompanyId.value } },
+        )
+      }
+
+      // Phone: only act on a non-empty changed value. The write endpoints require value.min(1);
+      // clearing a phone is not supported here (matches the "omit phone when blank" create path).
+      const phoneChanged = trimmedPhone !== (original.primary_phone ?? '')
+      if (phoneChanged && trimmedPhone) {
+        const methods = await api.people_contact_methods_list({
+          params: { person_id: personId },
+        })
+        const primaryPhone = methods.find(
+          (method) => method.method_type === 'phone' && method.is_primary,
+        )
+        if (primaryPhone) {
+          await api.people_contact_methods_partial_update(
+            { value: trimmedPhone },
+            { params: { person_id: personId, method_id: primaryPhone.id } },
+          )
+        } else {
+          await api.people_contact_methods_create(
+            { method_type: 'phone', value: trimmedPhone, is_primary: true },
+            { params: { person_id: personId } },
+          )
+        }
+      }
+
+      await loadPeople(currentCompanyId.value)
+
+      if (selectedPerson.value?.person_id === personId) {
+        const refreshed = people.value.find((person) => person.person_id === personId)
+        if (refreshed) selectedPerson.value = refreshed
+      }
+
+      cancelEdit()
+      closeModal()
+      return true
+    } catch (error) {
+      debugLog('Error updating person:', error)
+      return false
+    } finally {
+      isLoading.value = false
+    }
+  }
+
+  /**
+   * Soft-archives a person by removing their link to the current company
+   *
+   * The backend archives the Person itself when this was their last active company link.
+   * On a 400 phone-conflict the backend detail is exposed via `deleteErrorDetail`.
+   *
+   * @param person - The person to remove from the current company
+   * @returns Promise<boolean> - True if removal succeeded, false otherwise
+   */
+  const deletePerson = async (person: CompanyPerson): Promise<boolean> => {
+    if (!currentCompanyId.value) {
+      debugLog('Cannot remove person without company ID')
+      return false
+    }
+
+    isLoading.value = true
+    deleteErrorDetail.value = null
+    try {
+      await api.people_company_links_destroy(undefined, {
+        params: { person_id: person.person_id, company_id: currentCompanyId.value },
+      })
+
+      await loadPeople(currentCompanyId.value)
+
+      if (selectedPerson.value?.person_id === person.person_id) selectedPerson.value = null
+      if (editingPerson.value?.person_id === person.person_id) cancelEdit()
+
+      return true
+    } catch (error) {
+      if (isAxiosError(error) && error.response?.status === 400) {
+        const data = error.response.data
+        // Backend shape: { company_link: ["message"] }. Extract the first string message.
+        if (data && typeof data === 'object') {
+          const firstValue = Object.values(data as Record<string, unknown>)[0]
+          if (Array.isArray(firstValue) && typeof firstValue[0] === 'string') {
+            deleteErrorDetail.value = firstValue[0]
+          } else if (typeof firstValue === 'string') {
+            deleteErrorDetail.value = firstValue
+          } else {
+            deleteErrorDetail.value = null
+          }
+        } else {
+          deleteErrorDetail.value = null
+        }
+      }
+      debugLog('Error removing person:', error)
+      return false
+    } finally {
+      isLoading.value = false
+    }
+  }
+
   /**
    * Resets the new person form to its initial empty state
    */
@@ -397,6 +571,13 @@ export function usePersonManagement() {
     phoneOwnership,
 
     // Edit mode state
+    editingPerson,
+    isEditing,
+    deleteErrorDetail,
+    startEditPerson,
+    cancelEdit,
+    updatePerson,
+    deletePerson,
     activePeople,
 
     hasPeople,
diff --git a/frontend/tests/job/edit-job-settings.spec.ts b/frontend/tests/job/edit-job-settings.spec.ts
index 372af952d..be964d08f 100644
--- a/frontend/tests/job/edit-job-settings.spec.ts
+++ b/frontend/tests/job/edit-job-settings.spec.ts
@@ -499,6 +499,155 @@ test.describe.serial('edit job', () => {
     })
   })
 
+  test('edit an existing person from the selection modal', async ({ authenticatedPage: page }) => {
+    // Dedicated job — this mutates the company's people list, so isolate it.
+    const jobUrl = await createTestJob(page, 'Edit Person')
+    await page.goto(jobUrl)
+    await page.waitForLoadState('networkidle')
+
+    await autoId(page, 'JobViewTabs-jobSettings').click()
+    await autoId(page, 'PersonSelector-modal-button').waitFor({ timeout: 10000 })
+    await waitForSettingsInitialized(page)
+
+    const timestamp = Date.now()
+    const originalName = `Edit Target ${timestamp}`
+    const updatedName = `Edited Name ${timestamp}`
+
+    await test.step('create a person to edit', async () => {
+      await autoId(page, 'PersonSelector-modal-button').click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
+
+      const submitButton = autoId(page, 'PersonSelectionModal-submit')
+      await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
+      await autoId(page, 'PersonSelectionModal-name-input').fill(originalName)
+      await autoId(page, 'PersonSelectionModal-email-input').fill(`edit${timestamp}@example.com`)
+      await submitButton.click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({
+        state: 'hidden',
+        timeout: 10000,
+      })
+    })
+
+    await expectStepUnder(
+      'reopen modal and enter edit mode',
+      EDIT_JOB_BUDGET_MS.createOrSwitchPerson,
+      async () => {
+        await autoId(page, 'PersonSelector-modal-button').click()
+        await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
+
+        const card = page
+          .locator('[data-automation-id^="PersonSelectionModal-card-"]')
+          .filter({ hasText: originalName })
+          .first()
+        await card.waitFor({ timeout: 10000 })
+        await card.hover()
+        await card.locator('[data-automation-id="PersonSelectionModal-edit-button"]').click()
+
+        // Form flips to edit mode: submit label + prefilled name prove it.
+        await expect(autoId(page, 'PersonSelectionModal-submit')).toHaveText('Update Person', {
+          timeout: 10000,
+        })
+        await expect(autoId(page, 'PersonSelectionModal-name-input')).toHaveValue(originalName)
+      },
+    )
+
+    await test.step('change the name and save', async () => {
+      const nameInput = autoId(page, 'PersonSelectionModal-name-input')
+      await nameInput.clear()
+      await nameInput.pressSequentially(updatedName, { delay: 10 })
+      await autoId(page, 'PersonSelectionModal-submit').click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({
+        state: 'hidden',
+        timeout: 10000,
+      })
+    })
+
+    await expectStepUnder(
+      'verify the edit persisted',
+      EDIT_JOB_BUDGET_MS.verifyAfterRefresh,
+      async () => {
+        // Selected person display reflects the new name.
+        await expect(autoId(page, 'PersonSelector-display')).toHaveValue(new RegExp(updatedName), {
+          timeout: 10000,
+        })
+
+        // And the list shows the renamed person, not the old name.
+        await autoId(page, 'PersonSelector-modal-button').click()
+        await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
+        await expect(
+          page
+            .locator('[data-automation-id^="PersonSelectionModal-card-"]')
+            .filter({ hasText: updatedName }),
+        ).toHaveCount(1, { timeout: 10000 })
+        await expect(
+          page
+            .locator('[data-automation-id^="PersonSelectionModal-card-"]')
+            .filter({ hasText: originalName }),
+        ).toHaveCount(0)
+      },
+    )
+  })
+
+  test('delete (archive) a person from the selection modal', async ({
+    authenticatedPage: page,
+  }) => {
+    const jobUrl = await createTestJob(page, 'Delete Person')
+    await page.goto(jobUrl)
+    await page.waitForLoadState('networkidle')
+
+    await autoId(page, 'JobViewTabs-jobSettings').click()
+    await autoId(page, 'PersonSelector-modal-button').waitFor({ timeout: 10000 })
+    await waitForSettingsInitialized(page)
+
+    const timestamp = Date.now()
+    const personName = `Delete Target ${timestamp}`
+
+    await test.step('create a person to delete', async () => {
+      await autoId(page, 'PersonSelector-modal-button').click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
+
+      const submitButton = autoId(page, 'PersonSelectionModal-submit')
+      await expect(submitButton).toHaveText('Create Person', { timeout: 10000 })
+      await autoId(page, 'PersonSelectionModal-name-input').fill(personName)
+      await autoId(page, 'PersonSelectionModal-email-input').fill(`delete${timestamp}@example.com`)
+      await submitButton.click()
+      await autoId(page, 'PersonSelectionModal-container').waitFor({
+        state: 'hidden',
+        timeout: 10000,
+      })
+    })
+
+    await expectStepUnder(
+      'reopen modal and delete the person',
+      EDIT_JOB_BUDGET_MS.createOrSwitchPerson,
+      async () => {
+        await autoId(page, 'PersonSelector-modal-button').click()
+        await autoId(page, 'PersonSelectionModal-container').waitFor({ timeout: 10000 })
+
+        const card = page
+          .locator('[data-automation-id^="PersonSelectionModal-card-"]')
+          .filter({ hasText: personName })
+          .first()
+        await card.waitFor({ timeout: 10000 })
+        await card.hover()
+        await card.locator('[data-automation-id="PersonSelectionModal-delete-button"]').click()
+
+        // Confirmation overlay, then confirm.
+        await expect(page.getByText('Delete Person?')).toBeVisible({ timeout: 10000 })
+        await autoId(page, 'PersonSelectionModal-confirm-delete').click()
+      },
+    )
+
+    await test.step('verify the person is removed from the list', async () => {
+      // Modal stays open; the archived person drops out of the company's list.
+      await expect(
+        page
+          .locator('[data-automation-id^="PersonSelectionModal-card-"]')
+          .filter({ hasText: personName }),
+      ).toHaveCount(0, { timeout: 10000 })
+    })
+  })
+
   test('change company', async ({ authenticatedPage: page }) => {
     // Create a dedicated job for this test — changing company mutates state
     // that would break other tests sharing sharedEditJobUrl

From 00b2bce8137ee61360d84fd3ffd687a2d311198a Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:15:32 +1200
Subject: [PATCH 58/73] =?UTF-8?q?fix(crm):=20don't=20archive=20person=20on?=
 =?UTF-8?q?=20last-link=20removal=20=E2=80=94=20it=20broke=20link=20restor?=
 =?UTF-8?q?e?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The archive-on-last-link cascade in 913cd927 broke the existing person
link-lifecycle. Once a sole-company person's link was removed the Person was
archived (is_active=False), but every person/link endpoint does
get_object_or_404(Person, is_active=True) — so the person could no longer be
viewed or their link restored (people.spec.ts restore step 404'd).

The new model deliberately supports active, company-less people
(test_directory_includes_person_without_company), so link removal must leave
the person active and restorable. Remove the cascade; the delete button
unlinks only, which is exact production parity. Orphan cleanup, if wanted,
belongs in a separate explicit archive action, not tied to link removal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/company/services/person_service.py | 5 -----
 apps/company/tests/test_person_api.py   | 9 ++++++---
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index ca4e7b2c8..1420096d0 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -353,9 +353,4 @@ def remove_company_link(*, person: Person, company: Company) -> None:
         link.is_active = False
         link.is_primary = False
         link.save(update_fields=["is_active", "is_primary", "updated_at"])
-        if not projected_company_ids and person.is_active:
-            # Removing the person's last active company link archives the person
-            # so they no longer surface in people search as an orphan.
-            person.is_active = False
-            person.save(update_fields=["is_active", "updated_at"])
         _schedule_person_phone_rematch(person)
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index bdf3dec03..face8d645 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -202,8 +202,9 @@ def test_removing_link_preserves_person_and_other_company(self) -> None:
         other.refresh_from_db()
         self.assertTrue(other.is_active)
 
-    def test_removing_last_link_archives_person(self) -> None:
-        """Unlinking a person's only employer archives the now-orphaned identity."""
+    def test_removing_last_link_keeps_person_active(self) -> None:
+        """A company-less person stays active and restorable — links are the soft-delete unit,
+        not the person (the model deliberately supports people with no company link)."""
         person = self._person(company=self.company_a)
 
         with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
@@ -213,7 +214,9 @@ def test_removing_last_link_archives_person(self) -> None:
 
         self.assertEqual(response.status_code, 204)
         person.refresh_from_db()
-        self.assertFalse(person.is_active)
+        self.assertTrue(person.is_active)
+        link = CompanyPersonLink.objects.get(person=person, company=self.company_a)
+        self.assertFalse(link.is_active)
 
     def test_removing_link_is_blocked_when_phone_would_cross_companies(self) -> None:
         """Relationship edits must not create the duplicate-phone problem they manage."""

From 79f758e1db9692ae2b6f560704dada53ba23a425 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:32:20 +1200
Subject: [PATCH 59/73] docs(crm): design spec for person archive (retire
 departed people)

Archiving driven by links (last-link removal archives; restore/add un-archives),
archived people stay viewable so the restore-link lifecycle keeps working, plus
an explicit PersonDetail archive action and a directory show-archived filter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../specs/2026-07-16-person-archive-design.md | 99 +++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-16-person-archive-design.md

diff --git a/docs/superpowers/specs/2026-07-16-person-archive-design.md b/docs/superpowers/specs/2026-07-16-person-archive-design.md
new file mode 100644
index 000000000..20b636625
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-16-person-archive-design.md
@@ -0,0 +1,99 @@
+# Person archive (retire departed people) — design
+
+## Context
+
+In the first-class people model a `Person` is a shared record linked to companies via
+`CompanyPersonLink`. `Person.is_active` exists as a soft-delete flag but **no HTTP path toggles it** —
+only offline merge/cleanup services do. There is no way for a user to retire a person who has left or
+become irrelevant.
+
+The need surfaced while restoring the job-settings person selector's delete button. A first attempt made
+`remove_company_link` archive the person on last-link removal, but it only flipped `is_active` while every
+person/link endpoint still gated on `get_object_or_404(Person, is_active=True)`. That made archived people
+unviewable and their links un-restorable, breaking the existing CRM restore-link lifecycle
+(`frontend/tests/crm/people.spec.ts`). That cascade was reverted (`00b2bce8`).
+
+This design does it properly: archiving is driven mainly by links, archived people stay reachable, and
+restoring a link brings them back.
+
+## Purpose
+
+Retire departed/irrelevant people from everyday views (directory search, person selectors) without
+hard-deleting — history preserved, reversible.
+
+## The rule (Person.is_active state machine)
+
+- **Removing a person's last *active* company link → archive** (`is_active=False`). Removing one of
+  several active links leaves the person active.
+- **Restoring or adding any company link to an archived person → un-archive** (`is_active=True`). This is
+  the implicit un-archive; there is no separate un-archive button.
+- **Explicit "Archive person" (PersonDetail) → deactivate all active links + `is_active=False`** ("retire
+  everywhere now"). Secondary path.
+- **Active-but-company-less remains valid** when it arises from *creation* without a link (unchanged;
+  `test_directory_includes_person_without_company`). Only *removal* archives.
+
+Rationale for driving off links rather than a computed "zero active links = archived": a freshly created
+person with no link yet is intentionally active, and an explicit archive of a multi-company person cannot be
+expressed as "zero links". `is_active` is the single source of truth.
+
+## Backend
+
+All in `apps/company/` (models unchanged — `Person.is_active` and `CompanyPersonLink.is_active` already
+exist).
+
+1. **`services/person_service.py`**
+   - `remove_company_link`: after deactivating the link, if the person has no remaining active company links
+     (reuse the already-computed `projected_company_ids`), set `person.is_active = False`
+     (`update_fields=["is_active", "updated_at"]`).
+   - Link add/reactivate (`add_company_link` and the reactivate branch used by the company-links PUT): if the
+     target person is archived, set `person.is_active = True` in the same transaction.
+   - New `archive_person(*, person)`: deactivate all active `CompanyPersonLink`s for the person and set
+     `is_active = False`. Schedule phone rematch consistent with `remove_company_link`.
+2. **`views/person_views.py`** — relax the `is_active=True` gate on the endpoints restore needs, so archived
+   people are viewable/operable:
+   - `PersonDetailView` GET (retrieve): look up by id without the `is_active=True` filter.
+   - `PersonCompanyLinksView` / `PersonCompanyLinkDetailView`: person lookup without `is_active=True` so
+     restore-link works on an archived person.
+   - Keep contact-methods views gated for now (out of scope — see below).
+   - New explicit archive route (e.g. `POST /api/people/{person_id}/archive/`) → `archive_person`.
+3. **`views/person_views.py` `PersonListView`** (directory search): add an `include_archived` query param
+   (default `false` → keep the existing `is_active=True` filter; `true` → include archived).
+4. **Serializers (`person_serializers.py`)**: expose `is_active` on `PersonSummary` (directory rows) and
+   `PersonDetail` so the frontend can badge/branch. `CompanyPerson` unchanged (company lists only ever show
+   active links).
+
+## Frontend
+
+Regenerate the API client after the schema changes (`npm run update-schema && npm run gen:api`).
+
+1. **`/crm/people` directory**: a "Show archived" filter/toggle that sets `include_archived=true`; archived
+   rows render an **Archived** badge. (Files: the people directory page + its list/row components.)
+2. **PersonDetail page**: render an archived person (Archived badge); the existing **restore-link** button
+   already round-trips through the reactivate path, which now un-archives — verify it displays correctly for
+   an archived person. Add an explicit **Archive person** button calling the new archive endpoint.
+3. **Job-settings person selector**: unchanged. Its delete already calls `people_company_links_destroy`; for a
+   single-company person that now archives via the shared cascade, for multi-company it just unlinks. This is
+   the original job-settings request, satisfied by the shared rule.
+
+## Search / visibility (unchanged where it matters)
+
+- Directory default: archived hidden (existing `is_active=True` filter), shown only via the filter.
+- Company people list and person selector already filter to active links → archived people never appear. No
+  change.
+
+## Testing
+
+- Existing `frontend/tests/crm/people.spec.ts` restore-lifecycle passes again (remove sole link →
+  archived + viewable → restore → active).
+- Backend (`apps/company/tests/test_person_api.py`): last-link removal archives; restore-link un-archives;
+  removing one of several links keeps the person active; explicit archive deactivates all links + archives;
+  `PersonDetailView` returns an archived person; directory `include_archived` includes/excludes correctly.
+- Frontend unit: directory badge + filter; PersonDetail archived state + archive button.
+- E2E: show-archived filter → open archived person → restore → active.
+
+## Out of scope for v1 (accepted)
+
+- **Contact-method / phone-ownership for archived people.** An archived person still "owns" their phone
+  number, so it stays blocked for reuse. Left as-is; revisit only if it causes a problem.
+- No standalone "un-archive to a company-less state" button — coming back always happens via restoring/adding
+  a company link.

From 6aa95423f15129ef82a442adfef8d78078d43229 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:37:07 +1200
Subject: [PATCH 60/73] docs(crm): implementation plan for person archive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nine TDD tasks: backend archive/un-archive on link removal/add, relaxed
is_active gates, explicit archive endpoint, directory include_archived filter,
client regen, directory + PersonDetail UI, and an e2e archive→restore spec.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-07-16-person-archive.md        | 717 ++++++++++++++++++
 1 file changed, 717 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-16-person-archive.md

diff --git a/docs/superpowers/plans/2026-07-16-person-archive.md b/docs/superpowers/plans/2026-07-16-person-archive.md
new file mode 100644
index 000000000..9f95391aa
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-16-person-archive.md
@@ -0,0 +1,717 @@
+# Person Archive Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let users retire departed people so they drop out of everyday views (directory search, person selectors) without hard-deleting, reversibly.
+
+**Architecture:** `Person.is_active` is the retirement flag. Removing a person's last active company link archives them; adding/restoring any link un-archives them. Archived people stay viewable so the CRM restore-link lifecycle keeps working. An explicit PersonDetail "Archive person" action and a directory "Show archived" filter round it out. Backend-first (5 tasks), then regen the client and do the frontend (4 tasks).
+
+**Tech Stack:** Django REST Framework + DRF-spectacular (backend), Vue 3 + TS + zodios generated client + Playwright/vitest (frontend).
+
+## Global Constraints
+
+- Every exception handler persists once via `persist_app_error(exc)` and re-raises through the `AlreadyLoggedException` two-arm pattern (ADR 0019/0001). Match surrounding service style.
+- Backend authoritative type check: `bash scripts/check_mypy.sh`. New code must be fully type-clean; no `Any`/casts/ignores as shortcuts (ADR 0028).
+- Frontend: generated `api` client only (`@/api/client`); immutable state updates; `<script setup lang="ts">`; new/touched interactive elements expose stable `data-automation-id`s.
+- `is_active` is the single source of truth for archived state — do not compute "archived" from link counts anywhere.
+- Backend tests run with `poetry run python manage.py test <dotted.path> -v1`. Do not run the ~25-min e2e suite during implementation; write the spec only.
+- Never hand-edit `mypy-baseline.txt` or `__init__.py`.
+
+---
+
+### Task 1: Archive a person when their last active company link is removed
+
+**Files:**
+- Modify: `apps/company/services/person_service.py` (`remove_company_link`, ~`:325-357`)
+- Test: `apps/company/tests/test_person_api.py`
+
+**Interfaces:**
+- Consumes: existing `remove_company_link(*, person: Person, company: Company) -> None`, which already computes `projected_company_ids` (the person's remaining active links excluding this company).
+- Produces: after this task, removing a person's last active link sets `person.is_active = False`.
+
+Note: `test_person_api.py` currently contains `test_removing_last_link_keeps_person_active` (asserts the person stays active). This task **replaces** that test's intent — the person is now archived.
+
+- [ ] **Step 1: Replace the stale test with the archive assertion**
+
+In `apps/company/tests/test_person_api.py`, replace the whole `test_removing_last_link_keeps_person_active` method with:
+
+```python
+    def test_removing_last_link_archives_person(self) -> None:
+        """Removing a person's only active company link retires (archives) them."""
+        person = self._person(company=self.company_a)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        self.assertEqual(response.status_code, 204)
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+        link = CompanyPersonLink.objects.get(person=person, company=self.company_a)
+        self.assertFalse(link.is_active)
+```
+
+- [ ] **Step 2: Run the test, verify it FAILS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api.PersonApiTests.test_removing_last_link_archives_person -v2`
+Expected: FAIL — `person.is_active` is still `True` (assertFalse fails).
+
+- [ ] **Step 3: Add the cascade in `remove_company_link`**
+
+In `apps/company/services/person_service.py`, change the tail of `remove_company_link` from:
+
+```python
+        link.is_active = False
+        link.is_primary = False
+        link.save(update_fields=["is_active", "is_primary", "updated_at"])
+        _schedule_person_phone_rematch(person)
+```
+to:
+```python
+        link.is_active = False
+        link.is_primary = False
+        link.save(update_fields=["is_active", "is_primary", "updated_at"])
+        if not projected_company_ids and person.is_active:
+            # Removing the person's last active company link retires them.
+            person.is_active = False
+            person.save(update_fields=["is_active", "updated_at"])
+        _schedule_person_phone_rematch(person)
+```
+
+- [ ] **Step 4: Run tests, verify PASS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api -v1`
+Expected: PASS (all tests, including `test_removing_link_preserves_person_and_other_company` which keeps the person active because company_b link remains).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/company/services/person_service.py apps/company/tests/test_person_api.py
+git commit -m "feat(crm): archive a person when their last company link is removed"
+```
+
+---
+
+### Task 2: Un-archive a person when a company link is added or restored
+
+**Files:**
+- Modify: `apps/company/services/person_service.py` (`put_company_link`, `:281-322`)
+- Test: `apps/company/tests/test_person_api.py`
+
+**Interfaces:**
+- Consumes: `put_company_link(*, person, company, data) -> CompanyPersonLink` (create/reactivate a link), reached by `PUT /api/people/{person_id}/company-links/{company_id}/`.
+- Produces: after this task, `put_company_link` sets `person.is_active = True` when the target person was archived.
+
+Note: this task depends on Task 3's gate relaxation to be reachable via HTTP for an archived person, but the service-level behaviour and its unit test stand alone. Test at the service layer here to avoid the ordering coupling.
+
+- [ ] **Step 1: Write the failing test (service-level)**
+
+Add to `apps/company/tests/test_person_api.py`:
+
+```python
+    def test_restoring_a_link_unarchives_the_person(self) -> None:
+        """Adding/reactivating any company link brings an archived person back."""
+        from apps.company.services.person_service import (
+            put_company_link,
+            remove_company_link,
+        )
+
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            remove_company_link(person=person, company=self.company_a)
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            put_company_link(
+                person=person,
+                company=self.company_a,
+                data={"position": None, "notes": None, "is_primary": False},
+            )
+        person.refresh_from_db()
+        self.assertTrue(person.is_active)
+```
+
+- [ ] **Step 2: Run the test, verify it FAILS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api.PersonApiTests.test_restoring_a_link_unarchives_the_person -v2`
+Expected: FAIL — person stays archived (`assertTrue(person.is_active)` fails).
+
+- [ ] **Step 3: Un-archive in `put_company_link`**
+
+In `apps/company/services/person_service.py`, inside `put_company_link`, immediately before `_schedule_person_phone_rematch(person)` (after the `if existing is None / else` block that sets `link`), add:
+
+```python
+        if not person.is_active:
+            person.is_active = True
+            person.save(update_fields=["is_active", "updated_at"])
+```
+
+- [ ] **Step 4: Run tests, verify PASS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api -v1`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/company/services/person_service.py apps/company/tests/test_person_api.py
+git commit -m "feat(crm): un-archive a person when a company link is added or restored"
+```
+
+---
+
+### Task 3: Make archived people viewable and their links restorable over HTTP
+
+**Files:**
+- Modify: `apps/company/views/person_views.py` (`PersonDetailView` `:76`; `PersonCompanyLinksView.get` `:161`; `PersonCompanyLinkDetailView.put` `:176`, `.delete` `:197`)
+- Test: `apps/company/tests/test_person_api.py`
+
+**Interfaces:**
+- Consumes: the archive/un-archive behaviour from Tasks 1-2.
+- Produces: `GET /api/people/{id}/` returns archived people (200, not 404); `PUT /api/people/{id}/company-links/{company_id}/` works on an archived person and (via Task 2) un-archives them.
+
+Rationale: these four person lookups currently filter `is_active=True`, which 404s archived people and blocks the restore-link lifecycle. Contact-method views stay gated (out of scope).
+
+- [ ] **Step 1: Write the failing HTTP tests**
+
+Add to `apps/company/tests/test_person_api.py`:
+
+```python
+    def test_detail_returns_an_archived_person(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get(f"/api/people/{person.id}/")
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["is_active"])
+
+    def test_restore_link_over_http_unarchives_archived_person(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.put(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/",
+                data={"position": "", "notes": "", "is_primary": False},
+                format="json",
+            )
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["is_active"])
+        person.refresh_from_db()
+        self.assertTrue(person.is_active)
+```
+
+- [ ] **Step 2: Run the tests, verify they FAIL**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api.PersonApiTests.test_detail_returns_an_archived_person apps.company.tests.test_person_api.PersonApiTests.test_restore_link_over_http_unarchives_archived_person -v2`
+Expected: FAIL — both 404 (archived person filtered out).
+
+- [ ] **Step 3: Relax the four person lookups**
+
+In `apps/company/views/person_views.py`:
+
+1. `PersonDetailView` — change `queryset = Person.objects.filter(is_active=True)` to:
+```python
+    queryset = Person.objects.all()
+```
+2. `PersonCompanyLinksView.get` — change `person = get_object_or_404(Person, id=person_id, is_active=True)` to:
+```python
+        person = get_object_or_404(Person, id=person_id)
+```
+3. `PersonCompanyLinkDetailView.put` — same change:
+```python
+        person = get_object_or_404(Person, id=person_id)
+```
+4. `PersonCompanyLinkDetailView.delete` — same change:
+```python
+        person = get_object_or_404(Person, id=person_id)
+```
+
+- [ ] **Step 4: Run tests, verify PASS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api -v1`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/company/views/person_views.py apps/company/tests/test_person_api.py
+git commit -m "feat(crm): let archived people be viewed and their links restored"
+```
+
+---
+
+### Task 4: Explicit "Archive person" service + endpoint
+
+**Files:**
+- Modify: `apps/company/services/person_service.py` (add `archive_person`)
+- Modify: `apps/company/views/person_views.py` (add `PersonArchiveView`)
+- Modify: `apps/company/urls_people_rest.py` (add route)
+- Test: `apps/company/tests/test_person_api.py`
+
+**Interfaces:**
+- Produces: `archive_person(*, person: Person) -> None` (deactivate all active links + set `is_active=False`); `POST /api/people/{person_id}/archive/` → 200 with `PersonDetailSerializer` body.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `apps/company/tests/test_person_api.py`:
+
+```python
+    def test_archive_person_endpoint_deactivates_links_and_archives(self) -> None:
+        person = self._person(company=self.company_a)
+        CompanyPersonLink.objects.create(company=self.company_b, person=person)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.post(f"/api/people/{person.id}/archive/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["is_active"])
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+        self.assertFalse(
+            CompanyPersonLink.objects.filter(person=person, is_active=True).exists()
+        )
+```
+
+- [ ] **Step 2: Run the test, verify it FAILS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api.PersonApiTests.test_archive_person_endpoint_deactivates_links_and_archives -v2`
+Expected: FAIL — 404 (no such route).
+
+- [ ] **Step 3: Add the service function**
+
+In `apps/company/services/person_service.py`, add near `remove_company_link`:
+
+```python
+def archive_person(*, person: Person) -> None:
+    """Retire a person everywhere: deactivate all active links, then archive."""
+    with transaction.atomic():
+        locked = Person.objects.select_for_update().get(pk=person.pk)
+        CompanyPersonLink.objects.filter(person=locked, is_active=True).update(
+            is_active=False, is_primary=False
+        )
+        if locked.is_active:
+            locked.is_active = False
+            locked.save(update_fields=["is_active", "updated_at"])
+        _schedule_person_phone_rematch(locked)
+```
+
+- [ ] **Step 4: Add the view**
+
+In `apps/company/views/person_views.py`: import `archive_person` in the existing `from apps.company.services.person_service import (...)` block, then add:
+
+```python
+class PersonArchiveView(APIView):
+    """Explicitly retire a person (deactivate all links + archive)."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(request=None, responses={200: PersonDetailSerializer})
+    def post(self, request: Request, person_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id)
+        archive_person(person=person)
+        person.refresh_from_db()
+        return Response(PersonDetailSerializer(person).data)
+```
+
+- [ ] **Step 5: Add the route**
+
+In `apps/company/urls_people_rest.py`, import `PersonArchiveView` in the existing view import block and add to `urlpatterns`:
+
+```python
+    path(
+        "<uuid:person_id>/archive/",
+        PersonArchiveView.as_view(),
+        name="person_archive",
+    ),
+```
+
+- [ ] **Step 6: Run tests, verify PASS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api -v1`
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add apps/company/services/person_service.py apps/company/views/person_views.py apps/company/urls_people_rest.py apps/company/tests/test_person_api.py
+git commit -m "feat(crm): add explicit archive-person endpoint"
+```
+
+---
+
+### Task 5: Directory `include_archived` filter + expose `is_active` on summaries
+
+**Files:**
+- Modify: `apps/company/services/person_service.py` (`PersonDirectoryService.search`, `:65-103`)
+- Modify: `apps/company/views/person_views.py` (`PersonListView`, `:49-70`)
+- Modify: `apps/company/person_serializers.py` (`PersonSummarySerializer.Meta.fields`, `:40`)
+- Test: `apps/company/tests/test_person_api.py`
+
+**Interfaces:**
+- Produces: `PersonDirectoryService.search(query: str, *, include_archived: bool = False)`; `GET /api/people/?include_archived=true` includes archived people; `PersonSummary` gains `is_active`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add to `apps/company/tests/test_person_api.py`:
+
+```python
+    def test_directory_excludes_archived_by_default(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get("/api/people/")
+        ids = [row["id"] for row in response.json()["results"]]
+        self.assertNotIn(str(person.id), ids)
+
+    def test_directory_includes_archived_when_requested(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get("/api/people/", {"include_archived": "true"})
+        rows = {row["id"]: row for row in response.json()["results"]}
+        self.assertIn(str(person.id), rows)
+        self.assertFalse(rows[str(person.id)]["is_active"])
+```
+
+- [ ] **Step 2: Run the tests, verify they FAIL**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api.PersonApiTests.test_directory_excludes_archived_by_default apps.company.tests.test_person_api.PersonApiTests.test_directory_includes_archived_when_requested -v2`
+Expected: FAIL — `include_archived` test fails (archived person absent) and/or `is_active` missing from row (KeyError).
+
+- [ ] **Step 3: Thread `include_archived` through the service**
+
+In `apps/company/services/person_service.py`, change `search`'s signature and base queryset:
+
+```python
+    @staticmethod
+    def search(query: str, *, include_archived: bool = False) -> QuerySet[Person]:
+        base = Person.objects.all() if include_archived else Person.objects.filter(
+            is_active=True
+        )
+        people = (
+            base
+            .annotate(
+```
+(leave the rest of the method body unchanged.)
+
+- [ ] **Step 4: Pass the query param from the view**
+
+In `apps/company/views/person_views.py`, `PersonListView.get_queryset`:
+
+```python
+    def get_queryset(self) -> QuerySet[Person]:
+        include_archived = (
+            self.request.query_params.get("include_archived", "").lower() == "true"
+        )
+        return PersonDirectoryService.search(
+            self.request.query_params.get("q", ""),
+            include_archived=include_archived,
+        )
+```
+Also add an `include_archived` OpenApiParameter to the `@extend_schema` `parameters` list on `PersonListView.get` (mirror the existing `q` parameter, `type=OpenApiTypes.BOOL`).
+
+- [ ] **Step 5: Expose `is_active` on the summary serializer**
+
+In `apps/company/person_serializers.py`, `PersonSummarySerializer.Meta.fields`, add `"is_active"`:
+
+```python
+        fields = ["id", "name", "email", "is_active", "primary_phone", "companies"]
+```
+
+- [ ] **Step 6: Run tests, verify PASS**
+
+Run: `poetry run python manage.py test apps.company.tests.test_person_api -v1`
+Expected: PASS.
+
+- [ ] **Step 7: Type-check the backend and commit**
+
+Run: `bash scripts/check_mypy.sh`
+Expected: no new errors.
+
+```bash
+git add apps/company/services/person_service.py apps/company/views/person_views.py apps/company/person_serializers.py apps/company/tests/test_person_api.py
+git commit -m "feat(crm): directory include_archived filter and is_active on summaries"
+```
+
+---
+
+### Task 6: Regenerate the frontend API client
+
+**Files:**
+- Modify: `frontend/src/api/generated/api.ts` (generated — do not hand-edit), plus the schema snapshot the generator reads.
+
+**Interfaces:**
+- Produces: generated client ops `api.people_archive_create` (or the name the generator derives for `POST /people/{person_id}/archive/`), `include_archived` query on `people_list`, and `is_active` on `schemas.PersonSummary`.
+
+- [ ] **Step 1: Regenerate**
+
+Run (from `frontend/`): `npm run update-schema && npm run gen:api`
+Expected: `frontend/src/api/generated/api.ts` updates; `git status` shows it modified.
+
+- [ ] **Step 2: Confirm the new surface exists**
+
+Run: `grep -nE "person_archive|include_archived|PersonSummary" frontend/src/api/generated/api.ts | head`
+Expected: matches for the archive endpoint operation, the `include_archived` query param, and `is_active` inside the `PersonSummary` schema. Note the exact generated operation name for the archive POST — Tasks 7-8 use it.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/api/generated/api.ts
+git commit -m "chore(api): regenerate client for person archive endpoints"
+```
+
+---
+
+### Task 7: Directory "Show archived" filter + Archived badge
+
+**Files:**
+- Modify: `frontend/src/pages/crm/people/(index).vue`
+- Test: `frontend/src/pages/crm/people/__tests__/people-directory.test.ts`
+
+**Interfaces:**
+- Consumes: `api.people_list({ queries: { ..., include_archived } })`; `PersonSummary.is_active`.
+- Produces: a `data-automation-id="PeopleDirectory-show-archived"` checkbox; archived rows show a badge with `data-automation-id="PeopleDirectory-archived-badge-${person.id}"`.
+
+- [ ] **Step 1: Write the failing unit test**
+
+Add a test to `frontend/src/pages/crm/people/__tests__/people-directory.test.ts` following the existing mount/mock pattern in that file: mock `api.people_list` to return one row with `is_active: false`; assert the row renders the archived badge, and assert that toggling the `PeopleDirectory-show-archived` control calls `api.people_list` with `queries.include_archived === true`. (Read the file's existing helpers/mocks first and mirror them.)
+
+- [ ] **Step 2: Run it, verify FAIL**
+
+Run (from `frontend/`): `npx vitest run src/pages/crm/people/__tests__/people-directory.test.ts`
+Expected: FAIL — control/badge not present.
+
+- [ ] **Step 3: Add the filter state + control**
+
+In `(index).vue` script, add `const includeArchived = ref(false)`. In `loadPeople`, pass it:
+
+```ts
+    const response = await api.people_list({
+      queries: {
+        page: page.value,
+        page_size: 50,
+        q: query.value || undefined,
+        include_archived: includeArchived.value || undefined,
+      },
+    })
+```
+
+In the search Card (next to the Search input, `:52-62`), add:
+
+```html
+            <label class="flex items-center gap-2 text-sm text-gray-600">
+              <input
+                type="checkbox"
+                v-model="includeArchived"
+                data-automation-id="PeopleDirectory-show-archived"
+                @change="applySearch"
+              />
+              Show archived
+            </label>
+```
+
+- [ ] **Step 4: Add the Archived badge in the row**
+
+In the person cell (`:94-97`), after the name/email, add:
+
+```html
+                    <Badge
+                      v-if="!person.is_active"
+                      variant="secondary"
+                      :data-automation-id="`PeopleDirectory-archived-badge-${person.id}`"
+                    >
+                      Archived
+                    </Badge>
+```
+Import `Badge` from `@/components/ui/badge` in the script.
+
+- [ ] **Step 5: Run tests + type-check, verify PASS**
+
+Run (from `frontend/`): `npx vitest run src/pages/crm/people/__tests__/people-directory.test.ts && npm run type-check`
+Expected: PASS, clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/pages/crm/people/'(index).vue' frontend/src/pages/crm/people/__tests__/people-directory.test.ts
+git commit -m "feat(crm): show-archived filter and Archived badge in people directory"
+```
+
+---
+
+### Task 8: PersonDetail — Archived badge + "Archive person" button
+
+**Files:**
+- Modify: `frontend/src/pages/crm/people/[id].vue`
+- Test: none dedicated (covered by the e2e in Task 9); add a small unit test only if the file already has one.
+
+**Interfaces:**
+- Consumes: `person.is_active` (already on `PersonDetail`); the generated archive op from Task 6 (confirm the exact name; assume `api.people_archive_create(undefined, { params: { person_id } })`).
+- Produces: `data-automation-id="PersonDetail-archived-badge"` shown when `!person.is_active`; `data-automation-id="PersonDetail-archive"` button that archives and refreshes.
+
+- [ ] **Step 1: Add the archived badge in the header**
+
+In `[id].vue` template header area (near the page title, ~`:11`), add:
+
+```html
+        <Badge
+          v-if="person && !person.is_active"
+          variant="secondary"
+          data-automation-id="PersonDetail-archived-badge"
+        >
+          Archived
+        </Badge>
+```
+Ensure `Badge` is imported (the file already imports it for link status).
+
+- [ ] **Step 2: Add the Archive-person button + handler**
+
+Add a button in the header actions, shown only when the person is currently active:
+
+```html
+        <Button
+          v-if="person && person.is_active"
+          type="button"
+          variant="outline"
+          size="sm"
+          data-automation-id="PersonDetail-archive"
+          @click="archivePerson"
+        >
+          Archive person
+        </Button>
+```
+
+In the script, add (using the confirmed generated op name from Task 6):
+
+```ts
+const archiving = ref(false)
+async function archivePerson(): Promise<void> {
+  archiving.value = true
+  try {
+    await api.people_archive_create(undefined, { params: { person_id: props.id } })
+    toast.success('Person archived')
+    await loadPerson()
+  } catch (err) {
+    toast.error(err instanceof Error ? err.message : 'Failed to archive person')
+  } finally {
+    archiving.value = false
+  }
+}
+```
+
+- [ ] **Step 3: Verify the restore-link path already un-archives via UI**
+
+No code change expected: `restoreLink` calls `api.people_company_links_update`, which the backend now un-archives (Task 2). Confirm `loadPerson()` runs after `restoreLink` so the badge clears. If `restoreLink` does not already refresh `person`, add `await loadPerson()` at its end.
+
+- [ ] **Step 4: Type-check, verify PASS**
+
+Run (from `frontend/`): `npm run type-check`
+Expected: clean (no `any`, generated op name resolves).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/pages/crm/people/'[id].vue'
+git commit -m "feat(crm): archived badge and Archive-person button on PersonDetail"
+```
+
+---
+
+### Task 9: E2E — archive via directory show-archived → restore
+
+**Files:**
+- Create: `frontend/tests/crm/people-archive.spec.ts`
+
+**Interfaces:**
+- Consumes: automation ids from Tasks 7-8 and the existing `PersonDetail-*` / `PeopleDirectory-*` ids.
+
+Note: the existing `frontend/tests/crm/people.spec.ts` "manages link lifecycle" test now exercises archive-on-remove → restore implicitly and must still pass — do not modify it.
+
+- [ ] **Step 1: Write the e2e spec**
+
+Create `frontend/tests/crm/people-archive.spec.ts`, mirroring the patterns in `frontend/tests/crm/people.spec.ts` (import `{ expect, test }` from `../fixtures/auth`, `autoId`/`waitForCompanyCreateResponse` from `../fixtures/helpers`, the `createCompany` / `createPersonForSelectedCompany` helpers — copy those two helpers into this file or import if exported). The test:
+
+```ts
+test('archived person is hidden by default, findable via filter, and restorable', async ({
+  authenticatedPage: page,
+}) => {
+  const suffix = Math.floor(Math.random() * 1_000_000)
+  const companyName = `[TEST] Archive Company ${suffix}`
+  const personName = `[TEST] Archive Person ${suffix}`
+
+  // Create a single-company person, then archive by removing their only link.
+  await page.goto('/crm/people')
+  await autoId(page, 'PeopleDirectory-create').click()
+  await createCompany(page, companyName)
+  await createPersonForSelectedCompany(page, personName, `0219${String(suffix).padStart(6, '0')}`)
+
+  await autoId(page, 'PeopleDirectory-search').fill(personName)
+  await autoId(page, 'PeopleDirectory-search').press('Enter')
+  const row = page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName })
+  await row.getByRole('button', { name: 'Manage' }).click()
+
+  const link = page.locator('[data-automation-id^="PersonDetail-company-link-"]').filter({ hasText: companyName })
+  const linkId = (await link.getAttribute('data-automation-id'))!.replace('PersonDetail-company-link-', '')
+  page.once('dialog', (d) => d.accept())
+  await autoId(page, `PersonDetail-remove-link-${linkId}`).click()
+  await expect(autoId(page, 'PersonDetail-archived-badge')).toBeVisible()
+
+  // Hidden from default directory search.
+  await page.goto('/crm/people')
+  await autoId(page, 'PeopleDirectory-search').fill(personName)
+  await autoId(page, 'PeopleDirectory-search').press('Enter')
+  await expect(
+    page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName }),
+  ).toHaveCount(0)
+
+  // Visible with the show-archived filter.
+  await autoId(page, 'PeopleDirectory-show-archived').check()
+  await expect(
+    page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName }),
+  ).toHaveCount(1)
+
+  // Restore brings them back active.
+  await page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName })
+    .getByRole('button', { name: 'Manage' }).click()
+  await autoId(page, `PersonDetail-restore-link-${linkId}`).click()
+  await expect(link).toContainText('Active')
+  await expect(autoId(page, 'PersonDetail-archived-badge')).toHaveCount(0)
+})
+```
+
+- [ ] **Step 2: Confirm it compiles / is discovered (no full run)**
+
+Run (from `frontend/`): `npx playwright test tests/crm/people-archive.spec.ts --list`
+Expected: the test is listed with no compile error.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/tests/crm/people-archive.spec.ts
+git commit -m "test(crm): e2e for archive → show-archived → restore"
+```
+
+---
+
+## Self-review
+
+- **Spec coverage:** rule/state-machine → Tasks 1,2,4; relaxed gates → Task 3; explicit archive → Task 4; directory filter + `is_active` exposure → Task 5; client regen → Task 6; directory UI → Task 7; PersonDetail UI → Task 8; testing incl. existing `people.spec.ts` → Tasks 1-9 + Task 9. Out-of-scope (contact-method/phone-ownership for archived) intentionally untouched.
+- **Placeholder scan:** none — every code step shows the code; the only deferred detail is the generated archive op name, which Task 6 Step 2 pins down before Tasks 7-8 use it.
+- **Type/name consistency:** `archive_person`, `PersonArchiveView`, `include_archived`, `PersonDirectoryService.search(query, *, include_archived=False)`, `is_active` used consistently across tasks.

From cff8080405529a4a31d44bfae93253a0546e2734 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:43:35 +1200
Subject: [PATCH 61/73] feat(crm): archive a person when their last company
 link is removed

---
 apps/company/services/person_service.py | 4 ++++
 apps/company/tests/test_person_api.py   | 7 +++----
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index 1420096d0..fe78bd642 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -353,4 +353,8 @@ def remove_company_link(*, person: Person, company: Company) -> None:
         link.is_active = False
         link.is_primary = False
         link.save(update_fields=["is_active", "is_primary", "updated_at"])
+        if not projected_company_ids and person.is_active:
+            # Removing the person's last active company link retires them.
+            person.is_active = False
+            person.save(update_fields=["is_active", "updated_at"])
         _schedule_person_phone_rematch(person)
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index face8d645..b73ddeb06 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -202,9 +202,8 @@ def test_removing_link_preserves_person_and_other_company(self) -> None:
         other.refresh_from_db()
         self.assertTrue(other.is_active)
 
-    def test_removing_last_link_keeps_person_active(self) -> None:
-        """A company-less person stays active and restorable — links are the soft-delete unit,
-        not the person (the model deliberately supports people with no company link)."""
+    def test_removing_last_link_archives_person(self) -> None:
+        """Removing a person's only active company link retires (archives) them."""
         person = self._person(company=self.company_a)
 
         with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
@@ -214,7 +213,7 @@ def test_removing_last_link_keeps_person_active(self) -> None:
 
         self.assertEqual(response.status_code, 204)
         person.refresh_from_db()
-        self.assertTrue(person.is_active)
+        self.assertFalse(person.is_active)
         link = CompanyPersonLink.objects.get(person=person, company=self.company_a)
         self.assertFalse(link.is_active)
 

From 0234480727d7570ea62e99ecbdaa80175633e424 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:48:34 +1200
Subject: [PATCH 62/73] feat(crm): un-archive a person when a company link is
 added or restored

---
 apps/company/services/person_service.py |  3 +++
 apps/company/tests/test_person_api.py   | 22 ++++++++++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index fe78bd642..5e9528014 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -318,6 +318,9 @@ def put_company_link(
                 ]
             )
             link = existing
+        if not person.is_active:
+            person.is_active = True
+            person.save(update_fields=["is_active", "updated_at"])
         _schedule_person_phone_rematch(person)
         return link
 
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index b73ddeb06..6507b69bf 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -217,6 +217,28 @@ def test_removing_last_link_archives_person(self) -> None:
         link = CompanyPersonLink.objects.get(person=person, company=self.company_a)
         self.assertFalse(link.is_active)
 
+    def test_restoring_a_link_unarchives_the_person(self) -> None:
+        """Adding/reactivating any company link brings an archived person back."""
+        from apps.company.services.person_service import (
+            put_company_link,
+            remove_company_link,
+        )
+
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            remove_company_link(person=person, company=self.company_a)
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            put_company_link(
+                person=person,
+                company=self.company_a,
+                data={"position": None, "notes": None, "is_primary": False},
+            )
+        person.refresh_from_db()
+        self.assertTrue(person.is_active)
+
     def test_removing_link_is_blocked_when_phone_would_cross_companies(self) -> None:
         """Relationship edits must not create the duplicate-phone problem they manage."""
         person = self._person(company=self.company_a)

From 9fd1d1eda8f792fea70396d39b388d2701632323 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 18:53:51 +1200
Subject: [PATCH 63/73] feat(crm): let archived people be viewed and their
 links restored

---
 apps/company/tests/test_person_api.py | 31 +++++++++++++++++++++++++++
 apps/company/views/person_views.py    |  8 +++----
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index 6507b69bf..fcfdb3186 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -287,3 +287,34 @@ def test_old_person_links_collection_is_removed(self) -> None:
         response = self.client.get("/api/companies/person-links/")
 
         self.assertEqual(response.status_code, 404)
+
+    def test_detail_returns_an_archived_person(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get(f"/api/people/{person.id}/")
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["is_active"])
+
+    def test_restore_link_over_http_unarchives_archived_person(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.put(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/",
+                data={"position": "", "notes": "", "is_primary": False},
+                format="json",
+            )
+        self.assertEqual(response.status_code, 200)
+        self.assertTrue(response.json()["is_active"])
+        person.refresh_from_db()
+        self.assertTrue(person.is_active)
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
index 3f5a197ae..488aaca69 100644
--- a/apps/company/views/person_views.py
+++ b/apps/company/views/person_views.py
@@ -73,7 +73,7 @@ def get_queryset(self) -> QuerySet[Person]:
 class PersonDetailView(generics.RetrieveUpdateAPIView[Person]):
     """Retrieve or update a Person's identity fields."""
 
-    queryset = Person.objects.filter(is_active=True)
+    queryset = Person.objects.all()
     permission_classes = PERSON_PERMISSIONS
     lookup_url_kwarg = "person_id"
 
@@ -158,7 +158,7 @@ class PersonCompanyLinksView(APIView):
 
     @extend_schema(responses={200: PersonCompanyLinkSerializer(many=True)})
     def get(self, request: Request, person_id: str) -> Response:
-        person = get_object_or_404(Person, id=person_id, is_active=True)
+        person = get_object_or_404(Person, id=person_id)
         links = PersonDirectoryService.company_links(person)
         return Response(PersonCompanyLinkSerializer(links, many=True).data)
 
@@ -173,7 +173,7 @@ class PersonCompanyLinkDetailView(APIView):
         responses={200: PersonCompanyLinkSerializer},
     )
     def put(self, request: Request, person_id: str, company_id: str) -> Response:
-        person = get_object_or_404(Person, id=person_id, is_active=True)
+        person = get_object_or_404(Person, id=person_id)
         company = get_object_or_404(Company, id=company_id)
         payload = CompanyLinkWriteSerializer(data=request.data)
         payload.is_valid(raise_exception=True)
@@ -194,7 +194,7 @@ def put(self, request: Request, person_id: str, company_id: str) -> Response:
 
     @extend_schema(responses={204: None})
     def delete(self, request: Request, person_id: str, company_id: str) -> Response:
-        person = get_object_or_404(Person, id=person_id, is_active=True)
+        person = get_object_or_404(Person, id=person_id)
         company = get_object_or_404(Company, id=company_id)
         try:
             remove_company_link(person=person, company=company)

From 0c0888326e9b98a851aa64b9b7cc242db1831010 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 19:43:55 +1200
Subject: [PATCH 64/73] feat(crm): add explicit archive-person endpoint

---
 apps/company/services/__init__.py       |  2 ++
 apps/company/services/person_service.py | 13 +++++++++++++
 apps/company/tests/test_person_api.py   | 15 +++++++++++++++
 apps/company/urls_people_rest.py        |  6 ++++++
 apps/company/views/__init__.py          |  2 ++
 apps/company/views/person_views.py      | 14 ++++++++++++++
 docs/urls/company.md                    |  5 +++++
 frontend/schema.yml                     | 22 ++++++++++++++++++++++
 frontend/src/api/generated/api.ts       | 15 +++++++++++++++
 9 files changed, 94 insertions(+)

diff --git a/apps/company/services/__init__.py b/apps/company/services/__init__.py
index 2ba8b96d6..c617787c2 100644
--- a/apps/company/services/__init__.py
+++ b/apps/company/services/__init__.py
@@ -69,6 +69,7 @@
             PhoneCompanyOwner,
             PhoneOwnershipResult,
             PhonePersonMatch,
+            archive_person,
             classify_phone_ownership,
             create_person_for_company,
             put_company_link,
@@ -121,6 +122,7 @@
     "PhonePersonMatch",
     "RetainedDecision",
     "apply_reviewed_duplicate_cleanup",
+    "archive_person",
     "classify_phone_ownership",
     "create_person_for_company",
     "geocode_address",
diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index 5e9528014..ebe217c7f 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -325,6 +325,19 @@ def put_company_link(
         return link
 
 
+def archive_person(*, person: Person) -> None:
+    """Retire a person everywhere: deactivate all active links, then archive."""
+    with transaction.atomic():
+        locked = Person.objects.select_for_update().get(pk=person.pk)
+        CompanyPersonLink.objects.filter(person=locked, is_active=True).update(
+            is_active=False, is_primary=False
+        )
+        if locked.is_active:
+            locked.is_active = False
+            locked.save(update_fields=["is_active", "updated_at"])
+        _schedule_person_phone_rematch(locked)
+
+
 def remove_company_link(*, person: Person, company: Company) -> None:
     with transaction.atomic():
         link = (
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index fcfdb3186..3e7c4524e 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -318,3 +318,18 @@ def test_restore_link_over_http_unarchives_archived_person(self) -> None:
         self.assertTrue(response.json()["is_active"])
         person.refresh_from_db()
         self.assertTrue(person.is_active)
+
+    def test_archive_person_endpoint_deactivates_links_and_archives(self) -> None:
+        person = self._person(company=self.company_a)
+        CompanyPersonLink.objects.create(company=self.company_b, person=person)
+
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            response = self.client.post(f"/api/people/{person.id}/archive/")
+
+        self.assertEqual(response.status_code, 200)
+        self.assertFalse(response.json()["is_active"])
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+        self.assertFalse(
+            CompanyPersonLink.objects.filter(person=person, is_active=True).exists()
+        )
diff --git a/apps/company/urls_people_rest.py b/apps/company/urls_people_rest.py
index e956bc35c..e99982d6f 100644
--- a/apps/company/urls_people_rest.py
+++ b/apps/company/urls_people_rest.py
@@ -3,6 +3,7 @@
 from django.urls import path
 
 from apps.company.views.person_views import (
+    PersonArchiveView,
     PersonCompanyLinkDetailView,
     PersonCompanyLinksView,
     PersonContactMethodDetailView,
@@ -36,4 +37,9 @@
         PersonContactMethodDetailView.as_view(),
         name="person_contact_method_detail",
     ),
+    path(
+        "<uuid:person_id>/archive/",
+        PersonArchiveView.as_view(),
+        name="person_archive",
+    ),
 ]
diff --git a/apps/company/views/__init__.py b/apps/company/views/__init__.py
index 584d63562..8f75491e6 100644
--- a/apps/company/views/__init__.py
+++ b/apps/company/views/__init__.py
@@ -13,6 +13,7 @@
 from .person_views import (
     CompanyPeopleView,
     CompanyPersonPhoneOwnershipView,
+    PersonArchiveView,
     PersonCompanyLinkDetailView,
     PersonCompanyLinksView,
     PersonContactMethodDetailView,
@@ -49,6 +50,7 @@
     "CompanyUpdateRestView",
     "ContactMethodViewSet",
     "JobPersonRestView",
+    "PersonArchiveView",
     "PersonCompanyLinkDetailView",
     "PersonCompanyLinksView",
     "PersonContactMethodDetailView",
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
index 488aaca69..e2df1ef59 100644
--- a/apps/company/views/person_views.py
+++ b/apps/company/views/person_views.py
@@ -34,6 +34,7 @@
     PersonCompanyLinkData,
     PersonDirectoryService,
     PersonPhoneConflictError,
+    archive_person,
     classify_phone_ownership,
     create_person_for_company,
     put_company_link,
@@ -203,6 +204,19 @@ def delete(self, request: Request, person_id: str, company_id: str) -> Response:
         return Response(status=status.HTTP_204_NO_CONTENT)
 
 
+class PersonArchiveView(APIView):
+    """Explicitly retire a person (deactivate all links + archive)."""
+
+    permission_classes = PERSON_PERMISSIONS
+
+    @extend_schema(request=None, responses={200: PersonDetailSerializer})
+    def post(self, request: Request, person_id: str) -> Response:
+        person = get_object_or_404(Person, id=person_id)
+        archive_person(person=person)
+        person.refresh_from_db()
+        return Response(PersonDetailSerializer(person).data)
+
+
 def _schedule_contact_method_rematch(method: ContactMethod) -> None:
     if method.method_type != ContactMethod.MethodType.PHONE:
         return
diff --git a/docs/urls/company.md b/docs/urls/company.md
index eb7bfe7e9..f47a5bdaa 100644
--- a/docs/urls/company.md
+++ b/docs/urls/company.md
@@ -12,6 +12,11 @@
 |-------------|------|------|-------------|
 | `/all/` | `company_rest_views.CompanyListAllRestView` | `companies:company_list_all_rest` | REST view for listing all companies. |
 
+### Archive Management
+| URL Pattern | View | Name | Description |
+|-------------|------|------|-------------|
+| `/<uuid:person_id>/archive/` | `person_views.PersonArchiveView` | `people:person_archive` | Explicitly retire a person (deactivate all links + archive). |
+
 ### Company-Defaults Management
 | URL Pattern | View | Name | Description |
 |-------------|------|------|-------------|
diff --git a/frontend/schema.yml b/frontend/schema.yml
index b09a2283a..dc655b895 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -5893,6 +5893,28 @@ paths:
               schema:
                 $ref: '#/components/schemas/PersonIdentityUpdate'
           description: ''
+  /api/people/{person_id}/archive/:
+    post:
+      operationId: people_archive_create
+      description: Explicitly retire a person (deactivate all links + archive).
+      parameters:
+        - in: path
+          name: person_id
+          schema:
+            type: string
+            format: uuid
+          required: true
+      tags:
+        - people
+      security:
+        - cookieAuth: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PersonDetail'
+          description: ''
   /api/people/{person_id}/company-links/:
     get:
       operationId: people_company_links_list
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index defad838d..f8bffeb8c 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -8205,6 +8205,21 @@ POST: Processes selected jobs for month-end archiving and status updates`,
     ],
     response: PersonIdentityUpdate,
   },
+  {
+    method: 'post',
+    path: '/api/people/:person_id/archive/',
+    alias: 'people_archive_create',
+    description: `Explicitly retire a person (deactivate all links + archive).`,
+    requestFormat: 'json',
+    parameters: [
+      {
+        name: 'person_id',
+        type: 'Path',
+        schema: z.string().uuid(),
+      },
+    ],
+    response: PersonDetail,
+  },
   {
     method: 'get',
     path: '/api/people/:person_id/company-links/',

From e31b662fd6a6d319b2f484756b0e94028c8d30fc Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 20:31:23 +1200
Subject: [PATCH 65/73] feat(crm): directory include_archived filter and
 is_active on summaries

---
 apps/company/person_serializers.py      |  2 +-
 apps/company/services/person_service.py | 29 +++++++++++++------------
 apps/company/tests/test_person_api.py   | 23 ++++++++++++++++++++
 apps/company/views/person_views.py      | 16 ++++++++++++--
 frontend/schema.yml                     |  7 ++++++
 frontend/src/api/generated/api.ts       |  6 +++++
 6 files changed, 66 insertions(+), 17 deletions(-)

diff --git a/apps/company/person_serializers.py b/apps/company/person_serializers.py
index 335aab02e..914fa8139 100644
--- a/apps/company/person_serializers.py
+++ b/apps/company/person_serializers.py
@@ -37,7 +37,7 @@ class PersonSummarySerializer(serializers.ModelSerializer[Person]):
 
     class Meta:
         model = Person
-        fields = ["id", "name", "email", "primary_phone", "companies"]
+        fields = ["id", "name", "email", "is_active", "primary_phone", "companies"]
 
     def get_primary_phone(self, person: Person) -> str:
         if "primary_phone" in person.__dict__:
diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index ebe217c7f..af963df30 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -63,21 +63,22 @@ def __init__(self, ownership: PhoneOwnershipResult) -> None:
 
 class PersonDirectoryService:
     @staticmethod
-    def search(query: str) -> QuerySet[Person]:
-        people = (
-            Person.objects.filter(is_active=True)
-            .annotate(
-                primary_phone=ContactMethod.primary_phone_annotation(
-                    owner="person", outer_ref="pk"
-                )
+    def search(query: str, *, include_archived: bool = False) -> QuerySet[Person]:
+        base = (
+            Person.objects.all()
+            if include_archived
+            else Person.objects.filter(is_active=True)
+        )
+        people = base.annotate(
+            primary_phone=ContactMethod.primary_phone_annotation(
+                owner="person", outer_ref="pk"
             )
-            .prefetch_related(
-                Prefetch(
-                    "company_links",
-                    queryset=CompanyPersonLink.objects.filter(
-                        is_active=True
-                    ).select_related("company"),
-                )
+        ).prefetch_related(
+            Prefetch(
+                "company_links",
+                queryset=CompanyPersonLink.objects.filter(
+                    is_active=True
+                ).select_related("company"),
             )
         )
         search = query.strip()
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index 3e7c4524e..0e6c35510 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -333,3 +333,26 @@ def test_archive_person_endpoint_deactivates_links_and_archives(self) -> None:
         self.assertFalse(
             CompanyPersonLink.objects.filter(person=person, is_active=True).exists()
         )
+
+    def test_directory_excludes_archived_by_default(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get("/api/people/")
+        ids = [row["id"] for row in response.json()["results"]]
+        self.assertNotIn(str(person.id), ids)
+
+    def test_directory_includes_archived_when_requested(self) -> None:
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+
+        response = self.client.get("/api/people/", {"include_archived": "true"})
+        rows = {row["id"]: row for row in response.json()["results"]}
+        self.assertIn(str(person.id), rows)
+        self.assertFalse(rows[str(person.id)]["is_active"])
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
index e2df1ef59..712e5bd99 100644
--- a/apps/company/views/person_views.py
+++ b/apps/company/views/person_views.py
@@ -61,14 +61,26 @@ class PersonListView(generics.ListAPIView[Person]):
                 type=OpenApiTypes.STR,
                 location=OpenApiParameter.QUERY,
                 description="Search people by name, email, phone, or company.",
-            )
+            ),
+            OpenApiParameter(
+                name="include_archived",
+                type=OpenApiTypes.BOOL,
+                location=OpenApiParameter.QUERY,
+                description="Include archived (inactive) people in the results.",
+            ),
         ]
     )
     def get(self, request: Request, *args: object, **kwargs: object) -> Response:
         return super().get(request, *args, **kwargs)
 
     def get_queryset(self) -> QuerySet[Person]:
-        return PersonDirectoryService.search(self.request.query_params.get("q", ""))
+        include_archived = (
+            self.request.query_params.get("include_archived", "").lower() == "true"
+        )
+        return PersonDirectoryService.search(
+            self.request.query_params.get("q", ""),
+            include_archived=include_archived,
+        )
 
 
 class PersonDetailView(generics.RetrieveUpdateAPIView[Person]):
diff --git a/frontend/schema.yml b/frontend/schema.yml
index dc655b895..f9bfd47c3 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -5779,6 +5779,11 @@ paths:
       operationId: people_list
       description: List and search active people across company relationships.
       parameters:
+        - in: query
+          name: include_archived
+          schema:
+            type: boolean
+          description: Include archived (inactive) people in the results.
         - name: page
           required: false
           in: query
@@ -18170,6 +18175,8 @@ components:
           format: email
           nullable: true
           maxLength: 254
+        is_active:
+          type: boolean
         primary_phone:
           type: string
           readOnly: true
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index f8bffeb8c..ed5f9732f 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -2508,6 +2508,7 @@ const PersonSummary = z.object({
   id: z.string().uuid(),
   name: z.string().max(255),
   email: z.string().max(254).email().nullish(),
+  is_active: z.boolean().optional(),
   primary_phone: z.string(),
   companies: z.array(PersonCompanySummary),
 })
@@ -8132,6 +8133,11 @@ POST: Processes selected jobs for month-end archiving and status updates`,
     description: `List and search active people across company relationships.`,
     requestFormat: 'json',
     parameters: [
+      {
+        name: 'include_archived',
+        type: 'Query',
+        schema: z.boolean().optional(),
+      },
       {
         name: 'page',
         type: 'Query',

From 424ae3de0efee024a0e616665b30e51ee71d063f Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 20:37:16 +1200
Subject: [PATCH 66/73] feat(crm): show-archived filter and Archived badge in
 people directory

---
 frontend/src/pages/crm/people/(index).vue     | 29 +++++++++-
 .../people/__tests__/people-directory.test.ts | 57 +++++++++++++++++++
 2 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/frontend/src/pages/crm/people/(index).vue b/frontend/src/pages/crm/people/(index).vue
index 3927fbb31..158fefd89 100644
--- a/frontend/src/pages/crm/people/(index).vue
+++ b/frontend/src/pages/crm/people/(index).vue
@@ -59,6 +59,15 @@
             <Button type="button" variant="outline" @click="applySearch">
               <Search class="mr-2 h-4 w-4" /> Search
             </Button>
+            <label class="flex items-center gap-2 text-sm text-gray-600">
+              <input
+                type="checkbox"
+                v-model="includeArchived"
+                data-automation-id="PeopleDirectory-show-archived"
+                @change="applySearch"
+              />
+              Show archived
+            </label>
           </div>
         </CardContent>
       </Card>
@@ -92,7 +101,16 @@
                   :data-automation-id="`PeopleDirectory-row-${person.id}`"
                 >
                   <td class="p-4">
-                    <p class="font-medium text-gray-900">{{ person.name }}</p>
+                    <p class="flex items-center gap-2 font-medium text-gray-900">
+                      {{ person.name }}
+                      <Badge
+                        v-if="person.is_active === false"
+                        variant="secondary"
+                        :data-automation-id="`PeopleDirectory-archived-badge-${person.id}`"
+                      >
+                        Archived
+                      </Badge>
+                    </p>
                     <p class="text-gray-500">{{ person.email || 'No email' }}</p>
                   </td>
                   <td class="p-4 text-gray-700">{{ person.primary_phone || '—' }}</td>
@@ -156,6 +174,7 @@ import { schemas } from '@/api/generated/api'
 import AppLayout from '@/components/AppLayout.vue'
 import CompanyLookup from '@/components/CompanyLookup.vue'
 import PersonSelector from '@/components/PersonSelector.vue'
+import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
@@ -173,6 +192,7 @@ const totalPages = ref(0)
 const count = ref(0)
 const query = ref('')
 const searchInput = ref('')
+const includeArchived = ref(false)
 const showCreate = ref(false)
 const selectedCompany = ref<Company | null>(null)
 const selectedCompanyName = ref('')
@@ -185,7 +205,12 @@ async function loadPeople(): Promise<void> {
   error.value = null
   try {
     const response = await api.people_list({
-      queries: { page: page.value, page_size: 50, q: query.value || undefined },
+      queries: {
+        page: page.value,
+        page_size: 50,
+        q: query.value || undefined,
+        include_archived: includeArchived.value || undefined,
+      },
     })
     if (seq !== loadRequestSeq) return
     people.value = response.results
diff --git a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
index 61c8b699c..f19be0bc0 100644
--- a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
+++ b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
@@ -102,4 +102,61 @@ describe('people directory', () => {
     expect(wrapper.text()).toContain('Bob Searched')
     expect(wrapper.text()).not.toContain('Jane Doe')
   })
+
+  it('shows an Archived badge for inactive people', async () => {
+    const archivedResponse = {
+      results: [
+        {
+          id: '55555555-5555-4555-8555-555555555555',
+          name: 'Archie Ved',
+          email: 'archie@example.com',
+          is_active: false,
+          primary_phone: '021 555 0300',
+          companies: [],
+        },
+      ],
+      count: 1,
+      page: 1,
+      page_size: 50,
+      total_pages: 1,
+    }
+    vi.mocked(api.people_list).mockResolvedValue(archivedResponse)
+
+    const wrapper = mount(PeopleDirectory)
+    await flushPromises()
+
+    expect(
+      wrapper
+        .find(
+          '[data-automation-id="PeopleDirectory-archived-badge-55555555-5555-4555-8555-555555555555"]',
+        )
+        .exists(),
+    ).toBe(true)
+    expect(wrapper.text()).toContain('Archived')
+  })
+
+  it('does not show an Archived badge for active people', async () => {
+    const wrapper = mount(PeopleDirectory)
+    await flushPromises()
+
+    expect(
+      wrapper
+        .find(
+          '[data-automation-id="PeopleDirectory-archived-badge-11111111-1111-4111-8111-111111111111"]',
+        )
+        .exists(),
+    ).toBe(false)
+  })
+
+  it('sends include_archived when the show-archived checkbox is toggled on', async () => {
+    const wrapper = mount(PeopleDirectory)
+    await flushPromises()
+
+    await wrapper.find('[data-automation-id="PeopleDirectory-show-archived"]').setValue(true)
+    await flushPromises()
+
+    expect(api.people_list).toHaveBeenLastCalledWith({
+      queries: { page: 1, page_size: 50, q: undefined, include_archived: true },
+    })
+  })
 })

From 4db39590768e99aa644f6ea068586801f522e8d1 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 20:45:25 +1200
Subject: [PATCH 67/73] fix(crm): make Person is_active a required field in the
 response contract

PersonSummary/PersonDetail are response-only serializers and always emit
is_active, but ModelSerializer inferred required=False from the model's
BooleanField(default=True), so the schema marked it optional and the generated
zod rendered `is_active: z.boolean().optional()`. The type lied about the
contract (ADR 0028), and `!person.is_active` on an absent field would badge
every row as archived.

Declare is_active explicitly on PersonSummarySerializer so the schema lists it
as required; PersonDetailSerializer inherits it. The generated client now has
`is_active: z.boolean()`.

Drops the `=== false` workaround in the directory badge, and fixes the
directory test fixture that omitted is_active (not a valid PersonSummary).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/company/person_serializers.py                          | 6 ++++++
 frontend/schema.yml                                         | 2 ++
 frontend/src/api/generated/api.ts                           | 4 ++--
 frontend/src/pages/crm/people/(index).vue                   | 2 +-
 .../src/pages/crm/people/__tests__/people-directory.test.ts | 1 +
 5 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/apps/company/person_serializers.py b/apps/company/person_serializers.py
index 914fa8139..5707e50ee 100644
--- a/apps/company/person_serializers.py
+++ b/apps/company/person_serializers.py
@@ -32,6 +32,12 @@ class PersonCompanySummarySerializer(serializers.Serializer[dict[str, str]]):
 
 
 class PersonSummarySerializer(serializers.ModelSerializer[Person]):
+    # Declared explicitly so the response contract says always-present. The
+    # ModelSerializer default would infer required=False from the model default,
+    # which renders as optional in the schema even though every row carries it.
+    # These serializers are response-only; identity writes use
+    # PersonIdentityUpdateSerializer.
+    is_active = serializers.BooleanField()
     primary_phone = serializers.SerializerMethodField()
     companies = serializers.SerializerMethodField()
 
diff --git a/frontend/schema.yml b/frontend/schema.yml
index f9bfd47c3..c67e5d0f5 100644
--- a/frontend/schema.yml
+++ b/frontend/schema.yml
@@ -18134,6 +18134,7 @@ components:
         - company_links
         - created_at
         - id
+        - is_active
         - name
         - primary_phone
         - updated_at
@@ -18188,6 +18189,7 @@ components:
       required:
         - companies
         - id
+        - is_active
         - name
         - primary_phone
     PhoneCallJobLinkRequest:
diff --git a/frontend/src/api/generated/api.ts b/frontend/src/api/generated/api.ts
index ed5f9732f..ca24aaa96 100644
--- a/frontend/src/api/generated/api.ts
+++ b/frontend/src/api/generated/api.ts
@@ -2508,7 +2508,7 @@ const PersonSummary = z.object({
   id: z.string().uuid(),
   name: z.string().max(255),
   email: z.string().max(254).email().nullish(),
-  is_active: z.boolean().optional(),
+  is_active: z.boolean(),
   primary_phone: z.string(),
   companies: z.array(PersonCompanySummary),
 })
@@ -2523,7 +2523,7 @@ const PersonDetail = z.object({
   id: z.string().uuid(),
   name: z.string().max(255),
   email: z.string().max(254).email().nullish(),
-  is_active: z.boolean().optional(),
+  is_active: z.boolean(),
   created_at: z.string().datetime({ offset: true }),
   updated_at: z.string().datetime({ offset: true }),
   primary_phone: z.string(),
diff --git a/frontend/src/pages/crm/people/(index).vue b/frontend/src/pages/crm/people/(index).vue
index 158fefd89..9d2ddc60f 100644
--- a/frontend/src/pages/crm/people/(index).vue
+++ b/frontend/src/pages/crm/people/(index).vue
@@ -104,7 +104,7 @@
                     <p class="flex items-center gap-2 font-medium text-gray-900">
                       {{ person.name }}
                       <Badge
-                        v-if="person.is_active === false"
+                        v-if="!person.is_active"
                         variant="secondary"
                         :data-automation-id="`PeopleDirectory-archived-badge-${person.id}`"
                       >
diff --git a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
index f19be0bc0..78478bf66 100644
--- a/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
+++ b/frontend/src/pages/crm/people/__tests__/people-directory.test.ts
@@ -16,6 +16,7 @@ const response = {
       id: '11111111-1111-4111-8111-111111111111',
       name: 'Jane Doe',
       email: 'jane@example.com',
+      is_active: true,
       primary_phone: '021 555 0100',
       companies: [
         {

From ccb29117f8f17eb2d28253c664519d3970d04bb2 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 20:51:44 +1200
Subject: [PATCH 68/73] feat(crm): archived badge and Archive-person button on
 PersonDetail

Adds an "Archived" badge and Archive-person action to the person
detail page, and makes restoreLink refresh the full person (not just
company links) so the badge clears after un-archiving via link
restore.
---
 frontend/src/pages/crm/people/[id].vue        | 38 ++++++++++++++++++-
 .../people/__tests__/person-detail.test.ts    | 29 ++++++++++++++
 2 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/frontend/src/pages/crm/people/[id].vue b/frontend/src/pages/crm/people/[id].vue
index 1097bf6d1..64638e87f 100644
--- a/frontend/src/pages/crm/people/[id].vue
+++ b/frontend/src/pages/crm/people/[id].vue
@@ -6,11 +6,32 @@
           <ArrowLeft class="mr-2 h-4 w-4" /> People
         </Button>
         <div>
-          <h1 class="text-3xl font-bold text-gray-900">{{ person?.name || 'Person' }}</h1>
+          <div class="flex items-center gap-2">
+            <h1 class="text-3xl font-bold text-gray-900">{{ person?.name || 'Person' }}</h1>
+            <Badge
+              v-if="person && !person.is_active"
+              variant="secondary"
+              data-automation-id="PersonDetail-archived-badge"
+            >
+              Archived
+            </Badge>
+          </div>
           <p class="text-sm text-gray-600">
             Manage identity, contact methods, and company relationships.
           </p>
         </div>
+        <Button
+          v-if="person && person.is_active"
+          type="button"
+          variant="outline"
+          size="sm"
+          class="ml-auto"
+          :disabled="archiving"
+          data-automation-id="PersonDetail-archive"
+          @click="archivePerson"
+        >
+          Archive person
+        </Button>
       </header>
 
       <div v-if="loading" class="flex min-h-64 items-center justify-center text-gray-500">
@@ -284,6 +305,7 @@ const linkCompanyName = ref('')
 const linkPosition = ref('')
 const linkNotes = ref('')
 const linkPrimary = ref(false)
+const archiving = ref(false)
 
 async function loadPerson(): Promise<void> {
   loading.value = true
@@ -428,12 +450,24 @@ async function restoreLink(link: PersonCompanyLink): Promise<void> {
       { position: link.position, notes: link.notes, is_primary: link.is_primary },
       { params: { person_id: props.id, company_id: link.company_id } },
     )
-    companyLinks.value = await api.people_company_links_list({ params: { person_id: props.id } })
+    await loadPerson()
     toast.success('Company link restored')
   } catch (err) {
     toast.error(`Company link not restored: ${extractErrorMessage(err)}`)
   }
 }
+async function archivePerson(): Promise<void> {
+  archiving.value = true
+  try {
+    await api.people_archive_create(undefined, { params: { person_id: props.id } })
+    toast.success('Person archived')
+    await loadPerson()
+  } catch (err) {
+    toast.error(err instanceof Error ? err.message : 'Failed to archive person')
+  } finally {
+    archiving.value = false
+  }
+}
 function openCompany(companyId: string): void {
   router.push({ name: '/crm/companies/[id]', params: { id: companyId } })
 }
diff --git a/frontend/src/pages/crm/people/__tests__/person-detail.test.ts b/frontend/src/pages/crm/people/__tests__/person-detail.test.ts
index 59aecc894..700d357ac 100644
--- a/frontend/src/pages/crm/people/__tests__/person-detail.test.ts
+++ b/frontend/src/pages/crm/people/__tests__/person-detail.test.ts
@@ -12,6 +12,7 @@ vi.mock('@/api/client', () => ({
     people_company_links_list: vi.fn(),
     people_company_links_update: vi.fn(),
     people_company_links_destroy: vi.fn(),
+    people_archive_create: vi.fn(),
   },
 }))
 vi.mock('@/components/AppLayout.vue', () => ({ default: { template: '<div><slot /></div>' } }))
@@ -118,4 +119,32 @@ describe('person detail', () => {
     expect(wrapper.text()).not.toContain('Inactive')
     expect(api.people_company_links_list).toHaveBeenCalledOnce()
   })
+
+  it('archives an active person and shows the archived badge', async () => {
+    vi.mocked(api.people_archive_create).mockResolvedValue(undefined)
+    const wrapper = mount(PersonDetailPage, { props: { id: personId } })
+    await flushPromises()
+
+    expect(wrapper.find('[data-automation-id="PersonDetail-archived-badge"]').exists()).toBe(false)
+    vi.mocked(api.people_retrieve).mockResolvedValue({ ...person, is_active: false })
+
+    await wrapper.find('[data-automation-id="PersonDetail-archive"]').trigger('click')
+    await flushPromises()
+
+    expect(api.people_archive_create).toHaveBeenCalledWith(undefined, {
+      params: { person_id: personId },
+    })
+    expect(toast.success).toHaveBeenCalledWith('Person archived')
+    expect(wrapper.find('[data-automation-id="PersonDetail-archived-badge"]').exists()).toBe(true)
+    expect(wrapper.find('[data-automation-id="PersonDetail-archive"]').exists()).toBe(false)
+  })
+
+  it('does not show the archive button for an already-archived person', async () => {
+    vi.mocked(api.people_retrieve).mockResolvedValue({ ...person, is_active: false })
+    const wrapper = mount(PersonDetailPage, { props: { id: personId } })
+    await flushPromises()
+
+    expect(wrapper.find('[data-automation-id="PersonDetail-archived-badge"]').exists()).toBe(true)
+    expect(wrapper.find('[data-automation-id="PersonDetail-archive"]').exists()).toBe(false)
+  })
 })

From 39f84a1156a204906f7a51ee782af4d2ac9bf5ff Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 20:59:35 +1200
Subject: [PATCH 69/73] =?UTF-8?q?test(crm):=20e2e=20for=20archive=20?=
 =?UTF-8?q?=E2=86=92=20show-archived=20=E2=86=92=20restore?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/tests/crm/people-archive.spec.ts | 83 +++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 frontend/tests/crm/people-archive.spec.ts

diff --git a/frontend/tests/crm/people-archive.spec.ts b/frontend/tests/crm/people-archive.spec.ts
new file mode 100644
index 000000000..0dc0a3b6e
--- /dev/null
+++ b/frontend/tests/crm/people-archive.spec.ts
@@ -0,0 +1,83 @@
+import { expect, test } from '../fixtures/auth'
+import { autoId, waitForCompanyCreateResponse } from '../fixtures/helpers'
+
+async function createCompany(page: Parameters<typeof autoId>[0], companyName: string) {
+  const input = autoId(page, 'CompanyLookup-input')
+  await input.fill(companyName)
+  await autoId(page, 'CompanyLookup-results').waitFor({ timeout: 10000 })
+  await waitForCompanyCreateResponse(page, async () => {
+    await input.press('Control+Enter')
+  })
+  await expect(input).toHaveValue(companyName)
+}
+
+async function createPersonForSelectedCompany(
+  page: Parameters<typeof autoId>[0],
+  name: string,
+  phone: string,
+) {
+  await autoId(page, 'PersonSelector-modal-button').click()
+  await autoId(page, 'PersonSelectionModal-container').waitFor()
+  await autoId(page, 'PersonSelectionModal-name-input').fill(name)
+  await autoId(page, 'PersonSelectionModal-phone-input').fill(phone)
+  await autoId(page, 'PersonSelectionModal-submit').click()
+  await autoId(page, 'PersonSelectionModal-container').waitFor({ state: 'hidden' })
+}
+
+test.describe('people archive lifecycle', () => {
+  test('archived person is hidden by default, findable via filter, and restorable', async ({
+    authenticatedPage: page,
+  }) => {
+    const suffix = Math.floor(Math.random() * 1_000_000)
+    const companyName = `[TEST] Archive Company ${suffix}`
+    const personName = `[TEST] Archive Person ${suffix}`
+
+    // Create a single-company person, then archive by removing their only link.
+    await page.goto('/crm/people')
+    await autoId(page, 'PeopleDirectory-create').click()
+    await createCompany(page, companyName)
+    await createPersonForSelectedCompany(page, personName, `0219${String(suffix).padStart(6, '0')}`)
+
+    await autoId(page, 'PeopleDirectory-search').fill(personName)
+    await autoId(page, 'PeopleDirectory-search').press('Enter')
+    const row = page
+      .locator('[data-automation-id^="PeopleDirectory-row-"]')
+      .filter({ hasText: personName })
+    await row.getByRole('button', { name: 'Manage' }).click()
+
+    const link = page
+      .locator('[data-automation-id^="PersonDetail-company-link-"]')
+      .filter({ hasText: companyName })
+    const linkId = (await link.getAttribute('data-automation-id'))!.replace(
+      'PersonDetail-company-link-',
+      '',
+    )
+    page.once('dialog', (d) => d.accept())
+    await autoId(page, `PersonDetail-remove-link-${linkId}`).click()
+    await expect(autoId(page, 'PersonDetail-archived-badge')).toBeVisible()
+
+    // Hidden from default directory search.
+    await page.goto('/crm/people')
+    await autoId(page, 'PeopleDirectory-search').fill(personName)
+    await autoId(page, 'PeopleDirectory-search').press('Enter')
+    await expect(
+      page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName }),
+    ).toHaveCount(0)
+
+    // Visible with the show-archived filter.
+    await autoId(page, 'PeopleDirectory-show-archived').check()
+    await expect(
+      page.locator('[data-automation-id^="PeopleDirectory-row-"]').filter({ hasText: personName }),
+    ).toHaveCount(1)
+
+    // Restore brings them back active.
+    await page
+      .locator('[data-automation-id^="PeopleDirectory-row-"]')
+      .filter({ hasText: personName })
+      .getByRole('button', { name: 'Manage' })
+      .click()
+    await autoId(page, `PersonDetail-restore-link-${linkId}`).click()
+    await expect(link).toContainText('Active')
+    await expect(autoId(page, 'PersonDetail-archived-badge')).toHaveCount(0)
+  })
+})

From 446ff8990c6d2726e13c88e2f0f960a36037bee9 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 21:07:43 +1200
Subject: [PATCH 70/73] fix: complete exception dedup in Xero document managers

Address CodeRabbit review on #464.

The managers are service objects, not the HTTP boundary: the view is, and
it already converts AlreadyLoggedException into a 500 carrying error_id.
Their generic arms persisted then returned an error dict, so that path was
unreachable. Re-raise instead (ADR 0001), which also fixes real bugs:

- Unexpected server errors were reported to the frontend as HTTP 400: the
  manager set "status": 500 but the view ignores it and hardcodes 400.
- The dict path dropped error_id, which ADR 0013 requires.

Expected business failures still return success: False dicts -> 4xx. Only
unexpected exceptions raise.

Also fixes, found while verifying:

- delete_document on both managers had no AlreadyLoggedException arm at all,
  so its bare except re-persisted an already-persisted failure. That is the
  double-persistence ADR 0001 exists to prevent. CodeRabbit missed this.
- xero_quote_manager.delete_document returned "messages" as a list of dicts,
  but XeroDocumentSuccessResponseSerializer declares ListField(CharField());
  DRF rejects a dict, so that path raised on serialization. Fixed the
  producer to match the contract (ADR 0015).
- Four tests never configured xero_sales_branding_theme_id and so failed
  against the mandatory theme guard this PR added.
- xero_view: chain the fallback AssertionError with `from exc` (Ruff B904).

ADR 0001 gains an explicit chain-termination clause: the silence about where
the chain ends is what made this review ambiguous.

Views now pass message= to _build_xero_error_payload so the underlying
exception text survives the move to the raise path (ADR 0013).

Typing: create_document/delete_document now return a named XeroDocumentResponse
TypedDict rather than being unannotated (ADR 0028). It is what surfaced the
messages contract bug. mypy-baseline shrinks by 8.

Frontend: the branding-theme E2E asserted the selector was enabled before the
no-themes skip could run, but an empty theme list is exactly when the control
stays disabled by design, so the test timed out instead of skipping. Wait for
the load to settle, fail on the error marker, skip on the empty marker, then
assert enabled.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../tests/test_xero_branding_themes.py        |   8 +-
 .../test_xero_document_error_handling.py      | 160 ++++++++++++++++++
 .../tests/test_xero_document_raw_json.py      |   9 +
 .../tests/test_xero_readonly_provider.py      |  11 +-
 apps/workflow/views/xero/__init__.py          |   3 +-
 apps/workflow/views/xero/xero_base_manager.py |  24 +++
 .../views/xero/xero_invoice_manager.py        |  28 ++-
 .../workflow/views/xero/xero_quote_manager.py |  31 ++--
 apps/workflow/views/xero/xero_view.py         |  30 +++-
 .../0001-exception-already-logged-dedup.md    |   2 +
 frontend/tests/company-defaults.spec.ts       |  34 +++-
 mypy-baseline.txt                             |   8 -
 12 files changed, 284 insertions(+), 64 deletions(-)
 create mode 100644 apps/workflow/tests/test_xero_document_error_handling.py

diff --git a/apps/workflow/tests/test_xero_branding_themes.py b/apps/workflow/tests/test_xero_branding_themes.py
index bfc3530df..2147f8818 100644
--- a/apps/workflow/tests/test_xero_branding_themes.py
+++ b/apps/workflow/tests/test_xero_branding_themes.py
@@ -175,7 +175,9 @@ def test_invoice_creation_stops_when_theme_is_unconfigured(self) -> None:
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Configure the Xero sales branding theme", result["error"])
+        error = result["error"]
+        assert error is not None
+        self.assertIn("Configure the Xero sales branding theme", error)
         manager.provider.list_document_themes.assert_not_called()
         manager.provider.create_invoice.assert_not_called()
         self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
@@ -192,7 +194,9 @@ def test_quote_creation_stops_when_theme_is_unconfigured(self) -> None:
         self.assertFalse(result["success"])
         self.assertEqual(result["status"], 400)
         self.assertEqual(result["error_type"], "configuration_error")
-        self.assertIn("Configure the Xero sales branding theme", result["error"])
+        error = result["error"]
+        assert error is not None
+        self.assertIn("Configure the Xero sales branding theme", error)
         manager.provider.list_document_themes.assert_not_called()
         manager.provider.create_quote.assert_not_called()
         self.assertIsNone(CompanyDefaults.get_solo().xero_sales_branding_theme_id)
diff --git a/apps/workflow/tests/test_xero_document_error_handling.py b/apps/workflow/tests/test_xero_document_error_handling.py
new file mode 100644
index 000000000..5591e6d04
--- /dev/null
+++ b/apps/workflow/tests/test_xero_document_error_handling.py
@@ -0,0 +1,160 @@
+"""Error contract for Xero document managers.
+
+The managers are service objects, not the HTTP boundary (ADR 0001): an
+unexpected exception is persisted once and re-raised as AlreadyLoggedException
+for the view to convert into a 500 carrying ``error_id``. Only *expected*
+business outcomes come back as ``success: False`` dicts.
+"""
+
+import uuid
+from decimal import Decimal
+from unittest.mock import Mock, patch
+
+from django.utils import timezone
+
+from apps.company.models import Company
+from apps.job.models import Job
+from apps.testing import BaseTestCase
+from apps.workflow.exceptions import AlreadyLoggedException
+from apps.workflow.models import AppError, CompanyDefaults
+from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
+from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
+
+THEME_ID = "11111111-2222-3333-4444-555555555555"
+
+
+class XeroDocumentManagerErrorContractTests(BaseTestCase):
+    """Unexpected provider failures re-raise once; they never become a dict."""
+
+    def setUp(self) -> None:
+        defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_sales_branding_theme_id=uuid.UUID(THEME_ID)
+        )
+        CompanyDefaults.clear_cache()
+
+        self.company = Company.objects.create(
+            name="Error Contract Company",
+            xero_contact_id=str(uuid.uuid4()),
+            xero_last_modified=timezone.now(),
+        )
+        self.job = Job(
+            company=self.company,
+            name="Error Contract Job",
+            pricing_methodology="fixed_price",
+        )
+        self.job.save(staff=self.test_staff)
+
+    def _invoice_manager(self) -> tuple[XeroInvoiceManager, Mock]:
+        """Return the manager plus a handle on its mocked provider."""
+        manager = XeroInvoiceManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        provider = Mock()
+        manager.provider = provider
+        return manager, provider
+
+    def _quote_manager(self) -> tuple[XeroQuoteManager, Mock]:
+        manager = XeroQuoteManager(
+            company=self.company, job=self.job, staff=self.test_staff
+        )
+        provider = Mock()
+        manager.provider = provider
+        return manager, provider
+
+    # --- create -----------------------------------------------------------
+
+    def test_invoice_create_reraises_already_logged(self) -> None:
+        """A Xero blow-up must reach the view as AlreadyLoggedException, not a dict."""
+        manager, provider = self._invoice_manager()
+        provider.create_invoice.side_effect = RuntimeError("Xero exploded")
+
+        with patch.object(XeroInvoiceManager, "build_payload", return_value=Mock()):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.create_document(total_amount=Decimal("100"))
+
+        self.assertIsNotNone(caught.exception.app_error_id)
+        self.assertEqual(str(caught.exception), "Xero exploded")
+        self.assertEqual(AppError.objects.count(), 1)
+
+    def test_quote_create_reraises_already_logged(self) -> None:
+        manager, provider = self._quote_manager()
+        provider.create_quote.side_effect = RuntimeError("Xero exploded")
+
+        with patch.object(XeroQuoteManager, "build_payload", return_value=Mock()):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.create_document()
+
+        self.assertIsNotNone(caught.exception.app_error_id)
+        self.assertEqual(AppError.objects.count(), 1)
+
+    # --- delete -----------------------------------------------------------
+
+    def test_invoice_delete_reraises_already_logged(self) -> None:
+        manager, provider = self._invoice_manager()
+        provider.delete_invoice.side_effect = RuntimeError("Xero exploded")
+
+        with patch.object(XeroInvoiceManager, "get_xero_id", return_value="xero-1"):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.delete_document()
+
+        self.assertIsNotNone(caught.exception.app_error_id)
+        self.assertEqual(AppError.objects.count(), 1)
+
+    def test_quote_delete_reraises_already_logged(self) -> None:
+        manager, provider = self._quote_manager()
+        provider.delete_quote.side_effect = RuntimeError("Xero exploded")
+
+        with patch.object(XeroQuoteManager, "get_xero_id", return_value="xero-1"):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.delete_document()
+
+        self.assertIsNotNone(caught.exception.app_error_id)
+        self.assertEqual(AppError.objects.count(), 1)
+
+    # --- dedup regression guard ------------------------------------------
+
+    def test_invoice_delete_does_not_double_persist(self) -> None:
+        """The delete path once lacked the pass-through arm and re-persisted."""
+        original = RuntimeError("Persisted upstream")
+        already_logged = AlreadyLoggedException(original, uuid.uuid4())
+
+        manager, provider = self._invoice_manager()
+        provider.delete_invoice.side_effect = already_logged
+
+        with patch.object(XeroInvoiceManager, "get_xero_id", return_value="xero-1"):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.delete_document()
+
+        self.assertIs(caught.exception, already_logged)
+        self.assertEqual(AppError.objects.count(), 0)
+
+    def test_quote_delete_does_not_double_persist(self) -> None:
+        original = RuntimeError("Persisted upstream")
+        already_logged = AlreadyLoggedException(original, uuid.uuid4())
+
+        manager, provider = self._quote_manager()
+        provider.delete_quote.side_effect = already_logged
+
+        with patch.object(XeroQuoteManager, "get_xero_id", return_value="xero-1"):
+            with self.assertRaises(AlreadyLoggedException) as caught:
+                manager.delete_document()
+
+        self.assertIs(caught.exception, already_logged)
+        self.assertEqual(AppError.objects.count(), 0)
+
+    # --- expected failures still return a dict ----------------------------
+
+    def test_expected_provider_failure_still_returns_dict(self) -> None:
+        """A declined Xero call is a business outcome, not an exception."""
+        manager, provider = self._invoice_manager()
+        provider.create_invoice.return_value = Mock(
+            success=False, error="Contact is archived", status_code=400
+        )
+
+        with patch.object(XeroInvoiceManager, "build_payload", return_value=Mock()):
+            result = manager.create_document(total_amount=Decimal("100"))
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["status"], 400)
+        self.assertEqual(AppError.objects.count(), 0)
diff --git a/apps/workflow/tests/test_xero_document_raw_json.py b/apps/workflow/tests/test_xero_document_raw_json.py
index f9f41b018..70b4bbaef 100644
--- a/apps/workflow/tests/test_xero_document_raw_json.py
+++ b/apps/workflow/tests/test_xero_document_raw_json.py
@@ -7,6 +7,7 @@
 from apps.job.models import Job
 from apps.testing import BaseTestCase
 from apps.workflow.accounting.types import DocumentResult
+from apps.workflow.models import CompanyDefaults
 from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
 
@@ -44,6 +45,14 @@ def setUp(self):
             pricing_methodology="fixed_price",
             staff=self.test_staff,
         )
+        # Sales documents require a configured branding theme before any
+        # provider call; without it create_document stops at the config guard.
+        defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_sales_branding_theme_id=uuid.uuid4()
+        )
+        CompanyDefaults.clear_cache()
+        self.addCleanup(CompanyDefaults.clear_cache)
 
     def test_created_invoice_stores_canonical_raw_json_dict(self):
         raw_response = {
diff --git a/apps/workflow/tests/test_xero_readonly_provider.py b/apps/workflow/tests/test_xero_readonly_provider.py
index 4fe495cad..6a40a94e9 100644
--- a/apps/workflow/tests/test_xero_readonly_provider.py
+++ b/apps/workflow/tests/test_xero_readonly_provider.py
@@ -20,7 +20,7 @@
 from apps.workflow.accounting.types import DocumentLineItem, POPayload
 from apps.workflow.accounting.xero.provider import XeroAccountingProvider
 from apps.workflow.accounting.xero.readonly_provider import XeroReadOnlyProvider
-from apps.workflow.models import AppError, XeroAccount, XeroApp
+from apps.workflow.models import AppError, CompanyDefaults, XeroAccount, XeroApp
 from apps.workflow.views.xero.xero_invoice_manager import XeroInvoiceManager
 from apps.workflow.views.xero.xero_quote_manager import XeroQuoteManager
 
@@ -119,6 +119,15 @@ def setUp(self) -> None:
             xero_last_modified=timezone.now(),
             raw_json={},
         )
+        # Sales documents require a configured branding theme before any
+        # provider call; without it create_document stops at the config guard.
+        defaults = CompanyDefaults.get_solo()
+        CompanyDefaults.objects.filter(pk=defaults.pk).update(
+            xero_sales_branding_theme_id=uuid.uuid4()
+        )
+        CompanyDefaults.clear_cache()
+        self.addCleanup(CompanyDefaults.clear_cache)
+
         self._api_patcher = patch.object(
             XeroAccountingProvider, "_get_api", side_effect=_API_FORBIDDEN
         )
diff --git a/apps/workflow/views/xero/__init__.py b/apps/workflow/views/xero/__init__.py
index 937eb8503..ffc5d528f 100644
--- a/apps/workflow/views/xero/__init__.py
+++ b/apps/workflow/views/xero/__init__.py
@@ -40,7 +40,7 @@
     from django.apps import apps
 
     if apps.ready:
-        from .xero_base_manager import XeroDocumentManager
+        from .xero_base_manager import XeroDocumentManager, XeroDocumentResponse
         from .xero_invoice_manager import XeroInvoiceManager
         from .xero_po_manager import XeroPurchaseOrderManager
         from .xero_quote_manager import XeroQuoteManager
@@ -51,6 +51,7 @@
 __all__ = [
     "XeroAuthenticationResult",
     "XeroDocumentManager",
+    "XeroDocumentResponse",
     "XeroErrorDetailAPIView",
     "XeroErrorListAPIView",
     "XeroIndexView",
diff --git a/apps/workflow/views/xero/xero_base_manager.py b/apps/workflow/views/xero/xero_base_manager.py
index a2f1d130e..fad2a5d80 100644
--- a/apps/workflow/views/xero/xero_base_manager.py
+++ b/apps/workflow/views/xero/xero_base_manager.py
@@ -1,6 +1,7 @@
 # workflow/views/xero/xero_base_manager.py
 import logging
 from abc import ABC, abstractmethod
+from typing import TypedDict
 
 from apps.accounts.models import Staff
 from apps.company.models import Company
@@ -14,6 +15,29 @@
 logger = logging.getLogger("xero")
 
 
+class XeroDocumentResponse(TypedDict, total=False):
+    """Outcome of a document operation, as consumed by the Xero views.
+
+    Only *expected* outcomes travel as a value: success, or a business failure
+    the caller renders as a 4xx. Unexpected exceptions are persisted once and
+    re-raised as ``AlreadyLoggedException`` (ADR 0001) — they never appear here.
+    ``success`` is present on every response.
+    """
+
+    success: bool
+    error: str | None
+    error_type: str
+    status: int
+    invoice_id: str
+    xero_id: str | None
+    company: str
+    total_excl_tax: str
+    total_incl_tax: str
+    online_url: str | None
+    message: str
+    messages: list[str]
+
+
 class XeroDocumentManager(ABC):
     """
     Base class for managing Xero Documents (Invoices, Quotes, Purchase Orders).
diff --git a/apps/workflow/views/xero/xero_invoice_manager.py b/apps/workflow/views/xero/xero_invoice_manager.py
index 3a81e55b6..ce1101255 100644
--- a/apps/workflow/views/xero/xero_invoice_manager.py
+++ b/apps/workflow/views/xero/xero_invoice_manager.py
@@ -20,7 +20,7 @@
 from apps.workflow.services.error_persistence import persist_app_error
 
 # Import base class and helpers
-from .xero_base_manager import XeroDocumentManager
+from .xero_base_manager import XeroDocumentManager, XeroDocumentResponse
 from .xero_helpers import sanitize_for_xero
 
 logger = logging.getLogger("xero")
@@ -200,7 +200,7 @@ def create_document(
         self,
         total_amount: Decimal | None = None,
         billing_metadata: dict | None = None,
-    ):
+    ) -> XeroDocumentResponse:
         """Creates an invoice via the provider, processes result, and stores locally.
 
         Args:
@@ -313,7 +313,7 @@ def create_document(
                     f"Failed to create job event for invoice creation: {exc}"
                 )
 
-            result_dict = {
+            result_dict: XeroDocumentResponse = {
                 "success": True,
                 "invoice_id": str(invoice.id),
                 "xero_id": result.external_id,
@@ -329,19 +329,14 @@ def create_document(
         except AlreadyLoggedException:
             raise
         except Exception as exc:
-            persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
             logger.exception(
                 f"Unexpected error during invoice creation for job {job_id}"
             )
-            return {
-                "success": False,
-                "error": f"An unexpected error occurred ({str(exc)}) while creating "
-                f"the invoice. Please contact support to check the data sent.",
-                "status": 500,
-            }
+            err = persist_app_error(exc, job_id=str(job_id))
+            raise AlreadyLoggedException(exc, err.id) from exc
 
-    def delete_document(self):
+    def delete_document(self) -> XeroDocumentResponse:
         """Deletes an invoice via the provider and removes the local record."""
         try:
             self.validate_company()
@@ -391,15 +386,12 @@ def delete_document(self):
                 "message": "Invoice deleted successfully.",
             }
 
+        except AlreadyLoggedException:
+            raise
         except Exception as exc:
-            persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
             logger.exception(
                 f"Unexpected error during invoice deletion for job {job_id}"
             )
-            return {
-                "success": False,
-                "error": f"An unexpected error occurred ({str(exc)}) while deleting "
-                f"the invoice. Please contact support.",
-                "status": 500,
-            }
+            err = persist_app_error(exc, job_id=str(job_id))
+            raise AlreadyLoggedException(exc, err.id) from exc
diff --git a/apps/workflow/views/xero/xero_quote_manager.py b/apps/workflow/views/xero/xero_quote_manager.py
index d03664290..9187960e4 100644
--- a/apps/workflow/views/xero/xero_quote_manager.py
+++ b/apps/workflow/views/xero/xero_quote_manager.py
@@ -21,7 +21,7 @@
 from apps.workflow.services.error_persistence import persist_app_error
 
 # Import base class and helpers
-from .xero_base_manager import XeroDocumentManager
+from .xero_base_manager import XeroDocumentManager, XeroDocumentResponse
 from .xero_helpers import sanitize_for_xero
 
 logger = logging.getLogger("xero")
@@ -155,7 +155,7 @@ def build_payload(
             ),
         )
 
-    def create_document(self, breakdown: bool = True):
+    def create_document(self, breakdown: bool = True) -> XeroDocumentResponse:
         """
         Creates a quote via the provider, processes result, stores locally.
 
@@ -245,17 +245,12 @@ def create_document(self, breakdown: bool = True):
         except AlreadyLoggedException:
             raise
         except Exception as exc:
-            persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
             logger.exception(f"Unexpected error during quote creation for job {job_id}")
-            return {
-                "success": False,
-                "error": f"An unexpected error occurred ({str(exc)}) while creating "
-                f"the quote. Please contact support.",
-                "status": 500,
-            }
+            err = persist_app_error(exc, job_id=str(job_id))
+            raise AlreadyLoggedException(exc, err.id) from exc
 
-    def delete_document(self):
+    def delete_document(self) -> XeroDocumentResponse:
         """Deletes a quote via the provider and removes the local record."""
         try:
             self.validate_company()
@@ -278,10 +273,7 @@ def delete_document(self):
                     "success": True,
                     "xero_id": xero_id,
                     "messages": [
-                        {
-                            "level": "info",
-                            "message": "No local quote to delete, remote operation succeeded.",
-                        }
+                        "No local quote to delete, remote operation succeeded."
                     ],
                 }
 
@@ -318,13 +310,10 @@ def delete_document(self):
                 "messages": ["Quote deleted successfully."],
             }
 
+        except AlreadyLoggedException:
+            raise
         except Exception as exc:
-            persist_app_error(exc)
             job_id = self.job.id if self.job else "Unknown"
             logger.exception(f"Unexpected error during quote deletion for job {job_id}")
-            return {
-                "success": False,
-                "error": f"An unexpected error occurred ({str(exc)}) while deleting "
-                f"the quote. Please contact support.",
-                "status": 500,
-            }
+            err = persist_app_error(exc, job_id=str(job_id))
+            raise AlreadyLoggedException(exc, err.id) from exc
diff --git a/apps/workflow/views/xero/xero_view.py b/apps/workflow/views/xero/xero_view.py
index f3e3f145e..169c92f5d 100644
--- a/apps/workflow/views/xero/xero_view.py
+++ b/apps/workflow/views/xero/xero_view.py
@@ -540,7 +540,11 @@ def create_xero_invoice(request: Request, job_id: uuid.UUID) -> Response:
         messages.error(request, str(exc))
         return Response(error_data, status=status.HTTP_400_BAD_REQUEST)
     except AlreadyLoggedException as exc:
-        error_data = _build_xero_error_payload(exc)
+        error_data = _build_xero_error_payload(
+            exc,
+            message=f"An unexpected error occurred ({exc}) while creating "
+            "the invoice. Please contact support to check the data sent.",
+        )
         messages.error(request, "An unexpected error occurred while creating invoice.")
         return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
     except Exception as exc:
@@ -778,7 +782,11 @@ def create_xero_quote(request: Request, job_id: uuid.UUID) -> Response:
         error_data = {"success": False, "error": f"Job with ID {job_id} not found."}
         return Response(error_data, status=status.HTTP_404_NOT_FOUND)
     except AlreadyLoggedException as exc:
-        error_data = _build_xero_error_payload(exc)
+        error_data = _build_xero_error_payload(
+            exc,
+            message=f"An unexpected error occurred ({exc}) while creating "
+            "the quote. Please contact support.",
+        )
         return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
     except Exception as exc:
         try:
@@ -836,7 +844,7 @@ def delete_xero_invoice(request: Request, job_id: uuid.UUID) -> Response:
             staff=request.user,
             xero_invoice_id=invoice.xero_id,
         )
-        result_data: dict = manager.delete_document()
+        result_data = manager.delete_document()
 
         if result_data.get("success"):
             messages.success(request, "Invoice deleted successfully.")
@@ -861,7 +869,11 @@ def delete_xero_invoice(request: Request, job_id: uuid.UUID) -> Response:
         }
         return Response(error_data, status=status.HTTP_404_NOT_FOUND)
     except AlreadyLoggedException as exc:
-        error_data = _build_xero_error_payload(exc)
+        error_data = _build_xero_error_payload(
+            exc,
+            message=f"An unexpected error occurred ({exc}) while deleting "
+            "the invoice. Please contact support.",
+        )
         return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
     except Exception as exc:
         try:
@@ -896,7 +908,7 @@ def delete_xero_quote(request: Request, job_id: uuid.UUID) -> Response:
             raise ValueError(f"Job {job_id} has no company; cannot delete its quote")
         assert isinstance(request.user, Staff)  # IsAuthenticated guarantees Staff
         manager = XeroQuoteManager(company=job.company, job=job, staff=request.user)
-        result_data: dict = manager.delete_document()
+        result_data = manager.delete_document()
 
         if result_data.get("success"):
             messages.success(request, "Quote deleted successfully.")
@@ -917,7 +929,11 @@ def delete_xero_quote(request: Request, job_id: uuid.UUID) -> Response:
         return Response(error_data, status=status.HTTP_404_NOT_FOUND)
     except AlreadyLoggedException as exc:
         logger.exception(f"Error in delete_xero_quote view for job {job_id}")
-        error_data = _build_xero_error_payload(exc)
+        error_data = _build_xero_error_payload(
+            exc,
+            message=f"An unexpected error occurred ({exc}) while deleting "
+            "the quote. Please contact support.",
+        )
         messages.error(request, "An unexpected error occurred while deleting quote.")
         return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
     except Exception as exc:
@@ -998,7 +1014,7 @@ def delete_xero_purchase_order(
             error_data = _build_xero_error_payload(logged_exc)
             messages.error(request, f"An unexpected error occurred: {str(exc)}")
             return Response(error_data, status=status.HTTP_500_INTERNAL_SERVER_ERROR)
-        raise AssertionError("persist_and_raise returned without raising")
+        raise AssertionError("persist_and_raise returned without raising") from exc
 
 
 @extend_schema(
diff --git a/docs/adr/0001-exception-already-logged-dedup.md b/docs/adr/0001-exception-already-logged-dedup.md
index 11a177337..5c33ce188 100644
--- a/docs/adr/0001-exception-already-logged-dedup.md
+++ b/docs/adr/0001-exception-already-logged-dedup.md
@@ -10,6 +10,8 @@ Exceptions travel integration → service → view → scheduler. Every layer ha
 
 `AlreadyLoggedException` (in `apps/workflow/exceptions.py`) wraps the original exception plus the persisted `AppError.id`. Every handler is two-arm: re-raise `AlreadyLoggedException` unchanged; otherwise persist once, wrap, re-raise. `persist_app_error()` returns the `AppError` instance so callers can carry the id forward.
 
+The chain terminates at the HTTP boundary: the outermost view handler catches `AlreadyLoggedException` and converts it to a response (carrying `error_id`, per ADR 0013) instead of re-raising. Service objects invoked by views always re-raise; they never shape responses. A service object returns a failure value only for an *expected* business outcome, never for an unexpected exception.
+
 ## Why
 
 A marker exception is in-band — it works identically in views, services, schedulers, and management commands, so every handler in the codebase follows the same two-arm template. Reviewers and new handlers have one rule to remember. The id carries forward so an outer handler can correlate without re-querying.
diff --git a/frontend/tests/company-defaults.spec.ts b/frontend/tests/company-defaults.spec.ts
index 226ef284e..7e2e2cf78 100644
--- a/frontend/tests/company-defaults.spec.ts
+++ b/frontend/tests/company-defaults.spec.ts
@@ -1,4 +1,5 @@
 import { test, expect } from './fixtures/auth'
+import { autoId } from './fixtures/helpers'
 
 test('test can call backend API directly', async ({ authenticatedPage: page }) => {
   const response = await page.request.get('/api/company-defaults/', {
@@ -97,11 +98,30 @@ test('test Xero sales branding theme save, reload, and restore', async ({
 }) => {
   await page.goto('/admin/company/xero')
 
-  const selector = page.locator(
-    '[data-automation-id="SectionForm-xero-field-xero_sales_branding_theme_id"]',
-  )
+  const selector = autoId(page, 'SectionForm-xero-field-xero_sales_branding_theme_id')
+  const emptyMarker = autoId(page, 'SectionForm-xero-field-xero_sales_branding_theme_id-empty')
+  const errorMarker = autoId(page, 'SectionForm-xero-field-xero_sales_branding_theme_id-error')
+
   await expect(selector).toBeVisible({ timeout: 15000 })
-  await expect(selector).toBeEnabled({ timeout: 15000 })
+  // The select is enabled-and-empty for a beat before the themes fetch settles, so
+  // toBeEnabled alone is not a sound sync point. Poll until the load has resolved
+  // into exactly one of: error, empty, or ready.
+  await expect
+    .poll(
+      async () => {
+        if (await errorMarker.isVisible()) return 'error'
+        if (await emptyMarker.isVisible()) return 'empty'
+        const optionCount = await selector.locator('option:not([disabled])').count()
+        return (await selector.isEnabled()) && optionCount > 0 ? 'ready' : 'loading'
+      },
+      { timeout: 15000, message: 'Xero branding themes never finished loading' },
+    )
+    .not.toBe('loading')
+
+  // A load error means a broken Xero connection — fail loudly, don't skip.
+  await expect(errorMarker).toBeHidden()
+  test.skip(await emptyMarker.isVisible(), 'The connected Xero tenant has no branding themes')
+  await expect(selector).toBeEnabled()
 
   const originalValue = await selector.inputValue()
   const availableThemeIds = await selector
@@ -113,7 +133,6 @@ test('test Xero sales branding theme save, reload, and restore', async ({
         )
         .map((option) => option.value),
     )
-  test.skip(availableThemeIds.length === 0, 'The connected Xero tenant has no branding themes')
 
   const differentThemeId = availableThemeIds.find((id) => id !== originalValue)
   const testValue = originalValue === '' ? availableThemeIds[0] : differentThemeId
@@ -141,7 +160,10 @@ test('test Xero sales branding theme save, reload, and restore', async ({
     // completes setup, so never deliberately restore the invalid null state.
     if (originalValue !== '') {
       await page.goto('/admin/company/xero')
-      await expect(selector).toBeEnabled({ timeout: 15000 })
+      // Wait for the option itself so selectOption below cannot race the themes load.
+      await expect(selector.locator(`option[value="${originalValue}"]`)).toBeAttached({
+        timeout: 15000,
+      })
       if ((await selector.inputValue()) !== originalValue) {
         await selector.selectOption(originalValue)
         await page.click('[data-automation-id="AdminCompanySectionView-save-button"]')
diff --git a/mypy-baseline.txt b/mypy-baseline.txt
index cd156694e..543316eb4 100644
--- a/mypy-baseline.txt
+++ b/mypy-baseline.txt
@@ -2877,14 +2877,12 @@ apps/workflow/views/xero/xero_quote_manager.py:0: note: Use "-> None" if functio
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quoted"  [union-attr]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument "client_external_id" to "QuotePayload" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Incompatible type for "xero_id" of "Quote" (got "str | None", expected "str | UUID")  [misc]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "id"  [union-attr]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_quote_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_quote_manager.py:0: error: Item "None" of "Job | None" has no attribute "quote"  [union-attr]
@@ -2912,7 +2910,6 @@ apps/workflow/views/xero/xero_invoice_manager.py:0: error: Cannot resolve keywor
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "paid"  [union-attr]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument "client_external_id" to "InvoicePayload" has incompatible type "str | None"; expected "str"  [arg-type]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "state_valid_for_xero" in typed context  [no-untyped-call]
@@ -2921,7 +2918,6 @@ apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job |
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 2 to "_add_xero_history_note" of "XeroDocumentManager" has incompatible type "str | None"; expected "str"  [arg-type]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Argument 1 to "_attach_workshop_pdf" of "XeroInvoiceManager" has incompatible type "str | None"; expected "str"  [arg-type]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_invoice_manager.py:0: error: Function is missing a return type annotation  [no-untyped-def]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "validate_company" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Call to untyped function "get_xero_id" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_invoice_manager.py:0: error: Item "None" of "Job | None" has no attribute "save"  [union-attr]
@@ -3973,12 +3969,8 @@ apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [retur
 apps/workflow/views/xero/xero_view.py:0: error: Argument "company" to "XeroInvoiceManager" has incompatible type "Company | None"; expected "Company"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Argument "staff" to "XeroInvoiceManager" has incompatible type "Staff | AnonymousUser"; expected "Staff"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Argument "xero_invoice_id" to "XeroInvoiceManager" has incompatible type "UUID"; expected "str | None"  [arg-type]
-apps/workflow/views/xero/xero_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_view.py:0: error: Call to untyped function "delete_document" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_view.py:0: error: Incompatible types in assignment (expression has type "XeroDocumentErrorResponseSerializer", variable has type "XeroDocumentSuccessResponseSerializer")  [assignment]
 apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [return]
-apps/workflow/views/xero/xero_view.py:0: error: Missing type arguments for generic type "dict"  [type-arg]
-apps/workflow/views/xero/xero_view.py:0: error: Call to untyped function "delete_document" in typed context  [no-untyped-call]
 apps/workflow/views/xero/xero_view.py:0: error: Incompatible types in assignment (expression has type "XeroDocumentErrorResponseSerializer", variable has type "XeroDocumentSuccessResponseSerializer")  [assignment]
 apps/workflow/views/xero/xero_view.py:0: error: Argument 2 to "error" has incompatible type "object"; expected "str | _StrPromise"  [arg-type]
 apps/workflow/views/xero/xero_view.py:0: error: Missing return statement  [return]

From d4e4d780de8e6c3de13c5d4ecf5bc34ba85fb4fc Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 21:16:20 +1200
Subject: [PATCH 71/73] fix(crm): keep archived people reachable, restorable,
 and consistent

Fixes four regressions found in final review of the person-archive feature:

- PersonContactMethodsView.get/post 404'd on archived people, which broke
  the PersonDetail page's Promise.all load and hid the restore-link button.
  Drop the is_active filter to match PersonDetailView.
- classify_phone_ownership skipped archived people entirely, so a phone
  conflict with an archived owner surfaced as an unrecoverable "belongs to
  <empty>" company conflict instead of offering to restore the link.
- removeLink refetched only companyLinks, leaving person.value stale so the
  Archived badge and Archive button never updated after removing the last
  link. Mirror restoreLink and reload the whole person.
- archivePerson used an ad hoc error message instead of extractErrorMessage,
  inconsistent with its sibling handlers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/company/services/person_service.py |  2 +-
 apps/company/tests/test_person_api.py   | 51 +++++++++++++++++++++++++
 apps/company/views/person_views.py      |  4 +-
 frontend/src/pages/crm/people/[id].vue  |  4 +-
 4 files changed, 56 insertions(+), 5 deletions(-)

diff --git a/apps/company/services/person_service.py b/apps/company/services/person_service.py
index af963df30..61d759d8c 100644
--- a/apps/company/services/person_service.py
+++ b/apps/company/services/person_service.py
@@ -175,7 +175,7 @@ def classify_phone_ownership(
     for method in methods:
         if method.person_id is not None:
             person = method.person
-            if person is None or not person.is_active:
+            if person is None:
                 continue
             people_by_id.setdefault(
                 person.id,
diff --git a/apps/company/tests/test_person_api.py b/apps/company/tests/test_person_api.py
index 0e6c35510..f8c24300b 100644
--- a/apps/company/tests/test_person_api.py
+++ b/apps/company/tests/test_person_api.py
@@ -356,3 +356,54 @@ def test_directory_includes_archived_when_requested(self) -> None:
         rows = {row["id"]: row for row in response.json()["results"]}
         self.assertIn(str(person.id), rows)
         self.assertFalse(rows[str(person.id)]["is_active"])
+
+    def test_contact_methods_are_reachable_for_an_archived_person(self) -> None:
+        """The PersonDetail page loads contact-methods alongside the person; a 404
+        here fails the whole Promise.all and hides the restore-link button."""
+        person = self._person(company=self.company_a)
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        response = self.client.get(f"/api/people/{person.id}/contact-methods/")
+
+        self.assertEqual(response.status_code, 200)
+
+    def test_phone_ownership_offers_restore_for_an_archived_person(self) -> None:
+        """An archived person who still owns a phone must come back as status
+        'people' (not 'company') so the modal can offer to restore the link."""
+        person = self._person(company=self.company_a)
+        ContactMethod.objects.create(
+            person=person,
+            method_type=ContactMethod.MethodType.PHONE,
+            value="021 222 2222",
+            is_primary=True,
+        )
+        with patch("apps.crm.tasks.rematch_phone_calls_task.delay"):
+            self.client.delete(
+                f"/api/people/{person.id}/company-links/{self.company_a.id}/"
+            )
+        person.refresh_from_db()
+        self.assertFalse(person.is_active)
+
+        response = self.client.post(
+            f"/api/companies/{self.company_a.id}/people/phone-ownership/",
+            {"phone": "0212222222"},
+            format="json",
+        )
+
+        self.assertEqual(response.status_code, 200)
+        body = response.json()
+        self.assertEqual(body["status"], "people")
+        self.assertEqual(body["people"][0]["person_id"], str(person.id))
+        company_links = body["people"][0]["company_links"]
+        self.assertFalse(
+            next(
+                link
+                for link in company_links
+                if link["company_id"] == str(self.company_a.id)
+            )["is_active"]
+        )
diff --git a/apps/company/views/person_views.py b/apps/company/views/person_views.py
index 712e5bd99..892e44dc4 100644
--- a/apps/company/views/person_views.py
+++ b/apps/company/views/person_views.py
@@ -243,7 +243,7 @@ class PersonContactMethodsView(APIView):
 
     @extend_schema(responses={200: ContactMethodSerializer(many=True)})
     def get(self, request: Request, person_id: str) -> Response:
-        person = get_object_or_404(Person, id=person_id, is_active=True)
+        person = get_object_or_404(Person, id=person_id)
         methods = person.contact_methods.order_by(
             "method_type", "-is_primary", "label", "value"
         )
@@ -254,7 +254,7 @@ def get(self, request: Request, person_id: str) -> Response:
         responses={201: ContactMethodSerializer},
     )
     def post(self, request: Request, person_id: str) -> Response:
-        person = get_object_or_404(Person, id=person_id, is_active=True)
+        person = get_object_or_404(Person, id=person_id)
         payload = PersonContactMethodWriteSerializer(data=request.data)
         payload.is_valid(raise_exception=True)
         serializer = ContactMethodSerializer(
diff --git a/frontend/src/pages/crm/people/[id].vue b/frontend/src/pages/crm/people/[id].vue
index 64638e87f..8daadb78c 100644
--- a/frontend/src/pages/crm/people/[id].vue
+++ b/frontend/src/pages/crm/people/[id].vue
@@ -438,7 +438,7 @@ async function removeLink(companyId: string): Promise<void> {
     await api.people_company_links_destroy(undefined, {
       params: { person_id: props.id, company_id: companyId },
     })
-    companyLinks.value = await api.people_company_links_list({ params: { person_id: props.id } })
+    await loadPerson()
     toast.success('Company link removed')
   } catch (err) {
     toast.error(`Company link not removed: ${extractErrorMessage(err)}`)
@@ -463,7 +463,7 @@ async function archivePerson(): Promise<void> {
     toast.success('Person archived')
     await loadPerson()
   } catch (err) {
-    toast.error(err instanceof Error ? err.message : 'Failed to archive person')
+    toast.error(extractErrorMessage(err))
   } finally {
     archiving.value = false
   }

From 9601515f68dc973d39c90c4cbe22d77032436a5b Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 21:25:53 +1200
Subject: [PATCH 72/73] docs(crm): correct person-archive spec on
 contact-methods and phone-ownership

The draft put contact-methods gating and phone-ownership for archived people
out of scope. Both were load-bearing and are now fixed (d4e4d780): an archived
person was unreachable (PersonDetail loads contact-methods in the same
Promise.all, so its 404 collapsed the page and hid the restore-link button),
and classify_phone_ownership skipping archived people regressed the
"Restore company link" recovery path into an unrecoverable dead end.

Record what remains genuinely out of scope: reuse of an archived person's
number by a different person.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../specs/2026-07-16-person-archive-design.md | 25 ++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/docs/superpowers/specs/2026-07-16-person-archive-design.md b/docs/superpowers/specs/2026-07-16-person-archive-design.md
index 20b636625..000f7f571 100644
--- a/docs/superpowers/specs/2026-07-16-person-archive-design.md
+++ b/docs/superpowers/specs/2026-07-16-person-archive-design.md
@@ -54,7 +54,11 @@ exist).
    - `PersonDetailView` GET (retrieve): look up by id without the `is_active=True` filter.
    - `PersonCompanyLinksView` / `PersonCompanyLinkDetailView`: person lookup without `is_active=True` so
      restore-link works on an archived person.
-   - Keep contact-methods views gated for now (out of scope — see below).
+   - `PersonContactMethodsView` GET/POST: **also ungated.** (This section originally said "keep contact-methods
+     gated — out of scope". That was a mistake, caught by the final review: PersonDetail loads person +
+     contact-methods + company-links in one `Promise.all`, so a 404 there rejects the whole load and the
+     archived person renders "Failed to load person" with no restore-link button — the exact unreachable state
+     this design exists to prevent.)
    - New explicit archive route (e.g. `POST /api/people/{person_id}/archive/`) → `archive_person`.
 3. **`views/person_views.py` `PersonListView`** (directory search): add an `include_archived` query param
    (default `false` → keep the existing `is_active=True` filter; `true` → include archived).
@@ -93,7 +97,22 @@ Regenerate the API client after the schema changes (`npm run update-schema && np
 
 ## Out of scope for v1 (accepted)
 
-- **Contact-method / phone-ownership for archived people.** An archived person still "owns" their phone
-  number, so it stays blocked for reuse. Left as-is; revisit only if it causes a problem.
+- **Phone-number *reuse* by someone else.** An archived person still "owns" their phone number, so
+  `can_create_person` stays `False` for that number — you cannot create a *different* person on it. Left
+  as-is; the one-number-one-company rule is unchanged.
 - No standalone "un-archive to a company-less state" button — coming back always happens via restoring/adding
   a company link.
+
+## Corrections made during implementation
+
+The original draft of this spec put two things out of scope that turned out to be load-bearing. The final
+review caught both; the user authorised overriding the spec, and both are now fixed:
+
+1. **Contact-methods views must be ungated** (see Backend §2) — otherwise archived people are unreachable and
+   unrestorable.
+2. **`classify_phone_ownership` must not skip archived people.** It previously did, which — because
+   `ContactMethod.conflicting_company` still saw their number — produced `status='company'` with an empty
+   owner list and no way forward ("It belongs to  and cannot be assigned to a person."). That was a
+   *regression* of a pre-existing recovery path. Skipping only `person is None` restores the intended flow:
+   the archived owner is listed with a working "Restore company link" button, which reactivates the link and
+   un-archives them. This does not loosen the reuse rule above — `can_create_person` was already `False`.

From 2542cb845549922d3a9c6b9011ff225292ec73e0 Mon Sep 17 00:00:00 2001
From: Corrin Lakeland <corrin.lakeland@cmeconnect.com>
Date: Thu, 16 Jul 2026 21:42:41 +1200
Subject: [PATCH 73/73] test: drop no-op solo-cache cleanups from Xero tests

SOLO_CACHE is None under tests (settings.py:892, settings_test.py:25), so
django-solo's get_solo() reads straight through to the DB and clear_cache()
short-circuits on `if cache_name:`. There is no cache to leak between tests,
so registering clear_cache as a cleanup guards nothing and implies a hazard
that cannot occur.

Matches the existing convention in test_xero_branding_themes.py and
test_xero_quota_floor.py: clear_cache() in setUp, no cleanup registered.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/workflow/tests/test_xero_document_raw_json.py | 1 -
 apps/workflow/tests/test_xero_readonly_provider.py | 1 -
 2 files changed, 2 deletions(-)

diff --git a/apps/workflow/tests/test_xero_document_raw_json.py b/apps/workflow/tests/test_xero_document_raw_json.py
index 70b4bbaef..bf8359d1e 100644
--- a/apps/workflow/tests/test_xero_document_raw_json.py
+++ b/apps/workflow/tests/test_xero_document_raw_json.py
@@ -52,7 +52,6 @@ def setUp(self):
             xero_sales_branding_theme_id=uuid.uuid4()
         )
         CompanyDefaults.clear_cache()
-        self.addCleanup(CompanyDefaults.clear_cache)
 
     def test_created_invoice_stores_canonical_raw_json_dict(self):
         raw_response = {
diff --git a/apps/workflow/tests/test_xero_readonly_provider.py b/apps/workflow/tests/test_xero_readonly_provider.py
index 6a40a94e9..e90f57316 100644
--- a/apps/workflow/tests/test_xero_readonly_provider.py
+++ b/apps/workflow/tests/test_xero_readonly_provider.py
@@ -126,7 +126,6 @@ def setUp(self) -> None:
             xero_sales_branding_theme_id=uuid.uuid4()
         )
         CompanyDefaults.clear_cache()
-        self.addCleanup(CompanyDefaults.clear_cache)
 
         self._api_patcher = patch.object(
             XeroAccountingProvider, "_get_api", side_effect=_API_FORBIDDEN