diff --git a/sales/preheat/README.md b/sales/preheat/README.md
new file mode 100644
index 0000000..63d670d
--- /dev/null
+++ b/sales/preheat/README.md
@@ -0,0 +1,129 @@
+# Preheat
+
+See from Jamf Pro whether each Apple content cache is working, which devices it serves, and whether it already holds the OS update they are about to ask for. Preheat it when it does not.
+
+> **Status: early, working, looking for testers.** Proven end to end in one lab: one cache
+> server, three Macs, three iPads and an iPhone, through three real point releases. Not yet
+> done: an update enforced by a Blueprint across many devices, and a second cache server in a
+> second office. The full account is in
+> [What is proven, and what is not](docs/FINDINGS.md#what-is-proven-and-what-is-not).
+> Issues and pull requests welcome — open one at https://github.com/masterstompie/preheat/issues.
+
+![Jamf Pro dashboard with the content cache Smart Groups](docs/images/dashboard-smart-groups.png)
+
+*The day-to-day view: one cache server, ready for the next OS push, serving two Macs and four mobile devices. "Wiped recently" reads 1 because this cache's drive was erased the evening before: the tile to alert on, doing its job. "On but not chosen" and "Chosen but not caching" are the two that should always read 0. (Two captures of one page, joined. The "Preheat test" groups belong to the lab.)*
+
+## What it tells you
+Apple content caching keeps one copy of each update in the office, and saves the internet link
+every time a second device asks for it. When it works it needs no help. But Apple gives an
+administrator no way to see whether it is working, what it holds, or which devices can reach it.
+
+Preheat answers one question per cache server, judged only against the devices that use that
+server: does it already hold the OS update each of them is about to download?
+
+| Verdict | Meaning |
+|---|---|
+| READY | every file those devices will ask for is in the cache, complete |
+| PARTIAL | some of them are |
+| NOT READY | none of them is; or the cache is down; or the server has gone silent |
+
+The verdict is an extension attribute on the server's record, so Smart Groups, the dashboard and
+email alerts work on it like on anything else in Jamf Pro. Beside it, Preheat shows:
+
+- what each cache holds, by name: "iOS 27.0 (24A437) delta from 26.7 for iPhone17,3"
+- which cache each Mac, iPhone, iPad and Apple TV would use
+- whether the cache is earning its keep: the share of what it delivered that did not come from Apple
+- whether a cache was wiped, is low on space, or is caching when nobody chose it to
+
+When a cache is not ready, Preheat can fill it before the devices ask, with no test device at
+that site: see [Preheating](docs/PREHEATING.md).
+
+## How it works
+- Jamf Pro's inventory says which hardware and which OS build every device has.
+- Apple's own lookup service, the one every device asks, says which file that hardware and build
+  would download next.
+- An extension attribute on each cache server lists the files its cache holds.
+- An extension attribute on each Mac says which cache that Mac would use, as macOS itself decides.
+- `admin/readiness-check.py` puts the four together and writes the verdict.
+
+Nothing with a password runs on a device, and nothing is installed by hand on any Mac. More in
+[Reference](docs/REFERENCE.md).
+
+## What you need
+- Jamf Pro 11.31 or later, with computers enrolled and sending inventory, the cache servers
+  among them. Mobile devices too, if you want iPhone, iPad, Apple TV or Vision Pro readiness.
+- A Jamf Pro API role and client.
+- An admin Mac, or a scheduled job, with Python 3.8 or later and no extra packages.
+- One or more Macs running content caching, each with a fixed address and the Xcode Command Line
+  Tools.
+- macOS 27 on the cache servers, if you want their live status and to configure them by Blueprint.
+
+The full list, with the API privileges each feature needs, is in
+[Requirements](docs/SETUP.md#requirements).
+
+## Setup, in short
+| Do this | With |
+|---|---|
+| Create the API role and client, and store the credentials in your keychain | `python3 admin/readiness-check.py --store-credentials` |
+| Create the extension attributes | `python3 admin/sync-eas.py --create`, and two text fields by hand |
+| Run the check | `python3 admin/readiness-check.py`, and with `--write` to store the verdict |
+| Create the Smart Groups | `python3 admin/create-smart-groups.py` |
+| Have each cache server name its files | `python3 admin/create-labels-policy.py` |
+| Check your work | `python3 admin/doctor.py` |
+| Keep it current | run the check with `--write` on a schedule; hourly is plenty |
+
+Each step, with its tables, is in [Jamf setup](docs/SETUP.md#jamf-setup). The same installation
+as Terraform is in [`terraform/`](terraform/README.md). Every script answers `--help` and changes
+nothing when asked: [docs/USAGE.md](docs/USAGE.md).
+
+## Test without Jamf
+    python3 admin/readiness-check.py --inventory-json admin/sample-inventory.json
+    python3 admin/readiness-check.py --inventory-json admin/sample-inventory-large-site.json --platforms all   # two public addresses, two peer caches
+
+Each sample carries the answers Apple gave when it was recorded (2026-09-28), so it gives the same
+result whatever Apple has released since. `--record-answers` records them again.
+
+![Readiness check output for the sample fleet](docs/images/readiness-check-output.png)
+
+*Report for the sample two-office fleet: Office X ready, Office A missing the Mac14,2 asset.*
+
+## Read more
+| Page | What is in it |
+|---|---|
+| [Setup](docs/SETUP.md) | Requirements, the extension attributes as Jamf's form asks for them, setup step by step, where things live |
+| [Preheating](docs/PREHEATING.md) | Filling a cache before the devices ask: OS updates, hardware not yet enrolled, installers, Xcode, Aerials, and what cannot be preheated |
+| [Blueprints](docs/BLUEPRINTS.md) | Declarative updates in two waves, a group that holds on the previous OS, update settings, and configuring the cache servers themselves |
+| [Findings](docs/FINDINGS.md) | What was measured: what is proven, what one release weighs, what a full cache does, thin links and outages |
+| [Caveats](docs/CAVEATS.md) | What can go wrong, each one seen in the lab; and two scripts for when clients do not see the cache |
+| [Reference](docs/REFERENCE.md) | Every piece, where each fact comes from, large sites, mobile devices, live status, why a Mac downloaded at 1 pm, hardware coverage, the rest of the Jamf platform |
+| [Usage](docs/USAGE.md) | Every script and every option |
+
+## Prior art
+Charles Edge's [precache](https://github.com/krypted/precache) (2016 to 2020) pre-filled the old
+macOS Server Caching Service with installers, IPSWs and App Store apps, and could take its device
+list from Jamf Pro. Content caching has since moved into macOS itself and updates have become
+per-model deltas. Preheat starts from the same idea, that a cache can be filled before devices ask,
+and adds the parts that did not exist then: knowing what a cache holds, and whether it is ready for
+the devices that use it.
+
+## Bill of Materials
+
+| Component | Kind | Version | License |
+|---|---|---|---|
+| [jamf/jamfplatform](https://registry.terraform.io/providers/jamf/jamfplatform) | Terraform provider | ≥ 0.29 | Jamf — verify before redistribution |
+
+Python dependencies: none (stdlib only). Shell dependencies: `/usr/bin/curl` (system, macOS built-in).
+
+## Privacy
+
+Preheat does not collect telemetry, send analytics, or phone home. It reads your Jamf Pro inventory
+and queries Apple's public software update API (`gdmf.apple.com`), three other Apple catalogs for
+file names (`swscan.apple.com`, `configuration.apple.com`, `devimages-cdn.apple.com`) and AppleDB
+(`api.appledb.dev`). No device data leaves your network except in those outbound lookup calls, which carry no personally
+identifiable information. See [Jamf's Privacy Policy](https://www.jamf.com/legal/privacy-policy/).
+
+## License
+
+Copyright © 2026 Jamf Software LLC. All rights reserved.
+
+Distributed under the Jamf Concepts Use Agreement. See LICENSE for the full terms.
diff --git a/sales/preheat/admin/cache-collect.sh b/sales/preheat/admin/cache-collect.sh
new file mode 100755
index 0000000..e0707f3
--- /dev/null
+++ b/sales/preheat/admin/cache-collect.sh
@@ -0,0 +1,154 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# cache-collect.sh  --  READ-ONLY inspection of an Apple content caching server.
+#
+# Purpose: gather everything needed to design a Jamf Pro Extension Attribute that
+# reports which macOS updates are cached. Makes NO changes: the cache database is
+# copied to a temp folder before it is queried, and the service is never touched.
+#
+# Run on the caching Mac:   sudo bash admin/cache-collect.sh
+# Output: /Users/Shared/cache-report-<date>.txt  (plus a .json of macOS-update rows)
+
+set -u
+case "${1:-}" in -h|--help) /usr/bin/sed -n '2,/^set -u/p' "$0" | /usr/bin/sed -e '/^set -u/d' -e 's/^# \{0,1\}//'; exit 0;; esac
+if [[ $EUID -ne 0 ]]; then echo "Run with sudo: sudo bash $0"; exit 1; fi
+
+STAMP=$(date +%Y%m%d-%H%M%S)
+REPORT="/Users/Shared/cache-report-$STAMP.txt"
+JSON="/Users/Shared/cache-macos-assets-$STAMP.json"
+WORK=$(mktemp -d /tmp/cache-collect.XXXXXX)
+trap 'rm -rf "$WORK"' EXIT
+
+exec > >(tee "$REPORT") 2>&1
+section(){ printf '\n\n===== %s =====\n' "$1"; }
+
+section "SYSTEM"
+sw_vers
+echo "model:     $(sysctl -n hw.model)"
+echo "board id:  $(sysctl -n hw.target)"
+echo "uptime:    $(uptime)"
+echo "hostname:  $(scutil --get LocalHostName 2>/dev/null)"
+
+section "CONTENT CACHE STATUS (AssetCacheManagerUtil status)"
+AssetCacheManagerUtil status 2>&1
+
+section "CONTENT CACHE STATUS JSON"
+AssetCacheManagerUtil -j status 2>&1
+
+section "CONTENT CACHE SETTINGS JSON"
+SETTINGS_JSON=$(AssetCacheManagerUtil -j settings 2>&1)
+echo "$SETTINGS_JSON"
+
+section "LAUNCHD SERVICE STATE"
+launchctl print system/com.apple.AssetCache 2>&1 | head -40
+echo "--- processes ---"
+pgrep -lf AssetCache 2>&1
+
+# ---- locate the data folder (default or custom DataPath) ----
+DATA_PATH=$(echo "$SETTINGS_JSON" | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result",d)
+    print(r.get("DataPath") or "")
+except Exception: print("")' 2>/dev/null)
+[[ -z "$DATA_PATH" ]] && DATA_PATH="/Library/Application Support/Apple/AssetCache/Data"
+DB="$DATA_PATH/AssetInfo.db"
+
+section "DATA FOLDER: $DATA_PATH"
+ls -la "$DATA_PATH" 2>&1 | head -40
+echo "--- disk usage of data folder ---"
+du -sh "$DATA_PATH" 2>&1
+echo "--- largest 25 files under data folder ---"
+find "$DATA_PATH" -type f -size +100M -exec ls -l {} \; 2>/dev/null | sort -k5 -n -r | head -25
+
+if [[ ! -f "$DB" ]]; then
+  echo "AssetInfo.db not found at $DB -- stopping database section."
+else
+  # ---- copy DB (and WAL/SHM if present) so we never touch the live file ----
+  cp "$DB" "$WORK/AssetInfo.db"
+  [[ -f "$DB-wal" ]] && cp "$DB-wal" "$WORK/AssetInfo.db-wal"
+  [[ -f "$DB-shm" ]] && cp "$DB-shm" "$WORK/AssetInfo.db-shm"
+  Q(){ sqlite3 -readonly "$WORK/AssetInfo.db" "$@"; }
+
+  section "DATABASE SCHEMA"
+  Q ".schema"
+
+  section "ZASSET COLUMNS"
+  Q -header -column "PRAGMA table_info(ZASSET);"
+
+  section "ROW COUNTS PER TABLE"
+  for t in $(Q "select name from sqlite_master where type='table';"); do
+    printf '%-20s %s\n' "$t" "$(Q "select count(*) from $t;")"
+  done
+
+  section "ASSET SUMMARY BY URI PREFIX (first 2 path components)"
+  Q -header -column "
+    select substr(ZURI,1,instr(substr(ZURI,2),'/')+1) as prefix,
+           count(*) as n,
+           round(sum(ZTOTALBYTES)/1073741824.0,2) as GB
+    from ZASSET group by prefix order by GB desc limit 40;"
+
+  section "ASSET SUMMARY BY FILE EXTENSION"
+  Q -header -column "
+    select case when instr(ZURI,'.')=0 then '(none)' else lower(replace(ZURI, rtrim(ZURI, replace(ZURI,'.','')), '')) end as ext,
+           count(*) as n, round(sum(ZTOTALBYTES)/1073741824.0,2) as GB
+    from ZASSET group by ext order by GB desc limit 30;"
+
+  section "SAMPLE OF 15 URIS (to see exact format)"
+  Q "select ZURI from ZASSET order by ZTOTALBYTES desc limit 15;"
+
+  section "macOS UPDATE CANDIDATES (all columns, line mode)"
+  MATCH="ZURI like '%MacSoftwareUpdate%' or ZURI like '%InstallAssistant%' or ZURI like '%.ipsw%' or ZURI like '%macOSUpd%' or ZURI like '%SoftwareUpdate%' or ZURI like '%.aea%' or ZURI like '%FCS/%'"
+  Q -header -line "select *,
+        datetime(ZCREATIONDATE + 978307200,'unixepoch') as created_utc,
+        datetime(ZLASTACCESSED + 978307200,'unixepoch') as last_accessed_utc
+      from ZASSET where $MATCH order by ZTOTALBYTES desc;"
+
+  section "macOS UPDATE CANDIDATES (compact)"
+  Q -header -column "select round(ZTOTALBYTES/1073741824.0,2) as GB,
+        datetime(ZCREATIONDATE + 978307200,'unixepoch') as created_utc,
+        ZURI
+      from ZASSET where $MATCH order by ZTOTALBYTES desc;"
+
+  section "ON-DISK SIZE CHECK FOR CANDIDATES (is the file fully present?)"
+  # Try to relate DB rows to files on disk by GUID / checksum-looking columns.
+  Q -json "select * from ZASSET where $MATCH;" > "$JSON"
+  [[ -s "$JSON" ]] || echo "[]" > "$JSON"
+  echo "JSON written to $JSON ($(python3 -c "import json;print(len(json.load(open('$JSON'))))") rows)"
+  python3 - "$JSON" "$DATA_PATH" <<'PY'
+import json,sys,os
+rows=json.load(open(sys.argv[1])); data=sys.argv[2]
+# Layout learned 2026-09-17: each asset's bytes live in  <DataPath>/<ZGUID>/<chunk files>
+for r in rows:
+    uri=r.get("ZURI",""); total=r.get("ZTOTALBYTES") or 0; guid=r.get("ZGUID") or ""
+    d=os.path.join(data,guid); ondisk=0; files=0
+    if guid and os.path.isdir(d):
+        for root,_,fs in os.walk(d):
+            for f in fs:
+                try: ondisk+=os.path.getsize(os.path.join(root,f)); files+=1
+                except OSError: pass
+    pct=(100.0*ondisk/total) if total else 0
+    state="COMPLETE" if total and ondisk>=total else ("PARTIAL" if ondisk else "NO DATA ON DISK")
+    print(f"\n{uri}\n  guid={guid} files={files} ondisk={ondisk} total={total} ({pct:.1f}%) -> {state}")
+    print(f"  ZMD5OFFSET={r.get('ZMD5OFFSET')} ZCHECKSUM={r.get('ZCHECKSUM')!r}")
+PY
+
+  section "OTHER TABLES (first 20 rows each, may explain completeness/state)"
+  for t in $(Q "select name from sqlite_master where type='table' and name not in ('ZASSET');"); do
+    echo "--- $t ---"; Q -header -column "select * from $t limit 20;"
+  done
+fi
+
+section "RECENT CONTENT CACHE LOG (last 30 min, errors/faults + status summaries)"
+log show --last 30m --predicate 'subsystem == "com.apple.AssetCache"' --style compact 2>/dev/null \
+  | grep -Ei 'error|fault|fail|shut|deactivat|activat|start|stopp|status|registration' | tail -80
+
+section "RECENT MACOS UPDATE REQUESTS SEEN BY THE CACHE (last 24h, if any)"
+log show --last 24h --predicate 'subsystem == "com.apple.AssetCache"' --style compact 2>/dev/null \
+  | grep -Ei 'MacSoftwareUpdate|InstallAssistant|ipsw|\.zip|\.aea|FCS' | tail -40
+
+section "DONE"
+echo "Report: $REPORT"
+echo "JSON:   $JSON"
diff --git a/sales/preheat/admin/create-labels-policy.py b/sales/preheat/admin/create-labels-policy.py
new file mode 100644
index 0000000..4ac85ba
--- /dev/null
+++ b/sales/preheat/admin/create-labels-policy.py
@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+Put admin/preheat-labels.py into Jamf Pro as a script, and create the policy that runs it on cache servers:
+  General: trigger Recurring Check-in, frequency Ongoing     Scripts: preheat-labels.py
+  Maintenance: Update Inventory                              Scope: Smart Group "Content Caching - Servers"
+So at every check-in a cache server names any new files it holds, then sends inventory, and the decoded EA
+(ea-content-cache-decoded.sh) is current without anyone running the admin script. Disable the policy to stop.
+Run again after editing preheat-labels.py: the script in Jamf is updated, the policy is left alone.
+Needs API privileges: Create/Read/Update Scripts, Create/Read Policies, Read Smart Computer Groups.
+Usage: python3 admin/create-labels-policy.py [--group "Content Caching - Servers"] [--disabled]
+"""
+import os, sys, argparse, urllib.error, urllib.request
+from xml.sax.saxutils import escape
+sys.path.insert(0, os.path.dirname(__file__)); rc = __import__("readiness-check")
+SCRIPT_NAME = "preheat-labels.py"; POLICY_NAME = "Preheat - Refresh cache labels"
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--group", default="Content Caching - Servers"); ap.add_argument("--disabled", action="store_true", help="create the policy switched off")
+    args = ap.parse_args()
+    j = rc.jamf_from_credentials()
+    local = open(os.path.join(os.path.dirname(os.path.abspath(__file__)), SCRIPT_NAME)).read()
+    scripts = j.call("/api/v1/scripts?page=0&page-size=500").get("results", [])
+    hit = next((s for s in scripts if s["name"] == SCRIPT_NAME), None)
+    body = {"name": SCRIPT_NAME, "info": "Names the OS update files a content cache holds. No Jamf credentials. See the preheat README.",
+            "notes": "Managed by admin/create-labels-policy.py", "priority": "AFTER", "scriptContents": local}
+    if hit:
+        sid = hit["id"]
+        if (hit.get("scriptContents") or "").replace("\r\n", "\n").strip() == local.strip(): print(f"script {SCRIPT_NAME}: up to date (id {sid})")
+        else: j.call(f"/api/v1/scripts/{sid}", "PUT", {**hit, **body}); print(f"script {SCRIPT_NAME}: updated (id {sid})")
+    else:
+        sid = j.call("/api/v1/scripts", "POST", body)["id"]; print(f"script {SCRIPT_NAME}: created (id {sid})")
+    if any(p["name"] == POLICY_NAME for p in j.call("/JSSResource/policies")["policies"]):
+        print(f"policy '{POLICY_NAME}': already exists, left alone"); return
+    groups = j.call("/api/v2/computer-groups/smart-groups?page=0&page-size=500").get("results", [])
+    gid = next((g["id"] for g in groups if g["name"] == args.group), None)
+    if not gid: sys.exit(f"Smart Group '{args.group}' not found; run admin/create-smart-groups.py first")
+    xml = f"""<policy><general><name>{escape(POLICY_NAME)}</name><enabled>{str(not args.disabled).lower()}</enabled>
+<trigger>CHECKIN</trigger><trigger_checkin>true</trigger_checkin><frequency>Ongoing</frequency></general>
+<scope><computer_groups><computer_group><id>{gid}</id></computer_group></computer_groups></scope>
+<scripts><size>1</size><script><id>{sid}</id><priority>After</priority></script></scripts>
+<maintenance><recon>true</recon></maintenance></policy>"""
+    req = urllib.request.Request(j.base + "/JSSResource/policies/id/0", data=xml.encode(), method="POST",
+                                 headers={"Authorization": "Bearer " + j.token, "Content-Type": "application/xml"})
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r: print(f"policy '{POLICY_NAME}': created, scoped to '{args.group}'", r.read().decode()[-40:])
+    except urllib.error.HTTPError as e: sys.exit(f"policy create refused HTTP {e.code}: {e.read().decode()[:300]}")
+
+if __name__ == "__main__": main()
diff --git a/sales/preheat/admin/create-smart-groups.py b/sales/preheat/admin/create-smart-groups.py
new file mode 100644
index 0000000..98cfef2
--- /dev/null
+++ b/sales/preheat/admin/create-smart-groups.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+Create the Smart Computer Groups this project recommends, skipping any that already exist.
+Needs API client privileges: Read / Create Smart Computer Groups.
+Credentials: login keychain (readiness-check.py --store-credentials) or env JAMF_URL, JAMF_CLIENT_ID, JAMF_CLIENT_SECRET.
+Usage: python3 admin/create-smart-groups.py [--dry-run] [--update]
+       python3 admin/create-smart-groups.py --served-by "Office X" <server GUID>   # add a per-office group
+"""
+import os, sys, json, urllib.error, argparse
+sys.path.insert(0, os.path.dirname(__file__)); rc = __import__("readiness-check")
+
+
+def crit(name, search, value, and_or="and", prio=0):
+    return {"name": name, "searchType": search, "value": value, "andOr": and_or, "priority": prio,
+            "openingParen": False, "closingParen": False}
+
+GROUPS = [
+    ("Content Caching - Servers", "Macs running Apple content caching, serving or not (status EA starts with Active or Inactive).",
+     [crit(rc.EA_STATUS, "like", "Active")]),
+    ("Content Caching - Ready for OS push", "Cache servers whose local devices' next OS update is fully cached (readiness EA READY).",
+     [crit(rc.EA_READY, "like", "READY"), crit(rc.EA_READY, "not like", "NOT READY", "and", 1)]),
+    ("Content Caching - Partially ready", "Cache servers with some, not all, needed OS assets cached.",
+     [crit(rc.EA_READY, "like", "PARTIAL")]),
+    ("Content Caching - Not ready", "Cache servers missing every needed OS asset.",
+     [crit(rc.EA_READY, "like", "NOT READY")]),
+    ("Content Caching - Inactive or broken", "Caching turned on but not serving (registration failed, low space, data path missing).",
+     [crit(rc.EA_STATUS, "like", "Inactive")]),
+    ("Content Caching - Low on space", "Caches that report LOWSPACE: the cache volume is nearly full, missing or renamed. A cache that loses its volume switches itself off, and still shows here.",
+     [crit(rc.EA_STATUS, "like", "LOWSPACE")]),
+    ("Content Caching - Low benefit", "Cache servers that re-serve under 30% of what they download: few devices use them, or devices cannot reach them (VPN, wrong network).",
+     [crit(rc.EA_EFFECT, "like", "LOW ")]),
+    ("Content Caching - Wiped recently", "Cache servers that lost more than 90% of their content in the last 3 days: almost always a failed registration with Apple (VPN on the server, blocked egress, changed public IP).",
+     [crit(rc.EA_EFFECT, "like", "WIPED ")]),
+    ("Macs with no content cache", "Macs that will download OS updates straight from Apple (locator found no cache).",
+     [crit(rc.EA_FOUND, "is", "None found")]),
+]
+
+MOBILE_GROUPS = [
+    ("Mobile devices with no content cache", "iPads, iPhones and Apple TVs that will download OS updates straight from Apple.",
+     [crit(rc.EA_MOBILE_SERVER, "is", "None found")]),
+]
+
+def create_mobile(j, groups, dry):
+    try:
+        existing = {g["groupName"] for g in j.call("/api/v2/mobile-device-groups/smart-groups?page=0&page-size=1000").get("results", [])}
+    except urllib.error.HTTPError as e:
+        print(f"mobile groups skipped (HTTP {e.code}; needs Read Smart Mobile Device Groups)"); return
+    for name, desc, criteria in groups:
+        if name in existing: print(f"exists:  {name}"); continue
+        body = {"groupName": name, "groupDescription": desc, "criteria": criteria, "siteId": "-1"}
+        if dry: print(f"would create (mobile): {name}"); continue
+        for path in ("/api/v2/mobile-device-groups/smart-groups", "/api/v1/mobile-device-groups/smart-groups"):
+            try: j.call(path, "POST", body); print(f"created: {name} (mobile)"); break
+            except urllib.error.HTTPError as e:
+                if path.endswith("v1/mobile-device-groups/smart-groups") or e.code != 404:
+                    print(f"FAILED:  {name}: HTTP {e.code} {e.read().decode()[:200]}"); break
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--dry-run", action="store_true", help="print what would be created or updated")
+    ap.add_argument("--update", action="store_true", help="also bring existing groups of these names to the rules in this script (for installations made before a rule changed)")
+    ap.add_argument("--served-by", nargs=2, metavar=("LABEL", "GUID"), help="also create 'Macs served by <LABEL> cache' for that server GUID")
+    args = ap.parse_args()
+    groups = list(GROUPS)
+    mobile_groups = list(MOBILE_GROUPS)
+    if args.served_by:
+        label, guid = args.served_by
+        groups.append((f"Macs served by {label} cache", f"Macs whose locator reports cache server {guid}.",
+                       [crit(rc.EA_FOUND, "like", guid)]))
+        mobile_groups.append((f"Mobile devices served by {label} cache", f"Mobile devices matched (by public IP) to cache server {guid}.",
+                              [crit(rc.EA_MOBILE_SERVER, "like", guid)]))
+    j = rc.jamf_from_credentials()
+    try:
+        existing = {g["name"]: g["id"] for g in j.call("/api/v2/computer-groups/smart-groups?page=0&page-size=1000").get("results", [])}
+    except urllib.error.HTTPError as e:
+        sys.exit(f"cannot list smart groups (HTTP {e.code}); the API client needs Read Smart Computer Groups")
+    rule = lambda cs: [(c["name"], c["searchType"], (c["value"] or "").strip(), (c.get("andOr") or "and").lower()) for c in cs]      # Jamf trims values when a group is saved by hand
+    for name, desc, criteria in groups:
+        if name in existing:
+            if not args.update: print(f"exists:  {name}"); continue
+            try:
+                cur = j.call(f"/api/v2/computer-groups/smart-groups/{existing[name]}")
+                if rule(cur.get("criteria") or []) == rule(criteria): print(f"exists:  {name} (rule is current)"); continue
+                if args.dry_run: print(f"would update: {name}\n   from {json.dumps(rule(cur.get('criteria') or []))}\n   to   {json.dumps(rule(criteria))}"); continue
+                j.call(f"/api/v2/computer-groups/smart-groups/{existing[name]}", "PUT", {"name": name, "description": desc, "criteria": criteria, "siteId": str(cur.get("siteId") or "-1")})
+                print(f"updated: {name}")
+            except urllib.error.HTTPError as e: print(f"FAILED:  {name}: HTTP {e.code} {e.read().decode()[:200]} (updating needs Update Smart Computer Groups)")
+            continue
+        body = {"name": name, "description": desc, "criteria": criteria, "siteId": "-1"}
+        if args.dry_run: print(f"would create: {name}\n   {json.dumps(criteria)}"); continue
+        try: j.call("/api/v2/computer-groups/smart-groups", "POST", body); print(f"created: {name}")
+        except urllib.error.HTTPError as e: print(f"FAILED:  {name}: HTTP {e.code} {e.read().decode()[:200]}")
+    create_mobile(j, mobile_groups, args.dry_run)
+
+if __name__ == "__main__": main()
diff --git a/sales/preheat/admin/doctor.py b/sales/preheat/admin/doctor.py
new file mode 100644
index 0000000..1ec6461
--- /dev/null
+++ b/sales/preheat/admin/doctor.py
@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+doctor.py: check a Preheat installation end to end and say, in plain words, what to fix next.
+Read-only: it never changes anything in Jamf, on a Mac or in a cache.
+
+    python3 admin/doctor.py            # everything
+    python3 admin/doctor.py --offline  # only the parts that need no Jamf (Apple's lookup service, AppleDB, Python)
+
+Each line is PASS, WARN (works, but something is worth a look) or FAIL (a feature will not work until fixed),
+followed by what to do. Exit status 1 if anything failed. Credentials as for readiness-check.py.
+"""
+import argparse, datetime, os, re, sys, urllib.error, urllib.parse, urllib.request
+sys.path.insert(0, os.path.dirname(__file__)); rc = __import__("readiness-check")
+
+results = {"PASS": 0, "WARN": 0, "FAIL": 0}
+def say(level, what, fix=""):
+    results[level] += 1
+    print(f"{level:4}  {what}" + (f"\n        -> {fix}" if fix else ""))
+
+def probe(j, path):
+    """HTTP status of a GET, 200 when it works."""
+    try: j.call(path); return 200
+    except urllib.error.HTTPError as e: return e.code
+    except Exception: return 0
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--offline", action="store_true", help="skip everything that needs Jamf")
+    args = ap.parse_args()
+    here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    print("== This Mac and the outside services")
+    v = sys.version_info
+    say("PASS" if v >= (3, 8) else "FAIL", f"Python {v.major}.{v.minor}", "" if v >= (3, 8) else "install the Xcode Command Line Tools: xcode-select --install")
+    try:
+        a = rc.gdmf_assets("J274AP", "Macmini9,1", rc.NO_VERSION, "0", "mac")
+        say("PASS" if a else "FAIL", f"Apple's lookup service answers ({len(a)} macOS assets for a Mac mini M1)", "" if a else "gdmf.apple.com returned nothing: check outbound HTTPS, or Apple changed the service")
+    except Exception as e: say("FAIL", f"Apple's lookup service: {e}", "allow outbound HTTPS to gdmf.apple.com")
+    try:
+        try: os.remove(rc.BOARD_CACHE) if os.path.exists(rc.BOARD_CACHE) and os.path.getsize(rc.BOARD_CACHE) < 1000 else None
+        except OSError: pass
+        b = rc.board_for("iPhone17,3"); t2 = rc.board_for("MacBookPro16,1")
+        say("PASS" if b == "D47AP" and t2 == "J152FAP" else "FAIL", f"AppleDB model list (iPhone17,3 -> {b or '?'}, T2 MacBookPro16,1 -> {t2 or '?'})",
+            "" if b and t2 else "api.appledb.dev unreachable or its format changed; mobile devices and Intel T2 Macs cannot be looked up")
+    except Exception as e: say("FAIL", f"AppleDB: {e}", "allow outbound HTTPS to api.appledb.dev")
+    if args.offline: return finish()
+
+    print("\n== Jamf Pro: credentials and privileges")
+    try: j = rc.jamf_from_credentials()
+    except SystemExit as e: say("FAIL", str(e)); return finish()
+    except urllib.error.HTTPError as e:
+        say("FAIL", f"Jamf refused the API client (HTTP {e.code})", "check the client ID and secret, that the client is enabled, and that the URL is your Jamf Pro URL"); return finish()
+    except Exception as e: say("FAIL", f"cannot reach Jamf Pro: {e}", "check JAMF_URL and the network"); return finish()
+    say("PASS", f"API client accepted by {j.base}")
+    needs = [("/api/v1/computers-inventory?page=0&page-size=1", "Read Computers", "everything", "FAIL"),
+             ("/api/v1/computer-extension-attributes?page=0&page-size=1", "Read Computer Extension Attributes", "everything", "FAIL"),
+             ("/api/v2/mobile-devices/detail?page=0&page-size=1", "Read Mobile Devices", "--platforms (iPhone, iPad, Apple TV, Vision Pro)", "WARN"),
+             ("/api/v2/computer-groups/smart-groups?page=0&page-size=1", "Read Smart Computer Groups", "create-smart-groups.py and --cohort", "WARN"),
+             ("/api/v2/mobile-device-groups/smart-groups?page=0&page-size=1", "Read Smart Mobile Device Groups", "mobile Smart Groups and --cohort", "WARN"),
+             ("/api/v2/computer-groups/static-groups?page=0&page-size=1", "Read Static Computer Groups", "--cohort with a Static group", "WARN"),
+             ("/api/v1/mobile-device-groups/static-groups?page=0&page-size=1", "Read Static Mobile Device Groups", "--cohort with a Static mobile group", "WARN"),
+             ("/api/v1/scripts?page=0&page-size=1", "Read Scripts", "create-labels-policy.py", "WARN"),
+             ("/JSSResource/policies", "Read Policies", "create-labels-policy.py", "WARN")]
+    ok = {}
+    for path, priv, feature, level in needs:
+        code = probe(j, path); ok[priv] = code == 200
+        say("PASS" if code == 200 else level, f"{priv}" + ("" if code == 200 else f" (HTTP {code})"), "" if code == 200 else f"needed for {feature}: add it to the API role")
+    print("        (write privileges are only proven by use: Update Computers / Update Mobile Devices for --write, Create and Update for the setup scripts)")
+    if not ok["Read Computers"] or not ok["Read Computer Extension Attributes"]: return finish()
+
+    print("\n== Jamf Pro: what is installed")
+    eas = {e["name"]: e for e in j.call("/api/v1/computer-extension-attributes?page=0&page-size=500").get("results", [])}
+    for name, why in ((rc.EA_BOARD, "the board now comes from the model identifier"),):
+        old = eas.get(name)
+        if old: say("PASS", f"EA {old['name']} is installed and no longer needed ({why})", "it can be deleted in Jamf; nothing reads it" + (" except Macs from before 2016, which need it" if name == rc.EA_BOARD else ""))
+    scripts = {rc.EA_STATUS: "ea-content-cache-status.sh", rc.EA_FOUND: "ea-content-cache-servers-found.sh",
+               rc.EA_ASSETS: "ea-content-cache-macos-assets.sh", rc.EA_DECODED: "ea-content-cache-decoded.sh", rc.EA_EFFECT: "ea-content-cache-effectiveness.sh"}
+    for name, fn in scripts.items():
+        hit = eas.get(name)
+        if not hit: say("FAIL", f"EA {name} is not in Jamf", "python3 admin/sync-eas.py --create"); continue
+        local = open(os.path.join(here, "ea", fn)).read().strip()
+        if hit.get("inputType") != "SCRIPT": say("WARN", f"EA {hit['name']} is a {hit.get('inputType')} field, not a script", "python3 admin/sync-eas.py converts it")
+        elif (hit.get("scriptContents") or "").replace("\r\n", "\n").strip() != local: say("WARN", f"EA {hit['name']} differs from ea/{fn}", "python3 admin/sync-eas.py")
+        else: say("PASS", f"EA {hit['name']} matches ea/{fn}")
+    ready = eas.get(rc.EA_READY)
+    say("PASS" if ready else "FAIL", f"EA {rc.EA_READY} (Text Field, filled by --write)" + ("" if ready else " is not in Jamf"), "" if ready else "create it by hand: data type String, input type Text Field")
+    if ok.get("Read Smart Computer Groups"):
+        groups = {g["name"] for g in j.call("/api/v2/computer-groups/smart-groups?page=0&page-size=1000").get("results", [])}
+        want = ["Content Caching - Servers", "Content Caching - Ready for OS push", "Content Caching - Not ready", "Content Caching - Inactive or broken", "Content Caching - Low on space", "Content Caching - Low benefit", "Content Caching - Wiped recently", "Macs with no content cache"]
+        miss = [g for g in want if g not in groups]
+        say("PASS" if not miss else "WARN", "Smart Groups present" if not miss else "Smart Groups missing: " + ", ".join(miss), "" if not miss else "python3 admin/create-smart-groups.py")
+    if ok.get("Read Policies"):
+        pol = [p for p in j.call("/JSSResource/policies")["policies"] if p["name"] == "Preheat - Refresh cache labels"]
+        if not pol: say("WARN", "the labels policy is not in Jamf, so the decoded EA will show 'unidentified' for new files", "python3 admin/create-labels-policy.py")
+        else:
+            g = j.call(f"/JSSResource/policies/id/{pol[0]['id']}")["policy"]["general"]
+            say("PASS" if g.get("enabled") else "WARN", "labels policy present" + ("" if g.get("enabled") else " but DISABLED"), "" if g.get("enabled") else "enable it in Jamf, or decoded names stop updating")
+
+    print("\n== The fleet, as Jamf sees it today")
+    comps = j.inventory(); today = datetime.date.today()
+    servers = [c for c in comps if c["cache_guid"]]
+    say("PASS" if servers else "FAIL", f"{len(servers)} content cache server(s) among {len(comps)} Macs",
+        "" if servers else "Jamf's Content Caching inventory shows no Mac with caching switched on: is content caching on, is that Mac enrolled, has it sent inventory since?")
+    for c in comps:     # a Mac that found a cache on itself, and is not one now, was a cache server until recently
+        was = re.search(r"localhost:\d+ last-seen (\d{4}-\d\d-\d\d)", c["caches_found"] or "")
+        # Someone switched it off (its status is fine). A cache that lost its storage reports a problem instead,
+        # counts as a cache server that is down, and is reported further on.
+        if was and not c["cache_guid"] and (today - datetime.date.fromisoformat(was.group(1))).days <= 7:
+            say("WARN", f"{c['name']} was a content cache on {was.group(1)} and is switched off now",
+                "if that was meant, nothing to do (this note stops after 7 days). If not: Sharing > Content Caching on that Mac, then an inventory update")
+    sites = rc.collect_sites(comps)
+    for st in sites:
+        inside = [s["name"] for s in servers if rc.in_ranges(s.get("cache_public_ip"), st["public"])]
+        say("PASS" if inside else "WARN", f"site with public addresses {rc.show_ranges(st['public'])}" + (f", favored caches {rc.show_ranges(st['favored'])}" if st["favored"] else "") + f" ({st['source']}): " + (", ".join(inside) if inside else "no cache server registers from any of them"),
+            "" if inside else "the DNS TXT record and the caches' public addresses disagree: devices on this network are offered no cache")
+        if st["favored"]:
+            fav = [s["name"] for s in servers if any(rc.in_ranges(a, st["favored"]) for a in s.get("cache_ips") or [])]
+            if not fav: say("WARN", f"the favored range {rc.show_ranges(st['favored'])} contains no cache server Jamf knows", "devices fall back to other caches for shared content; check the fss record against the caches' addresses")
+    limit = j.silent_threshold(); utcnow = datetime.datetime.now(datetime.timezone.utc)
+    for s in servers:      # a server that is off, or off the network, changes nothing in Jamf: only its silence shows
+        heard = rc.last_heard(s, rc.live_cache(j.cache_status(s.get("management_id")), s.get("inventory_time") or ""))
+        if not heard: continue
+        quiet = int((utcnow - heard).total_seconds() // 60)
+        if quiet > limit: say("FAIL", f"{s['name']} has not been heard from since {heard.astimezone().strftime('%Y-%m-%d %H:%M')} ({quiet} minutes; limit {limit})",
+                              "it is off or off the network, and no device can use its cache. Its record in Jamf still reads as it did: check the Mac, its cable and its address")
+        else: say("PASS", f"{s['name']} was last heard from {quiet} minute(s) ago")
+    seen_live = 0
+    for c in comps:      # what each cache server, or former one, says about itself right now (macOS 27, through DDM)
+        if not (c["cache_guid"] or "localhost:" in (c["caches_found"] or "")): continue
+        live = rc.live_cache(j.cache_status(c.get("management_id")), c.get("inventory_time") or "")
+        if not live: continue
+        seen_live += 1
+        if not c["cache_guid"]:      # not a cache by inventory: said above. Worth a line only if it has been switched on since
+            if live["on"]: say("WARN", f"{c['name']} reports itself a running content cache since {live['since']}, and its inventory does not show that yet", "run an inventory update on it (sudo jamf recon)")
+            continue
+        if live["on"]: say("PASS", f"{c['name']} reports itself {live['line']} (DDM, {live['as_of']})")
+        else: say("FAIL", f"{c['name']} reports: {live['problem']} since {live['since']} (DDM, {live['as_of']})",
+                  "no device can use this cache until it is running and registered: check Sharing > Content Caching, its storage volume and its network")
+        known = {s["cache_guid"]: s["name"] for s in servers}
+        for x in live["peer_list"]:
+            who = known.get(x["guid"])
+            if who and x["healthy"]: say("PASS", f"{c['name']} has a peer: {who} at {x['address']}")
+            elif who: say("WARN", f"{c['name']} reports its peer {who} as unhealthy", "its content is not counted until it is healthy again")
+            else: say("WARN", f"{c['name']} has a peer at {x['address']} that Jamf does not list as a cache server", "a Mac with content caching on that is not enrolled, or has not sent inventory since it was switched on. Its content cannot be counted, and devices may be using it")
+        if live["changed_since_inventory"] and live["on"] != (c.get("cache_status") or "").startswith("Active"):      # a cache reports again whenever anything about it changes; only a different state matters
+            say("WARN", f"{c['name']}: the cache changed state at {live['since']}, after its last inventory", "run an inventory update on it (sudo jamf recon) so the file list and readiness are current")
+    if servers and not seen_live:
+        print("        (no live cache status through DDM: needs macOS 27 on the cache server and the privilege to read DDM status; inventory is used instead)")
+    for s in servers:
+        if "status OK" not in (s["cache_status"] or ""): say("WARN", f"{s['name']}: {s['cache_status'][:90]}", "see docs/CAVEATS.md: registration, VPN on the server, disk space")
+        assets = rc.parse_assets_ea(s["assets_ea"])
+        if not s["assets_ea"] or s["assets_ea"].startswith(("Must run", "No database")): say("WARN", f"{s['name']}: assets EA says '{s['assets_ea'][:60]}'", "run an inventory update on the server (sudo jamf recon)")
+        else: say("PASS", f"{s['name']}: {len(assets)} OS update file(s) listed, last inventory {s['last_inventory']}")
+        if s["last_inventory"] and (today - datetime.date.fromisoformat(s["last_inventory"])).days > 2:
+            say("WARN", f"{s['name']}: no inventory for {(today - datetime.date.fromisoformat(s['last_inventory'])).days} days, so every cache EA is stale", "check the Mac is on and checking in")
+    def age(c):
+        try: return (today - datetime.date.fromisoformat(c["last_inventory"])).days
+        except (TypeError, ValueError): return 9999
+    old = [c for c in comps if not c["cache_guid"] and age(c) > 30]     # readiness-check.py leaves these out too (--max-age-days)
+    if old: say("PASS", f"{len(old)} Mac record(s) with no inventory for over 30 days, left out of the readiness check: " + ", ".join(f"{c['name']} ({c['last_inventory'] or 'never'})" for c in old[:6]),
+                "nothing to do if they are retired or kept for reference")
+    macs = [c for c in comps if not c["cache_guid"] and age(c) <= 30]
+    noboard = []; nofound = [c["name"] for c in macs if not c["caches_found"]]
+    oldmacs = [c["name"] for c in macs if not c["board"]]
+    if oldmacs: say("WARN", f"{len(oldmacs)} Mac(s) whose board cannot be worked out from the model: " + ", ".join(oldmacs[:6]), "Macs from before 2016 with more than one board per model: install ea/ea-board-id.sh as a script EA named \"" + rc.EA_BOARD + "\" for them")
+    none = [c["name"] for c in macs if c["caches_found"].strip() == "None found"]
+    if noboard or nofound: say("WARN", f"{len(set(noboard + nofound))} Mac(s) have empty EAs (no inventory since the EAs were created): " + ", ".join(sorted(set(noboard + nofound))[:6]), "they fill in at the next inventory update")
+    if none: say("WARN", f"{len(none)} Mac(s) report 'None found': " + ", ".join(none[:6]), "expected for remote Macs; for office Macs look for a VPN or full-tunnel client (README caveats)")
+    if ok.get("Read Mobile Devices"):
+        try:
+            mob = j.mobile_inventory(); pubs = {s["cache_public_ip"] for s in servers if s.get("cache_public_ip")}
+            known = [r for st in sites for r in st["public"]]
+            off = [m["name"] for m in mob if m.get("ip") and pubs and m["ip"] not in pubs and not rc.in_ranges(m["ip"], known)]
+            say("PASS", f"{len(mob)} mobile device(s) in inventory")
+            if off: say("WARN", f"{len(off)} mobile device(s) report a public IP that matches no cache server: " + ", ".join(off[:6]), "remote devices, or a VPN on the device: Apple will not offer them the cache either. If the site has more than one public address, see --public-ranges in readiness-check.py --help. Otherwise either")
+        except Exception as e: say("WARN", f"mobile inventory: {e}")
+    return finish()
+
+def finish():
+    print(f"\n{results['PASS']} passed, {results['WARN']} to look at, {results['FAIL']} failed")
+    sys.exit(1 if results["FAIL"] else 0)
+
+if __name__ == "__main__": main()
diff --git a/sales/preheat/admin/make-usage.sh b/sales/preheat/admin/make-usage.sh
new file mode 100644
index 0000000..4ee3e50
--- /dev/null
+++ b/sales/preheat/admin/make-usage.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# make-usage.sh: write docs/USAGE.md from every script's own --help, so the page cannot drift from the code.
+# Run after changing any option:   bash admin/make-usage.sh
+# Needs nothing but this repository: --help never contacts Jamf or Apple.
+set -u
+case "${1:-}" in -h|--help) /usr/bin/sed -n '2,/^set -u/p' "$0" | /usr/bin/sed -e '/^set -u/d' -e 's/^# \{0,1\}//'; exit 0;; esac
+cd "$(dirname "$0")/.." || exit 1
+OUT=docs/USAGE.md; mkdir -p docs
+{
+  echo "# Every script and its options"
+  echo
+  echo "Generated by \`admin/make-usage.sh\` from each script's own \`--help\`. Do not edit by hand."
+  echo "Every script answers \`--help\` (or \`-h\`) and changes nothing when asked."
+  for f in admin/readiness-check.py admin/preheat.sh admin/doctor.py admin/preheat-labels.py admin/sync-eas.py \
+           admin/create-smart-groups.py admin/create-labels-policy.py admin/cache-collect.sh \
+           admin/troubleshoot-server.sh admin/troubleshoot-client.sh admin/make-usage.sh; do
+    echo; echo "## ${f#admin/}"; echo; echo '```'
+    case "$f" in *.py) COLUMNS=100 /usr/bin/python3 "$f" --help;; *) /bin/bash "$f" --help;; esac
+    echo '```'
+  done
+} > "$OUT"
+echo "wrote $OUT ($(wc -l < "$OUT" | tr -d ' ') lines)"
diff --git a/sales/preheat/admin/preheat-labels.py b/sales/preheat/admin/preheat-labels.py
new file mode 100644
index 0000000..223c8f8
--- /dev/null
+++ b/sales/preheat/admin/preheat-labels.py
@@ -0,0 +1,278 @@
+#!/usr/bin/python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+preheat-labels.py: name the OS update files a content cache holds. Runs ON the cache server, as root,
+from a Jamf policy (recurring check-in, ongoing, with Update Inventory). Needs NO Jamf credentials.
+
+The cache stores updates under opaque paths. Apple's public lookup service (gdmf.apple.com) is the only
+way to turn a path into "iOS 27.0 (24A437) full for iPhone17,3". This script asks that service on behalf
+of every device model (list from AppleDB), and writes what it learns to
+    /Library/Application Support/preheat/labels.json      {"labels": {"<path>": "<human label>"}}
+The EA script ea-content-cache-decoded.sh reads that file at inventory time, so the EA itself stays
+local-only. A path's label never changes, so labels are kept forever and the network is only used when
+the cache holds a path that has no label yet.
+
+Passes, each only if unlabelled paths remain:
+  1. full installers (InstallAssistant.pkg) from Apple's software update catalog
+  2. every model with no source build: full images, and every tvOS delta
+  3. every model of the platforms still unlabelled, per released build (newest first): deltas.
+     iOS only offers a delta when the source version AND build both match a real release (AppleDB supplies the pair)
+
+Usage:  preheat-labels.py [--paths FILE] [--out FILE] [--all] [--max-builds N]
+  --paths FILE   read cached paths from FILE (one per line, or raw assets EA text) instead of the cache database
+  --all          label everything Apple offers, not just what this cache holds (passes 1-2)
+Python 3 standard library only.
+"""
+import argparse, base64, concurrent.futures, datetime, json, os, re, shutil, sqlite3, subprocess, sys, tempfile
+import urllib.parse, urllib.request, uuid
+
+GDMF_URL = "https://gdmf.apple.com/v2/assets"
+APPLEDB_DEVICES = "https://api.appledb.dev/device/main.json"
+APPLEDB_BUILDS = "https://api.appledb.dev/ios/index.json"      # ["iOS;23H24", "macOS;25G229", ...]
+SUCATALOG_URL = ("https://swscan.apple.com/content/catalogs/others/"
+                 "index-26-15-14-13-12-10.16-10.15-10.14-10.13-10.12-10.11-10.10-10.9-mountainlion-lion-snowleopard-leopard.merged-1.sucatalog")
+STATE_DIR = "/Library/Application Support/preheat"
+UA = {"User-Agent": "preheat/1.0"}
+FORMAT = 3      # bump when label wording changes: every file is renamed once
+SEARCH_REV = 3  # bump when the search gets smarter: paths given up on are tried again at once      # bump when label wording or logic changes
+SU = "com.apple.MobileAsset.SoftwareUpdate"
+# platform -> (asset type, release audience, OS name, AppleDB build-list names)
+PLATFORMS = {
+    "mac":      ("com.apple.MobileAsset.MacSoftwareUpdate", "60b55e25-a8ed-4f45-826c-c1495a4ccc65", "macOS", ("macOS",)),
+    "ios":      (SU, "01c1d682-6e8f-4908-b724-5501fe3f5e5c", "iOS", ("iOS",)),
+    "ipados":   (SU, "01c1d682-6e8f-4908-b724-5501fe3f5e5c", "iPadOS", ("iPadOS", "iOS")),
+    "tvos":     (SU, "356d9da0-eee4-4c6c-bbe5-99b60eadddf0", "tvOS", ("tvOS",)),
+    "visionos": (SU, "c59ff9d1-5468-4f6c-9e54-f68d5eeab93b", "visionOS", ("visionOS",)),
+    "watchos":  (SU, "b82fcf9c-c284-41c9-8eb2-e69bf5a5269f", "watchOS", ("watchOS",)),
+    "audioos":  (SU, "0322d49d-d558-4ddf-bdff-c0443d0e6fac", "HomePod software", ("audioOS",)),
+}
+# Source version sent when there is no real one. It must look like a real version: "0" is refused for HomePod and
+# "1.0" returns nothing for Apple TV, while any two-part version (tested 18.0, 26.0, 99.0) works on every platform.
+NO_VERSION = "26.0"
+# The previous OS branch (iOS 26.7 once 27 is out) is published on a second, "alternate" audience; ask both
+ALT_AUDIENCE = {"ios": "c724cb61-e974-42d3-a911-ffd4dce11eda", "ipados": "c724cb61-e974-42d3-a911-ffd4dce11eda",
+                "visionos": "bb4eeb45-d4f7-4777-bd18-eb38c8443a9c"}
+
+def platform_of(model):
+    for prefix, plat in (("iPhone", "ios"), ("iPod", "ios"), ("iPad", "ipados"), ("AppleTV", "tvos"), ("RealityDevice", "visionos"),
+                         ("Watch", "watchos"), ("AudioAccessory", "audioos")):
+        if model.startswith(prefix): return plat
+    return "mac" if re.match(r"(Mac|iMac|MacBook)", model) else None
+
+def fetch(url, timeout=120):
+    with urllib.request.urlopen(urllib.request.Request(url, headers=UA), timeout=timeout) as r: return r.read()
+
+def cached_paths():
+    """OS update paths in this Mac's content cache database (root only)."""
+    try:
+        st = json.loads(subprocess.run(["/usr/bin/AssetCacheManagerUtil", "-j", "settings"], capture_output=True, text=True).stdout or "{}")
+    except Exception: st = {}
+    data = (st.get("result") or {}).get("DataPath") or "/Library/Application Support/Apple/AssetCache/Data"
+    db = os.path.join(data, "AssetInfo.db")
+    if not os.path.isfile(db): return []
+    w = tempfile.mkdtemp(prefix="preheat-labels.")
+    try:
+        for ext in ("", "-wal", "-shm"):
+            if os.path.exists(db + ext): shutil.copy(db + ext, os.path.join(w, "db" + ext))
+        con = sqlite3.connect(os.path.join(w, "db"))
+        return [r[0] for r in con.execute("select ZURI from ZASSET where ZURI like '%/InstallAssistant.pkg' "
+                "or ZURI like '%com_apple_MobileAsset_MacSoftwareUpdate/%' or ZURI like '%com_apple_MobileAsset_SoftwareUpdate/%' "
+                "or ZURI like '%SimulatorRuntime/%' or ZURI like '%com_apple_MobileAsset_MetalToolchain/%' or ZURI like '/itunes-assets/Aerials%'")]
+    finally: shutil.rmtree(w, ignore_errors=True)
+
+def models():
+    """[(model identifier, board, platform)] for everything released since 2013, from AppleDB (Macs incl. Intel, iPhone, iPad, Apple TV, Vision Pro, Watch, HomePod)."""
+    out, seen = [], set()
+    db = json.loads(fetch(APPLEDB_DEVICES))
+    # Intel Macs with a T2 chip: Apple answers for the T2's own board in capitals (MacBookPro16,1 -> J152FAP), not Mac-xxxx
+    t2 = {m.group(1): (d.get("board") if isinstance(d.get("board"), str) else (d.get("board") or [""])[0])[:-2].upper() + "AP"
+          for d in db for m in [re.fullmatch(r"T2 \((\w+,\d+)\)", d.get("name") or "")] if m and d.get("board")}
+    for d in db:
+        ids = d.get("identifier") or []; ids = [ids] if isinstance(ids, str) else ids
+        bs = d.get("board") or []; bs = [bs] if isinstance(bs, str) else bs
+        rel = d.get("released"); rel = (rel[0] if isinstance(rel, list) and rel else rel) or ""
+        if not ids or not bs or str(rel) < "2013": continue
+        for i, m in enumerate(ids):
+            p = platform_of(m)
+            for b in ([t2[m]] if m in t2 else bs if len(ids) == 1 else [bs[i] if i < len(bs) else bs[0]]):
+                if p and (m, b) not in seen: seen.add((m, b)); out.append((m, b, p))
+    return out
+
+def gdmf(model, board, plat, build="0", version=NO_VERSION):
+    atype, audience = PLATFORMS[plat][:2]; assets = []
+    for aud in [audience] + ([ALT_AUDIENCE[plat]] if plat in ALT_AUDIENCE else []):
+        body = {"ClientVersion": 2, "AssetType": atype, "AssetAudience": aud, "CertIssuanceDay": "2023-12-10",
+                "BuildVersion": build, "HWModelStr": board, "ProductType": model, "ProductVersion": version,
+                "CompatibilityVersion": 20, "Nonce": str(uuid.uuid4())}
+        req = urllib.request.Request(GDMF_URL, data=json.dumps(body).encode(), headers={"Content-Type": "application/json"}, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=60) as r: jwt = r.read().decode()
+            p = jwt.split(".")[1]
+            assets += json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4))).get("Assets", [])
+        except Exception: pass
+    return model, plat, assets
+
+def sweep(jobs, info):
+    """Run lookups in parallel and fold every asset seen into info[path]."""
+    with concurrent.futures.ThreadPoolExecutor(8) as ex:
+        for model, plat, assets in ex.map(lambda j: gdmf(*j), jobs):
+            for a in assets:
+                path = urllib.parse.urlparse(a.get("__BaseURL", "") + a.get("__RelativePath", "")).path
+                e = info.setdefault(path, {"plat": plat, "ver": (a.get("OSVersion") or "").replace("9.9.", "", 1), "build": a.get("Build"),
+                                           "from_ver": a.get("PrerequisiteOSVersion"), "from_build": a.get("PrerequisiteBuild"),
+                                           "beta": a.get("ReleaseType") == "Beta", "models": set()})
+                if e["beta"] and a.get("ReleaseType") != "Beta": e.update(beta=False, build=a.get("Build"))   # same file listed as beta and release
+                e["models"].add(model)
+
+def label(e):
+    ms = sorted(e["models"])
+    who = f"all Macs ({len(ms)} models)" if e["plat"] == "mac" and len(ms) >= 10 else ", ".join(ms[:3]) + (f" +{len(ms)-3} more" if len(ms) > 3 else "")
+    kind = f"delta from {e['from_ver']} ({e['from_build']})" if e["from_build"] else "full"
+    return f"{PLATFORMS[e['plat']][2]} {e['ver']} ({e['build']}) {kind}{' beta' if e['beta'] else ''} for {who}"
+
+def label_installers(want, labels):
+    import plistlib
+    cat = plistlib.loads(fetch(SUCATALOG_URL))
+    for pid, prod in cat.get("Products", {}).items():
+        for pkg in prod.get("Packages", []):
+            path = urllib.parse.urlparse(pkg.get("URL", "")).path
+            if path not in want: continue
+            labels[path] = f"macOS full installer, product {pid}"
+            try:
+                dists = prod.get("Distributions", {}); x = fetch(dists.get("English") or next(iter(dists.values())), 60).decode(errors="ignore")
+                v = re.search(r"<key>VERSION</key>\s*<string>([^<]+)</string>", x); b = re.search(r"<key>BUILD</key>\s*<string>([^<]+)</string>", x)
+                t = re.search(r"<title>([^<]+)</title>", x)
+                if v: labels[path] = f"{(t.group(1) if t else 'macOS').strip()} {v.group(1)} ({b.group(1) if b else '?'}) full installer for all Macs"
+            except Exception: pass
+
+def build_key(b):
+    m = re.match(r"(\d+)([A-Z])(\d+)", b); return (int(m.group(1)), m.group(2), int(m.group(3))) if m else (0, "", 0)
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--paths"); ap.add_argument("--out", default=os.path.join(STATE_DIR, "labels.json"))
+    ap.add_argument("--all", action="store_true"); ap.add_argument("--max-builds", type=int, default=16, help="pass 3 rounds: how many earlier builds per model to try")
+    args, _ = ap.parse_known_args()          # Jamf passes mount point, computer name and user as $1-$3
+    if args.paths: paths = [l.split()[-1] for l in open(args.paths) if l.strip() and l.split()[-1].startswith("/")]
+    else: paths = cached_paths()
+    try: state = json.load(open(args.out))
+    except Exception: state = {}
+    labels = state.get("labels", {}) if state.get("format") == FORMAT else {}      # a format bump renames everything once
+    today = datetime.date.today().isoformat()
+    if state.get("search_rev") != SEARCH_REV: state["gave_up"] = {}
+    todo = lambda: [p for p in paths if p not in labels and state.get("gave_up", {}).get(p) != today]
+    print(f"{len(paths)} cached OS update path(s), {len(todo())} without a label")
+    if not todo() and not args.all: return
+    if any(p.startswith("/itunes-assets/Aerials") for p in todo()):      # Aerial screen savers: names from Apple's public manifest
+        try:
+            import plistlib, tarfile, io
+            cfg = plistlib.loads(fetch("https://configuration.apple.com/configurations/internetservices/aerials/resources-config-27-0.plist"))
+            tar = tarfile.open(fileobj=io.BytesIO(fetch(cfg["resources-url"])))
+            d = json.load(tar.extractfile(next(m for m in tar.getmembers() if m.name.endswith("entries.json"))))
+            cats = {c["id"]: c.get("localizedNameKey", "").replace("AerialCategory", "") for c in d.get("categories", [])}
+            for a in d.get("assets", []):
+                for k, u in a.items():
+                    if k.startswith("url") and u:
+                        labels[urllib.parse.urlparse(u).path] = f"Aerial screen saver: {a.get('accessibilityLabel') or a.get('id')} ({', '.join(cats.get(c, c) for c in a.get('categories', [])) or 'Aerial'})"
+            # The manifest lists one file per video (4K). Apple TVs and older systems ask for other encodings of the
+            # same shot, stored under another folder with the same opening to the file name: name those by their shot.
+            known = {os.path.basename(k): v for k, v in labels.items() if k.startswith("/itunes-assets/Aerials") and "another encoding" not in v}
+            def shot(a, b):      # how much of the opening two file names share: (whole words, letters)
+                n = len(os.path.commonprefix([a, b])); whole = a[:n] if n == len(a) or not a[n:n+1].isalnum() else a[:n].rpartition("_")[0]
+                return len([w for w in whole.split("_") if w and w != "comp"]), n
+            for path in [x for x in todo() if x.startswith("/itunes-assets/Aerials")]:
+                name = os.path.basename(path); ranked = {}
+                for fn, lab in known.items(): ranked[lab] = max(ranked.get(lab, (0, 0)), shot(name, fn))
+                best = sorted(ranked.items(), key=lambda kv: kv[1], reverse=True)[:2]
+                if best and best[0][1][0] >= 2 and (len(best) == 1 or best[0][1] > best[1][1]):
+                    labels[path] = best[0][0] + ", another encoding"
+            print(f"aerials: {len(todo())} path(s) still without a label after Apple's manifest")
+        except Exception as e: print(f"warning: Apple's Aerial manifest unavailable ({e})")
+    if any("SimulatorRuntime" in p or "MetalToolchain" in p for p in todo()):      # Xcode components: names from Apple's public index
+        try:
+            import plistlib
+            idx = plistlib.loads(fetch("https://devimages-cdn.apple.com/downloads/xcode/simulators/index2.dvtdownloadableindex"))
+            fam = {"iOS ": "com.apple.MobileAsset.iOSSimulatorRuntime", "tvOS ": "com.apple.MobileAsset.appleTVOSSimulatorRuntime",
+                   "watchOS ": "com.apple.MobileAsset.watchOSSimulatorRuntime", "visionOS ": "com.apple.MobileAsset.xrOSSimulatorRuntime", "xrOS ": "com.apple.MobileAsset.xrOSSimulatorRuntime"}
+            jobs = [(d["simulatorVersion"]["buildUpdate"], d["name"], t) for d in idx.get("downloadables", []) if d.get("simulatorVersion")
+                    for pre, t in fam.items() if d["name"].startswith(pre)]
+            jobs += [(m.group(1), d["name"], "com.apple.MobileAsset.MetalToolchain") for d in idx.get("otherDownloadables", [])
+                     for m in [re.search(r"^Metal Toolchain \((\w+)\)", d.get("name", ""))] if m]
+            def ask(job):
+                build, name, atype = job
+                body = {"ClientVersion": 2, "AssetType": atype, "AssetAudience": "02d8e57e-dd1c-4090-aa50-b4ed2aef0062", "CertIssuanceDay": "2023-12-10",
+                        "BuildVersion": "26A428", "HWModelStr": "J274AP", "ProductType": "Macmini9,1", "ProductVersion": "27.0", "CompatibilityVersion": 20,
+                        "RequestedBuild": build, "Nonce": str(uuid.uuid4())}
+                req = urllib.request.Request(GDMF_URL, data=json.dumps(body).encode(), headers={"Content-Type": "application/json"}, method="POST")
+                try:
+                    with urllib.request.urlopen(req, timeout=60) as r: p = r.read().decode().split(".")[1]
+                    return [(urllib.parse.urlparse(a.get("__BaseURL", "") + a.get("__RelativePath", "")).path, name) for a in json.loads(base64.urlsafe_b64decode(p + "=" * (-len(p) % 4))).get("Assets", [])]
+                except Exception: return []
+            with concurrent.futures.ThreadPoolExecutor(8) as ex:
+                for pairs in ex.map(ask, jobs):
+                    for path, name in pairs: labels[path] = name
+            print(f"xcode: {len(jobs)} index entries asked, {len(todo())} path(s) still without a label")
+        except Exception as e: print(f"warning: Apple's simulator index unavailable ({e})")
+    info = {}
+    try:
+        inst = {p for p in todo() if p.endswith("/InstallAssistant.pkg")}
+        if inst: label_installers(inst, labels)
+        if todo() or args.all:
+            devs = models(); print(f"pass 2: {len(devs)} models, no source build")
+            sweep([(m, b, p) for m, b, p in devs], info)
+            labels.update({p: label(e) for p, e in info.items()})
+        if todo():      # pass 3: deltas. Each model is asked about ITS OWN recent builds, newest first: the builds that share
+            # a leading number with the newest OS it can run (17.7.11 is 21H461, so 21H450, 21H440 ...), then the
+            # generation before (how a 26.7 device reaches 27.0). One round = one build per model.
+            index = json.loads(fetch(APPLEDB_BUILDS)); meta = state.setdefault("build_meta", {})
+            fam = {}      # (os name, leading number) -> builds, newest first
+            for x in index:
+                o, _, bld = x.partition(";")
+                if re.fullmatch(r"\d+[A-Z]\d+", bld): fam.setdefault((o, re.match(r"\d+", bld).group()), []).append(bld)
+            for k in fam: fam[k].sort(key=build_key, reverse=True)
+            def build_info(ob):      # AppleDB lists release candidates, betas and internal builds beside releases; devices only
+                o, bld = ob          # run releases, and trying the others first pushed real source builds out of reach
+                key = f"{o};{bld}"
+                if key not in meta:
+                    try:
+                        d = json.loads(fetch(f"https://api.appledb.dev/ios/{urllib.parse.quote(o)};{bld}.json", 60))
+                        meta[key] = {"v": (d.get("version") or "").split(" ")[0], "skip": bool(d.get("beta") or d.get("rc") or d.get("internal"))}
+                    except Exception: meta[key] = {"v": "", "skip": False}
+                return meta[key]
+            def version_of(o, bld): return build_info((o, bld))["v"]
+            newest = {}      # model -> build of the newest full image Apple offers it
+            for e in info.values():
+                if not e["from_build"]:
+                    for m in e["models"]:
+                        if m not in newest or build_key(e["build"]) > build_key(newest[m]): newest[m] = e["build"]
+            left = todo()
+            kinds = {"mac"} if all("MacSoftwareUpdate" in p for p in left) else set(PLATFORMS) - {"mac", "tvos"} if not any("MacSoftwareUpdate" in p for p in left) else set(PLATFORMS) - {"tvos"}
+            cands = {}
+            for m, b, p in devs:
+                if p not in kinds or m not in newest: continue
+                lead = int(re.match(r"\d+", newest[m]).group()); o = next((n for n in PLATFORMS[p][3] if (n, str(lead)) in fam), PLATFORMS[p][3][0])
+                same = [x for x in fam.get((o, str(lead)), []) if build_key(x) < build_key(newest[m])]; prev = fam.get((o, str(lead - 1)), [])
+                merged = [x for pair in zip(same, prev) for x in pair] + same[len(prev):] + prev[len(same):]
+                cands[(m, b, p)] = [(o, x) for x in merged[:40]]
+            with concurrent.futures.ThreadPoolExecutor(8) as ex: list(ex.map(build_info, {ob for c in cands.values() for ob in c}))
+            cands = {k: [ob for ob in c if not build_info(ob)["skip"]] for k, c in cands.items()}
+            rnd = -1
+            for rnd in range(args.max_builds):
+                if not todo(): break
+                jobs = [(m, b, p, c[rnd][1], version_of(*c[rnd]) or NO_VERSION) for (m, b, p), c in cands.items() if rnd < len(c)]
+                if not jobs: break
+                sweep(jobs, info); labels.update({p: label(e) for p, e in info.items()})
+            print(f"pass 3: {rnd + 1} round(s), {len(todo())} path(s) still without a label")
+            for p in todo(): state.setdefault("gave_up", {})[p] = today      # retry tomorrow, not at every check-in
+    finally:
+        os.makedirs(os.path.dirname(args.out), exist_ok=True)
+        tmp = args.out + ".tmp"
+        json.dump({"format": FORMAT, "search_rev": SEARCH_REV, "updated": datetime.datetime.now().strftime("%Y-%m-%d %H:%M"), "labels": labels,
+                   "build_meta": state.get("build_meta", {}), "gave_up": {p: d for p, d in state.get("gave_up", {}).items() if p not in labels}}, open(tmp, "w"), indent=0)
+        os.chmod(tmp, 0o644); os.replace(tmp, args.out)
+    left = [p for p in paths if p not in labels]      # includes paths given up on until tomorrow
+    print(f"{len(labels)} label(s) on file; {len(left)} cached path(s) still unidentified" + (": " + ", ".join(os.path.basename(p)[:12] for p in left) if left else ""))
+
+if __name__ == "__main__": main()
diff --git a/sales/preheat/admin/preheat.sh b/sales/preheat/admin/preheat.sh
new file mode 100755
index 0000000..4a94793
--- /dev/null
+++ b/sales/preheat/admin/preheat.sh
@@ -0,0 +1,80 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# preheat.sh: pull the OS update assets a cache server is missing THROUGH that cache, so it is
+# warm for hardware families nobody on site owns. Reads a plan written by
+#   python3 admin/readiness-check.py --preheat-plan plan.json
+#
+# Run ON the cache server (default: talks to the local cache, finds its own GUID and port):
+#   sudo bash preheat.sh plan.json
+#   bash preheat.sh https://your.host/plan.json        # plan can be a URL (e.g. a Jamf policy parameter)
+# Or from any Mac on the server's network:
+#   bash preheat.sh plan.json --server 10.0.0.2:49152 --guid <server GUID>
+# Options: --dry-run (list only)   --max-gb N (stop after N GB)   --platform mac|ios|ipados|tvos|visionos|xcode|installer|aerial
+#
+# Jamf policy use: script parameter 4 = plan URL, 5 = extra options; scope to the "Content Caching - Servers" Smart Group.
+set -u
+case "${1:-}" in -h|--help) /usr/bin/sed -n '2,/^set -u/p' "$0" | /usr/bin/sed -e '/^set -u/d' -e 's/^# \{0,1\}//'; exit 0;; esac
+PLAN="${1:-${4:-}}"; shift || true
+[[ "$PLAN" == "" ]] && { echo "usage: preheat.sh <plan.json or URL> [--server host:port --guid GUID] [--dry-run] [--max-gb N] [--platform p]"; exit 1; }
+SERVER=""; GUID=""; DRY=0; MAXGB=0; PLAT=""
+ARGS=("$@"); [[ -n "${5:-}" && "${1:-}" == "" ]] && read -ra ARGS <<< "$5"
+i=0; while [[ $i -lt ${#ARGS[@]} ]]; do
+  case "${ARGS[$i]}" in
+    --server) SERVER="${ARGS[$((i+1))]}"; i=$((i+2));; --guid) GUID="${ARGS[$((i+1))]}"; i=$((i+2));;
+    --dry-run) DRY=1; i=$((i+1));; --max-gb) MAXGB="${ARGS[$((i+1))]}"; i=$((i+2));; --platform) PLAT="${ARGS[$((i+1))]}"; i=$((i+2));;
+    *) i=$((i+1));;
+  esac
+done
+if [[ -z "$SERVER" ]]; then   # running on the cache server itself
+  ST=$(/usr/bin/AssetCacheManagerUtil -j status 2>/dev/null)
+  PORT=$(/usr/bin/python3 -c 'import json,sys; r=json.loads(sys.argv[1])["result"]; print(r.get("Port") or 0)' "$ST")
+  [[ -z "$GUID" ]] && GUID=$(/usr/bin/python3 -c 'import json,sys; print(json.loads(sys.argv[1])["result"].get("ServerGUID",""))' "$ST")
+  [[ "$PORT" == "0" || -z "$GUID" ]] && { echo "content caching is not active here and no --server/--guid given"; exit 1; }
+  SERVER="localhost:$PORT"
+fi
+W=$(/usr/bin/mktemp -d /tmp/preheat.XXXXXX); trap 'rm -rf "$W"' EXIT
+if [[ "$PLAN" == http* ]]; then /usr/bin/curl -sf -m 60 -o "$W/plan.json" "$PLAN" || { echo "cannot fetch plan $PLAN"; exit 1; }; PLAN="$W/plan.json"; fi
+/usr/bin/python3 - "$PLAN" "$GUID" "$PLAT" > "$W/list" <<'PY'
+import json,sys,urllib.parse
+plan=json.load(open(sys.argv[1])); guid=sys.argv[2].upper(); plat=sys.argv[3]
+seen=set()
+for a in plan.get("assets",[]):
+    if a.get("server_guid","").upper()!=guid: continue
+    if plat and a.get("platform")!=plat: continue
+    u=urllib.parse.urlparse(a["url"])
+    if a["url"] in seen: continue
+    seen.add(a["url"])
+    print(f"{a['size']}\t{u.hostname}\t{u.path}\t{a['platform']} {a['model']} {a['from_version']}->{a['to_version']}")
+PY
+N=$(wc -l < "$W/list" | tr -d ' '); TOTAL=$(awk -F'\t' '{s+=$1} END{printf "%.1f", s/1e9}' "$W/list")
+echo "server $SERVER guid $GUID: $N asset(s), $TOTAL GB to pull"
+[[ "$N" == "0" ]] && exit 0
+DONE_GB=0; FAILED=0
+while IFS=$'\t' read -r SIZE HOST PATHP LABEL; do
+  GB=$(awk -v b="$SIZE" 'BEGIN{printf "%.1f", b/1e9}')
+  if [[ "$MAXGB" != "0" ]] && awk -v d="$DONE_GB" -v g="$GB" -v m="$MAXGB" 'BEGIN{exit !(d+g>m)}'; then echo "skip  $LABEL ($GB GB): --max-gb $MAXGB reached"; continue; fi
+  if [[ $DRY == 1 ]]; then echo "would pull  $LABEL ($GB GB)  $HOST$PATHP"; continue; fi
+  printf 'pull  %s (%s GB) ... ' "$LABEL" "$GB"
+  # "HTTP 200" only says the download started. curl's own exit status says whether every byte arrived
+  # (18 = the connection closed early), and a second request picks up where the cache left off.
+  TRY=0; OK=0
+  while [[ $TRY -lt 3 ]]; do
+    TRY=$((TRY+1))
+    OUT=$(/usr/bin/curl -s -m 14400 -o /dev/null -w '%{http_code} %{size_download}' "http://$SERVER$PATHP?source=$HOST&sourceScheme=https"); RC=$?
+    CODE=${OUT%% *}; GOT=${OUT##* }
+    if [[ $RC -eq 0 && "$CODE" == "200" ]]; then OK=1; break; fi
+    [[ "$CODE" != "200" && "$CODE" != "000" ]] && break      # the cache answered with an error: asking again will not help
+    sleep 5
+  done
+  if [[ $OK == 1 ]]; then
+    echo "HTTP 200$([[ $TRY -gt 1 ]] && echo " (complete on attempt $TRY)")"
+    DONE_GB=$(awk -v d="$DONE_GB" -v g="$GB" 'BEGIN{printf "%.1f", d+g}')
+  else
+    echo "INCOMPLETE: HTTP $CODE, curl error $RC, $(awk -v b="${GOT:-0}" 'BEGIN{printf "%.1f", b/1e9}') GB received after $TRY attempt(s)"
+    FAILED=$((FAILED+1))
+  fi
+done < "$W/list"
+echo "pulled $DONE_GB GB through $SERVER; run a Jamf inventory update on the server to refresh its assets EA"
+if [[ $FAILED -gt 0 ]]; then echo "$FAILED file(s) did not arrive whole. Run the same plan again: the cache keeps what it has and fetches the rest."; exit 1; fi
diff --git a/sales/preheat/admin/readiness-check.py b/sales/preheat/admin/readiness-check.py
new file mode 100755
index 0000000..68a04fd
--- /dev/null
+++ b/sales/preheat/admin/readiness-check.py
@@ -0,0 +1,1166 @@
+#!/usr/bin/env python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+Content cache macOS update readiness check, per cache server  (admin-side, NOT an EA script)
+
+Question answered: for each content caching server, is it ready for the Macs that actually
+use it, i.e. does it already hold the macOS update every hardware/build combination on its
+network would download?
+
+Data sources (all from Jamf Pro inventory)
+  every Mac        model identifier -> board          hardware family key Apple uses (J413AP ...), from AppleDB
+  every Mac        EA "Content Caching - Servers Found" which cache server(s) this Mac would use (GUID host:port ...)
+  cache servers    Jamf's Content Caching inventory   activated, active, server GUID (the join key), port, addresses
+                   (and EA "Content Caching - Status", the same facts worked out during inventory, for Smart Groups)
+  cache servers    EA "Content Caching - macOS Assets"  cached macOS assets with COMPLETE / PARTIAL
+  every Mac        model identifier, OS version, OS build, site, building
+
+Steps
+  1. Group Macs by the cache server they report (or by building with --group-by building).
+  2. For each server, for each distinct (board, model, version, build) among ITS Macs, ask
+     Apple's lookup service (gdmf.apple.com) which asset that Mac would download.
+  3. Check that asset against the server's cached assets.
+  4. Print a per-server report; with --write store "READY / PARTIAL / NOT READY ..." in the
+     server's EA "Content Caching - macOS Readiness" for Smart Groups.
+
+Auth: the macOS login keychain (store once with --store-credentials), or the environment
+      variables JAMF_URL, JAMF_CLIENT_ID, JAMF_CLIENT_SECRET for CI and one-off runs.
+Offline test:  --inventory-json admin/sample-inventory.json
+Python 3 standard library only.
+"""
+import argparse, json, os, re, sys, time, urllib.error, urllib.request, urllib.parse, uuid, base64, datetime, collections
+
+GDMF_URL = "https://gdmf.apple.com/v2/assets"
+MACOS_RELEASE_AUDIENCE = "60b55e25-a8ed-4f45-826c-c1495a4ccc65"
+# Platform -> (Apple lookup asset type, release audience). iOS and iPadOS share both.
+PLATFORMS = {
+    "mac":      ("com.apple.MobileAsset.MacSoftwareUpdate", "60b55e25-a8ed-4f45-826c-c1495a4ccc65"),
+    "ios":      ("com.apple.MobileAsset.SoftwareUpdate",    "01c1d682-6e8f-4908-b724-5501fe3f5e5c"),
+    "ipados":   ("com.apple.MobileAsset.SoftwareUpdate",    "01c1d682-6e8f-4908-b724-5501fe3f5e5c"),
+    "tvos":     ("com.apple.MobileAsset.SoftwareUpdate",    "356d9da0-eee4-4c6c-bbe5-99b60eadddf0"),
+    "visionos": ("com.apple.MobileAsset.SoftwareUpdate",    "c59ff9d1-5468-4f6c-9e54-f68d5eeab93b"),
+    # Jamf does not inventory these, so they never appear in readiness; they exist for --preheat-models
+    "watchos":  ("com.apple.MobileAsset.SoftwareUpdate",    "b82fcf9c-c284-41c9-8eb2-e69bf5a5269f"),
+    "audioos":  ("com.apple.MobileAsset.SoftwareUpdate",    "0322d49d-d558-4ddf-bdff-c0443d0e6fac"),
+}
+OSNAME = {"mac": "macOS", "ios": "iOS", "ipados": "iPadOS", "tvos": "tvOS", "visionos": "visionOS", "watchos": "watchOS", "audioos": "HomePod software"}
+# Source version sent when there is no real one; must look real ("0" is refused for HomePod, "1.0" gets nothing for Apple TV)
+NO_VERSION = "26.0"
+
+# ---------- Xcode components ----------
+# Apple publishes the index Xcode itself reads: every simulator runtime and Metal toolchain, with the mapping from an
+# Xcode or SDK build to the runtime build it wants. No login. The download URL then comes from the same lookup service
+# as OS updates, asked with the runtime's build as RequestedBuild on the "generic" audience.
+XCODE_INDEX_URL = "https://devimages-cdn.apple.com/downloads/xcode/simulators/index2.dvtdownloadableindex"
+XCODE_GENERIC_AUDIENCE = "02d8e57e-dd1c-4090-aa50-b4ed2aef0062"
+XCODE_PLATFORMS = {"ios": ("com.apple.platform.iphoneos", "com.apple.MobileAsset.iOSSimulatorRuntime", "iOS"),
+                   "tvos": ("com.apple.platform.appletvos", "com.apple.MobileAsset.appleTVOSSimulatorRuntime", "tvOS"),
+                   "watchos": ("com.apple.platform.watchos", "com.apple.MobileAsset.watchOSSimulatorRuntime", "watchOS"),
+                   "visionos": ("com.apple.platform.xros", "com.apple.MobileAsset.xrOSSimulatorRuntime", "visionOS")}
+
+def xcode_index():
+    """Apple's simulator index as a dict, cached for a day."""
+    import plistlib
+    path = _cache("xcode-index.plist", "~/.preheat-xcode-index.plist")
+    fresh = os.path.exists(path) and (datetime.datetime.now().timestamp() - os.path.getmtime(path)) < 86400
+    if not fresh:
+        with urllib.request.urlopen(urllib.request.Request(XCODE_INDEX_URL, headers={"User-Agent": "preheat/1.0"}), timeout=120) as r: open(path, "wb").write(r.read())
+    return plistlib.load(open(path, "rb"))
+
+def xcode_wants(xcode_version, platforms, betas=False):
+    """[(kind, platform key, name, build, size)] for the simulator runtimes and Metal toolchain an Xcode version wants.
+    xcode_version '27.0' matches Xcode 27.0.x; 'latest' = the newest Xcode the index knows."""
+    idx = xcode_index(); out = []
+    runtimes = {d["simulatorVersion"]["buildUpdate"]: d for d in idx.get("downloadables", []) if d.get("downloadMethod") == "mobileAsset" and d.get("simulatorVersion")}
+    # Xcode version -> SDK identifiers it ships. The index maps SDK build -> runtime build; the SDK a given Xcode
+    # ships is named by the runtime entries' "version" (27.0.0.x = Xcode 27.0 generation). Simplest reliable rule:
+    # take, per platform, the "preferred" (else newest available) runtime whose major.minor equals Xcode's.
+    want = None
+    if xcode_version != "latest": want = ".".join(xcode_version.split(".")[:2])
+    for key, (plat_id, atype, osname) in XCODE_PLATFORMS.items():
+        if key not in platforms: continue
+        cands = [d for d in runtimes.values() if d.get("platform") == plat_id and not d.get("isInternalContent")]
+        if not betas: cands = [d for d in cands if "beta" not in d.get("name", "").lower()]
+        if want: cands = [d for d in cands if d["simulatorVersion"]["version"].split(".")[0] == want.split(".")[0]]
+        if not cands: continue
+        best = max(cands, key=lambda d: (vkey(d["simulatorVersion"]["version"]), d["simulatorVersion"]["buildUpdate"]))
+        out.append(("simulator", key, best["name"], best["simulatorVersion"]["buildUpdate"], best.get("fileSize") or 0))
+    # Metal toolchain: the index names each one "Metal Toolchain (<build>) for Xcode <version>"
+    mts = [d for d in idx.get("otherDownloadables", []) if d.get("name", "").startswith("Metal Toolchain")]
+    def xv(d):
+        m = re.search(r"for Xcode ([\d.]+)", d.get("name", "")); return m.group(1) if m else ""
+    if not betas: mts = [d for d in mts if "beta" not in d.get("name", "").lower()]
+    if want: mts = [d for d in mts if xv(d).split(".")[:2] == want.split(".")[:2]] or [d for d in mts if xv(d).split(".")[0] == want.split(".")[0]]
+    if mts:
+        d = max(mts, key=lambda d: vkey(xv(d)))
+        b = re.search(r"\(([\w]+)\)", d["name"]); build = b.group(1) if b else ""
+        if build: out.append(("metal", "mac", d["name"], build, d.get("fileSize") or 0))
+    return out
+
+def gdmf_xcode(kind, plat, build):
+    """The file Apple serves for a simulator runtime or Metal toolchain build: {url, path, size, build} or None."""
+    atype = "com.apple.MobileAsset.MetalToolchain" if kind == "metal" else XCODE_PLATFORMS[plat][1]
+    body = {"ClientVersion": 2, "AssetType": atype, "AssetAudience": XCODE_GENERIC_AUDIENCE, "CertIssuanceDay": "2023-12-10",
+            "BuildVersion": "26A428", "HWModelStr": "J274AP", "ProductType": "Macmini9,1", "ProductVersion": "27.0",
+            "CompatibilityVersion": 20, "RequestedBuild": build, "Nonce": str(uuid.uuid4())}
+    req = urllib.request.Request(GDMF_URL, data=json.dumps(body).encode(), headers={"Content-Type": "application/json"}, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r: jwt = r.read().decode()
+    except urllib.error.HTTPError as e: jwt = e.read().decode()
+    parts = jwt.strip().split(".")
+    if len(parts) != 3: return None
+    payload = json.loads(base64.urlsafe_b64decode(parts[1] + "=" * (-len(parts[1]) % 4)))
+    for a in payload.get("Assets", []):
+        url = a.get("__BaseURL", "") + a.get("__RelativePath", "")
+        label = f"{XCODE_PLATFORMS[plat][2]} {a.get('SimulatorVersion') or ''} Simulator Runtime ({a.get('Build')})" if kind != "metal" else f"Metal Toolchain ({a.get('Build')})"
+        _decoded.setdefault(urllib.parse.urlparse(url).path, label.replace("  ", " "))
+        return {"url": url, "path": urllib.parse.urlparse(url).path, "size": a.get("_DownloadSize") or 0, "build": a.get("Build")}
+    return None
+APPLEDB_URL = "https://api.appledb.dev/device/main.json"   # model identifier -> board ID, all platforms
+# Per-user download caches live where macOS expects them; everything here can be deleted at any time.
+CACHE_DIR = os.path.expanduser("~/Library/Caches/preheat")
+def _cache(name, old):
+    """Path in CACHE_DIR; a file from the earlier ~/.preheat-* location is moved across once."""
+    path = os.path.join(CACHE_DIR, name); legacy = os.path.expanduser(old)
+    try:
+        os.makedirs(CACHE_DIR, exist_ok=True)
+        if os.path.exists(legacy) and not os.path.exists(path): os.replace(legacy, path)
+    except OSError: pass
+    return path
+BOARD_CACHE = _cache("boards.json", "~/.preheat-boards.json")
+
+def platform_of(model):
+    """Jamf model identifier -> platform key, or None."""
+    m = (model or "")
+    for prefix, plat in (("iPhone", "ios"), ("iPod", "ios"), ("iPad", "ipados"), ("AppleTV", "tvos"),
+                         ("RealityDevice", "visionos"), ("Watch", "watchos"), ("AudioAccessory", "audioos")):
+        if m.startswith(prefix): return plat
+    return "mac" if m else None
+
+_boards = None; _board_count = {}      # _board_count: how many different boards AppleDB lists for a model
+def board_for(model):
+    """Board ID for a model identifier, from AppleDB (cached locally for 7 days)."""
+    global _boards
+    if _boards is None:
+        _boards = {}
+        try:
+            fresh = os.path.exists(BOARD_CACHE) and (datetime.datetime.now().timestamp() - os.path.getmtime(BOARD_CACHE)) < 7*86400
+            if not fresh:
+                req = urllib.request.Request(APPLEDB_URL, headers={"User-Agent": "preheat/1.0"})
+                with urllib.request.urlopen(req, timeout=120) as r: raw = r.read()
+                open(BOARD_CACHE, "wb").write(raw)
+            t2 = {}
+            for d in json.load(open(BOARD_CACHE)):
+                ids = d.get("identifier") or []; ids = [ids] if isinstance(ids, str) else ids
+                b = d.get("board") or []; b = [b] if isinstance(b, str) else b
+                m = re.fullmatch(r"T2 \((\w+,\d+)\)", d.get("name") or "")
+                if m and b: t2[m.group(1)] = b[0][:-2].upper() + "AP"; continue
+                for i in ids:
+                    if b: _board_count.setdefault(i, set()).update(b)
+                    if b and i not in _boards: _boards[i] = b[0]
+            _boards.update(t2)
+            for i in t2: _board_count[i] = {t2[i]}
+        except Exception as e:
+            print(f"warning: could not load board map from AppleDB: {e}")
+    return _boards.get(model, "")
+
+def lookup_board(model, board):
+    """The board Apple's lookup service keys on. Intel Macs with a T2 chip (2018-2020) report a Mac-xxxx board ID, but
+    Apple answers for the T2's own board, in capitals (MacBookPro16,1 -> J152FAP); with Mac-xxxx it offers only macOS 11."""
+    if (board or "").startswith("Mac-"): return board_for(model) or board
+    return board
+# The name of each EA in Jamf. One name each: the setup tools create them under it and everything else finds them by it.
+EA_BOARD  = "Content Caching - Board ID"          # only for Macs from before 2016 (ea/ea-board-id.sh)
+EA_FOUND  = "Content Caching - Servers Found"     # ea/ea-content-cache-servers-found.sh
+EA_STATUS = "Content Caching - Status"            # ea/ea-content-cache-status.sh
+EA_ASSETS = "Content Caching - macOS Assets"      # ea/ea-content-cache-macos-assets.sh
+EA_EFFECT = "Content Caching - Effectiveness"     # ea/ea-content-cache-effectiveness.sh
+EA_READY  = "Content Caching - macOS Readiness"   # Text Field, written by --write
+EA_MOBILE_SERVER = "Content Caching - Server"     # mobile device Text Field EA, written by --write
+EA_DECODED = "Content Caching - Cached Updates"   # ea/ea-content-cache-decoded.sh, fed by admin/preheat-labels.py; if left a Text Field, --write fills it
+SUCATALOG_URL = ("https://swscan.apple.com/content/catalogs/others/"
+                 "index-15-14-13-12-10.16-10.15-10.14-10.13-10.12-10.11-10.10-10.9-mountainlion-lion-snowleopard-leopard.merged-1.sucatalog")
+SUCATALOG_CACHE = _cache("sucatalog.plist", "~/.preheat-sucatalog.plist")
+DECODED_CACHE = _cache("decoded.json", "~/.preheat-decoded.json")
+_decoded = {}   # asset URL path -> human label, filled by every lookup and by the installer catalog, persisted across runs
+try: _decoded.update(json.load(open(DECODED_CACHE)))
+except Exception: pass
+def save_decoded():
+    try: json.dump(_decoded, open(DECODED_CACHE, "w"), indent=0)
+    except Exception: pass
+
+# ---------- Apple lookup ----------
+_gdmf_cache = {}
+_recorded = None      # what Apple answered when a sample fleet was recorded (--inventory-json): used in place of asking
+# Apple publishes the previous OS branch (iOS 26.7 once 27 is out) on a second, "alternate" audience. A device that
+# holds on the old branch is offered its updates from there, so both are asked and the answers merged.
+ALT_AUDIENCE = {"ios": "c724cb61-e974-42d3-a911-ffd4dce11eda", "ipados": "c724cb61-e974-42d3-a911-ffd4dce11eda",
+                "visionos": "bb4eeb45-d4f7-4777-bd18-eb38c8443a9c"}
+
+def gdmf_assets(board, model, version, build, platform="mac"):
+    key = (platform, board, model, version, build)
+    if key in _gdmf_cache: return _gdmf_cache[key]
+    if _recorded is not None:      # a recorded fleet: the same answer every time, whatever Apple has released since
+        _gdmf_cache[key] = [dict(a, path=urllib.parse.urlparse(a["url"]).path) for a in _recorded.get("|".join(str(k) for k in key)) or []]
+        return _gdmf_cache[key]
+    asset_type, audience = PLATFORMS[platform]
+    out = []; seen = set()
+    for n, aud in enumerate([audience] + ([ALT_AUDIENCE[platform]] if platform in ALT_AUDIENCE else [])):
+        body = {"ClientVersion": 2, "AssetType": asset_type,
+                "AssetAudience": aud, "CertIssuanceDay": "2023-12-10",
+                "BuildVersion": build, "HWModelStr": board, "ProductType": model,
+                "ProductVersion": version, "CompatibilityVersion": 20, "DelayRequested": False,
+                "Supervised": False, "DeviceName": "Mac", "Nonce": str(uuid.uuid4())}
+        req = urllib.request.Request(GDMF_URL, data=json.dumps(body).encode(),
+                                     headers={"Content-Type": "application/json"}, method="POST")
+        try:
+            try:
+                with urllib.request.urlopen(req, timeout=60) as r: jwt = r.read().decode()
+            except urllib.error.HTTPError as e:
+                jwt = e.read().decode()
+            parts = jwt.strip().split(".")
+            if len(parts) != 3: raise RuntimeError(f"unexpected gdmf reply: {jwt[:200]}")
+            payload = json.loads(base64.urlsafe_b64decode(parts[1] + "=" * (-len(parts[1]) % 4)))
+            if payload.get("Status"): raise RuntimeError(f"gdmf {payload.get('Status')}: {payload.get('Message')}")
+        except Exception:
+            if n == 0: raise
+            continue      # the alternate audience is a bonus; never fail a lookup over it
+        for a in payload.get("Assets", []):
+            url = a.get("__BaseURL", "") + a.get("__RelativePath", "")
+            if url in seen: continue
+            seen.add(url)
+            ver = (a.get("OSVersion") or "").replace("9.9.", "", 1)      # Apple marks full iOS images "9.9.<version>"
+            out.append({"version": ver, "build": a.get("Build"), "url": url, "prereq": a.get("PrerequisiteBuild") or "",
+                        "path": urllib.parse.urlparse(url).path, "size": a.get("_DownloadSize") or 0})
+            osname = OSNAME[platform]
+            kind = f"delta from {a.get('PrerequisiteOSVersion')} ({a.get('PrerequisiteBuild')})" if a.get("PrerequisiteBuild") else "full"
+            _decoded.setdefault(urllib.parse.urlparse(url).path, f"{osname} {ver} ({a.get('Build')}) {kind} for {model}")
+    _gdmf_cache[key] = out
+    return out
+
+def vkey(v): return tuple(int(x) for x in (v or "0").split(".") if x.isdigit())
+
+def wanted(assets, target, current=""):
+    """Version tuple a target means: '' = newest Apple offers this device, '26' = newest 26.x, '26.7' = exactly that,
+    'same' = newest within the major version the device runs now (a Blueprint set to "Ignore major versions")."""
+    if target == "same": target = (current or "").split(".")[0]
+    if not target: return max((vkey(a["version"]) for a in assets), default=())
+    if "." not in target: return max((vkey(a["version"]) for a in assets if vkey(a["version"])[:1] == vkey(target)), default=vkey(target))
+    return vkey(target)
+
+def choose(assets, build, target, target_build, current=""):
+    """The asset a device on `build` downloads for the target: its delta if Apple offers one, else the full image."""
+    if target_build: pick = [a for a in assets if a["build"] == target_build]
+    else:
+        want = wanted(assets, target, current)
+        pick = [a for a in assets if vkey(a["version"]) == want]
+    pick.sort(key=lambda a: (a["prereq"] != build, bool(a["prereq"])))     # own delta, then full, then other deltas
+    pick = [a for a in pick if a["prereq"] in ("", build)]
+    return pick[0] if pick else None
+
+BUILDS_CACHE = _cache("builds.json", "~/.preheat-builds.json")
+def builds_for(platform, version):
+    """Release builds of an OS version (ios 26.0 -> 23A341, 23A345, ...; one version can have several, some for a single
+    hardware family). From AppleDB. Builds that share a leading number share a major version, so one lookup per leading
+    number finds the right group and only that group is read in full. Cached locally."""
+    try: known = json.load(open(BUILDS_CACHE))
+    except Exception: known = {}
+    osname = {"audioos": "audioOS"}.get(platform, OSNAME[platform]); tab = known.setdefault(osname, {"majors": {}, "versions": {}, "read": []})
+    if version in tab["versions"]: return tab["versions"][version]
+    def get(u, tries=3):      # AppleDB is a community service and sometimes times out: retry before giving up
+        for n in range(tries):
+            try: return urllib.request.urlopen(urllib.request.Request(u, headers={"User-Agent": "preheat/1.0"}), timeout=60).read()
+            except Exception:
+                if n == tries - 1: raise
+                import time; time.sleep(3 * (n + 1))
+    ver_of = lambda bld: json.loads(get(f"https://api.appledb.dev/ios/{osname};{bld}.json")).get("version") or ""
+    try:
+        groups = collections.defaultdict(list)
+        for x in json.loads(get("https://api.appledb.dev/ios/index.json")):
+            o, _, bld = x.partition(";")
+            if o == osname and re.fullmatch(r"\d+[A-Z]\d+", bld): groups[re.match(r"\d+", bld).group()].append(bld)
+        major = version.split(".")[0]
+        for lead in sorted(groups, key=int, reverse=True):
+            if lead not in tab["majors"]:
+                try: tab["majors"][lead] = ver_of(sorted(groups[lead])[0]).split(".")[0]
+                except Exception: continue
+            if tab["majors"][lead] == major and lead not in tab["read"]:
+                for bld in sorted(groups[lead], reverse=True):
+                    try: tab["versions"].setdefault(ver_of(bld), []).append(bld)
+                    except Exception: pass
+                tab["read"].append(lead)
+            if tab["majors"].get(lead) == major: break
+        json.dump(known, open(BUILDS_CACHE, "w"), indent=0)
+    except Exception as e: print(f"WARNING: AppleDB did not answer ({e}): {osname} {version} could not be turned into a build, so --from {version} is SKIPPED for {osname} in this run. Run it again.")
+    return tab["versions"].get(version, [])
+
+def decode_installers(paths):
+    """Label InstallAssistant.pkg paths from Apple's software update catalog (cached locally for a day)."""
+    import plistlib
+    want = [p for p in paths if p.endswith("/InstallAssistant.pkg") and p not in _decoded]
+    if not want: return
+    try:
+        fresh = os.path.exists(SUCATALOG_CACHE) and (datetime.datetime.now().timestamp() - os.path.getmtime(SUCATALOG_CACHE)) < 86400
+        if not fresh:
+            with urllib.request.urlopen(SUCATALOG_URL, timeout=120) as r: open(SUCATALOG_CACHE, "wb").write(r.read())
+        cat = plistlib.load(open(SUCATALOG_CACHE, "rb"))
+    except Exception as e:
+        print(f"warning: software update catalog unavailable ({e}); installers stay unidentified"); return
+    for pid, prod in cat.get("Products", {}).items():
+        for pkg in prod.get("Packages", []):
+            path = urllib.parse.urlparse(pkg.get("URL", "")).path
+            if path in want:
+                label = f"macOS full installer, product {pid}"
+                try:
+                    dist = prod.get("Distributions", {}).get("English") or next(iter(prod.get("Distributions", {}).values()))
+                    with urllib.request.urlopen(dist, timeout=60) as r: x = r.read().decode(errors="ignore")
+                    b = re.search(r"<key>BUILD</key>\s*<string>([^<]+)</string>", x); v = re.search(r"<key>VERSION</key>\s*<string>([^<]+)</string>", x)
+                    t = re.search(r"<title>([^<]+)</title>", x)
+                    if v: label = f"{(t.group(1) if t else 'macOS').strip()} {v.group(1)} ({b.group(1) if b else '?'}) full installer"
+                except Exception: pass
+                _decoded[path] = label
+
+def full_installers():
+    """Every full macOS installer in Apple's software update catalog: [{version, build, title, size, url, path, date}],
+    newest first. This is what softwareupdate --fetch-full-installer and Jamf's installer packages download."""
+    import plistlib
+    fresh = os.path.exists(SUCATALOG_CACHE) and (datetime.datetime.now().timestamp() - os.path.getmtime(SUCATALOG_CACHE)) < 86400
+    if not fresh:
+        with urllib.request.urlopen(SUCATALOG_URL, timeout=120) as r: open(SUCATALOG_CACHE, "wb").write(r.read())
+    cat = plistlib.load(open(SUCATALOG_CACHE, "rb")); out = []
+    for pid, prod in cat.get("Products", {}).items():
+        pkg = next((p for p in prod.get("Packages", []) if p.get("URL", "").endswith("/InstallAssistant.pkg")), None)
+        if not pkg: continue
+        e = {"product": pid, "url": pkg["URL"], "path": urllib.parse.urlparse(pkg["URL"]).path, "size": pkg.get("Size") or 0,
+             "date": str(prod.get("PostDate", ""))[:10], "version": "", "build": "", "title": "macOS"}
+        try:
+            dists = prod.get("Distributions", {}); x = urllib.request.urlopen(dists.get("English") or next(iter(dists.values())), timeout=60).read().decode(errors="ignore")
+            v = re.search(r"<key>VERSION</key>\s*<string>([^<]+)</string>", x); b = re.search(r"<key>BUILD</key>\s*<string>([^<]+)</string>", x)
+            t = re.search(r"<title>([^<]+)</title>", x)
+            e.update(version=v.group(1) if v else "", build=b.group(1) if b else "", title=(t.group(1) if t else "macOS").strip())
+        except Exception: pass
+        if e["version"]:
+            _decoded.setdefault(e["path"], f"{e['title']} {e['version']} ({e['build']}) full installer for all Macs"); out.append(e)
+    return sorted(out, key=lambda e: vkey(e["version"]), reverse=True)
+
+# ---------- Aerial screen savers ----------
+# macOS finds its Aerials through a public config plist that points at a manifest tarball; entries.json inside lists
+# every video with its name, category and 4K URL on sylvan.apple.com. ~170 MB each, 164 of them on macOS 27.
+AERIAL_CONFIG_URL = "https://configuration.apple.com/configurations/internetservices/aerials/resources-config-27-0.plist"
+
+def aerials():
+    """[{name, category, url, path, id}] for every Aerial video macOS offers, from Apple's manifest (cached for a day)."""
+    import plistlib, tarfile, io
+    path = _cache("aerials-entries.json", "~/.preheat-aerials.json")
+    fresh = os.path.exists(path) and (datetime.datetime.now().timestamp() - os.path.getmtime(path)) < 86400
+    if not fresh:
+        get = lambda u: urllib.request.urlopen(urllib.request.Request(u, headers={"User-Agent": "preheat/1.0"}), timeout=120).read()
+        cfg = plistlib.loads(get(AERIAL_CONFIG_URL)); tar = tarfile.open(fileobj=io.BytesIO(get(cfg["resources-url"])))
+        member = next(m for m in tar.getmembers() if m.name.endswith("entries.json"))
+        open(path, "wb").write(tar.extractfile(member).read())
+    d = json.load(open(path)); cats = {c["id"]: c.get("localizedNameKey", "").replace("AerialCategory", "") for c in d.get("categories", [])}
+    out = []
+    for a in d.get("assets", []):
+        url = a.get("url-4K-SDR-240FPS")
+        if not url: continue
+        cat = ", ".join(cats.get(c, c) for c in a.get("categories", [])) or "Aerial"
+        e = {"name": a.get("accessibilityLabel") or a.get("id"), "category": cat, "url": url, "path": urllib.parse.urlparse(url).path, "id": a.get("id")}
+        _decoded.setdefault(e["path"], f"Aerial screen saver: {e['name']} ({cat})"); out.append(e)
+    return out
+
+def decoded_lines(assets_ea):
+    """Turn a server's raw assets EA into human lines."""
+    have = parse_assets_ea(assets_ea); decode_installers(list(have))
+    out = []
+    for line in (assets_ea or "").splitlines():
+        p = line.split()
+        if len(p) < 4 or not p[-1].startswith("/"): continue
+        path = p[-1]; state, size, date = " ".join(p[:-3]), p[-3], p[-2]
+        label = _decoded.get(path)
+        if not label:
+            kind = "macOS update" if "MacSoftwareUpdate" in path else "iOS/iPadOS/tvOS/visionOS update" if "MobileAsset_SoftwareUpdate" in path else "asset"
+            label = f"unidentified {kind} {os.path.basename(path)[:12]}... (no device in inventory matches it)"
+        out.append(f"{state} {size} {date} {label}")
+    return out
+
+# ---------- credentials ----------
+KEYCHAIN_SERVICE = "preheat"
+CRED_KEYS = ("JAMF_URL", "JAMF_CLIENT_ID", "JAMF_CLIENT_SECRET")
+
+def keychain_get(key):
+    """Read one item from the login keychain (service 'preheat', account = key)."""
+    import subprocess
+    r = subprocess.run(["/usr/bin/security", "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", key, "-w"],
+                       capture_output=True, text=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+def keychain_store(values):
+    """Store the three credentials in the login keychain. Values go through security's stdin, never argv."""
+    import subprocess
+    script = "".join(f"add-generic-password -U -s {KEYCHAIN_SERVICE} -a {k} -w {json.dumps(v)}\n" for k, v in values.items())
+    r = subprocess.run(["/usr/bin/security", "-i"], input=script, capture_output=True, text=True)
+    if r.returncode != 0: sys.exit("keychain store failed: " + (r.stderr or r.stdout).strip())
+
+def load_credentials():
+    """Environment variables win (CI, one-off runs); otherwise the login keychain."""
+    creds = {k: os.environ.get(k, "") for k in CRED_KEYS}
+    if not all(creds.values()):
+        for k in CRED_KEYS:
+            if not creds[k]: creds[k] = keychain_get(k)
+    missing = [k for k in CRED_KEYS if not creds[k]]
+    if missing:
+        sys.exit("missing credentials: " + ", ".join(missing) +
+                 ". Set them as environment variables, or store them once with: python3 admin/readiness-check.py --store-credentials")
+    return creds
+
+def jamf_from_credentials():
+    c = load_credentials(); return Jamf(c["JAMF_URL"], c["JAMF_CLIENT_ID"], c["JAMF_CLIENT_SECRET"])
+
+# ---------- Jamf ----------
+class Jamf:
+    def __init__(self, url, cid, secret):
+        self.base = url.rstrip("/"); self._cid, self._secret = cid, secret
+        self.login()
+    def login(self):
+        """Jamf's tokens are short-lived (the API client sets the lifetime, often a few minutes) and a long run outlives one."""
+        data = urllib.parse.urlencode({"client_id": self._cid, "client_secret": self._secret,
+                                       "grant_type": "client_credentials"}).encode()
+        req = urllib.request.Request(self.base + "/api/oauth/token", data=data,
+                                     headers={"Content-Type": "application/x-www-form-urlencoded"})
+        with urllib.request.urlopen(req, timeout=60) as r: t = json.load(r)
+        self.token = t["access_token"]; self.expires = time.time() + max(0, int(t.get("expires_in") or 60) - 15)
+    def call(self, path, method="GET", body=None):
+        if time.time() >= self.expires: self.login()
+        for attempt in (1, 2):
+            req = urllib.request.Request(self.base + path, method=method,
+                                         data=json.dumps(body).encode() if body is not None else None,
+                                         headers={"Authorization": "Bearer " + self.token, "Accept": "application/json",
+                                                  "Content-Type": "application/json"})
+            try:
+                with urllib.request.urlopen(req, timeout=120) as r:
+                    txt = r.read().decode(); return json.loads(txt) if txt else {}
+            except urllib.error.HTTPError as e:
+                if e.code != 401 or attempt == 2: raise
+                self.login()
+    def cache_status(self, management_id):
+        """What the Mac itself last reported about its content cache through declarative device management
+        (macOS 27 and later): {"status.active": ("true", datetime), ...}. Empty when there is nothing to read:
+        an older macOS, an older Jamf Pro, or an API role without the privilege. Never an error."""
+        if not management_id: return {}
+        try: items = self.call(f"/api/v1/ddm/{management_id}/status-items").get("statusItems") or []
+        except (urllib.error.HTTPError, urllib.error.URLError, ValueError): return {}
+        out = {}
+        for i in items:
+            k = i.get("key") or ""
+            if not k.startswith("content-cache."): continue
+            try: when = datetime.datetime.fromisoformat((i.get("lastUpdateTime") or "")[:19]).replace(tzinfo=datetime.timezone.utc)
+            except ValueError: when = None
+            out[k[len("content-cache."):]] = (str(i.get("value") or ""), when)
+        return out
+    def silent_threshold(self):
+        """Minutes without any word from a cache server before it counts as silent: three times the tenant's check-in
+        frequency and at least 30. Where the frequency cannot be read (needs Read Computer Check-In) it is 180, three
+        times the longest check-in Jamf Pro allows: a shorter guess would call a healthy server silent between check-ins."""
+        try: return max(30, 3 * int(self.call("/api/v3/check-in").get("checkInFrequency") or 60))
+        except (urllib.error.HTTPError, urllib.error.URLError, ValueError, TypeError): return 180
+    def inventory(self):
+        page, out = 0, []
+        while True:
+            q = urllib.parse.urlencode({"page": page, "page-size": 500, "section":
+                ["GENERAL", "HARDWARE", "OPERATING_SYSTEM", "USER_AND_LOCATION", "CONTENT_CACHING", "EXTENSION_ATTRIBUTES"]}, doseq=True)
+            res = self.call("/api/v1/computers-inventory?" + q)
+            out += [normalize(c) for c in res.get("results", [])]
+            page += 1
+            if page * 500 >= res.get("totalCount", 0): break
+        return out
+
+    def group_members(self, name):
+        """Ids in a Smart or Static group of that name: ({computer ids}, {mobile device ids}). Either kind may not exist."""
+        out = []
+        for path, top, key in (("computergroups", "computer_group", "computers"), ("mobiledevicegroups", "mobile_device_group", "mobile_devices")):
+            try: out.append({str(d["id"]) for d in self.call(f"/JSSResource/{path}/name/{urllib.parse.quote(name)}")[top][key]})
+            except urllib.error.HTTPError: out.append(None)
+        return out
+
+    def mobile_inventory(self):
+        page, out = 0, []
+        while True:
+            q = urllib.parse.urlencode({"page": page, "page-size": 500, "section":
+                ["GENERAL", "HARDWARE", "USER_AND_LOCATION", "EXTENSION_ATTRIBUTES"]}, doseq=True)
+            res = self.call("/api/v2/mobile-devices/detail?" + q)
+            out += [normalize_mobile(d) for d in res.get("results", [])]
+            page += 1
+            if page * 500 >= res.get("totalCount", 0): break
+        return out
+
+def normalize_mobile(d):
+    g = d.get("general", {}); h = d.get("hardware", {}); loc = d.get("userAndLocation", {})
+    model = h.get("modelIdentifier") or ""
+    served = ""
+    for ea in (d.get("extensionAttributes") or []) + (g.get("extensionAttributes") or []) + (h.get("extensionAttributes") or []) + (loc.get("extensionAttributes") or []):
+        if ea.get("name") == EA_MOBILE_SERVER and ea.get("value"): served = ea["value"][0]
+    return {"id": d.get("mobileDeviceId") or d.get("id"), "name": g.get("displayName") or d.get("name"),
+            "model": model, "platform": platform_of(model),
+            "version": g.get("osVersion"), "build": g.get("osBuild"),
+            "last_inventory": (g.get("lastInventoryUpdateDate") or "")[:10],
+            "ip": g.get("ipAddress") or "", "site": "", "building": loc.get("building") or "",
+            "board": board_for(model), "caches_found": "", "cache_guid": "", "cache_status": "",
+            "assets_ea": "", "ready_ea_id": None, "served_ea": served}
+
+def ea_value(c, name):
+    for ea in c.get("extensionAttributes", []) + c.get("general", {}).get("extensionAttributes", []):
+        if ea.get("name") == name:
+            v = ea.get("values") or []; return (v[0] if v else ""), ea.get("definitionId")
+    return "", None
+
+def mac_board(model):
+    """A Mac's board from its model identifier alone (AppleDB), for Macs that have not reported the Board ID EA, or
+    where that EA is not installed. Empty for the few old Intel models that came with more than one board."""
+    b = board_for(model) if model else ""
+    return b if b and len(_board_count.get(model, ())) == 1 else ""
+
+def cache_status_line(c):
+    """One line about this Mac as a cache server, from Jamf's own Content Caching inventory (collected from every Mac
+    on macOS 10.15.4 or later, no EA needed): "Not a content cache" | "Active; guid ...; ip ...; port ...; public ...;
+    free ...; used ...; status OK" | "Inactive (LOWSPACE; ...); guid ...". Every Mac has a server GUID and a cache
+    status of OK, cache or not, so only 'activated' says that a Mac is a cache server. "" if Jamf sent no such section."""
+    cc = c.get("contentCaching") or {}
+    if cc.get("activated") is None: return ""
+    gb = lambda b: f"{(b or 0)/1e9:.1f} GB"
+    guid = cc.get("serverGuid") or "?"; g = c.get("general", {})
+    if not cc["activated"]:      # never a cache: status OK. Storage gone: caching switches itself off and reports a problem
+        st = cc.get("cacheStatus") or "OK"
+        return "Not a content cache" if st == "OK" else f"Inactive ({st}; caching switched itself off); guid {guid}"
+    if not cc.get("active"):
+        why = "; ".join(x for x in (cc.get("cacheStatus") or "?", cc.get("registrationError") or cc.get("startupStatus") or "") if x and x != "OK") or "not running"
+        return f"Inactive ({why}); guid {guid}"
+    return (f"Active; guid {guid}; ip {g.get('lastReportedIp') or '?'}; port {cc.get('port') or '?'}; public {cc.get('publicAddress') or '?'}; "
+            f"free {gb(cc.get('cacheBytesFree'))}; used {gb(cc.get('actualCacheBytesUsed') or cc.get('cacheBytesUsed'))}; status {cc.get('cacheStatus') or '?'}")
+
+def normalize(c):
+    g = c.get("general", {}); loc = c.get("userAndLocation", {})
+    status = cache_status_line(c) or ea_value(c, EA_STATUS)[0]      # Jamf's own section (collected just after inventory), else the status EA
+    m = re.search(r"guid ([0-9A-Fa-f-]{36})", status)
+    ipm = re.search(r"\bip ([0-9.,]+)", status); pubm = re.search(r"\bpublic ([0-9.]+)", status)
+    return {"id": c.get("id"), "name": g.get("name"), "model": c.get("hardware", {}).get("modelIdentifier"),
+            "platform": "mac", "ip": g.get("lastReportedIp") or g.get("lastIpAddress") or "",
+            "management_id": g.get("managementId") or "", "inventory_time": g.get("reportDate") or "",
+            "last_contact": g.get("lastContactTime") or "",
+            "last_inventory": (g.get("reportDate") or "")[:10],
+            "version": c.get("operatingSystem", {}).get("version"), "build": c.get("operatingSystem", {}).get("build"),
+            "site": ((g.get("site") or {}).get("name") or "").replace("None", ""), "building": loc.get("building") or "",
+            "board": ea_value(c, EA_BOARD)[0].strip() or mac_board(c.get("hardware", {}).get("modelIdentifier")), "caches_found": ea_value(c, EA_FOUND)[0],
+            "cache_guid": m.group(1).upper() if m else "", "cache_status": status,
+            "cache_ips": ipm.group(1).split(",") if ipm else [], "cache_public_ip": pubm.group(1) if pubm else "",
+            "assets_ea": ea_value(c, EA_ASSETS)[0], "ready_ea_id": ea_value(c, EA_READY)[1]}
+
+def parse_time(t):
+    """A Jamf time such as 2026-09-29T00:17:46.011Z, which is UTC, as a datetime; None if there is none."""
+    m = re.match(r"\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d", t or "")
+    return datetime.datetime.fromisoformat(m.group(0)).replace(tzinfo=datetime.timezone.utc) if m else None
+
+def last_heard(c, live=None):
+    """The latest moment Jamf heard from this Mac in any way: a check-in, an inventory update or a DDM status report.
+    A Mac that is off, or off the network, sends none of them, and nothing in its record changes: no Smart Group
+    moves and no alert is sent. This is the only sign."""
+    return max([t for t in (parse_time(c.get("last_contact")), parse_time(c.get("inventory_time")), (live or {}).get("as_of_time")) if t], default=None)
+
+def live_cache(items, inventory_time=""):
+    """Read Jamf.cache_status() into plain facts. The status items change when the cache changes state, so they are
+    newer than inventory whenever something happened in between. (The size figures, info.*, are only refreshed when the
+    declaration sets DeclarativeStatusInterval, so they are not used here.)
+    -> None if there is nothing to read, else {"on", "as_of", "line", "changed_since_inventory", "problem"}"""
+    val = lambda k: (items.get(k) or ("", None))[0]
+    when = lambda k: (items.get(k) or ("", None))[1]
+    if "status.active" not in items and "status.activated" not in items: return None
+    activated, active = val("status.activated") == "true", val("status.active") == "true"
+    times = [t for k, (v, t) in items.items() if k.startswith("status.") and t]
+    state_time = max([t for t in (when("status.active"), when("status.activated")) if t], default=None)
+    as_of = max(times, default=None)
+    registered = val("status.registration-status") == "1"
+    problem = ""
+    if not activated: problem = "content caching is switched off"
+    elif not active: problem = "content caching is on but not running" + (f" ({val('status.cache-status')})" if val("status.cache-status") not in ("", "OK") else "")
+    elif not registered: problem = "not registered with Apple" + (f" ({val('status.registration-error')}, code {val('status.registration-response-code')})" if val("status.registration-error") else "")
+    try: inv = datetime.datetime.fromisoformat(inventory_time.replace("Z", "+00:00")[:32]) if inventory_time else None
+    except ValueError: inv = None
+    if inv and inv.tzinfo is None: inv = inv.replace(tzinfo=datetime.timezone.utc)
+    local = lambda t: t.astimezone().strftime("%Y-%m-%d %H:%M") if t else "?"
+    line = ("running, registered with Apple" if not problem else problem) + f", address {val('status.private-addresses') or '?'} port {val('status.port') or '?'}"
+    # Jamf returns each peer as "{address=10.0.0.3, port=49152, healthy=true, friendly=true, identifier=<GUID>, version=265}"
+    peer_list = []
+    for rec in re.findall(r"\{([^{}]*)\}", val("peers")) or ([val("peers")] if val("peers") else []):
+        f = dict(kv.split("=", 1) for kv in re.split(r",\s*", rec) if "=" in kv)
+        g = re.search(r"[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}", f.get("identifier") or f.get("guid") or rec)
+        if g and f.get("_removed") != "true": peer_list.append({"guid": g.group(0).upper(), "address": f.get("address", ""), "healthy": f.get("healthy", "true") == "true"})
+    return {"on": not problem, "as_of": local(as_of), "as_of_time": as_of, "since": local(state_time), "line": line, "problem": problem,
+            "changed_since_inventory": bool(inv and state_time and state_time > inv),
+            "guid": val("status.server-guid").upper(), "peers": val("peers"), "parents": val("parents"),
+            "peer_guids": [x["guid"] for x in peer_list if x["healthy"] and x["guid"] != val("status.server-guid").upper()],
+            "peer_list": peer_list}
+
+def parse_assets_ea(text):
+    out = {}
+    for line in (text or "").splitlines():
+        p = line.split()
+        if len(p) >= 4 and p[-1].startswith("/"):
+            out[p[-1]] = " ".join(p[:-3]) if p[0] == "PARTIAL" else p[0]
+    return out
+
+def parse_served(text):
+    """mobile 'served by' EA -> {GUID: (server name, last-seen date or None)}"""
+    out = {}
+    for part in (text or "").split(";"):
+        m = re.search(r"^\s*(.*?)\s+guid\s+([0-9A-Fa-f-]{36})(?:\s+seen\s+(\d{4}-\d{2}-\d{2}))?", part)
+        if m:
+            try: dt = datetime.date.fromisoformat(m.group(3)) if m.group(3) else None
+            except ValueError: dt = None
+            out[m.group(2).upper()] = (m.group(1).strip(), dt)
+    return out
+
+def found_guids(text):
+    return {p.split()[0].upper() for p in (text or "").splitlines() if re.match(r"[0-9A-Fa-f-]{36} ", p)}
+
+def favored_guids(text):
+    """Servers this Mac's DNS marks as favored (Apple's fss record): while one of them is up, the Mac uses no other."""
+    return {p.split()[0].upper() for p in (text or "").splitlines() if re.match(r"[0-9A-Fa-f-]{36} ", p) and " favored" in p and "last-seen" not in p}
+
+# ---------- sites with several public addresses, favored caches, peers ----------
+def parse_ranges(text):
+    """'203.0.113.10-203.0.113.19, 198.51.100.7, 10.0.0.0/24' -> [(low, high)] as integers. What cannot be read is left out."""
+    import ipaddress
+    out = []
+    for part in re.split(r"[,;\s]+", text or ""):
+        if not part or part == "more": continue
+        try:
+            if "-" in part: a, b = part.split("-", 1); lo, hi = int(ipaddress.ip_address(a)), int(ipaddress.ip_address(b))
+            elif "/" in part: n = ipaddress.ip_network(part, strict=False); lo, hi = int(n[0]), int(n[-1])
+            else: lo = hi = int(ipaddress.ip_address(part))
+            out.append((min(lo, hi), max(lo, hi)))
+        except ValueError: continue
+    return out
+
+def in_ranges(ip, ranges):
+    import ipaddress
+    try: n = int(ipaddress.ip_address((ip or "").strip()))
+    except ValueError: return False
+    return any(lo <= n <= hi for lo, hi in ranges)
+
+def show_ranges(ranges):
+    import ipaddress
+    f = lambda n: str(ipaddress.ip_address(n))
+    return ", ".join(f(lo) if lo == hi else f"{f(lo)}-{f(hi)}" for lo, hi in ranges) or "none"
+
+def dns_line(text):
+    """The 'dns:' line of the servers-found EA -> (public ranges, favored ranges): what this Mac read from Apple's
+    content caching TXT records in its own DNS."""
+    for line in (text or "").splitlines():
+        if line.startswith("dns:"):
+            pub = re.search(r"public ([^;]*)", line); fav = re.search(r"favored ([^;]*)", line)
+            return parse_ranges(pub.group(1) if pub else ""), parse_ranges(fav.group(1) if fav else "")
+    return [], []
+
+def txt_records(name):
+    """TXT strings for a DNS name, through dig or nslookup (Python has no TXT lookup of its own). None if there are none."""
+    import subprocess, shutil
+    unescape = lambda t: re.sub(r"\\(\d{3}|.)", lambda m: chr(int(m.group(1))) if m.group(1).isdigit() else m.group(1), t)
+    for tool, argv in (("dig", ["+short", "+time=3", "+tries=1", "TXT", name]), ("nslookup", ["-type=TXT", "-timeout=3", name])):
+        exe = shutil.which(tool)
+        if not exe: continue
+        try: out = subprocess.run([exe] + argv, capture_output=True, text=True, timeout=15).stdout
+        except Exception: continue
+        found = ["".join(unescape(q) for q in re.findall(r'"((?:[^"\\]|\\.)*)"', line)) for line in out.splitlines() if '"' in line]
+        found = [f for f in found if re.match(r"(prs|prn|fss|fsn)=", f)]
+        return found or None
+    return None
+
+def packed_ranges(raw):
+    """Apple's compact form (prn, fsn): a tag byte, then one address (0x14, 0x16) or a first and a last (0x24, 0x26)."""
+    import ipaddress
+    b = raw.encode("latin-1"); i = 0; out = []; more = False
+    while i < len(b):
+        tag = b[i]; i += 1
+        if tag == 0x2b: more = True; continue
+        count, size = tag >> 4, {4: 4, 6: 16}.get(tag & 0x0f)
+        if count not in (1, 2) or not size or i + count * size > len(b): break
+        vals = [int(ipaddress.ip_address(b[i + k * size:i + (k + 1) * size])) for k in range(count)]; i += count * size
+        out.append((min(vals), max(vals)))
+    return out, more
+
+def dns_site(domain):
+    """Apple's content caching TXT records in one DNS domain (_aaplcache._tcp, then _aaplcache1 ... 24) -> (public, favored)."""
+    pub, fav = [], []
+    for i in range(25):
+        recs = txt_records(f"_aaplcache{i or ''}._tcp.{domain.strip('.')}")
+        if not recs: break
+        more = False
+        for r in recs:
+            key, val = r.split("=", 1)
+            if key in ("prs", "fss"): got = parse_ranges(val); more = more or val.rstrip().endswith("more")
+            else: got, m = packed_ranges(val); more = more or m
+            (pub if key.startswith("p") else fav).extend(got)
+        if not more: break
+    return pub, fav
+
+def collect_sites(comps, public_ranges=(), dns_domains=()):
+    """Every set of public addresses that counts as one site: given by hand, read from DNS, or reported by the Macs
+    themselves (the 'dns:' line of the servers-found EA). -> [{"public", "favored", "source"}]"""
+    sites = []
+    def add(pub, fav, source):
+        if not pub and not fav: return
+        for st in sites:
+            if st["public"] == pub:
+                st["favored"] = st["favored"] or fav; st["seen"] += 1; return
+        sites.append({"public": pub, "favored": fav, "source": source, "seen": 1})
+    for spec in public_ranges: add(parse_ranges(spec), [], "--public-ranges")
+    for dom in dns_domains:
+        pub, fav = dns_site(dom)
+        if pub or fav: add(pub, fav, f"DNS TXT records of {dom}")
+        else: print(f"--dns-domain {dom}: no content caching TXT record found (_aaplcache._tcp.{dom}); give the addresses with --public-ranges if this Mac cannot see that DNS")
+    for c in comps:
+        pub, fav = dns_line(c.get("caches_found"))
+        add(pub, fav, "reported by Macs on that network")
+    return sites
+
+# ---------- main ----------
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--target", help="macOS version to check readiness for (default: newest Apple offers)")
+    ap.add_argument("--target-build", help="exact build to check for (e.g. 26B123), as pinned in a DDM declaration; overrides --target")
+    ap.add_argument("--max-age-days", type=int, default=30,
+                    help="ignore Macs whose last Jamf inventory is older than this (default 30); they are not on the network. 0 = keep all")
+    ap.add_argument("--platforms", default="",
+                    help="add mobile platforms: a comma list of ios,ipados,tvos,visionos, or 'all'. Macs are always included")
+    ap.add_argument("--group-by", choices=["locator", "building", "subnet"], default="locator",
+                    help="how a device is matched to a server. locator: the Mac reports which server it uses (Macs only; "
+                         "mobile devices fall back to same-public-IP-as-server, which is Apple's own rule, then subnet, "
+                         "then building). building: same Jamf building as the server. subnet: device IP in the server's subnet")
+    ap.add_argument("--subnet-bits", type=int, default=24, help="prefix length for subnet matching (default 24)")
+    ap.add_argument("--sticky-days", type=int, default=90,
+                    help="a device stays 'served by' a cache server for this many days after it was last seen using it (default 90)")
+    ap.add_argument("--write", action="store_true", help="store the summary in each cache server's readiness EA")
+    ap.add_argument("--preheat-plan", metavar="FILE", help="write a JSON plan of every MISSING/PARTIAL asset per server, for admin/preheat.sh")
+    ap.add_argument("--cohort", action="append", metavar="GROUP=VERSION", default=[],
+                    help="devices in this Jamf group (computer or mobile, Smart or Static) are judged against this version instead of "
+                         "--target: '26' = the newest 26.x Apple offers them, '26.7' = exactly that, 'same' = the newest within each "
+                         "device's current major version (what a Blueprint set to Ignore major versions enforces). Repeat for more groups; the first "
+                         "match wins. For fleets where one group holds on the previous OS while the rest move on")
+    ap.add_argument("--preheat-models", metavar="MODELS",
+                    help="with --preheat-plan: also plan for hardware that is not in inventory yet, a list of model "
+                         "identifiers, e.g. \"iPhone18,3 Mac17,5\" (commas or spaces between them both work), or a whole family: "
+                         "all, mac, iphone, ipad, appletv, visionpro. Without --from these are treated as new hardware: full images")
+    ap.add_argument("--from", dest="preheat_from", metavar="VERSIONS",
+                    help="the OS version(s) the --preheat-models devices will be on, e.g. 26.7 or 26.6,26.7 (or 26.7:23H24 to name "
+                         "the build). Devices download a delta from their current build, so this picks the right file")
+    ap.add_argument("--preheat-xcode", metavar="VERSION",
+                    help="with --preheat-plan: also plan the simulator runtimes and Metal toolchain this Xcode version wants "
+                         "(27.0, or latest), for developer Macs on each server's network. iOS by default; --xcode-platforms adds "
+                         "tvos, watchos, visionos. Uses Apple's public simulator index, so Xcode need not be installed here")
+    ap.add_argument("--xcode-platforms", default="ios", help="comma list for --preheat-xcode: ios, tvos, watchos, visionos, or all (default ios)")
+    ap.add_argument("--xcode-betas", action="store_true", help="let --preheat-xcode pick beta simulator runtimes")
+    ap.add_argument("--preheat-installers", metavar="VERSIONS",
+                    help="with --preheat-plan: also plan full macOS installers (InstallAssistant.pkg, what softwareupdate "
+                         "--fetch-full-installer and Jamf installer packages download), for erase-and-install and rebuild work. "
+                         "'latest' = the newest of each major Apple still offers; '27' = the newest 27.x; '27.0,26.7' = exactly those; 'all' = every one")
+    ap.add_argument("--preheat-aerials", metavar="CATEGORIES",
+                    help="with --preheat-plan: also plan Aerial screen saver videos (164 in all, about 80 GB; 0.5 GB on average, the largest 1.5 GB): a comma list of "
+                         "categories (landscapes, cities, underwater, space, mac, dynamic), or all")
+    ap.add_argument("--preheat-server", metavar="NAME_OR_GUID", help="limit --preheat-models to cache servers whose name or GUID contains this (default: every server)")
+    ap.add_argument("--inventory-json", help="use this JSON list of normalized computers instead of Jamf")
+    ap.add_argument("--public-ranges", action="append", default=[], metavar="RANGES",
+                    help="for a site that reaches the internet from more than one public address: all of them, as in the site's "
+                         "DNS TXT record, e.g. \"203.0.113.10-203.0.113.19,198.51.100.7\". A mobile device coming from any of them "
+                         "is matched to the caches registered from any of them. Repeat for each site. Not needed where Macs on "
+                         "the site report the ranges themselves (servers-found EA, 'dns:' line)")
+    ap.add_argument("--dns-domain", action="append", default=[], metavar="DOMAIN",
+                    help="read a site's public and favored ranges from Apple's content caching TXT records in this DNS domain "
+                         "(_aaplcache._tcp.DOMAIN), the way devices do. Needs dig or nslookup, and a Mac that can see that DNS. Repeat for each site")
+    ap.add_argument("--record-answers", action="store_true",
+                    help="with --inventory-json: ask Apple now and store its answers in that file. From then on the file gives "
+                         "the same result whatever Apple releases, which is what a sample or a test needs")
+    ap.add_argument("--silent-minutes", type=int, metavar="N",
+                    help="a cache server Jamf has not heard from for this long (no check-in, inventory or status report) is "
+                         "NOT READY: it is off or off the network, and nothing else in Jamf will say so. Default: three times "
+                         "your check-in frequency and at least 30; 180 if the API role cannot read the frequency. 0 = do not check")
+    ap.add_argument("--assume-peers", action="store_true",
+                    help="treat cache servers that share a public address (or site) and a subnet as peers even when they do not "
+                         "report each other. Peers hand each other content, so a file on any of them counts. Without this, only "
+                         "peers a cache reports itself (macOS 27) are used")
+    ap.add_argument("--store-credentials", action="store_true",
+                    help="prompt for the Jamf URL, API client ID and secret and store them in the macOS login keychain, then exit")
+    args = ap.parse_args()
+    if args.store_credentials:
+        import getpass
+        vals = {"JAMF_URL": input("Jamf Pro URL (https://yourorg.jamfcloud.com): ").strip().rstrip("/"),
+                "JAMF_CLIENT_ID": input("API client ID: ").strip(),
+                "JAMF_CLIENT_SECRET": getpass.getpass("API client secret (not echoed): ").strip()}
+        keychain_store(vals); print(f"stored in the login keychain under service '{KEYCHAIN_SERVICE}'"); return
+
+    if (args.preheat_models or args.preheat_xcode or args.preheat_installers or args.preheat_aerials) and not args.preheat_plan: sys.exit("--preheat-models, --preheat-xcode, --preheat-installers and --preheat-aerials need --preheat-plan FILE to write to")
+    plats = set(PLATFORMS) if args.platforms == "all" else {"mac"} | {p.strip() for p in args.platforms.split(",") if p.strip()}
+    bad = plats - set(PLATFORMS)
+    if bad: sys.exit(f"unknown platform(s): {', '.join(bad)}; choose from {', '.join(PLATFORMS)}")
+    if args.inventory_json:
+        data = json.load(open(args.inventory_json)); jamf = None
+        # a plain list of devices, or {"devices": [...], "apple_answers": {...}} as --record-answers writes it
+        comps = data["devices"] if isinstance(data, dict) else data
+        recorded_devices = json.loads(json.dumps(comps))
+        if isinstance(data, dict) and "apple_answers" in data and not args.record_answers:
+            global _recorded; _recorded = data["apple_answers"]
+        for c in comps:
+            c.setdefault("platform", platform_of(c.get("model"))); c.setdefault("ip", "")
+            if not c.get("board"): c["board"] = board_for(c.get("model"))
+            ipm = re.search(r"\bip ([0-9a-fA-F.:,]+)", c.get("cache_status") or ""); pubm = re.search(r"\bpublic ([0-9a-fA-F.:]+)", c.get("cache_status") or "")
+            c.setdefault("cache_ips", ipm.group(1).split(",") if ipm else []); c.setdefault("cache_public_ip", pubm.group(1) if pubm else "")
+    else:
+        jamf = jamf_from_credentials()
+        comps = jamf.inventory()
+        if plats - {"mac"}:
+            try: comps += jamf.mobile_inventory()
+            except urllib.error.HTTPError as e: print(f"warning: mobile device inventory not readable (HTTP {e.code}); Macs only")
+    comps = [c for c in comps if c.get("platform") in plats or c.get("cache_guid")]
+    for spec in args.cohort:      # GROUP=VERSION: members are judged against VERSION
+        group, _, ver = spec.rpartition("=")
+        if not group or not re.fullmatch(r"same|\d+(\.\d+)*", ver): sys.exit(f"--cohort '{spec}': expected GROUP NAME=VERSION, e.g. \"Hold on 26=26\"")
+        macs, mobiles = jamf.group_members(group) if jamf else (None, None)
+        if jamf and macs is None and mobiles is None: sys.exit(f"--cohort: no computer or mobile device group named '{group}' that this API client can see. Check the spelling; "
+                                                                      "a Static group also needs Read Static Computer Groups / Read Static Mobile Device Groups on the API role "
+                                                                      "(python3 admin/doctor.py shows which are missing)")
+        n = 0
+        for c in comps:
+            ids = macs if c.get("platform") == "mac" else mobiles
+            if c.get("cohort"): continue
+            if (ids is not None and str(c.get("id")) in ids) or group in (c.get("groups") or []): c["cohort"] = (group, ver); n += 1
+        print(f"Cohort '{group}' -> {ver}: {n} device(s)")
+
+    if args.max_age_days:
+        cutoff = (datetime.date.today() - datetime.timedelta(days=args.max_age_days)).isoformat()
+        stale = [c for c in comps if c.get("last_inventory") and c["last_inventory"] < cutoff]
+        comps = [c for c in comps if c not in stale]
+        if stale: print(f"Ignoring {len(stale)} Mac(s) with no inventory in {args.max_age_days} days: " + ", ".join(c["name"] for c in stale))
+    servers = [c for c in comps if c["cache_guid"] or parse_assets_ea(c["assets_ea"])]
+    if not servers: sys.exit("No cache servers found: Jamf's Content Caching inventory shows no Mac with content caching switched on. Nothing to check.")
+
+    # ---- assign client Macs to servers ----
+    def same_subnet(ip, ips, bits):
+        try:
+            import ipaddress
+            net = lambda a: ipaddress.ip_network(f"{a}/{bits}", strict=False)
+            return any(ip and a and net(ip) == net(a) for a in ips)
+        except ValueError: return False
+    sites = collect_sites(comps, args.public_ranges, args.dns_domain)
+    site_of = lambda ip: {i for i, st in enumerate(sites) if ip and in_ranges(ip, st["public"])}
+    for st in sites:
+        print(f"Site with public addresses {show_ranges(st['public'])}" + (f", favored caches {show_ranges(st['favored'])}" if st["favored"] else "") + f" ({st['source']})")
+    for s in servers:      # what each cache says about itself through DDM: read once, used for peers and in the report
+        s["ddm"] = live_cache(jamf.cache_status(s.get("management_id")), s.get("inventory_time") or "") if jamf else None
+    silent_after = (jamf.silent_threshold() if args.silent_minutes is None else args.silent_minutes) if jamf else 0
+    for s in servers:      # a server nobody has heard from: off, or off the network
+        s["heard"] = last_heard(s, s["ddm"])
+        s["quiet_minutes"] = int((datetime.datetime.now(datetime.timezone.utc) - s["heard"]).total_seconds() // 60) if s["heard"] else 0
+        s["silent"] = bool(silent_after and s["heard"] and s["quiet_minutes"] > silent_after)
+    by_guid = {s["cache_guid"]: s for s in servers if s["cache_guid"]}
+    peers = {g: {} for g in by_guid}      # guid -> {peer guid: how we know}
+    for s in servers:
+        for g in (s.get("peers") or []) + ((s["ddm"] or {}).get("peer_guids") or []):
+            g = g.upper()
+            if g in by_guid and g != s["cache_guid"] and s["cache_guid"]:
+                peers[s["cache_guid"]][g] = "reported by the cache"; peers[g].setdefault(s["cache_guid"], "reported by the cache")
+    if args.assume_peers:
+        for a in servers:
+            for b in servers:
+                if a is b or not a["cache_guid"] or not b["cache_guid"] or b["cache_guid"] in peers[a["cache_guid"]]: continue
+                same_site = (a.get("cache_public_ip") and a.get("cache_public_ip") == b.get("cache_public_ip")) or (site_of(a.get("cache_public_ip")) & site_of(b.get("cache_public_ip")))
+                if same_site and any(same_subnet(x, b.get("cache_ips") or [], args.subnet_bits) for x in a.get("cache_ips") or []):
+                    peers[a["cache_guid"]][b["cache_guid"]] = "assumed: same public address and subnet"
+    members = {s["name"]: [] for s in servers}; assigned = set()
+    for c in comps:
+        hits = []
+        for s in servers:
+            mode = args.group_by
+            if mode == "locator" and not c.get("caches_found"):   # no locator EA (mobile devices): use Apple's own rule,
+                if c.get("ip") and s.get("cache_public_ip"): mode = "public-ip"   # same public IP as the server
+                elif c.get("ip") and s.get("cache_ips"): mode = "subnet"
+                else: mode = "building"
+            if mode == "locator": hit = s["cache_guid"] and s["cache_guid"] in found_guids(c["caches_found"])
+            elif mode == "public-ip":      # the same public address, or two addresses of one site
+                hit = c.get("ip") == s.get("cache_public_ip") or bool(site_of(c.get("ip")) & site_of(s.get("cache_public_ip")))
+            elif mode == "subnet": hit = same_subnet(c.get("ip"), s.get("cache_ips") or [], args.subnet_bits)
+            else: hit = c["building"] and c["building"] == s["building"]
+            sticky = False
+            if not hit and c.get("platform") != "mac" and s["cache_guid"]:   # mobile: keep a recent sighting alive
+                prev = parse_served(c.get("served_ea")).get(s["cache_guid"])
+                if prev and prev[1] and (datetime.date.today() - prev[1]).days <= args.sticky_days: sticky = True
+            if hit or sticky: hits.append((s, bool(hit)))
+        # Favored caches (Apple's fss record): while one of them is up, a device uses no other.
+        live = [s for s, now in hits if now]
+        if c.get("platform") == "mac": fav = [s for s in live if s["cache_guid"] in favored_guids(c.get("caches_found"))]
+        else:
+            ranges = [r for i in site_of(c.get("ip")) for r in sites[i]["favored"]]
+            fav = [s for s in live if ranges and any(in_ranges(a, ranges) for a in s.get("cache_ips") or [])]
+        if fav: hits = [(s, now) for s, now in hits if s in fav or not now]
+        for s, now in hits:
+            if now: c.setdefault("matched_now", set()).add(s["cache_guid"])
+            members[s["name"]].append(c); assigned.add(c["name"])
+    unassigned = [c for c in comps if c["name"] not in assigned and c["name"] not in members]
+
+    extra = []      # --preheat-models: (model, platform, board, from version, from build)
+    want = args.preheat_models or ""
+    words = {w.lower() for w in re.findall(r"\b(all|mac|iphone|ipad|appletv|visionpro)\b", want, re.I)}
+    ids = re.findall(r"[A-Za-z]+\d+,\d+", want)      # identifiers contain a comma themselves (iPhone18,3)
+    junk = re.sub(r"[A-Za-z]+\d+,\d+|\b(all|mac|iphone|ipad|appletv|visionpro)\b", "", want, flags=re.I).strip(" ,;")
+    if junk: print(f"--preheat-models: could not read '{junk}'; use model identifiers such as iPhone18,3, or all / mac / iphone / ipad / appletv / visionpro")
+    if words:      # a whole family: every model AppleDB lists since 2013 (Apple Watch and HomePod only when named by identifier)
+        fam = {"mac": "mac", "iphone": "ios", "ipad": "ipados", "appletv": "tvos", "visionpro": "visionos"}
+        keep = set(fam.values()) if "all" in words else {fam[w] for w in words}
+        board_for("")
+        try:
+            for d in json.load(open(BOARD_CACHE)):
+                rel = d.get("released"); rel = (rel[0] if isinstance(rel, list) and rel else rel) or ""
+                di = d.get("identifier") or []; di = [di] if isinstance(di, str) else di
+                for m in di:
+                    if str(rel) >= "2013" and platform_of(m) in keep and board_for(m) and m not in ids: ids.append(m)
+        except Exception as e: print(f"--preheat-models: cannot read the AppleDB model list ({e})")
+        print(f"--preheat-models {' '.join(sorted(words))}: {len(ids)} models")
+    froms = [f.strip() for f in (args.preheat_from or "").split(",") if f.strip()]
+    quiet = len(ids) > 12      # a family run reports totals, not a line per model and version
+    def resolve(model):
+        """[(model, platform, board, from version, from build)] for one model, plus the messages it produced."""
+        plat, board = platform_of(model), board_for(model); msgs = []
+        if not plat or not board: return [], [f"--preheat-models: {model} is not a model identifier AppleDB knows (expected e.g. iPhone18,3 or Mac17,5); skipped"]
+        got = []
+        for f in froms:      # one --from list can serve several platforms; a version that is not this platform's is skipped
+            fver, _, fbuild = f.partition(":")
+            cands = [fbuild] if fbuild else builds_for(plat, fver)
+            for bld in cands:      # the build of that version Apple offers THIS model a delta from
+                try:
+                    if any(a["prereq"] == bld for a in gdmf_assets(board, model, fver, bld, plat)): got.append((fver, bld)); break
+                except Exception: pass
+            else:
+                if cands: msgs.append(f"--from {fver}: Apple offers {model} no delta from it; the full image covers it")
+        if froms and not got:
+            try: newest = max((vkey(a["version"]) for a in gdmf_assets(board, model, NO_VERSION, "0", plat)), default=())
+            except Exception: newest = ()
+            if newest and any(vkey(f.partition(":")[0]) >= newest for f in froms):
+                return [], msgs + [f"--preheat-models: {model} on {args.preheat_from} already runs the newest OS Apple offers it; nothing to preheat"]
+            msgs.append(f"--from: nothing in '{args.preheat_from}' gives {model} a delta; planned as a full image")
+        return [(model, plat, board, fver, fbuild) for fver, fbuild in got or [("", "")]], msgs
+    if ids:
+        for plat in {platform_of(m) for m in ids if platform_of(m)}:      # warm the version -> build table once, not per thread
+            for f in froms:
+                if ":" not in f: builds_for(plat, f.partition(":")[0])
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor(8) as ex:
+            for rows, msgs in ex.map(resolve, ids):
+                extra += rows
+                if not quiet:
+                    for m in msgs: print(m)
+    xcode = []      # --preheat-xcode: [(name, platform key, {url,path,size,build})]
+    if args.preheat_xcode:
+        xp = set(XCODE_PLATFORMS) if args.xcode_platforms == "all" else {p.strip() for p in args.xcode_platforms.split(",") if p.strip()}
+        bad = xp - set(XCODE_PLATFORMS)
+        if bad: sys.exit(f"--xcode-platforms: unknown {', '.join(bad)}; choose from {', '.join(XCODE_PLATFORMS)} or all")
+        try: wants = xcode_wants(args.preheat_xcode, xp, args.xcode_betas)
+        except Exception as e: sys.exit(f"--preheat-xcode: cannot read Apple's simulator index ({e})")
+        if not wants: sys.exit(f"--preheat-xcode: Apple's index lists no simulator runtime for Xcode {args.preheat_xcode}")
+        for kind, plat, name, build, size in wants:
+            a = gdmf_xcode(kind, plat, build)
+            if a: xcode.append((name, plat, a))
+            else: print(f"--preheat-xcode: Apple's lookup offers no file for {name}; skipped")
+        print(f"--preheat-xcode {args.preheat_xcode}: {len(xcode)} file(s), {sum(a['size'] for _, _, a in xcode)/1e9:.1f} GB")
+    installers = []      # --preheat-installers: full macOS installers from Apple's catalog
+    if args.preheat_installers:
+        try: allinst = full_installers()
+        except Exception as e: sys.exit(f"--preheat-installers: cannot read Apple's software update catalog ({e})")
+        want = args.preheat_installers.strip().lower()
+        if want == "all": installers = allinst
+        elif want == "latest":
+            seen = set()
+            for e in allinst:
+                if e["version"].split(".")[0] not in seen: seen.add(e["version"].split(".")[0]); installers.append(e)
+        else:
+            for w in [x.strip() for x in want.split(",") if x.strip()]:
+                hit = [e for e in allinst if e["version"] == w] or [e for e in allinst if e["version"].startswith(w + ".")] or [e for e in allinst if e["version"].split(".")[0] == w]
+                if hit: installers.append(hit[0])
+                else: print(f"--preheat-installers: Apple's catalog has no full installer for macOS {w}")
+        print(f"--preheat-installers {args.preheat_installers}: {len(installers)} installer(s), {sum(e['size'] for e in installers)/1e9:.1f} GB: " + ", ".join(f"{e['version']} ({e['build']})" for e in installers))
+    aerial = []      # --preheat-aerials
+    if args.preheat_aerials:
+        try: allaer = aerials()
+        except Exception as e: sys.exit(f"--preheat-aerials: cannot read Apple's Aerial manifest ({e})")
+        want = {w.strip().lower() for w in args.preheat_aerials.split(",") if w.strip()}
+        aerial = allaer if "all" in want else [e for e in allaer if any(w in e["category"].lower() for w in want)]
+        if not aerial: sys.exit(f"--preheat-aerials: no category matches '{args.preheat_aerials}'; the manifest has: " + ", ".join(sorted({c for e in allaer for c in e["category"].split(", ")})))
+        print(f"--preheat-aerials {args.preheat_aerials}: {len(aerial)} video(s), about {len(aerial) * 0.49:.0f} GB (sizes are not in the manifest; all 164 measured 2026-09-27: 79.7 GB, 0.49 on average, from under 0.1 to 1.5 GB)")
+    if args.preheat_server: servers_for_extra = [s for s in servers if args.preheat_server.lower() in (s["name"] + " " + (s["cache_guid"] or "")).lower()]
+    now = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
+    print(f"Inventory: {len(comps)} devices ({', '.join(sorted(plats))}), {len(servers)} cache server(s), grouping by {args.group_by}.")
+    values = {}; plan = []
+    for s in servers:
+        have = parse_assets_ea(s["assets_ea"]); macs = members[s["name"]]
+        label = ", ".join(x for x in (s["site"], s["building"]) if x) or "no site/building set"
+        print(f"\n### {s['name']}  [{label}]  guid {s['cache_guid'] or '?'}  {s['cache_status'] or ''}")
+        live = s.get("ddm")
+        mine = peers.get(s["cache_guid"]) or {}
+        peer_have = {}      # path -> name of a peer that holds it whole
+        for g, how in mine.items():
+            pr = by_guid[g]; up = not (pr.get("ddm") and not pr["ddm"]["on"]) and (pr.get("cache_status") or "").startswith("Active") and not pr.get("silent")
+            print(f"    peer: {pr['name']} ({how})" + ("" if up else ", not running: its content is not counted"))
+            if up:
+                for path, state in parse_assets_ea(pr["assets_ea"]).items():
+                    if state == "COMPLETE": peer_have.setdefault(path, pr["name"])
+        if s.get("silent"):
+            print(f"    NOT HEARD FROM since {s['heard'].astimezone().strftime('%Y-%m-%d %H:%M')}: no check-in, inventory or status report for {s['quiet_minutes']} minutes (limit {silent_after}). What follows is what Jamf last knew")
+        if live:
+            print(f"    reported by the Mac itself (DDM, {live['as_of']}): {live['line']}")
+            if live["changed_since_inventory"] and live["on"] != (s.get("cache_status") or "").startswith("Active"):
+                print(f"    note: the cache changed state at {live['since']}, after the last inventory; the file list below is older than that")
+        byplat = collections.Counter(c.get("platform") for c in macs)
+        print(f"    serves {len(macs)} device(s) {dict(byplat)}; {sum(1 for v in have.values() if v == 'COMPLETE')} complete OS asset(s) cached")
+        combos = collections.defaultdict(list); noboard = 0
+        for c in macs:
+            if c["board"] and c["model"] and c["build"] and c["version"] and c.get("platform"):
+                combos[(c["platform"], c["board"], c["model"], c["version"], c["build"], c.get("cohort") or ("", ""))].append(c["name"])
+            else: noboard += 1
+        if noboard: print(f"    {noboard} device(s) skipped: missing board ID / model / OS data")
+        ok = partial = missing = dev_ok = dev_total = via_peer = 0
+        for (plat, board, model, version, build, (cgroup, cver)), names in sorted(combos.items()):
+            n = len(names); head = f"    [{plat}] {model} ({board}) on {version} ({build}) x{n}" + (f" [{cgroup} -> {cver}]" if cgroup else "") + ": "
+            target, target_build = (cver, "") if cgroup else (args.target, args.target_build)
+            try: assets = gdmf_assets(lookup_board(model, board), model, version, build, plat)
+            except Exception as e: print(head + f"lookup error: {e}"); continue
+            if not assets: print(head + "already current (Apple offers nothing for this device)"); continue
+            if target_build and build == target_build: print(head + "already on that build"); continue
+            want = wanted(assets, target, version)
+            if not target_build and want and vkey(version) >= want: print(head + ("already current" if not cgroup else f"already on {version}, nothing newer wanted")); continue
+            a = choose(assets, build, target, target_build, version)
+            if not a: print(head + (f"Apple offers no asset with build {target_build} for this hardware/build" if target_build else f"Apple offers this device no {target or 'newer'} update from {version}")); continue
+            st = have.get(a["path"], "MISSING"); dev_total += n
+            if st != "COMPLETE" and a["path"] in peer_have:      # a peer on the same network hands it over: no download from Apple
+                print(head + f"needs {a['version']} ({a['build']}) {'delta' if a['prereq'] else 'full'} {a['size']/1e9:.1f} GB -> COMPLETE on peer {peer_have[a['path']]} (here: {st})")
+                st = "COMPLETE"; via_peer += 1
+            else:
+                print(head + f"needs {a['version']} ({a['build']}) {'delta' if a['prereq'] else 'full'} {a['size']/1e9:.1f} GB -> {st}")
+            if st != "COMPLETE":
+                plan.append({"server": s["name"], "server_guid": s["cache_guid"], "platform": plat, "model": model, "board": board,
+                             "from_version": version, "from_build": build, "to_version": a["version"], "to_build": a["build"],
+                             "devices": n, "size": a["size"], "url": a["url"], "state": st})
+            if st == "COMPLETE": ok += 1; dev_ok += n
+            elif st.startswith("PARTIAL"): partial += 1
+            else: missing += 1
+        for model, plat, board, fver, fbuild in (extra if not args.preheat_server or s in servers_for_extra else []):      # hardware nobody here owns yet: plan only, never part of readiness
+            head = f"    [extra {plat}] {model} ({board}) " + (f"from {fver} ({fbuild}): " if fbuild else "new hardware: ")
+            try: assets = gdmf_assets(board, model, fver or NO_VERSION, fbuild or "0", plat)
+            except Exception as e: print(head + f"lookup error: {e}"); continue
+            a = choose(assets, fbuild, args.target, args.target_build)
+            if not a:
+                if not quiet: print(head + "Apple offers nothing (not released yet, or this model cannot run the target)")
+                continue
+            st = have.get(a["path"], "MISSING"); where = ""
+            if st != "COMPLETE" and a["path"] in peer_have: st, where = "COMPLETE", f" on peer {peer_have[a['path']]}"
+            if not quiet or st != "COMPLETE": print(head + f"{a['version']} ({a['build']}) {'delta' if a['prereq'] else 'full'} {a['size']/1e9:.1f} GB -> {st}{where}")
+            if st != "COMPLETE" and not any(x["url"] == a["url"] and x["server_guid"] == s["cache_guid"] for x in plan):
+                plan.append({"server": s["name"], "server_guid": s["cache_guid"], "platform": plat, "model": model, "board": board,
+                             "from_version": fver or "new", "from_build": fbuild, "to_version": a["version"], "to_build": a["build"],
+                             "devices": 0, "size": a["size"], "url": a["url"], "state": st})
+        for name, plat, a in (xcode if not args.preheat_server or s in servers_for_extra else []):      # Xcode components: plan only
+            st = have.get(a["path"], "MISSING")
+            print(f"    [xcode] {name} {a['size']/1e9:.1f} GB -> {st}")
+            if st != "COMPLETE" and not any(x["url"] == a["url"] and x["server_guid"] == s["cache_guid"] for x in plan):
+                plan.append({"server": s["name"], "server_guid": s["cache_guid"], "platform": "xcode", "model": name, "board": "",
+                             "from_version": "", "from_build": "", "to_version": args.preheat_xcode, "to_build": a["build"],
+                             "devices": 0, "size": a["size"], "url": a["url"], "state": st})
+        for e in (installers if not args.preheat_server or s in servers_for_extra else []):      # full installers: plan only
+            st = have.get(e["path"], "MISSING")
+            print(f"    [installer] {e['title']} {e['version']} ({e['build']}) {e['size']/1e9:.1f} GB -> {st}")
+            if st != "COMPLETE" and not any(x["url"] == e["url"] and x["server_guid"] == s["cache_guid"] for x in plan):
+                plan.append({"server": s["name"], "server_guid": s["cache_guid"], "platform": "installer", "model": f"{e['title']} {e['version']}", "board": "",
+                             "from_version": "", "from_build": "", "to_version": e["version"], "to_build": e["build"],
+                             "devices": 0, "size": e["size"], "url": e["url"], "state": st})
+        for e in (aerial if not args.preheat_server or s in servers_for_extra else []):      # Aerials: plan only
+            st = have.get(e["path"], "MISSING")
+            if st != "COMPLETE" and not any(x["url"] == e["url"] and x["server_guid"] == s["cache_guid"] for x in plan):
+                plan.append({"server": s["name"], "server_guid": s["cache_guid"], "platform": "aerial", "model": f"{e['name']} ({e['category']})", "board": "",
+                             "from_version": "", "from_build": "", "to_version": "", "to_build": "",
+                             "devices": 0, "size": 490_000_000, "url": e["url"], "state": st})
+        if aerial: print(f"    [aerials] {sum(1 for e in aerial if have.get(e['path']) == 'COMPLETE')} of {len(aerial)} cached")
+        total = ok + partial + missing
+        if total == 0: val = f"READY (nothing pending for {len(macs)} devices)"
+        elif ok == total: val = f"READY {ok}/{total} combos, {dev_ok} devices" + (f" ({via_peer} held by a peer)" if via_peer else "")
+        # Jamf's "like" ignores case and matches anywhere in the value: no word here may contain PARTIAL or READY by accident
+        elif ok == 0: val = f"NOT READY 0/{total} combos, 0/{dev_total} devices ({partial} still downloading)"
+        else: val = f"PARTIAL {ok}/{total} combos, {dev_ok}/{dev_total} devices" + (f" ({via_peer} held by a peer)" if via_peer else "")
+        if live and not live["on"]:      # the files may be there, but no device can get them
+            val = f"NOT READY cache is down: {live['problem']} since {live['since']}"
+        if s.get("silent"):      # off, or off the network: whatever Jamf last knew, no device can reach it
+            val = f"NOT READY cache server silent since {s['heard'].astimezone().strftime('%Y-%m-%d %H:%M')}"
+        values[s["name"]] = val + f" @ {now}"
+        print(f"    => {values[s['name']]}")
+
+    if args.record_answers:
+        if not args.inventory_json: sys.exit("--record-answers needs --inventory-json")
+        answers = {"|".join(str(k) for k in key): [{k: v for k, v in a.items() if k != "path"} for a in assets] for key, assets in sorted(_gdmf_cache.items())}
+        json.dump({"recorded": now, "devices": recorded_devices, "apple_answers": answers}, open(args.inventory_json, "w"), indent=1)
+        print(f"\nRecorded Apple's answers for {len(answers)} hardware and build combination(s) in {args.inventory_json}")
+    if args.preheat_plan:
+        json.dump({"generated": now, "sticky_days": args.sticky_days, "assets": plan}, open(args.preheat_plan, "w"), indent=1)
+        gb = sum(a["size"] for a in plan) / 1e9
+        print(f"\nPreheat plan: {len(plan)} asset(s), {gb:.1f} GB total, written to {args.preheat_plan}")
+        for a in plan: print(f"    {a['server']}: [{a['platform']}] {a['model']} {a['from_version']}->{a['to_version']} {a['size']/1e9:.1f} GB ({a['state']})")
+    if unassigned:
+        by = collections.Counter((c["site"], c["building"]) for c in unassigned)
+        print(f"\n### {len(unassigned)} device(s) matched no cache server:")
+        for (site, bld), n in by.most_common(): print(f"    {n:4d}  {site or '-'} / {bld or '-'}")
+
+    if args.write:
+        if not jamf: sys.exit("--write needs Jamf (not --inventory-json)")
+        # mobile devices: record which server they matched (Macs already carry this in their locator EA)
+        mobile = [c for c in comps if c.get("platform") and c["platform"] != "mac"]
+        if mobile:
+            try:
+                eas = jamf.call("/api/v1/mobile-device-extension-attributes?page=0&page-size=500").get("results", [])
+                ea_id = next((e["id"] for e in eas if e["name"] == EA_MOBILE_SERVER), None)
+            except urllib.error.HTTPError: ea_id = None
+            if not ea_id: print(f"mobile devices: EA '{EA_MOBILE_SERVER}' not found in Jamf; create it (Text Field) to enable per-office mobile groups")
+            else:
+                today = datetime.date.today(); n = 0
+                for c in mobile:
+                    entries = {}
+                    for g, (nm, dt) in parse_served(c.get("served_ea")).items():      # previous sightings still inside the window
+                        if dt and (today - dt).days <= args.sticky_days: entries[g] = (nm, dt)
+                    for s in servers:                                                  # what matched right now
+                        if s["cache_guid"] in (c.get("matched_now") or set()): entries[s["cache_guid"]] = (s["name"], today)
+                    val = "; ".join(f"{nm} guid {g} seen {dt.isoformat()}" for g, (nm, dt) in sorted(entries.items(), key=lambda kv: kv[1][1], reverse=True)) or "None found"
+                    if c.get("served_ea") == val: continue
+                    try:
+                        jamf.call(f"/api/v2/mobile-devices/{c['id']}", "PATCH",
+                                  {"updatedExtensionAttributes": [{"id": str(ea_id), "name": EA_MOBILE_SERVER, "type": "STRING", "value": [val]}]})
+                        n += 1
+                    except urllib.error.HTTPError as e: print(f"{c['name']}: write failed HTTP {e.code}")
+                print(f"mobile devices: wrote '{EA_MOBILE_SERVER}' on {n} device(s)")
+        try:
+            ceas = jamf.call("/api/v1/computer-extension-attributes?page=0&page-size=500").get("results", [])
+            # Written from here only while it is a text field; as a script EA (ea-content-cache-decoded.sh) the server fills it itself.
+            decoded_id = next((e["id"] for e in ceas if e["name"] == EA_DECODED and e.get("inputType") != "SCRIPT"), None)
+        except urllib.error.HTTPError: decoded_id = None
+        for s in servers:
+            if not s["ready_ea_id"]: print(f"{s['name']}: EA '{EA_READY}' not on record; create it in Jamf first"); continue
+            eas = [{"definitionId": str(s["ready_ea_id"]), "values": [values[s["name"]]]}]
+            if decoded_id:
+                eas.append({"definitionId": str(decoded_id), "values": ["\n".join(decoded_lines(s["assets_ea"])) or "No OS update assets cached"]})
+            jamf.call(f"/api/v1/computers-inventory-detail/{s['id']}", "PATCH", {"extensionAttributes": eas})
+            print(f"{s['name']}: wrote readiness EA" + (" and decoded assets EA" if decoded_id else ""))
+
+if __name__ == "__main__":
+    try: main()
+    except urllib.error.HTTPError as e:
+        hint = {401: "Jamf refused the API client: check the client ID and secret, and that the client is enabled",
+                403: "the API role lacks a privilege this step needs (docs/SETUP.md lists them per feature)",
+                404: "Jamf does not know that address: check JAMF_URL, and that the EA, group or record still exists"}.get(e.code, "unexpected reply")
+        sys.exit(f"\nStopped: HTTP {e.code} from {e.url.split('?')[0]}\n  {hint}\n  python3 admin/doctor.py checks the whole setup and says what to fix")
+    except urllib.error.URLError as e:
+        sys.exit(f"\nStopped: cannot reach a server ({e.reason}). Needs outbound HTTPS to your Jamf Pro, gdmf.apple.com and api.appledb.dev\n  python3 admin/doctor.py --offline tests the two Apple-side services")
+    finally: save_decoded()
+        
\ No newline at end of file
diff --git a/sales/preheat/admin/sample-inventory-large-site.json b/sales/preheat/admin/sample-inventory-large-site.json
new file mode 100644
index 0000000..5eb72af
--- /dev/null
+++ b/sales/preheat/admin/sample-inventory-large-site.json
@@ -0,0 +1,569 @@
+{
+ "recorded": "2026-09-28 21:15",
+ "devices": [
+  {
+   "id": 2,
+   "name": "officeX-cache",
+   "model": "Macmini9,1",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J274AP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "AAAA1111-2222-3333-4444-0FF1CE000001",
+   "cache_status": "Active; guid AAAA1111-2222-3333-4444-0FF1CE000001; ip 10.10.0.106; public 203.0.113.10; free 481.7 GB; used 20.6 GB; status OK",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 localhost:49419 healthy reachable",
+   "assets_ea": "No macOS assets cached",
+   "ready_ea_id": 42,
+   "ip": "10.10.0.106"
+  },
+  {
+   "id": 1,
+   "name": "laptop",
+   "model": "Mac16,8",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J614sAP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 10.10.0.106:49419 healthy reachable\ndns: public 203.0.113.10-203.0.113.19",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 3,
+   "name": "x-air-1",
+   "model": "Mac14,2",
+   "version": "26.0",
+   "build": "25A353",
+   "board": "J413AP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 10.10.0.106:49419 healthy reachable",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 101,
+   "name": "x-ipad-1",
+   "model": "iPad13,16",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "HQ",
+   "building": "Office X",
+   "ip": "203.0.113.10",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 102,
+   "name": "x-appletv-1",
+   "model": "AppleTV14,1",
+   "version": "26.0",
+   "build": "23J345",
+   "site": "HQ",
+   "building": "Office X",
+   "ip": "203.0.113.10",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 20,
+   "name": "officeX-cache-2",
+   "model": "Macmini9,1",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J274AP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "BBBB1111-2222-3333-4444-0FF1CE000002",
+   "cache_status": "Active; guid BBBB1111-2222-3333-4444-0FF1CE000002; ip 10.10.0.107; public 203.0.113.10; free 481.7 GB; used 20.6 GB; status OK",
+   "caches_found": "BBBB1111-2222-3333-4444-0FF1CE000002 localhost:49419 healthy reachable",
+   "assets_ea": "COMPLETE 18.4GB 2026-09-18 /content/downloads/52/44/142-16670-A_C1NGFF0VNT/e1mno92ap4g9s6epq5bbee9a57b5tm983g/InstallAssistant.pkg\nCOMPLETE 18.4GB 2026-09-28 /2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+   "ready_ea_id": 42,
+   "ip": "10.10.0.107",
+   "peers": [
+    "AAAA1111-2222-3333-4444-0FF1CE000001"
+   ]
+  },
+  {
+   "id": 110,
+   "name": "x-ipad-other-exit",
+   "model": "iPad13,16",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "HQ",
+   "building": "",
+   "ip": "203.0.113.17",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 111,
+   "name": "stranger-ipad",
+   "model": "iPad13,16",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "",
+   "building": "",
+   "ip": "198.18.7.7",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  }
+ ],
+ "apple_answers": {
+  "ipados|J407AP|iPad13,16|26.0|23A341": [
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6d1a429-45e8-4652-a07f-31ea7e4f4edb/com_apple_MobileAsset_SoftwareUpdate/1cb69da96a4545098cbde383410345092e0d9bd9.zip",
+    "prereq": "",
+    "size": 8345528509
+   },
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6399312e-3770-4c06-ae01-c3836b6cb7da/com_apple_MobileAsset_SoftwareUpdate/060db0349a690dcd54ce31273ebcbda6462d221a.zip",
+    "prereq": "23A341",
+    "size": 5699492509
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/70b5af77-06c5-444e-9d5a-a8e456b6ac89/com_apple_MobileAsset_SoftwareUpdate/d55646ffb43553e423f64e6806342d1dd440ebff.zip",
+    "prereq": "",
+    "size": 7964352371
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e0d62fe5-d1e1-462a-9b8c-374f165dafa7/com_apple_MobileAsset_SoftwareUpdate/060f7f8ddb9a6e17a00f177abb5015a157c3e619.zip",
+    "prereq": "23A341",
+    "size": 4258597123
+   }
+  ],
+  "mac|J274AP|Macmini9,1|27.0.1|26A434": [
+   {
+    "version": "13.7.8",
+    "build": "22H730",
+    "url": "https://updates.cdn-apple.com/2025SummerFCS/patches/093-21919/26CB8378-0A7E-4002-A29A-783807562955/com_apple_MobileAsset_MacSoftwareUpdate/97a386b5182904411d3cf455febfcf86757eb2cd.zip",
+    "prereq": "",
+    "size": 12185064350
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   },
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "14.8.9",
+    "build": "23J631",
+    "url": "https://updates.cdn-apple.com/2026SpringFCS/patches/140-88610/0C176173-8545-411A-A339-D34839E9433B/com_apple_MobileAsset_MacSoftwareUpdate/7742064d78e178b2ed119862104e6620dad4caa5.zip",
+    "prereq": "",
+    "size": 13634151792
+   },
+   {
+    "version": "12.7.6",
+    "build": "21H1320",
+    "url": "https://updates.cdn-apple.com/2024SpringFCS/patches/062-40399/DE1EC861-93E8-4EC5-8C9D-66ABF9E03140/com_apple_MobileAsset_MacSoftwareUpdate/74d53fc10d4f444b01cb19944407a34a8edccebf.zip",
+    "prereq": "",
+    "size": 11495541757
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "11.7.11",
+    "build": "20G1443",
+    "url": "https://updates.cdn-apple.com/2023SpringFCS/patches/047-32255/8C537538-2276-4D30-AEA3-8934521EA560/com_apple_MobileAsset_MacSoftwareUpdate/e7e703b5528a1d73fbcdb37c487160f9e4af5948.zip",
+    "prereq": "",
+    "size": 11492857293
+   }
+  ],
+  "mac|J413AP|Mac14,2|26.0|25A353": [
+   {
+    "version": "13.7.8",
+    "build": "22H730",
+    "url": "https://updates.cdn-apple.com/2025SummerFCS/patches/093-21919/26CB8378-0A7E-4002-A29A-783807562955/com_apple_MobileAsset_MacSoftwareUpdate/97a386b5182904411d3cf455febfcf86757eb2cd.zip",
+    "prereq": "",
+    "size": 12185064350
+   },
+   {
+    "version": "14.8.9",
+    "build": "23J631",
+    "url": "https://updates.cdn-apple.com/2026SpringFCS/patches/140-88610/0C176173-8545-411A-A339-D34839E9433B/com_apple_MobileAsset_MacSoftwareUpdate/7742064d78e178b2ed119862104e6620dad4caa5.zip",
+    "prereq": "",
+    "size": 13634151792
+   },
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "12.7.6",
+    "build": "21H1320",
+    "url": "https://updates.cdn-apple.com/2024SpringFCS/patches/062-40399/DE1EC861-93E8-4EC5-8C9D-66ABF9E03140/com_apple_MobileAsset_MacSoftwareUpdate/74d53fc10d4f444b01cb19944407a34a8edccebf.zip",
+    "prereq": "",
+    "size": 11495541757
+   }
+  ],
+  "mac|J614sAP|Mac16,8|27.0.1|26A434": [
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   }
+  ],
+  "tvos|J255AP|AppleTV14,1|26.0|23J345": [
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0c859739-d90e-427e-a8ea-8c3733a0461b/com_apple_MobileAsset_SoftwareUpdate/35400de192388eac95c568781814f83e8249a82aeec264a926d95a89c1711344.aea",
+    "prereq": "23J362",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/f144ac26-a720-44a7-8114-8a0607a4f672/com_apple_MobileAsset_SoftwareUpdate/2104dbeeffe1e2f7ac38c883f0c82c8fc7deccc80823014c3f34923f9cc68b51.aea",
+    "prereq": "20L497",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/499a07e9-49a0-4693-ae59-dcb69016c802/com_apple_MobileAsset_SoftwareUpdate/a242763b8c7532ab1ece1e97deac2fe223ee5ff7cfa71ef1001ce6932496b670.aea",
+    "prereq": "21L569",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/82022510-ece2-4d42-ab31-497df2008016/com_apple_MobileAsset_SoftwareUpdate/fa811277ad21f7530c59020911ca4b05167070201552ac40f17ff573d400801b.aea",
+    "prereq": "20K672",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6da069ed-49df-47b6-b45f-da16939d2273/com_apple_MobileAsset_SoftwareUpdate/e0490b4385345f8e1375a7c5e3971fabf0e34b06246fc3f968d6d5e81c0c13e7.aea",
+    "prereq": "20K661",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/1fb5b4a5-721a-4589-9508-9a9401457148/com_apple_MobileAsset_SoftwareUpdate/64dcf83ca9c4c38182b71fab9f01ea459ff0a5079fc42aedac96b3c022563373.aea",
+    "prereq": "21M71",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/d5957056-e572-40c7-91f4-fe918760f952/com_apple_MobileAsset_SoftwareUpdate/9d0763adf98269b83609c5c46538d00c1d780ca61fae069822896d56a171e167.aea",
+    "prereq": "20J8378",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/35b3b52f-d9e6-490e-8997-76105740800d/com_apple_MobileAsset_SoftwareUpdate/0b2494bdc182b91be9cba63dd3a4468e43ecbcf720cd9c2f609ddade4bd20c92.aea",
+    "prereq": "21K69",
+    "size": 3154116608
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/41b8913a-41a4-48c8-b3a1-6e6f8c30a80c/com_apple_MobileAsset_SoftwareUpdate/e8684c07ef78e2ec067586cefbd5193837426c9331269286290a2544b826e425.aea",
+    "prereq": "22L261",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a59232d6-af15-432d-b36e-228f5c190ae0/com_apple_MobileAsset_SoftwareUpdate/d417441e26b80b4ab06529e948db0b9b1aae2a05f723127d5f41a40c7cfe88eb.aea",
+    "prereq": "23J582",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/aa3c63ef-b4e6-4b8a-ae84-0daf15cf1ba4/com_apple_MobileAsset_SoftwareUpdate/06f9703cf00f172bfbc0226b3ca6211c8c429643206564ea3f5436b0ba3cdb32.aea",
+    "prereq": "22K561",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/74d52f4f-b217-406b-b646-97c6eab068e5/com_apple_MobileAsset_SoftwareUpdate/8072b444430e65ad7d5a5394238d76fda294ea44a9af2eae503f6545421652a9.aea",
+    "prereq": "22K557",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/246b63f8-b70d-4fcf-8adf-65b274f71c42/com_apple_MobileAsset_SoftwareUpdate/a6820d2d0d442d18aeabd3a8d935d13de402a7eac4b9eb2aa02ad03505fc081a.aea",
+    "prereq": "23J353",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6d98cda1-5422-466c-925e-0b2e2a83191f/com_apple_MobileAsset_SoftwareUpdate/3eb83a7e19512c33ce064656c0373edf70cc6e85a009ddacb2cb5470040bff9f.aea",
+    "prereq": "21K646",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/33135f98-36f9-4a54-b9b6-49a31ffa9a81/com_apple_MobileAsset_SoftwareUpdate/3459df78cac44630a9a34d3836a864a364317f2b98775cbed3606a8876392b08.aea",
+    "prereq": "23L773",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/708a7b9a-5a24-474d-908c-dcc192535abb/com_apple_MobileAsset_SoftwareUpdate/5fe152218b8bc239014b536946b03cc272b228c2e2d6393c4ae46b91322795c3.aea",
+    "prereq": "21K364",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/08f782b4-b150-4598-b2d4-3b9661bcc46b/com_apple_MobileAsset_SoftwareUpdate/284576c8c95b28f2332091892e9ceada2d14b0efb88eaa3a851f13135b41bf52.aea",
+    "prereq": "20L498",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/27b22cbc-495f-427b-a997-85fd6e096435/com_apple_MobileAsset_SoftwareUpdate/dce5c2222c4b12dbafe8aae9f984e55c617fb789215f0f6e76f3e1bcab7339d1.aea",
+    "prereq": "22L255",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/21a88284-433a-4986-9592-3c0b7eccddb9/com_apple_MobileAsset_SoftwareUpdate/f6647c3f4a33a0814d4de8d1f343dc148ce5b973114e1da571c4dfb91cbe65cb.aea",
+    "prereq": "22K160",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/7d9186c9-76df-44f9-b9de-a817ade6efdb/com_apple_MobileAsset_SoftwareUpdate/c60653d1d17664ab9057de6b9b181eff52922ab2488267e96a857cade86c3b7f.aea",
+    "prereq": "23L243",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/de096ad6-d2ef-4c0d-8e61-77568e3124e3/com_apple_MobileAsset_SoftwareUpdate/9975b082de4a6ce32a0b77c4b6f507e397a206ad4780fac932c41a531585da06.aea",
+    "prereq": "21J354",
+    "size": 3154116608
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/5f82f493-2f16-415c-baca-94639f59cdf5/com_apple_MobileAsset_SoftwareUpdate/557f57477a15d13609f30539847f55a88e474bb141fb737d10924482bb26e047.aea",
+    "prereq": "22M84",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/3f7570b0-b247-4f68-a7f6-6b26d348f6f3/com_apple_MobileAsset_SoftwareUpdate/80511384cf6a9a33ac47403ed6917b0f8fdf82b5b59e46abe7f430322e24f5d5.aea",
+    "prereq": "20M73",
+    "size": 3355443200
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0f7e610e-c7da-4bbf-9459-032f72863a7f/com_apple_MobileAsset_SoftwareUpdate/c12def7918f42b5da79ffadab519aa43fba79b568907bf6a9fd3f0fdfe4f3e0e.aea",
+    "prereq": "21K365",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0f35bc0e-06e1-4cd5-a27c-6f22d2f1c563/com_apple_MobileAsset_SoftwareUpdate/0019cfb77d90f14ea82ce16ede9df20458e2145e1e65b5e51c68d62446ba3890.aea",
+    "prereq": "23K54",
+    "size": 2113929216
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/232b012b-e417-4473-8285-7023d623ec01/com_apple_MobileAsset_SoftwareUpdate/3220637ef5119415005b5c81734dc62d166e83e75cefe69af04cf11bf896c8f1.aea",
+    "prereq": "22L572",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/319b56a0-027e-4b7d-b26a-5f7acc76cd7b/com_apple_MobileAsset_SoftwareUpdate/78d411ce71ac8fe5daa1134bf23e3414756ceeb5203684016c47f034d2949137.aea",
+    "prereq": "22J580",
+    "size": 2751463424
+   },
+   {
+    "version": "27.0",
+    "build": "24J6361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/fbf3c544-b770-4756-9cca-abfb2d3cb65e/com_apple_MobileAsset_SoftwareUpdate/9bf3ad6ac49c25016599bbb77d8ea1c612cb745eb7ee9e502af1926c860b7e18.aea",
+    "prereq": "",
+    "size": 4831838208
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a5557d58-82d2-420b-9dc9-fb49c346505b/com_apple_MobileAsset_SoftwareUpdate/a0dc959bf2a11d3631258340c5340b0d0d0caa0af2a853d8b8267c330da9e8e2.aea",
+    "prereq": "20K680",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/4f14641c-4eeb-49c1-85c9-fa76b486931e/com_apple_MobileAsset_SoftwareUpdate/acc82afb77e866044cf29e570bf36630327a419f4a420d43fd93fe04f91373f1.aea",
+    "prereq": "21L227",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/f494b608-0019-4241-8166-02dfd14e8ef0/com_apple_MobileAsset_SoftwareUpdate/0ab31a3ab0112f7d01603110326d4115bcbe6124198ad2f7f40c0395b1d4311d.aea",
+    "prereq": "21L580",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e4ab7d69-4e29-4cd9-8dcd-18613273e8a1/com_apple_MobileAsset_SoftwareUpdate/bdebbe8bb2c665ff36fee3ddb59865d70c818821c4b1eef281cf62f99fecbb26.aea",
+    "prereq": "24J360",
+    "size": 209715200
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/1be3b503-e746-4c50-a1bc-2c4d1e3a9145/com_apple_MobileAsset_SoftwareUpdate/56fa657afbf3f797b11a21f62dc6a7ff8eb300d52c2b1fba90f27f780de14ecd.aea",
+    "prereq": "20K71",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a7dd39f5-3e41-4f2e-9fdf-2cae62ce8e9f/com_apple_MobileAsset_SoftwareUpdate/4c27a46082f879b0e8fce2f319a773eda7374a40e09ce2d6c87f0e71fb2a0df5.aea",
+    "prereq": "23L471",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/922035bd-c98e-455f-af5c-365e27cb2225/com_apple_MobileAsset_SoftwareUpdate/7a37675b00bdb775cad7ad090eac7cc299c2583c52108bdb445a01247c92c799.aea",
+    "prereq": "20L563",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0c0f3805-1f24-4b27-b640-e95043c3f1f8/com_apple_MobileAsset_SoftwareUpdate/686e01e1dc4687ff15daf4e093ba1562275a45fe509e12463d080e41391d9de8.aea",
+    "prereq": "23K620",
+    "size": 2113929216
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6043924-1a0f-46e1-b169-4daf9766494e/com_apple_MobileAsset_SoftwareUpdate/9c58752514b8b66498ece0bab4112f80d6086b8c677a23ed0b74290964785e99.aea",
+    "prereq": "22K155",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a6160594-3bee-4845-8594-fd1e63149a89/com_apple_MobileAsset_SoftwareUpdate/cc09e958bd4431fe6c7779813bd7c1a6be5504f242314e8959c5fd2dbe95480f.aea",
+    "prereq": "20K362",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/7ecad802-54b5-45c2-b376-c86dc32b5cd9/com_apple_MobileAsset_SoftwareUpdate/e6978eff3fabeeaf3d5d4f19a5e7c06defdf1b633371308b4356a84376dce0e8.aea",
+    "prereq": "22J357",
+    "size": 2751463424
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6ccc85d-88a5-4929-9936-2353858fc6cf/com_apple_MobileAsset_SoftwareUpdate/36fe9b5caa24447c5503690c1954c030f42d94ad94072bf839ca4744fcff06d7.aea",
+    "prereq": "20K650",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e2acf11d-15aa-4cc5-bdfb-2c0b395cee63/com_apple_MobileAsset_SoftwareUpdate/b433c9bc30a35fdb6b3649d3e54bbd4530dbc1034778886e858d26fbebdd64d3.aea",
+    "prereq": "21M80",
+    "size": 3019898880
+   }
+  ]
+ }
+}
\ No newline at end of file
diff --git a/sales/preheat/admin/sample-inventory.json b/sales/preheat/admin/sample-inventory.json
new file mode 100644
index 0000000..afdfe61
--- /dev/null
+++ b/sales/preheat/admin/sample-inventory.json
@@ -0,0 +1,674 @@
+{
+ "recorded": "2026-09-28 21:15",
+ "devices": [
+  {
+   "id": 2,
+   "name": "officeX-cache",
+   "model": "Macmini9,1",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J274AP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "AAAA1111-2222-3333-4444-0FF1CE000001",
+   "cache_status": "Active; guid AAAA1111-2222-3333-4444-0FF1CE000001; ip 10.10.0.5; public 203.0.113.10; free 481.7 GB; used 20.6 GB; status OK",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 localhost:49419 healthy reachable",
+   "assets_ea": "COMPLETE 18.4GB 2026-09-18 /content/downloads/52/44/142-16670-A_C1NGFF0VNT/e1mno92ap4g9s6epq5bbee9a57b5tm983g/InstallAssistant.pkg\nCOMPLETE 18.4GB 2026-09-28 /2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+   "ready_ea_id": 42,
+   "ip": "10.10.0.5"
+  },
+  {
+   "id": 1,
+   "name": "laptop",
+   "model": "Mac16,8",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J614sAP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 10.10.0.5:49419 healthy reachable",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 3,
+   "name": "x-air-1",
+   "model": "Mac14,2",
+   "version": "26.0",
+   "build": "25A353",
+   "board": "J413AP",
+   "site": "HQ",
+   "building": "Office X",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 10.10.0.5:49419 healthy reachable",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 5,
+   "name": "officeA-cache",
+   "model": "Macmini9,1",
+   "version": "27.0.1",
+   "build": "26A434",
+   "board": "J274AP",
+   "site": "Branch",
+   "building": "Office A",
+   "cache_guid": "11111111-2222-3333-4444-555555555555",
+   "cache_status": "Active; guid 11111111-2222-3333-4444-555555555555; ip 10.20.0.5; public 198.51.100.7; free 900 GB; used 0 GB; status OK",
+   "caches_found": "11111111-2222-3333-4444-555555555555 localhost:49419 healthy reachable",
+   "assets_ea": "No macOS assets cached",
+   "ready_ea_id": 42,
+   "ip": "10.20.0.5"
+  },
+  {
+   "id": 6,
+   "name": "a-air-1",
+   "model": "Mac14,2",
+   "version": "26.0",
+   "build": "25A353",
+   "board": "J413AP",
+   "site": "Branch",
+   "building": "Office A",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "11111111-2222-3333-4444-555555555555 10.20.0.5:49419 healthy reachable",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 7,
+   "name": "a-air-2",
+   "model": "Mac14,2",
+   "version": "26.0",
+   "build": "25A353",
+   "board": "J413AP",
+   "site": "Branch",
+   "building": "Office A",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "11111111-2222-3333-4444-555555555555 10.20.0.5:49419 healthy reachable",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 8,
+   "name": "b-air-1",
+   "model": "Mac14,2",
+   "version": "15.6",
+   "build": "24G84",
+   "board": "J413AP",
+   "site": "Branch",
+   "building": "Office B",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "None found",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 101,
+   "name": "x-ipad-1",
+   "model": "iPad13,16",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "HQ",
+   "building": "Office X",
+   "ip": "203.0.113.10",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 102,
+   "name": "x-appletv-1",
+   "model": "AppleTV14,1",
+   "version": "26.0",
+   "build": "23J345",
+   "site": "HQ",
+   "building": "Office X",
+   "ip": "203.0.113.10",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 103,
+   "name": "a-iphone-1",
+   "model": "iPhone16,1",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "Branch",
+   "building": "Office A",
+   "ip": "198.51.100.7",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 9,
+   "name": "x-air-travelling",
+   "model": "Mac14,2",
+   "version": "26.0",
+   "build": "25A353",
+   "board": "J413AP",
+   "site": "HQ",
+   "building": "Office X",
+   "ip": "",
+   "cache_guid": "",
+   "cache_status": "Not a content cache",
+   "caches_found": "AAAA1111-2222-3333-4444-0FF1CE000001 10.10.0.5:49419 last-seen 2026-09-09",
+   "assets_ea": "",
+   "ready_ea_id": null
+  },
+  {
+   "id": 104,
+   "name": "x-iphone-travelling",
+   "model": "iPhone16,1",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "HQ",
+   "building": "",
+   "ip": "198.18.0.5",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null,
+   "served_ea": "officeX-cache guid AAAA1111-2222-3333-4444-0FF1CE000001 seen 2026-09-09"
+  },
+  {
+   "id": 105,
+   "name": "a-iphone-longgone",
+   "model": "iPhone16,1",
+   "version": "26.0",
+   "build": "23A341",
+   "site": "Branch",
+   "building": "",
+   "ip": "198.18.0.6",
+   "cache_guid": "",
+   "cache_status": "",
+   "caches_found": "",
+   "assets_ea": "",
+   "ready_ea_id": null,
+   "served_ea": "officeA-cache guid 11111111-2222-3333-4444-555555555555 seen 2026-06-11"
+  }
+ ],
+ "apple_answers": {
+  "ios|D83AP|iPhone16,1|26.0|23A341": [
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0b564256-ca39-4632-8763-cc38d1b9a322/com_apple_MobileAsset_SoftwareUpdate/12fc28f9b124762775d7efc7640f427e308bf24d1a9eaa1950c63df54aa2061b.aea",
+    "prereq": "",
+    "size": 8992587776
+   },
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6c80141b-8935-4182-a330-c4c769177c86/com_apple_MobileAsset_SoftwareUpdate/860968f7160d7a67931e8266baec472c9d2baa9393dd916d61402ca771f8e71c.aea",
+    "prereq": "23A341",
+    "size": 5972688896
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/4c704cd1-db5b-4bcd-bc27-2e91b376b786/com_apple_MobileAsset_SoftwareUpdate/1d8664c042eda3aebcced9d7312c9d8aa644a38ec4e3ca7d13de314d7faa8d9e.aea",
+    "prereq": "23A341",
+    "size": 4362076160
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c8864644-c053-4f22-b247-7f47b69e0770/com_apple_MobileAsset_SoftwareUpdate/f0c96382305d1f534b840cd9165f7ff329f5d58c38b640dfbeda2a93649d0379.aea",
+    "prereq": "",
+    "size": 8724152320
+   }
+  ],
+  "ipados|J407AP|iPad13,16|26.0|23A341": [
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6d1a429-45e8-4652-a07f-31ea7e4f4edb/com_apple_MobileAsset_SoftwareUpdate/1cb69da96a4545098cbde383410345092e0d9bd9.zip",
+    "prereq": "",
+    "size": 8345528509
+   },
+   {
+    "version": "27.0.1",
+    "build": "24A446",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6399312e-3770-4c06-ae01-c3836b6cb7da/com_apple_MobileAsset_SoftwareUpdate/060db0349a690dcd54ce31273ebcbda6462d221a.zip",
+    "prereq": "23A341",
+    "size": 5699492509
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/70b5af77-06c5-444e-9d5a-a8e456b6ac89/com_apple_MobileAsset_SoftwareUpdate/d55646ffb43553e423f64e6806342d1dd440ebff.zip",
+    "prereq": "",
+    "size": 7964352371
+   },
+   {
+    "version": "26.7.1",
+    "build": "23H30",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e0d62fe5-d1e1-462a-9b8c-374f165dafa7/com_apple_MobileAsset_SoftwareUpdate/060f7f8ddb9a6e17a00f177abb5015a157c3e619.zip",
+    "prereq": "23A341",
+    "size": 4258597123
+   }
+  ],
+  "mac|J274AP|Macmini9,1|27.0.1|26A434": [
+   {
+    "version": "13.7.8",
+    "build": "22H730",
+    "url": "https://updates.cdn-apple.com/2025SummerFCS/patches/093-21919/26CB8378-0A7E-4002-A29A-783807562955/com_apple_MobileAsset_MacSoftwareUpdate/97a386b5182904411d3cf455febfcf86757eb2cd.zip",
+    "prereq": "",
+    "size": 12185064350
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   },
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "14.8.9",
+    "build": "23J631",
+    "url": "https://updates.cdn-apple.com/2026SpringFCS/patches/140-88610/0C176173-8545-411A-A339-D34839E9433B/com_apple_MobileAsset_MacSoftwareUpdate/7742064d78e178b2ed119862104e6620dad4caa5.zip",
+    "prereq": "",
+    "size": 13634151792
+   },
+   {
+    "version": "12.7.6",
+    "build": "21H1320",
+    "url": "https://updates.cdn-apple.com/2024SpringFCS/patches/062-40399/DE1EC861-93E8-4EC5-8C9D-66ABF9E03140/com_apple_MobileAsset_MacSoftwareUpdate/74d53fc10d4f444b01cb19944407a34a8edccebf.zip",
+    "prereq": "",
+    "size": 11495541757
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "11.7.11",
+    "build": "20G1443",
+    "url": "https://updates.cdn-apple.com/2023SpringFCS/patches/047-32255/8C537538-2276-4D30-AEA3-8934521EA560/com_apple_MobileAsset_MacSoftwareUpdate/e7e703b5528a1d73fbcdb37c487160f9e4af5948.zip",
+    "prereq": "",
+    "size": 11492857293
+   }
+  ],
+  "mac|J413AP|Mac14,2|26.0|25A353": [
+   {
+    "version": "13.7.8",
+    "build": "22H730",
+    "url": "https://updates.cdn-apple.com/2025SummerFCS/patches/093-21919/26CB8378-0A7E-4002-A29A-783807562955/com_apple_MobileAsset_MacSoftwareUpdate/97a386b5182904411d3cf455febfcf86757eb2cd.zip",
+    "prereq": "",
+    "size": 12185064350
+   },
+   {
+    "version": "14.8.9",
+    "build": "23J631",
+    "url": "https://updates.cdn-apple.com/2026SpringFCS/patches/140-88610/0C176173-8545-411A-A339-D34839E9433B/com_apple_MobileAsset_MacSoftwareUpdate/7742064d78e178b2ed119862104e6620dad4caa5.zip",
+    "prereq": "",
+    "size": 13634151792
+   },
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "12.7.6",
+    "build": "21H1320",
+    "url": "https://updates.cdn-apple.com/2024SpringFCS/patches/062-40399/DE1EC861-93E8-4EC5-8C9D-66ABF9E03140/com_apple_MobileAsset_MacSoftwareUpdate/74d53fc10d4f444b01cb19944407a34a8edccebf.zip",
+    "prereq": "",
+    "size": 11495541757
+   }
+  ],
+  "mac|J614sAP|Mac16,8|27.0.1|26A434": [
+   {
+    "version": "26.7.1",
+    "build": "25G241",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8ec11cd7-dce3-46fa-9b24-28f72dd1f7ec/com_apple_MobileAsset_MacSoftwareUpdate/af34f3ce7e69c63e0635ee357f5405cefd45834a.zip",
+    "prereq": "",
+    "size": 18352010723
+   },
+   {
+    "version": "15.8.1",
+    "build": "24H32",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/ad22d07e-0d68-4679-9375-99a5c4fc95ae/com_apple_MobileAsset_MacSoftwareUpdate/a30f5f5e5659a0760382124bee535d7ac33cb51f.zip",
+    "prereq": "",
+    "size": 15640056810
+   },
+   {
+    "version": "27.0.1",
+    "build": "26A5434",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/8eeb9130-a13c-4b78-996e-23ecf3c58476/com_apple_MobileAsset_MacSoftwareUpdate/da5d4070865b20aa138e6fef954889710e559a06.zip",
+    "prereq": "",
+    "size": 18359340881
+   }
+  ],
+  "tvos|J255AP|AppleTV14,1|26.0|23J345": [
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0c859739-d90e-427e-a8ea-8c3733a0461b/com_apple_MobileAsset_SoftwareUpdate/35400de192388eac95c568781814f83e8249a82aeec264a926d95a89c1711344.aea",
+    "prereq": "23J362",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/f144ac26-a720-44a7-8114-8a0607a4f672/com_apple_MobileAsset_SoftwareUpdate/2104dbeeffe1e2f7ac38c883f0c82c8fc7deccc80823014c3f34923f9cc68b51.aea",
+    "prereq": "20L497",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/499a07e9-49a0-4693-ae59-dcb69016c802/com_apple_MobileAsset_SoftwareUpdate/a242763b8c7532ab1ece1e97deac2fe223ee5ff7cfa71ef1001ce6932496b670.aea",
+    "prereq": "21L569",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/82022510-ece2-4d42-ab31-497df2008016/com_apple_MobileAsset_SoftwareUpdate/fa811277ad21f7530c59020911ca4b05167070201552ac40f17ff573d400801b.aea",
+    "prereq": "20K672",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6da069ed-49df-47b6-b45f-da16939d2273/com_apple_MobileAsset_SoftwareUpdate/e0490b4385345f8e1375a7c5e3971fabf0e34b06246fc3f968d6d5e81c0c13e7.aea",
+    "prereq": "20K661",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/1fb5b4a5-721a-4589-9508-9a9401457148/com_apple_MobileAsset_SoftwareUpdate/64dcf83ca9c4c38182b71fab9f01ea459ff0a5079fc42aedac96b3c022563373.aea",
+    "prereq": "21M71",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/d5957056-e572-40c7-91f4-fe918760f952/com_apple_MobileAsset_SoftwareUpdate/9d0763adf98269b83609c5c46538d00c1d780ca61fae069822896d56a171e167.aea",
+    "prereq": "20J8378",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/35b3b52f-d9e6-490e-8997-76105740800d/com_apple_MobileAsset_SoftwareUpdate/0b2494bdc182b91be9cba63dd3a4468e43ecbcf720cd9c2f609ddade4bd20c92.aea",
+    "prereq": "21K69",
+    "size": 3154116608
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/41b8913a-41a4-48c8-b3a1-6e6f8c30a80c/com_apple_MobileAsset_SoftwareUpdate/e8684c07ef78e2ec067586cefbd5193837426c9331269286290a2544b826e425.aea",
+    "prereq": "22L261",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a59232d6-af15-432d-b36e-228f5c190ae0/com_apple_MobileAsset_SoftwareUpdate/d417441e26b80b4ab06529e948db0b9b1aae2a05f723127d5f41a40c7cfe88eb.aea",
+    "prereq": "23J582",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/aa3c63ef-b4e6-4b8a-ae84-0daf15cf1ba4/com_apple_MobileAsset_SoftwareUpdate/06f9703cf00f172bfbc0226b3ca6211c8c429643206564ea3f5436b0ba3cdb32.aea",
+    "prereq": "22K561",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/74d52f4f-b217-406b-b646-97c6eab068e5/com_apple_MobileAsset_SoftwareUpdate/8072b444430e65ad7d5a5394238d76fda294ea44a9af2eae503f6545421652a9.aea",
+    "prereq": "22K557",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/246b63f8-b70d-4fcf-8adf-65b274f71c42/com_apple_MobileAsset_SoftwareUpdate/a6820d2d0d442d18aeabd3a8d935d13de402a7eac4b9eb2aa02ad03505fc081a.aea",
+    "prereq": "23J353",
+    "size": 2147483648
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/6d98cda1-5422-466c-925e-0b2e2a83191f/com_apple_MobileAsset_SoftwareUpdate/3eb83a7e19512c33ce064656c0373edf70cc6e85a009ddacb2cb5470040bff9f.aea",
+    "prereq": "21K646",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/33135f98-36f9-4a54-b9b6-49a31ffa9a81/com_apple_MobileAsset_SoftwareUpdate/3459df78cac44630a9a34d3836a864a364317f2b98775cbed3606a8876392b08.aea",
+    "prereq": "23L773",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/708a7b9a-5a24-474d-908c-dcc192535abb/com_apple_MobileAsset_SoftwareUpdate/5fe152218b8bc239014b536946b03cc272b228c2e2d6393c4ae46b91322795c3.aea",
+    "prereq": "21K364",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/08f782b4-b150-4598-b2d4-3b9661bcc46b/com_apple_MobileAsset_SoftwareUpdate/284576c8c95b28f2332091892e9ceada2d14b0efb88eaa3a851f13135b41bf52.aea",
+    "prereq": "20L498",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/27b22cbc-495f-427b-a997-85fd6e096435/com_apple_MobileAsset_SoftwareUpdate/dce5c2222c4b12dbafe8aae9f984e55c617fb789215f0f6e76f3e1bcab7339d1.aea",
+    "prereq": "22L255",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/21a88284-433a-4986-9592-3c0b7eccddb9/com_apple_MobileAsset_SoftwareUpdate/f6647c3f4a33a0814d4de8d1f343dc148ce5b973114e1da571c4dfb91cbe65cb.aea",
+    "prereq": "22K160",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/7d9186c9-76df-44f9-b9de-a817ade6efdb/com_apple_MobileAsset_SoftwareUpdate/c60653d1d17664ab9057de6b9b181eff52922ab2488267e96a857cade86c3b7f.aea",
+    "prereq": "23L243",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/de096ad6-d2ef-4c0d-8e61-77568e3124e3/com_apple_MobileAsset_SoftwareUpdate/9975b082de4a6ce32a0b77c4b6f507e397a206ad4780fac932c41a531585da06.aea",
+    "prereq": "21J354",
+    "size": 3154116608
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/5f82f493-2f16-415c-baca-94639f59cdf5/com_apple_MobileAsset_SoftwareUpdate/557f57477a15d13609f30539847f55a88e474bb141fb737d10924482bb26e047.aea",
+    "prereq": "22M84",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/3f7570b0-b247-4f68-a7f6-6b26d348f6f3/com_apple_MobileAsset_SoftwareUpdate/80511384cf6a9a33ac47403ed6917b0f8fdf82b5b59e46abe7f430322e24f5d5.aea",
+    "prereq": "20M73",
+    "size": 3355443200
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0f7e610e-c7da-4bbf-9459-032f72863a7f/com_apple_MobileAsset_SoftwareUpdate/c12def7918f42b5da79ffadab519aa43fba79b568907bf6a9fd3f0fdfe4f3e0e.aea",
+    "prereq": "21K365",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0f35bc0e-06e1-4cd5-a27c-6f22d2f1c563/com_apple_MobileAsset_SoftwareUpdate/0019cfb77d90f14ea82ce16ede9df20458e2145e1e65b5e51c68d62446ba3890.aea",
+    "prereq": "23K54",
+    "size": 2113929216
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/232b012b-e417-4473-8285-7023d623ec01/com_apple_MobileAsset_SoftwareUpdate/3220637ef5119415005b5c81734dc62d166e83e75cefe69af04cf11bf896c8f1.aea",
+    "prereq": "22L572",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/319b56a0-027e-4b7d-b26a-5f7acc76cd7b/com_apple_MobileAsset_SoftwareUpdate/78d411ce71ac8fe5daa1134bf23e3414756ceeb5203684016c47f034d2949137.aea",
+    "prereq": "22J580",
+    "size": 2751463424
+   },
+   {
+    "version": "27.0",
+    "build": "24J6361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/fbf3c544-b770-4756-9cca-abfb2d3cb65e/com_apple_MobileAsset_SoftwareUpdate/9bf3ad6ac49c25016599bbb77d8ea1c612cb745eb7ee9e502af1926c860b7e18.aea",
+    "prereq": "",
+    "size": 4831838208
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a5557d58-82d2-420b-9dc9-fb49c346505b/com_apple_MobileAsset_SoftwareUpdate/a0dc959bf2a11d3631258340c5340b0d0d0caa0af2a853d8b8267c330da9e8e2.aea",
+    "prereq": "20K680",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/4f14641c-4eeb-49c1-85c9-fa76b486931e/com_apple_MobileAsset_SoftwareUpdate/acc82afb77e866044cf29e570bf36630327a419f4a420d43fd93fe04f91373f1.aea",
+    "prereq": "21L227",
+    "size": 3087007744
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/f494b608-0019-4241-8166-02dfd14e8ef0/com_apple_MobileAsset_SoftwareUpdate/0ab31a3ab0112f7d01603110326d4115bcbe6124198ad2f7f40c0395b1d4311d.aea",
+    "prereq": "21L580",
+    "size": 3019898880
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e4ab7d69-4e29-4cd9-8dcd-18613273e8a1/com_apple_MobileAsset_SoftwareUpdate/bdebbe8bb2c665ff36fee3ddb59865d70c818821c4b1eef281cf62f99fecbb26.aea",
+    "prereq": "24J360",
+    "size": 209715200
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/1be3b503-e746-4c50-a1bc-2c4d1e3a9145/com_apple_MobileAsset_SoftwareUpdate/56fa657afbf3f797b11a21f62dc6a7ff8eb300d52c2b1fba90f27f780de14ecd.aea",
+    "prereq": "20K71",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a7dd39f5-3e41-4f2e-9fdf-2cae62ce8e9f/com_apple_MobileAsset_SoftwareUpdate/4c27a46082f879b0e8fce2f319a773eda7374a40e09ce2d6c87f0e71fb2a0df5.aea",
+    "prereq": "23L471",
+    "size": 2046820352
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/922035bd-c98e-455f-af5c-365e27cb2225/com_apple_MobileAsset_SoftwareUpdate/7a37675b00bdb775cad7ad090eac7cc299c2583c52108bdb445a01247c92c799.aea",
+    "prereq": "20L563",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/0c0f3805-1f24-4b27-b640-e95043c3f1f8/com_apple_MobileAsset_SoftwareUpdate/686e01e1dc4687ff15daf4e093ba1562275a45fe509e12463d080e41391d9de8.aea",
+    "prereq": "23K620",
+    "size": 2113929216
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6043924-1a0f-46e1-b169-4daf9766494e/com_apple_MobileAsset_SoftwareUpdate/9c58752514b8b66498ece0bab4112f80d6086b8c677a23ed0b74290964785e99.aea",
+    "prereq": "22K155",
+    "size": 2483027968
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/a6160594-3bee-4845-8594-fd1e63149a89/com_apple_MobileAsset_SoftwareUpdate/cc09e958bd4431fe6c7779813bd7c1a6be5504f242314e8959c5fd2dbe95480f.aea",
+    "prereq": "20K362",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/7ecad802-54b5-45c2-b376-c86dc32b5cd9/com_apple_MobileAsset_SoftwareUpdate/e6978eff3fabeeaf3d5d4f19a5e7c06defdf1b633371308b4356a84376dce0e8.aea",
+    "prereq": "22J357",
+    "size": 2751463424
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/c6ccc85d-88a5-4929-9936-2353858fc6cf/com_apple_MobileAsset_SoftwareUpdate/36fe9b5caa24447c5503690c1954c030f42d94ad94072bf839ca4744fcff06d7.aea",
+    "prereq": "20K650",
+    "size": 3422552064
+   },
+   {
+    "version": "27.0",
+    "build": "24J361",
+    "url": "https://updates.cdn-apple.com/2026FallFCS/e2acf11d-15aa-4cc5-bdfb-2c0b395cee63/com_apple_MobileAsset_SoftwareUpdate/b433c9bc30a35fdb6b3649d3e54bbd4530dbc1034778886e858d26fbebdd64d3.aea",
+    "prereq": "21M80",
+    "size": 3019898880
+   }
+  ]
+ }
+}
\ No newline at end of file
diff --git a/sales/preheat/admin/sync-eas.py b/sales/preheat/admin/sync-eas.py
new file mode 100644
index 0000000..38d7f11
--- /dev/null
+++ b/sales/preheat/admin/sync-eas.py
@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+"""
+Push the EA scripts in ea/ into their Jamf Pro computer extension attribute definitions.
+Jamf runs the script text stored in the EA, so after editing a file here, run this.
+Needs the API client privilege "Update Computer Extension Attributes" (and "Create ..." to add missing ones).
+Credentials: login keychain (readiness-check.py --store-credentials) or env JAMF_URL, JAMF_CLIENT_ID, JAMF_CLIENT_SECRET.   Usage: python3 admin/sync-eas.py [--create]
+"""
+import os, sys, json, urllib.error, argparse
+sys.path.insert(0, os.path.dirname(__file__)); rc = __import__("readiness-check")
+FILES = {  # EA name in Jamf -> script file
+    rc.EA_STATUS: "ea-content-cache-status.sh",
+    rc.EA_FOUND:  "ea-content-cache-servers-found.sh", rc.EA_ASSETS: "ea-content-cache-macos-assets.sh",
+    rc.EA_DECODED: "ea-content-cache-decoded.sh", rc.EA_EFFECT: "ea-content-cache-effectiveness.sh"}
+def main():
+    ap = argparse.ArgumentParser(description=__doc__); ap.add_argument("--create", action="store_true", help="create EAs that do not exist yet")
+    args = ap.parse_args()
+    j = rc.jamf_from_credentials()
+    existing = {e["name"]: e for e in j.call("/api/v1/computer-extension-attributes?page=0&page-size=500").get("results", [])}
+    eadir = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "ea")
+    for name, fn in FILES.items():
+        local = open(os.path.join(eadir, fn)).read()
+        hit = existing.get(name)
+        if hit:
+            if (hit.get("scriptContents") or "").replace("\r\n", "\n").strip() == local.strip():
+                print(f"{hit['name']}: up to date"); continue
+            body = {k: hit[k] for k in ("name", "description", "dataType", "enabled", "inventoryDisplayType", "inputType") if k in hit}
+            body["scriptContents"] = local; body["inputType"] = "SCRIPT"     # also converts a text-field EA to a script EA
+            try: j.call(f"/api/v1/computer-extension-attributes/{hit['id']}", "PUT", body); print(f"{hit['name']}: updated from {fn}")
+            except urllib.error.HTTPError as e: print(f"{hit['name']}: refused HTTP {e.code} (needs Update Computer Extension Attributes); paste ea/{fn} by hand")
+        elif args.create:
+            body = {"name": name, "description": f"See README, {fn}", "dataType": "STRING", "enabled": True,
+                    "inventoryDisplayType": "EXTENSION_ATTRIBUTES", "inputType": "SCRIPT", "scriptContents": local}
+            try: j.call("/api/v1/computer-extension-attributes", "POST", body); print(f"{name}: created")
+            except urllib.error.HTTPError as e: print(f"{name}: create refused HTTP {e.code}")
+        else: print(f"{name}: not in Jamf (use --create)")
+if __name__ == "__main__": main()
diff --git a/sales/preheat/admin/troubleshoot-client.sh b/sales/preheat/admin/troubleshoot-client.sh
new file mode 100755
index 0000000..c008989
--- /dev/null
+++ b/sales/preheat/admin/troubleshoot-client.sh
@@ -0,0 +1,50 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# troubleshoot-client.sh: why does this Mac not see the content cache? Read-only; no root needed.
+#
+#   bash admin/troubleshoot-client.sh [server LAN address] [port]
+#
+# Prints this Mac's public address, what Apple's locator returns for it, whether the
+# server's port answers (when the address and port are given), and any tunnel that could
+# change the route. Pair it with troubleshoot-server.sh on the caching Mac.
+#
+# Read the public address first: if it differs from the server's, nothing else matters until
+# the two leave for the internet from the same place. "Found 0 content caches" with a matching
+# address means Apple has no registration for it (check the server). "Found 1" with the port
+# BLOCKED means a firewall, an ACL between VLANs or client isolation on the Wi-Fi network.
+# A client remembers a located result for about an hour; this script always asks afresh.
+set -u
+case "${1:-}" in -h|--help) /usr/bin/sed -n '2,/^set -u/p' "$0" | /usr/bin/sed -e '/^set -u/d' -e 's/^# \{0,1\}//'; exit 0;; esac
+
+SERVER="${1:-}"; PORT="${2:-}"
+
+echo "== Public address (must match the server's)"
+/usr/bin/curl -s --max-time 5 https://api.ipify.org; echo
+
+echo "== What Apple's locator returns for this Mac (fresh answer, shared caching)"
+/usr/bin/AssetCacheLocatorUtil 2>&1 | awk '
+  /public IP address is/ {print; next}
+  /^--- Information for/ {print; next}
+  /Finding refreshed content caches supporting shared caching/ {want=1; next}
+  want && /Found [0-9]+ content cache/ {print "  " $0; want=0; grab=1; next}
+  grab && /rank/ {print "  " $0; next}
+  {grab=0}'
+
+echo "== Can this Mac reach the server's port?"
+if [[ -n "$SERVER" && -n "$PORT" ]]; then
+  if /usr/bin/nc -z -w 3 "$SERVER" "$PORT" 2>/dev/null; then
+    echo "port $PORT on $SERVER: open"
+  else
+    echo "port $PORT on $SERVER: BLOCKED or wrong"
+  fi
+  /usr/bin/curl -s -o /dev/null -w "HTTP %{http_code} from http://$SERVER:$PORT/ (any code means the cache answered; 400 is normal here)\n" --max-time 5 "http://$SERVER:$PORT/"
+else
+  echo "(pass the server's address and port to test reachability)"
+fi
+
+echo "== Tunnels, VPN and filters on this Mac"
+/usr/bin/scutil --nc list 2>/dev/null | grep -i "connected" || echo "no VPN configuration is connected"
+/sbin/ifconfig | awk '/^(utun|ipsec|ppp)/ {ifc=$1} /inet / && ifc {print "  " ifc " has an address: " $2; ifc=""}'
+echo "(a connected VPN or a ZTNA agent can change the public address or the route to the server)"
diff --git a/sales/preheat/admin/troubleshoot-server.sh b/sales/preheat/admin/troubleshoot-server.sh
new file mode 100755
index 0000000..3f3dd29
--- /dev/null
+++ b/sales/preheat/admin/troubleshoot-server.sh
@@ -0,0 +1,46 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# troubleshoot-server.sh: is this content cache registered, scoped and reachable? Read-only.
+#
+#   sudo bash admin/troubleshoot-server.sh
+#
+# Prints the server's public address, the status fields that decide whether clients can find
+# it, the settings that decide which clients it serves, whether it is listening, and the
+# last two hours of registration, refusal and request lines from its log. Pair it with
+# troubleshoot-client.sh on a Mac that does not see the cache.
+#
+# What to look for:
+#   Activated or Active false     the service is off (System Settings, General, Sharing, Content Caching)
+#   RegistrationStatus 0          cannot reach Apple's registration service: needs outbound HTTPS to
+#                                 Apple (17.0.0.0/8) with no proxy or TLS inspection in the path
+#   LocalSubnetsOnly true         the default; only the server's own subnet is served. Set Clients to
+#                                 "all networks" or add ranges when clients sit on other VLANs or Wi-Fi
+#   Port                          random by default; fix it if a firewall or ACL is in the way
+#   PublicAddress                 must equal the clients' public address
+#   no "Received GET" lines       no client has asked: they never found it, or the port is blocked
+set -u
+case "${1:-}" in -h|--help) /usr/bin/sed -n '2,/^set -u/p' "$0" | /usr/bin/sed -e '/^set -u/d' -e 's/^# \{0,1\}//'; exit 0;; esac
+if [[ $EUID -ne 0 ]]; then echo "Run with sudo for the log section: sudo bash $0"; echo; fi
+
+echo "== Public address (must match the clients')"
+/usr/bin/curl -s --max-time 5 https://api.ipify.org; echo
+
+echo "== Status (want Activated: true, Active: true, RegistrationStatus: 1, CacheStatus: OK)"
+/usr/bin/AssetCacheManagerUtil status 2>&1 | grep -E "Activated|Active:|RegistrationStatus|RegistrationError|CacheStatus|Port|PublicAddress|PrivateAddresses|StartupStatus|TotalBytes"
+
+echo "== Settings that decide which clients it serves"
+/usr/bin/AssetCacheManagerUtil settings 2>&1 | grep -E "LocalSubnetsOnly|ListenRanges|ListenRangesOnly|ListenWithPeersAndParents|Port|DataPath|PeerLocalSubnetsOnly|AllowPersonalCaching|AllowSharedCaching"
+
+echo "== Listening?"
+PORT=$(/usr/bin/AssetCacheManagerUtil status 2>&1 | awk -F': ' '/^ *Port:/{print $2}')
+if [[ -n "$PORT" && "$PORT" != "0" ]]; then
+  /usr/sbin/lsof -nP -iTCP:"$PORT" -sTCP:LISTEN 2>/dev/null | head -3 | grep . || echo "nothing is listening on port $PORT"
+else
+  echo "(no port: the service is not active)"
+fi
+
+echo "== Last 2 hours of the cache log: registration, refusals, client requests"
+/usr/bin/log show --last 2h --info --predicate 'subsystem == "com.apple.AssetCache"' 2>/dev/null \
+  | grep -iE "regist|refus|deny|denied|public|Received GET|error" | tail -40
diff --git a/sales/preheat/docs/BLUEPRINTS.md b/sales/preheat/docs/BLUEPRINTS.md
new file mode 100644
index 0000000..a4ac86c
--- /dev/null
+++ b/sales/preheat/docs/BLUEPRINTS.md
@@ -0,0 +1,217 @@
+# Preheat: Blueprints
+
+[Preheat](../README.md) > Blueprints
+
+Declarative software updates in two waves, the update settings, and configuring the cache servers themselves.
+
+## Using this with DDM software updates (Blueprints)
+Apple's declarative update model does the "preheating" for you, if you scope it in two waves.
+
+- When a Mac receives an enforced software update declaration it downloads and prepares the
+  update in the background right away, well before the enforcement date. That download goes
+  through the content cache like any other. So the FIRST Mac of each hardware family on a
+  network to receive the declaration is the one that warms the cache.
+- Deferrals (Software Update Settings declaration) only hide updates from users in System
+  Settings for N days after release. Apple states enforced updates apply "regardless of
+  configured deferrals", so a deferral does not delay the background download either.
+  Deferrals stop users from pulling updates early on their own; they are not the lever for
+  cache readiness.
+- Recommended sequence per release:
+  1. Wave 1 ("preheat"): a Blueprint with the update declaration scoped to a pilot Smart
+     Group of one Mac per hardware family per cache server, enforcement date = the same date
+     as everyone else or earlier. Their downloads populate each office's cache.
+  2. Run `readiness-check.py --target <version>` (or `--target-build <build>` if the
+     declaration pins a build). Wait for every server to show READY.
+  3. Wave 2: the broad Blueprint. Every Mac's background download is then served locally.
+  Content caching also coalesces simultaneous requests for the same asset, so a wave of Macs
+  starting together does not each pull from Apple; the first fetch feeds the rest.
+- Set the enforcement deadline further out than the deferral period, so users are not
+  surprised by a forced install they never saw offered.
+- A pilot group can be built per hardware family with Jamf's own criterion:
+  Smart Group "one per family" = Model Identifier is <identifier>, plus a serial or name filter.
+
+![The Blueprints for a two-wave rollout with a hold group](images/blueprints-deployed.png)
+
+*The whole arrangement in Blueprints: an enforcement Blueprint for each wave and one for the hold group, and a settings Blueprint for the waves and one for the hold group.*
+
+### Two cohorts: one group holds on the previous OS, the rest move on
+Apple offers the last release of the previous OS alongside the new one, and most fleets use
+that: a group waiting on an app vendor, a change freeze, a validated environment, hardware the
+new OS dropped. In DDM terms that is two software update declarations (two Blueprints), each
+scoped to its own Smart Group, one pinned to the old branch. Readiness then has to be judged
+per group, because the two groups will ask the cache for different files:
+
+    python3 admin/readiness-check.py --platforms all --cohort "Hold on 26=26" --write
+    python3 admin/readiness-check.py --platforms all --cohort "Hold on 26=26.7" --cohort "Pilot ring=27.0" --preheat-plan plan.json
+
+`GROUP=26` means the newest 26.x Apple offers each device; `GROUP=26.7` means exactly that
+version; `GROUP=same` means the newest release within whatever major version each device runs
+now. In Blueprints the Software Updates component's "Latest OS version" setting has an "Ignore
+major versions" box: a Blueprint with it ticked is a `same` cohort, one without it follows the
+default. Groups can be computer or mobile, Smart or Static; the first match wins and everyone
+else follows `--target` (or the newest OS). The same Mac model in the same office then shows
+as two lines, one per target, and the cache is READY only when it holds both files, so plan
+the space for both. For iPhone, iPad and Vision Pro the previous branch is published on a
+separate Apple channel; the scripts ask both, so a device holding on 26 is offered 26.7 even
+after 27 ships. The API client needs to read the groups (Read Smart/Static Computer Groups,
+Read Smart/Static Mobile Device Groups).
+
+**Enforce the hold group too, and hide the new major from it.** Holding on a major version is
+not the same as not patching: the hold group still needs 26.7.1 and its successors, so its
+Blueprint keeps an enforcement deadline ("Latest OS version", "Ignore major versions" ticked,
+a few days). Enforcement is also what makes the download predictable enough to check readiness
+against. But an enforcement declaration only sets a floor. It does not stop a user choosing the
+new major in Settings. That takes the settings declaration below: on a Mac a major deferral
+(`MajorPeriodInDays`, 90 days at most, so a longer hold has to accept that the new major becomes
+visible), and on iPhone and iPad, which have no separate major deferral, `RecommendedCadence`
+set to `Oldest` so that only the lower-numbered update is shown when Apple offers two.
+
+### The other half: Software Update Settings
+The enforcement Blueprints say what must be installed by when. A separate Blueprint carrying
+Apple's `com.apple.configuration.softwareupdate.settings` declaration says how Software Update
+behaves in the meantime. Keep it separate from the enforcement Blueprints. One settings Blueprint
+can serve every group that wants the same behaviour (both waves); a hold group needs its own,
+because its values differ, and a device should receive only one.
+
+| Key (Apple's name) | Everyone | Hold group | Why |
+|---|---|---|---|
+| `AllowStandardUserOSUpdates` (macOS) | true | true | standard users can install major and minor updates; without it only administrators can |
+| `AutomaticActions` > `Download` | AlwaysOn | AlwaysOn | devices fetch in the background as soon as an update is offered, which is what sends them to the cache early and predictably |
+| `AutomaticActions` > `InstallSecurityUpdate` | AlwaysOn | AlwaysOn | security responses and system files install themselves |
+| `AutomaticActions` > `InstallOSUpdates` | Allowed | Allowed | the enforcement deadline does the forcing; this leaves the user free to go sooner |
+| `Notifications` | true | true | users see every enforcement reminder, not only the last hour |
+| `RapidSecurityResponse` > `Enable`, `EnableRollback` | true, true | true, true | Background Security Improvements stay available |
+| `Beta` > `ProgramEnrollment` | AlwaysOff | AlwaysOff | no betas on managed devices (a test ring would differ) |
+| `Deferrals` > `MajorPeriodInDays` (macOS) | not set | up to 90 | hides the new major from the hold group |
+| `Deferrals` > `MinorPeriodInDays` (macOS), `CombinedPeriodInDays` (iPhone, iPad, Apple TV, Vision Pro) | not set, or 1 to 3 days | same | optional: a short delay before users are offered a release is a window in which to preheat; enforced updates apply regardless of deferrals |
+| `RecommendedCadence` (iPhone, iPad, Vision Pro) | All | Oldest | when Apple offers two versions, the hold group sees only the lower one |
+
+Key names and allowed values are from Apple's device management documentation (checked
+2026-09-20). Deferrals, automatic actions and security-response settings need supervised devices.
+In Jamf Pro 11.32 the Blueprints "Software Update Settings" component exposes every key above, each
+shown with Apple's key name under its title, so no configuration profile is needed. Three things
+to know in that screen: only the settings whose box you tick are sent; AlwaysOn and AlwaysOff
+appear as "Always" and "Never"; and the two Background Security Improvements settings come
+preselected on "Restrict", so after ticking them switch both to "Allow" unless you mean to block
+them. Automatic downloads and automatic security installs are not offered for Apple TV.
+
+**Scope the Blueprints to devices that can take them.** Found by scoping them to everything in a
+lab: the enforcement declaration needs iOS/iPadOS 17 or macOS 14 (an iPad on 16 reports every one
+as "InvalidPayload"); the settings declaration needs iOS/iPadOS 18 or macOS 15 (an iPad on 17
+reports "Unknown Declaration Type"); and a settings declaration that contains deferrals, automatic
+actions or security-response keys is rejected whole by an unsupervised device ("cannot be enforced
+on unsupervised devices"), which in practice means user-enrolled and personal devices. A Blueprint's
+scope is a list of groups with no exclusions, so build the rule into the groups it is scoped to:
+OS Version greater than or equal to 17 in the groups for the enforcement Blueprints, and a separate
+group with OS Version greater than or equal to 18 and Supervised is Yes for the settings Blueprint.
+Devices left out are still counted by the readiness check and still preheated for, because that
+works from inventory, not from Blueprint scope; they simply update on their own schedule. The rest of what a "Latest OS
+version" Blueprint shows as failures is expected: it sends one activation per OS version Apple
+offers, each with a predicate, and a device reports every one that does not apply to it as
+inactive, with its configuration "ActivationFailed". A healthy Mac shows about forty of those.
+
+![The settings Blueprint before and after its scope was narrowed](images/blueprint-scope-before-after.png)
+
+*The same settings Blueprint, scoped first to every device and then to groups that carry the requirement: three errors, then none.*
+
+### Configuring the cache servers themselves with a Blueprint (macOS 27)
+From macOS 27 a cache server can be configured by declaration, and Jamf's Blueprints have a
+component for it: **Content Cache Settings** (`com.apple.configuration.content-cache.settings`).
+It exposes every setting, each with Apple's key name under its title. Two Blueprints cover most
+organisations.
+
+**A declaration replaces the cache's whole configuration.** Only the settings you tick are sent,
+but every setting you leave out goes back to Apple's default on the Mac, whatever had been set by
+hand. Seen on the lab cache when a Blueprint with three settings arrived: its limit went from
+4 TB to unlimited and iCloud caching, which had been switched off, came back on. So tick every
+setting whose value matters to you, not only the ones you want to change. (The storage path was
+the one hand-set value that stayed; declare it anyway.) When the first declaration arrived, and
+when the limit and the storage path were added, the cache switched off, told Apple it had gone,
+switched on and registered again, within ten seconds; its content was kept and its counters
+started again from zero. A later change of one setting (Log client identity) was applied in
+place: no restart, counters untouched.
+
+**1. The cache servers.** Scope it to a group of the Macs you have chosen as cache servers (a
+Static group, or a Smart Group by name or serial number). Do not scope it to "Content
+Caching - Servers": that group means "caching is on", so a cache that goes off would fall out of
+the very Blueprint that turns it on.
+
+| Setting | Value | Why |
+|---|---|---|
+| Auto activation | True | Turns caching on and stops anyone switching it off |
+| Allow shared caching | True | OS updates, apps, everything Preheat deals with |
+| Allow personal caching | True or False, but tick it | iCloud data. Left out, it is True. One of the two "Allow" settings must be True |
+| Keep awake | True | A sleeping Mac serves nothing |
+| Allow cache delete | False | Otherwise macOS empties the cache when other software wants the space |
+| Cache limit | bytes | Left out, or 0, it is unlimited, which fills the volume to its last 2 GB. Leave about a tenth of the volume free |
+| Declarative status interval | 300 | Without it the size figures in DDM status are not refreshed |
+| Data path | the path in use, if not the startup volume | Must end with `/Library/Application Support/Apple/AssetCache/Data`. A cache given a new path tries to move its content there |
+| Port | a fixed number, if firewalls sit between devices and cache | 0 picks a port at random |
+| Log client identity | True, if the cache's log should say which device asked | Off by default: the log names the file, not the device. On, each request is logged with the address it came from |
+
+**2. Every other Mac.** One setting, **Deny activation: True**, so that no one's laptop becomes a
+cache by accident and starts being offered to the devices around it. A Blueprint's scope has no
+exclusions, so the group has to carry the rule: a Smart Group with the criterion Computer Group,
+"not member of", your cache servers group.
+
+**Scope both by your choice of servers, not by what is running.** It is tempting to scope the
+deny Blueprint to "Macs that are not caching" and the settings to "Macs that are". Both go wrong,
+because the Blueprint changes the thing the group measures:
+
+| Scope by state | What goes wrong |
+|---|---|
+| Deny to "not caching" | A laptop that already has caching on is not in the group and is never denied |
+| Deny to "not caching" | A new server cannot be switched on: it is denied until it caches |
+| Settings to "caching" | A server that goes off leaves the group, and with it the Blueprint that keeps it on |
+
+Keep the state groups for what they are good at, reporting and alerts, and compare the two:
+
+| Group | Rule | Use |
+|---|---|---|
+| Content Caching - Chosen servers | Serial Number is ..., one line per server (or a Static group) | scope of the settings Blueprint |
+| Content Caching - Everything else | Computer Group, not member of, Chosen servers | scope of the deny Blueprint |
+| Content Caching - On but not chosen | status EA like Active or Inactive, and not member of Chosen servers | a cache nobody planned: alert |
+| Content Caching - Chosen but not caching | member of Chosen servers, and status EA is "Not a content cache" | a server that is off: alert |
+
+These four are made by hand, because only you know which Macs you chose; the rules are the whole
+recipe. `create-smart-groups.py` and the Terraform module make the groups that are the same for
+everyone.
+
+(Jamf Pro has built-in groups "All Managed Clients" and "All Managed Servers"; state groups
+named "All Managed Content Caching Servers" and "All Managed Clients - Not Cache Servers" sit
+beside them in every list.)
+
+**For larger networks**, the same component holds the settings that go with [Large sites](REFERENCE.md#large-sites-several-public-addresses-favored-caches-peers):
+
+| Setting | Use |
+|---|---|
+| Public ranges | Every public address the site uses. Goes with the DNS TXT record: the record tells devices, this tells Apple |
+| Local subnets only | True (the default) serves the cache's own subnet. For more subnets set it False and give Listen ranges |
+| Listen ranges, Listen ranges only | Which client addresses the cache serves |
+| Peer local subnets only, Peer filter ranges, Peer listen ranges | Which other caches it shares with. By default, those on its own subnet |
+| Parents, Parent selection policy | Caches this one fetches from before Apple: a branch cache behind a head-office cache |
+| Management status target, reporting interval, security | A URL the cache sends its own statistics to, as often as once a minute. Preheat does not use it yet |
+
+Three traps in that component. **Data path is filled in for you with Apple's default**,
+`/Library/Application Support/Apple/AssetCache/Data`, which is on the startup disk. For a cache
+on an external volume, replace it before you deploy with the full path,
+`/Volumes/<volume name>/Library/Application Support/Apple/AssetCache/Data`. Left as it is, it
+tells the cache to move its content to the startup disk.
+Ticking **Peer listen ranges** or **Peer filter ranges** and adding no item sends an empty list,
+which means "answer no peer" and "ask no peer": peering is off. And **Local subnets only: True**
+makes the cache ignore Listen ranges altogether.
+
+What Preheat reads back is unchanged by how a cache was configured: its state, peers and parents
+through DDM, its content through the EAs.
+
+*Status, 2026-09-27: both Blueprints are deployed in the lab. The deny Blueprint took about ten
+minutes to arrive, after which macOS reported "Content caching can not be activated". The
+settings Blueprint was delivered with three settings (allow cache delete off, keep awake, status
+interval 300): all three took effect, the cache kept its 1,889 GB, and the size figures in DDM
+status, frozen until then, were refreshed. A second delivery added the two "Allow" settings, the
+limit and auto activation, which all took effect, and the storage path. The settings for larger
+networks have not been tried.*
+
+![The Content Cache Settings component in Jamf Blueprints](images/blueprint-content-cache-settings.png)
+
+*Jamf's Blueprint component for a cache server: each setting carries Apple's key name, and only the ones ticked are sent.*
diff --git a/sales/preheat/docs/CAVEATS.md b/sales/preheat/docs/CAVEATS.md
new file mode 100644
index 0000000..16b3beb
--- /dev/null
+++ b/sales/preheat/docs/CAVEATS.md
@@ -0,0 +1,124 @@
+# Preheat: Caveats
+
+[Preheat](../README.md) > Caveats
+
+What can go wrong, each one seen in the lab.
+
+## Caveats
+- **Two outside services.** Answers come from Apple's software lookup service (gdmf.apple.com),
+  which is public but undocumented, and the model list, board IDs and build numbers come from
+  [AppleDB](https://appledb.dev), a community project. If either changes shape the lookups stop
+  until the scripts are updated; nothing on the devices or in the cache is affected.
+- **A refused registration wipes the cache.** (An unreachable Apple only suspends it; see
+  [Thin links and outages](FINDINGS.md#thin-links-and-outages).) If the server cannot register
+  with Apple (a VPN changes its public IP, egress is blocked, Apple returns 403) it deletes
+  everything about two minutes later. Ten minutes after that it is Active, registered and
+  reporting "status OK", with nothing in it. So the "Inactive or broken" group is not enough of
+  an alarm: the effectiveness EA's WIPED flag and the "Content Caching - Wiped recently" Smart
+  Group exist for exactly this. Keep the server's public IP and egress stable, and keep any VPN
+  client that connects at startup off it.
+- **A cache server needs a cable, a fixed address and an unattended restart.** Use Ethernet:
+  the same 237 MB file took 8 to 12 s from the lab cache on Wi-Fi and 4 s wired, and on Wi-Fi the
+  cache registers with Apple again every time its link speed changes. Give it a DHCP
+  reservation (if it must use Wi-Fi, set the network's private Wi-Fi address to Fixed or Off, or
+  the reservation will not hold). Devices keep a cache's address for an hour, so after an address
+  change they try the old one until their next lookup. A Mac with FileVault on waits at the
+  unlock screen after a restart and serves nothing until someone logs in. With FileVault off it
+  serves from the login window: on the lab cache (macOS 27, content on an external USB drive)
+  the drive was mounted, the cache registered and a 1.9 GB file served from cache one minute
+  after a restart, with nobody logged in and no automatic login. A restart also sets the cache's
+  counters back to zero, so the effectiveness EA reads NEW for a while afterwards.
+- **A cache server updates itself too, and serves nothing while it does.** In the same
+  enforcement Blueprint as the other Macs it restarts at their deadline, in working hours, and
+  the cache is out of service for some minutes. It comes back by itself with its content. Give
+  cache servers their own Blueprint, with a deadline outside working hours.
+- **The cache's storage is a path, not a drive.** Rename or erase the volume and content caching
+  switches itself off ("Timed out waiting for /Volumes/... to appear" in its log) and the EAs read
+  "Not a content cache", the same as a Mac that never was one. Choose the volume again under
+  Sharing > Content Caching > Options. `doctor.py` names a Mac that was a cache and no longer is.
+  In the Options slider the far right is "Unlimited", which fills the volume to its last 2 GB;
+  for a smaller limit use `defaults write /Library/Preferences/com.apple.AssetCache.plist
+  CacheLimit -int <bytes>` and `AssetCacheManagerUtil reloadSettings`.
+- **An external cache drive can be the only storage the server accepts.** A cache server with
+  FileVault off and its content on an external drive is a Mac anyone nearby can plug a drive
+  into. Jamf Protect's removable storage controls close that: a control set whose default
+  permission is Prevent, with one override for the cache drive, in a plan scoped to the cache
+  servers and nothing else. Tested 2026-09-27 on the lab cache (Jamf Protect 8.20, macOS 27):
+
+  | Test | Result |
+  |---|---|
+  | The plan arrives while the cache drive is mounted | the drive stays mounted; the cache reads from it and writes to it as before |
+  | A second drive, of another make, is plugged in | refused, with Protect's notice on screen; refused again when macOS was asked to mount it; the cache was not disturbed |
+  | The server restarts | the cache drive mounted at the login window, three seconds after Protect had started; the cache was Active and serving within a minute |
+
+  Two limits. An override names a vendor ID, a product ID or a serial number, and many drive
+  enclosures report their bridge chip's identifiers and a default serial number (the lab's:
+  ASMedia, 0x174c / 0x55aa, serial 000000000001). A rule on those allows every enclosure built
+  on that chip, not one drive. A ready-made external SSD is the better choice where this matters:
+  it reports its maker's own identifiers and a serial number of its own (the second drive in the
+  test, a SanDisk portable SSD, did), so an override by serial number allows that one drive and
+  no other. And an override that applies to unencrypted drives stops matching if the drive is
+  encrypted later, which would block the cache's own storage. A cache whose drive is blocked
+  switches itself off, so deliver the plan to one server and check it before the rest.
+
+![Jamf Protect refusing a second drive while the cache drive stays mounted](images/protect-drive-denied.png)
+
+*A second drive plugged into the cache server: Protect's notice, and only the cache drive in the Finder.*
+- **Jamf "Calculate sizes" (home folder sizes) can hang inventory** on any Mac with a
+  streaming cloud drive (Google Drive, OneDrive, iCloud) in the home folder: recon walks the
+  cloud folder and waits on metadata fetches. Turn it off under Settings > Computer
+  Management > Inventory Collection. It has nothing to do with these EAs but blocks them.
+- **VPN, ZTNA and SASE clients: it is the tunnelling model that matters, not the vendor.**
+  A client uses a cache only when two things hold: Apple's locator sees the client's query
+  from the same public IP the cache registered with, and the client can reach the cache's LAN
+  address directly. Per-app ZTNA satisfies both by default, because traffic that matches no
+  access policy is handled as if the client were off: Jamf Connect's ZTNA works this way, and
+  so do the app-based modes of other vendors. Full-tunnel or "secure internet"
+  modes (tunnel-all VPN profiles, cloud web gateways that carry all traffic) break the first
+  condition, since Apple then sees the tunnel's egress address; the standard fix is the
+  client's exclusion or bypass list: Apple's locator, registration and update hosts (the list
+  is in Apple's "Use Apple products on enterprise networks") plus the office subnets.
+  On-device filters that do not tunnel (DNS filtering, endpoint protection) change nothing.
+  The "Macs with no content cache" Smart Group is the detector: office Macs landing there means
+  something is in the way. (The ZTNA part follows Jamf's published
+  [network engineer's guide](https://concepts.jamf.com/en/guides/resource-access-control/network-engineers-guide-to-private-access/);
+  it has not been tested on hardware.) Two admin choices to avoid in any ZTNA product: a Direct IP policy overlapping
+  an office subnet, and a policy covering Apple's hosts.
+- **The cache server itself must not be behind a tunnel.** Registration must reach Apple
+  from the server's real public IP, and a change of that address costs the whole cache (see
+  "A refused registration wipes the cache" above). Exempt at least lcdn-registration.apple.com, suconfig.apple.com and
+  Apple's update CDNs, or keep the server off the client entirely.
+- **Remote Macs should not be routed through an office cache.** It is constructible (a Direct
+  IP policy for the server, its public-ranges setting widened to the ZTNA egress ranges, its
+  listen ranges widened to the gateway subnet) but the bytes then travel Apple to office to
+  cloud to Mac: the office uplink pays for every update and the remote Mac gains nothing.
+  Content caching only ever saves the last local hop.
+
+## Clients do not see the cache
+
+A client finds a cache by asking Apple for the servers registered under the client's public address, then connecting to the server directly on its port. Four things must hold: the client and the server leave for the internet from the same public address; the server is registered; the server is set to serve the client's subnet; the server's port is reachable. Two read-only scripts check all four:
+
+- On the caching Mac: `sudo bash admin/troubleshoot-server.sh`
+- On a Mac that does not see it: `bash admin/troubleshoot-client.sh <server address> <port>` (address and port from the server's output)
+
+Read the server's output first.
+
+| Line | Problem value | What to do |
+|---|---|---|
+| `Activated` / `Active` | `false` | Turn the service on: System Settings, General, Sharing, Content Caching. |
+| `RegistrationStatus` | `0`, or a `RegistrationError` line | The server cannot reach Apple's registration service. It needs outbound HTTPS to Apple (17.0.0.0/8) with no proxy or TLS inspection in the path. |
+| `LocalSubnetsOnly` | `true` with clients on other VLANs or on Wi-Fi | The default serves only the server's own subnet. Set Clients to "all networks", or add ranges. |
+| `Port` | random | Set a fixed port if a firewall or an ACL sits between clients and the server. |
+| `PublicAddress` | differs from the client's | Different internet exits: dual WAN, SD-WAN, a guest VLAN with its own NAT, or a security agent on the client (ZTNA, always-on VPN, a cloud web filter). Either put both on the same exit or declare the ranges to the server (Advanced, Clients, public IP ranges) or in a `_aaplcache._tcp` DNS TXT record. |
+| no `Received GET` lines | | No client has asked. They never found the server, or the port is blocked. |
+
+Then the client's.
+
+| Line | Value | Meaning |
+|---|---|---|
+| public address | differs from the server's | Stop here; fix the exit first. |
+| `Found 0 content caches` with matching address | | Apple has no registration for that address: back to `RegistrationStatus` and `LocalSubnetsOnly`. |
+| `Found 1`, port `BLOCKED` | | Firewall on the server, an ACL between VLANs, or client isolation on the Wi-Fi network. |
+| `Found 1`, port `open` | | The client is fine. It remembers a located result for about an hour; after a server-side fix, run `AssetCacheLocatorUtil` on the client to refresh. |
+
+Also: a caching server on Wi-Fi or allowed to sleep unregisters; use Ethernet and prevent sleep. The cache does not use Bonjour, so multicast settings do not matter. The "Macs with no content cache" Smart Group (docs/SETUP.md) lists which clients do not see a server; the list usually maps onto one VLAN, site or SSID.
diff --git a/sales/preheat/docs/FINDINGS.md b/sales/preheat/docs/FINDINGS.md
new file mode 100644
index 0000000..17f83cb
--- /dev/null
+++ b/sales/preheat/docs/FINDINGS.md
@@ -0,0 +1,162 @@
+# Preheat: Findings
+
+[Preheat](../README.md) > Findings
+
+What was measured in the lab: what is proven, what one release weighs, what a full cache does, thin links and outages.
+
+## What is proven, and what is not
+Proven end to end on one lab: an M1 Mac mini
+cache server, two Apple silicon Macs, three iPads (2016 to 2021) and an iPhone XR, Jamf Pro
+11.32. Two real point releases have gone through it: an iPad Pro from 2017 (iPadOS 17.7.10 to
+17.7.11) and the iPhone (iOS 18.7.9 to 18.7.10) were each planned, preheated, and updated
+from the cache with nothing fetched from Apple. Lookups are checked against every model
+Apple has shipped since 2013, not only this hardware, and 187 update files covering every
+current model (from 26.7 to 27.0, and from 26.6 to 26.7) were planned, pulled through the
+cache and named by it without a failure. Beyond OS updates, full macOS installers, Xcode
+components and Aerial screen savers have been preheated the same way, and the cache's
+behaviour on a thin link and through an outage has been measured. The first Mac point release (27.0 to 27.0.1,
+2026-09-28) arrived by an enforced Blueprint: the file the check had predicted for both lab Macs
+is the file that reached the cache, and a third Mac then took all 3.3 GB of it from the cache with
+nothing fetched from Apple. Not yet done: an update enforced by a Blueprint across many
+devices, and a second cache server in a second office. Peer caches are proven on two real caches. Configuring cache servers and
+denying caching on every other Mac by Blueprint (macOS 27) is proven on the same lab. Sites with more than one public
+address and favored caches are handled but have only been run against sample data: testers
+with such a network are the most useful of all. Hardware where a tester would help most: an Intel Mac with a T2 chip (its lookup is
+inferred, not confirmed), any Intel Mac, a current iPhone, Apple TV and Apple Vision Pro.
+Issues and pull requests welcome.
+
+## What the caveats rest on
+Each was seen in the lab. The advice is in [Caveats](CAVEATS.md); this is the evidence.
+
+| Seen | Date |
+|---|---|
+| A cache that could not register deleted 19.71 GB two minutes later ("Still not registered, flushing the cache") | 2026-09-19 |
+| A consumer VPN connecting at startup cost a 500 GB cache within two minutes of a restart; ten minutes later the server reported "status OK" with nothing in it | 2026-09-20 |
+| Two iPads behind a consumer VPN matched no cache server, and found the cache when the VPN was turned off | 2026-09-20 |
+| The size figures in DDM status stood still for 45 minutes while the cache grew by 99 GB; they moved once the declaration set a status interval | 2026-09-26 |
+| A Mac with caching just switched on joined a group built on Jamf's own criteria one inventory late | 2026-09-27 |
+| A Blueprint delivered with the pre-filled data path made the cache try to move 1.9 TB to the startup disk; only the lack of space stopped it | 2026-09-27 |
+| The cache server restarted for its own update at 14:00 on a working day; the cache was out of service for about six minutes | 2026-09-28 |
+| The cache server lost its network address; for an hour and a half Jamf showed an Active, READY cache that no device could reach | 2026-09-28 |
+
+## What one OS release looks like in a cache
+Measured on 2026-09-20 by asking Apple's lookup service on behalf of 212 models and pulling
+every OS 27 full image through one Mac mini cache (56 files, 491 GB, all named by the decoded EA):
+
+- **macOS is one universal file.** The 18.4 GB macOS 27.0 full image and the 12.0 GB delta from
+  26.7 each serve every supported Mac. (Where Intel Macs are still supported, as on 26.x, they get
+  their own smaller delta: 1.4 GB from 26.6 to 26.7 against 3.1 GB for Apple silicon.) A Mac-only
+  site needs very little cache per release.
+- **iPhone and iPad are per model.** Recent iPhones each have their own 8 to 9.5 GB file (older
+  pairs such as iPhone 12 and 12 Pro share one); iPads share within a generation. 53 full images
+  in all, about 454 GB. A mixed mobile fleet, not the Macs, decides how big a cache must be.
+- **Wi-Fi and cellular usually share a file, but not always.** iPad (A16) has separate Wi-Fi and
+  cellular files, and iPhone 18 Pro Max has separate US and Global files. Always match on the
+  exact model identifier.
+- **Devices take deltas, not full images.** Asked with a device's real version and build, Apple
+  also offers a delta (iPhone 16: 9.1 GB full, 4.5 GB from 26.7, 6.1 GB from 26.0), and that is
+  what the device downloads. A cache warmed with full images only will miss. The readiness check
+  asks with each device's real build, so its plans contain the right file. iOS offers a delta
+  only when version and build both match a real release; macOS matches on build alone.
+- **tvOS ignores the source build** and returns every delta back to tvOS 16 plus the full image.
+- **One release does not fit in 511 GB.** Full images (454 GB) plus iPhone and iPad deltas from
+  the previous release (81 files, 327 GB) come to about 780 GB before any app or iCloud content.
+- **New hardware appears in the lookup service before it ships**, so a cache can be warm for a
+  model on the day it arrives.
+
+![Six kinds of content on one cache server's record](images/decoded-ea-full-fleet.png)
+
+*Six kinds of content on one cache server's record, each named by the server itself at check-in: Aerial screen savers, visionOS and tvOS updates, Xcode components, full macOS installers, macOS updates and deltas. Names above, Apple's opaque paths below. Taken on 2026-09-27 while the whole cache was being refilled, so two lines are PARTIAL: the file downloading at that moment, and an installer whose download had stopped halfway (what led to `preheat.sh` checking that every byte arrives). The whole list at that moment, 361 lines: [decoded-ea-whole-list.png](images/decoded-ea-whole-list.png).*
+
+## Is the cache earning its keep?
+A content cache that works needs no help; one that has quietly stopped working looks exactly the
+same from Jamf. The effectiveness EA reads the cache's own counters: of everything it delivered
+to devices, how much did not have to come from Apple, since when, what it holds by type, and
+whether it is under pressure to evict. The first word (GOOD, FAIR, LOW, NEW) feeds the Smart
+Group "Content Caching - Low benefit", which finds caches few devices use or can reach.
+
+**A whole catalogue, measured (2026-09-27).** Everything Preheat can plan, pulled into an empty
+cache on a 4 TB drive in one run: every supported model's full image, the deltas from two
+starting versions to 27.0 and to 26.7, the newest full installer of each macOS, Xcode's
+components and every Aerial.
+
+| Content | Files | GB |
+|---|---|---|
+| iPad updates | 263 | 799 |
+| iPhone updates | 172 | 700 |
+| Mac updates | 13 | 136 |
+| Full macOS installers | 7 | 103 |
+| Aerial screen savers | 164 | 80 |
+| Vision Pro updates | 4 | 28 |
+| Xcode components | 5 | 24 |
+| Apple TV updates | 6 | 22 |
+| **All** | **634** | **1,890** |
+
+It took 14 hours 8 minutes, 37 MB/s on average, on a gigabit line behind a home router that
+forwarded about 300 Mbit/s. The cause was found afterwards: a bandwidth limiter on a guest
+network had switched off the router's hardware acceleration for every device. With the limiter
+off and the router restarted, the same cache server downloaded from Apple at 860 to 890 Mbit/s,
+which would have made this a five-hour job. A preheat is as fast as the slowest of the line,
+the router and the cache's disk, so measure from the cache server before a large one. Afterwards
+every one of the 634 files was complete, the same size as planned to within 0.05 GB, and named;
+the labels refresh took 3 seconds at a check-in and the inventory update 28. Three downloads had
+stopped partway during the run and were pulled again, which is why `preheat.sh` now checks that
+each file arrives whole. No organisation needs all of this; it is the upper bound.
+
+**What a full cache does (tested 2026-09-20).** A 511 GB cache holding 502 GB was sent another
+44.8 GB. Every download succeeded. The cache let free space run down to almost nothing, then
+removed about 18 GB in one go, and repeated: a sawtooth, with its pressure figure climbing from
+0.2 to 0.8. It removed the oldest files nobody had asked for since they arrived: first a full
+installer from two days earlier, then a tvOS delta, then the macOS 27 full image that serves
+every Mac. It has no idea what a file is worth. The two files real devices had used that morning
+survived. The lesson for preheating: a preheated file that no device has touched yet looks like
+the least valuable thing in the cache, so on a small, busy cache it can be the first to go.
+Preheat after Apple publishes but not days ahead of need, size the cache for what it must hold,
+and let the readiness EA tell you when READY has quietly become NOT READY.
+
+![The effectiveness EA on a cache server's record](images/effectiveness-ea.png)
+
+*A lab cache filled by hand and used by two devices reads LOW 2%: honest. A busy office cache should read GOOD.*
+
+## Thin links and outages
+Measured on the lab cache, 2026-09-26, by cutting and then limiting its internet at the router
+and reading the cache's own log.
+
+**The cache asks Apple about every file before it serves it.** Each request from a device makes
+the cache send one small question to the file's origin ("changed since I stored it?"). Apple
+answers "no" (HTTP 304) in about a tenth of a second and the file is served from disk.
+
+| The cache's internet | What devices get |
+|---|---|
+| Normal | cached files at LAN speed |
+| Limited to 0.125 Mbit/s | cached files at LAN speed: 738 MB in 12 s, first byte after 0.7 s. A file the cache does not hold arrives at the link's speed (11 KB/s) |
+| None | nothing. The question to Apple times out and the file is not served, from the first request. Content on disk is not enough |
+
+**What an outage does to the cache itself**
+
+| After the link is lost | |
+|---|---|
+| at once | requests fail (the device waits about two minutes for an error) |
+| 3 failed registrations, about 20 to 35 minutes | the cache suspends itself: not Active, answers HTTP 503 immediately |
+| while suspended | the content stays. 674 GB was intact after 33 minutes suspended |
+| link returns | the cache does not notice. It resumes at its next registration attempt, and the wait between attempts grows (1, 1, 9, 17 minutes). A 55-minute outage cost 66 minutes of service and no content |
+
+This is different from the wipe under Caveats: there Apple answered and refused the registration.
+No answer suspends a cache; a refusal empties it.
+
+**What this means for a site on a satellite or metered link**
+
+1. Preheat while the link is good or cheap (in port, overnight). The readiness EA says when the
+   site is ready.
+2. Limit the cache server's bandwidth at the firewall rather than blocking it. The questions to
+   Apple are a few kilobytes and pass; anything unplanned crawls instead of taking the link. When
+   a device gives up on a file the cache does not hold, the cache stops its own download too.
+   On a small router, check what a limiter costs: in the lab one limiter, set for other devices,
+   cut the whole network's speed to a third (see [A whole catalogue, measured](#is-the-cache-earning-its-keep)).
+3. Control what devices ask for in Jamf: automatic downloads, deferrals and beta enrolment in the
+   Software Update Settings Blueprint, automatic app updates in Restrictions. A cache downloads
+   only what a device requests.
+4. Watch "fetched from Apple" in the effectiveness EA. If it climbs while the link is limited,
+   something in step 3 is not locked down.
+
+A site with no link at all cannot use content caching, however full the cache is.
diff --git a/sales/preheat/docs/PREHEATING.md b/sales/preheat/docs/PREHEATING.md
new file mode 100644
index 0000000..f35078c
--- /dev/null
+++ b/sales/preheat/docs/PREHEATING.md
@@ -0,0 +1,114 @@
+# Preheat: Preheating
+
+[Preheat](../README.md) > Preheating
+
+Filling a cache before the devices ask, and what can and cannot be filled.
+
+## Preheating a cache without test hardware
+The users in an office have the hardware; IT usually does not have a matching test device at
+every site, and recruiting early adopters to "go first" so the cache fills is unreliable. The
+readiness check already knows which hardware and build combinations each server must be ready
+for, and Apple's lookup service returns the asset URL for any of them without a device in
+hand. A cache server accepts a request for any Apple CDN URL from any Mac on its network. Put
+together: IT can warm every office's cache for the hardware that office actually has, from a
+script, with no test fleet and no volunteers. First verified with a tvOS 27.0 update for an Apple
+TV 4K, pulled through a Mac mini cache with no Apple TV present; the cache grew by exactly its
+size.
+
+    python3 admin/readiness-check.py --platforms all --preheat-plan plan.json   # every MISSING/PARTIAL asset per server
+    sudo bash admin/preheat.sh plan.json                                        # on the cache server: pulls its own entries
+    bash admin/preheat.sh plan.json --server 192.168.x.x:49419 --guid <GUID>  # or from any Mac on that network
+
+**Hardware that is not in inventory yet.** `--preheat-models` adds models nobody has enrolled
+to the plan, for "200 new iPhones arrive Monday" or "we are buying more of what we already run".
+Name models, or a whole family: `all`, `mac`, `iphone`, `ipad`, `appletv`, `visionpro`:
+
+    # new hardware ships on the current OS: full images
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-models "iPhone18,3 Mac17,5"
+    # more of a model the fleet runs on 26.7 (and a few still on 26.0): the deltas those devices will ask for
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-models "iPhone17,3 iPad15,8" --from 26.7,26.0
+
+`--from` matters because a device downloads a delta from its current build, not the full
+image; the script finds the build of that version Apple offers the model a delta from
+(a version can have several builds), or takes `26.7:23H24` to name it. Where Apple offers no
+delta the full image is planned. `--target` / `--target-build` choose the destination as
+usual, `--preheat-server NAME_OR_GUID` limits it to one office, files a server already holds
+are skipped, and these extra models never count towards the readiness EA. A model Apple
+does not answer for yet (announced, not shipped) is reported and skipped; run it again later.
+
+Proven on a real device (2026-09-20): an iPad Pro 12.9-inch from 2017 on iPadOS 17.7.10 was
+planned with `--preheat-models "iPad7,2" --from 17.7.10`, which chose the 0.3 GB delta rather
+than the 5.3 GB full image, and the cache server pulled it. The iPad then ran the update: by
+the cache's own counters it was served 339.8 MB while 6.4 MB came from Apple, all of that
+before the download began (small companion files). Checking for updates had cached nothing
+beforehand, and with a VPN on, the same iPad could not see the cache at all.
+
+**Timing matters more than anything else here.** A device starts fetching an update on its own
+schedule, often within minutes of learning about it, and whatever it fetched before the file was
+cached came from Apple. In the second real-device test an iPhone XR had already taken about 230 MB
+of its 583 MB delta directly before the file was preheated; the remaining 353 MB came from the
+cache, with nothing from Apple. So preheat when Apple publishes, before devices check in: release
+day, the evening before an enforced deadline, the weekend before new hardware is unboxed. A week
+later most of the benefit has gone, because the first device at each site has already filled the
+cache the ordinary way.
+
+![Decoded EA with the two real devices' update files on top](images/decoded-ea-real-devices.png)
+
+*The top two lines are the deltas an iPhone XR and a 2017 iPad Pro actually needed, planned from inventory, pulled by the cache server, and named by it at the next check-in. (Taken 2026-09-20, when there was still a Board ID EA; see [What is an EA, what is not, and why](REFERENCE.md#what-is-an-ea-what-is-not-and-why).)*
+
+**Xcode components.** A new Xcode sends every developer to fetch the same simulator runtimes
+(7 to 9 GB each) and Metal toolchain. `--preheat-xcode` plans them from Apple's public simulator
+index, the same one Xcode reads, so Xcode need not be installed on the admin Mac:
+
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-xcode 27.0                        # iOS runtime + Metal toolchain
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-xcode latest --xcode-platforms all  # iOS, tvOS, watchOS, visionOS
+
+Verified 2026-09-26: the iOS 27.0 Simulator Runtime (8.1 GB) pulled through a Mac mini cache and
+was named by the decoded EA. Xcode itself and Xcode's own installer are not cacheable content;
+only the components it downloads afterwards are.
+
+**Full macOS installers and Aerials.** `--preheat-installers` plans InstallAssistant.pkg from
+Apple's software update catalog, the file `softwareupdate --fetch-full-installer` and Jamf's
+installer packages download, for erase-and-install and rebuild work; `--preheat-aerials` plans
+the screen saver videos, half a gigabyte each on average and up to 1.5 GB, that every Mac in a lobby or classroom otherwise
+fetches for itself:
+
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-installers latest        # newest of each major (27.0, 26.7, 15.8 ...)
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-installers 27,26.7        # exactly these
+    python3 admin/readiness-check.py --preheat-plan plan.json --preheat-aerials cities,landscapes  # or all (164 videos, 80 GB)
+
+`preheat.sh` finds the local cache's GUID and port itself, takes the plan as a file or a URL
+(so it can be a Jamf policy scoped to the "Content Caching - Servers" Smart Group, with the plan
+URL as script parameter 4), and has `--dry-run`, `--max-gb N` and `--platform` filters.
+It checks that every file arrived whole, not only that the download started: a file cut short
+is asked for again, up to three times (the cache keeps what it has and fetches the rest), and
+the script ends with an error if anything is still incomplete.
+Mind the sizes (see [What one OS release looks like in a cache](FINDINGS.md#what-one-os-release-looks-like-in-a-cache)); the plan prints totals first.
+After a preheat, an inventory update on the server refreshes its assets EA, and the next
+readiness run turns MISSING into COMPLETE without any device having downloaded anything.
+This removes the "one test device per hardware family per site" requirement from the two-wave
+plan in [Blueprints](BLUEPRINTS.md#using-this-with-ddm-software-updates-blueprints): wave one becomes optional, useful mainly as a canary for the update itself.
+
+## What else the cache holds, and what can be preheated
+Content caching stores far more than OS updates: App Store apps, iCloud photos and documents,
+Xcode components and simulators, Rosetta, dictionaries and Siri voices, Aerial screen savers,
+Books, and Apple Intelligence models (Apple's list is
+[here](https://support.apple.com/en-us/102860)). A lab cache that was never asked to hold
+anything but OS updates picked up 100 GB of iCloud data on its own within a day.
+
+Preheating needs a file's URL before any device asks, and that decides what Preheat can do:
+
+| Content | URL known in advance? | Preheat |
+|---|---|---|
+| OS updates and deltas | yes, Apple's lookup service | yes (this project) |
+| Full macOS installers | yes, Apple's software update catalog | **yes**, `--preheat-installers` |
+| Xcode simulator runtimes, Metal toolchain | yes: Apple's public simulator index names them, the lookup service gives the file | **yes**, `--preheat-xcode` |
+| Aerial screen savers | yes, Apple's public Aerial manifest | **yes**, `--preheat-aerials` |
+| Dictionaries, Siri voices, image-caption models, other mobile assets | yes, the lookup service's generic audience | not yet; small change |
+| App Store apps | only at download time, per device | no; a first device fills the cache |
+| iCloud data | no; per user and encrypted | no; caches on its own |
+| Apple Intelligence models | no; served by Apple's Unified Asset Framework, which the public lookup service does not know (checked 2026-09-26: every `UAF_` asset type is "AssetType not found") | no; a first eligible device with Apple Intelligence on fills the cache for the rest |
+
+So for apps and Apple Intelligence models the two-wave pattern is the whole answer: one device per
+site goes first, everyone else downloads locally. Preheat's readiness EA does not count those
+files, but the decoded EA names what it can and the effectiveness EA shows the sharing.
diff --git a/sales/preheat/docs/REFERENCE.md b/sales/preheat/docs/REFERENCE.md
new file mode 100644
index 0000000..274935c
--- /dev/null
+++ b/sales/preheat/docs/REFERENCE.md
@@ -0,0 +1,373 @@
+# Preheat: Reference
+
+[Preheat](../README.md) > Reference
+
+How Preheat works, piece by piece.
+
+## The goal
+Goal: know, from Jamf Pro, whether each Apple content caching server already holds the
+OS update that every hardware family **on its own network** would download: macOS by
+default, and iOS, iPadOS, tvOS and visionOS with `--platforms`. Office X's
+server is judged against the Macs that use Office X's server, Office A's against Office A's.
+
+## Pieces
+
+| File | Where it runs | What it does |
+|---|---|---|
+| `ea/ea-content-cache-status.sh` | every Mac (EA "Content Caching - Status") | "Not a content cache", "Active; guid <GUID>; ..." or "Inactive (<reason>); guid <GUID>". Worked out during inventory, so the Smart Groups that raise alerts are built on it. |
+| (from Jamf) Content Caching inventory | every Mac, collected by Jamf itself | The same facts and more (server GUID, port, addresses, space, counters), read by the admin scripts. Collected just after inventory, so Smart Groups on it run one inventory behind. |
+| `ea/ea-content-cache-servers-found.sh` | every Mac (EA "Content Caching - Servers Found") | Which cache server(s) this Mac would use, as macOS itself decides: `<GUID> host:port healthy reachable`. |
+| `ea/ea-content-cache-macos-assets.sh` | every Mac (EA "Content Caching - macOS Assets") | On cache servers: one line per cached OS update or installer, any Apple platform, with COMPLETE or PARTIAL nn% and Apple's opaque path. The machine key the admin script joins on. |
+| (no script) | mobile devices (Mobile Device EA "Content Caching - Server", input type Text Field) | Written by the admin script: which cache server this device matched, "<server name> guid <GUID>", or "None found". Basis for Smart Mobile Device Groups. |
+| `ea/ea-content-cache-effectiveness.sh` | every Mac (EA "Content Caching - Effectiveness") | On cache servers: is the cache earning its keep? "GOOD 87% from cache; served 1840 GB, fetched from Apple 239 GB, saved 1601 GB since 2026-06-01; holds ...; pressure 0.2". First word GOOD / FAIR / LOW / NEW is the contract for Smart Groups. |
+| `ea/ea-content-cache-decoded.sh` | every Mac (EA "Content Caching - Cached Updates") | On cache servers: the assets EA translated for humans, one line per cached asset, e.g. "COMPLETE 2.1GB 2026-09-19 tvOS 27.0 (24J361) delta from 26.0.1 (23J362) for AppleTV14,1". Reads a local labels file, makes no network calls. The raw path EA stays as the machine key. |
+| `admin/preheat-labels.py` | cache servers, from a Jamf policy | Writes the labels file the decoded EA reads: asks Apple's lookup service what every model would download and keeps path -> name in `/Library/Application Support/preheat/labels.json`. Needs no Jamf credentials. Only touches the network when the cache holds a file it has not named yet. |
+| `admin/create-labels-policy.py` | an admin Mac, once | Uploads `preheat-labels.py` to Jamf and creates the policy that runs it: recurring check-in, ongoing, Update Inventory, scoped to "Content Caching - Servers". Disable the policy to stop it; run again to update the script. |
+| (no script) | cache servers (EA "Content Caching - macOS Readiness", input type Text Field) | Not collected by the Mac. The admin script writes it through the API: "READY 3/3 combos, 41 devices @ date", "PARTIAL 2/3 combos, 30/41 devices @ date", or "NOT READY 0/3 combos, 0/41 devices (1 still downloading) @ date". Empty on Macs that are not cache servers. |
+| `admin/preheat.sh` | a cache server (or any Mac on its network) | Pulls the assets a plan says that server is missing through the cache itself, so it is warm for the hardware that site's users have without IT needing a test device there. Plan comes from `readiness-check.py --preheat-plan`. |
+| `admin/readiness-check.py` | an admin Mac, or a scheduled job | Groups Macs by the server they report, asks Apple what each hardware/build would download, checks the server's cached assets; prints a per-server report; `--write` fills EA "Content Caching - macOS Readiness" on each server. |
+| `admin/sync-eas.py` | an admin Mac, once and after any change to a file in `ea/` | Creates the five script EAs in Jamf (`--create`) and keeps the script stored in each one the same as the file here. |
+| `admin/create-smart-groups.py` | an admin Mac, once | Creates the Smart Groups listed under [Jamf setup](SETUP.md#jamf-setup); `--served-by` adds the two groups for one office; `--dry-run` shows what it would do. |
+| `terraform/` | an admin Mac or a pipeline | The same installation as code: EAs, Smart Groups, the labels script and its policy. An alternative to the two scripts above, not an addition. See [`terraform/README.md`](../terraform/README.md). |
+| `admin/doctor.py` | an admin Mac, any time | Read-only health check of the whole installation: Apple's lookup service and AppleDB, credentials, each API privilege and what it is for, every EA (and whether it matches the repo), Smart Groups, the labels policy, each cache server's state, Macs with empty EAs, mobile devices behind a VPN. PASS / WARN / FAIL with the command that fixes it. Start here when something looks wrong. |
+| `admin/cache-collect.sh` | a cache server, with sudo | Read-only diagnostic report of a cache server (settings, status, locator, database layout, recent log lines). Written on day one to learn how the cache stores things; still useful when a server misbehaves and you want everything in one file. |
+
+Every script answers `--help` and changes nothing when asked. All of them on one page:
+[docs/USAGE.md](USAGE.md), generated from the scripts by `admin/make-usage.sh`.
+
+![A cache server's Extension Attributes tab](images/cache-server-extension-attributes.png)
+
+*Everything the project produces, on one cache server's record: decoded cached updates (the top two lines are downloads in progress), effectiveness, raw cached assets, readiness, servers found. Decoded and raw lists match line for line. The effectiveness line starts with WIPED: the cache's drive had been erased the evening before, and it is being refilled.*
+
+![An ordinary Mac's Extension Attributes tab](images/client-mac-extension-attributes.png)
+
+*The same EAs on an ordinary Mac: every cache EA says "Not a content cache", and "servers found" names the cache this Mac would use. That one line is what ties a device to an office.*
+
+The EAs are named "Content Caching - Status", "Content Caching - Servers Found" and so on (the table under
+[EA definitions](SETUP.md#ea-definitions-as-the-jamf-form-asks-for-them)). Screenshots taken before 2026-09-27 show them under the names they had then,
+ea-content-cache-status and so on; the values are the same.
+
+## How it works
+- The cache database (`AssetInfo.db`, table ZASSET) stores each cached asset's URL path
+  without the host, and stores its bytes in a folder named by the row's GUID. An asset is
+  complete when that folder's size reaches ZTOTALBYTES.
+- Apple silicon update assets are opaque: `/2026FallFCS/<uuid>/com_apple_MobileAsset_MacSoftwareUpdate/<sha1>.zip`.
+  Apple's lookup service (POST gdmf.apple.com/v2/assets, with board ID, model, current version
+  and build) returns the exact URL a given device would download, so the admin script can
+  ask "is this path cached?" for every hardware/build combination in inventory.
+- The cache never prefetches. It fills when the first Mac of a hardware family downloads
+  through it: either a DDM declaration doing its background download, or a user running
+  Software Update. See [Using this with DDM software updates](BLUEPRINTS.md#using-this-with-ddm-software-updates-blueprints).
+
+## Where each fact comes from: Jamf inventory, EAs, DDM
+Preheat reads four sources. They differ in what they know, how fresh they are, and whether a Smart
+Group can use them. This is the whole picture:
+
+| | Jamf's own inventory | Extension attributes | DDM status | Readiness |
+|---|---|---|---|---|
+| Produced by | Jamf, from every Mac, with no setup | a script Jamf runs on every Mac (five of them) | the cache server itself, on macOS 27 | `readiness-check.py --write` |
+| Tells you | which Macs are cache servers; each one's GUID, port, addresses, space and counters; every device's model, OS and build | whether a Mac is a cache and serving, what a cache holds, which cache each Mac would use, whether the cache earns its keep, WIPED | whether the cache is switched on, running and registered; its address, port, peers and parents | READY, PARTIAL or NOT READY for the devices a cache serves |
+| Changes when | just after the Mac sends inventory | the Mac sends inventory | the cache changes state | the script runs |
+| A Smart Group sees it | one inventory later | at that inventory | never | when the script writes it |
+| Smart Groups | yes: "Content Caching - Activated", "- Active", "- Cache Status" | yes | **no** | yes |
+| Email on change | through a Smart Group | through a Smart Group | no | through a Smart Group |
+| Needs | macOS 10.15.4 | the EAs installed; python3 on cache servers | macOS 27 on the cache server | an API client; a schedule if it is to stay current |
+
+How they are used together:
+
+- **Smart Groups, the dashboard and email alerts** run on the first, second and fourth column.
+  They are as fresh as the last inventory update, or the last run of the script.
+- **Groups on Jamf's own Content Caching criteria run one inventory behind.** Jamf collects that
+  section with a command it sends just after each inventory, by which time the groups have been
+  worked out. That is why the groups in this project are built on the status EA, and why that EA exists
+  although Jamf has the same facts.
+- **DDM status is the freshest word on whether a cache is up**, but Jamf cannot build a group on
+  it. The scripts read it instead: `readiness-check.py` turns a cache that is down into NOT READY,
+  which a Smart Group does see, and `doctor.py` reports it. That is how a change DDM noticed
+  reaches an alert.
+- **One fact is collected twice, on purpose:** the cache's status, for the reason above (see
+  [What is an EA, what is not, and why](#what-is-an-ea-what-is-not-and-why)). Every other EA reports what nothing else does.
+- **DDM also delivers the updates.** That is a different use of the same channel: see [Using this with DDM software updates (Blueprints)](BLUEPRINTS.md#using-this-with-ddm-software-updates-blueprints).
+
+## What is an EA, what is not, and why
+**The board ID is not an EA.** Every Mac's board comes from its model identifier through AppleDB,
+the way it always has for iPhone and iPad. (`ea/ea-board-id.sh` stays in the repository for Macs
+from before 2016, where one model came with more than one board; `doctor.py` says if you have any.)
+An older installation may still have a Board ID EA. Nothing reads it; delete it rather than
+disable it, because a disabled EA still appears on inventory records.
+
+**The cache's status is both.** Jamf collects it on its own, in the Content Caching section of the
+inventory record, and the admin scripts read it there. But Jamf collects that section with a
+command it sends just after inventory, so a Smart Group built on Jamf's criteria is one inventory
+behind: a day, with daily inventory. Alerts should not be a day late, so the groups are built on
+a status EA, which is worked out during inventory. For a short while (2026-09-27) this project
+used Jamf's criteria alone; the delay was seen on a second cache and the EA came back.
+
+If you do build a group on Jamf's criteria, note that every Mac has a cache "Server GUID" and a
+"Cache Status" of OK, cache server or not. Only "Activated" says that a Mac is one.
+
+![The Content Caching section of a cache server's inventory record](images/content-caching-inventory.png)
+
+*What Jamf collects on its own from a cache server: state, registration, server GUID, port, addresses, space, and the served and fetched counters. Jamf shows sizes in binary units, so a 4 TB limit reads 3,725.29 GB. "Returned to Clients" equals "Stored from Origin" here because this cache was being refilled by preheating: every file had been fetched once and served once.*
+
+## How Macs are matched to a server
+Default (`--group-by locator`): each Mac's "Servers Found" EA lists the cache server GUID(s)
+macOS would use, based on Apple's locator service (public IP + local subnet rules). This is
+the same decision the OS makes at download time, so it's authoritative. Macs that report
+"None found" are listed at the end of the report, grouped by site and building, so you can
+see which offices have no cache at all.
+Alternative (`--group-by building`): Macs in the same Jamf building as the server.
+
+## Devices that come and go: the 90-day memory
+Laptops leave the office; readiness should still count them. "Served by" is therefore a
+rolling window, not a snapshot:
+- Macs: the servers-found EA keeps a small state file
+  (`/Library/Application Support/preheat/servers-seen.json`) and reports every
+  server seen in the last 90 days: `<GUID> host:port healthy reachable` when found right
+  now, `<GUID> host:port last-seen YYYY-MM-DD` otherwise. "None found" only after 90 days
+  without one. Change `STICKY_DAYS` at the top of the script to alter the window.
+- Mobile devices: the admin script writes `<server> guid <GUID> seen YYYY-MM-DD` and keeps
+  earlier sightings inside the window (`--sticky-days`, default 90) when today's match fails.
+- Readiness counts a device for every server it was seen on within the window. A device
+  that splits time between two offices makes both caches responsible for its hardware
+  family, which is the safe direction: over-counting only asks for one more cached asset,
+  under-counting produces a false READY.
+- Unrelated: `--max-age-days` (default 30) drops devices that have stopped reporting to
+  Jamf at all. That is about dead records, not travel.
+
+## iOS, iPadOS, tvOS and visionOS
+Macs are always included. `--platforms all`, or a list such as `ipados,tvos`, adds Jamf
+mobile device inventory as well. The API client then also needs Read Mobile Devices.
+Differences from Macs:
+- Mobile devices cannot run EA scripts, so there is no board ID EA and no "servers found"
+  EA. The script maps model identifier to board ID with the public AppleDB device list
+  (cached for 7 days in ~/Library/Caches/preheat/). To match a device to a server it
+  uses Apple's own locator rule: the device's public IP (which is what Jamf records for
+  mobile devices) must equal the server's public IP (Public Address in its Content Caching inventory). Failing
+  that, subnet (`--subnet-bits`) and then Jamf building.
+- Apple's lookup service is queried with the platform's own asset type and audience. iOS,
+  iPadOS and tvOS are verified on devices or by pulling their files; visionOS answers correctly for
+  both Vision Pro models but has not been tried on one.
+- The cache lists mobile OTA assets under the same MobileAsset path family, and the assets EA
+  now includes them. Apple Watch and HomePod updates
+  that land in a cache are named by the decoded EA, but Jamf does not inventory those devices, so
+  they never count towards readiness.
+- DDM enforced updates pre-download on these platforms too, so the two-wave plan in [Blueprints](BLUEPRINTS.md#using-this-with-ddm-software-updates-blueprints)
+  applies unchanged.
+- Smart Mobile Device Groups: mobile devices carry none of the script EAs, so the admin
+  script writes one Text Field mobile device EA, "Content Caching - Server" (create it in
+  Jamf: Mobile Device Extension Attributes, Text Field), with "<server name> guid <GUID>" or
+  "None found". `admin/create-smart-groups.py` then creates "Mobile devices with no content
+  cache" and, with `--served-by`, "Mobile devices served by <office> cache": the scope for a
+  wave-one iPadOS/tvOS Blueprint.
+
+## Large sites: several public addresses, favored caches, peers
+Apple's rule for offering a cache is "same public address as the device". Large networks bend
+that rule in three ways, and Apple has an answer to each. Preheat follows Apple's answer.
+
+| On the network | What Apple does | What Preheat does |
+|---|---|---|
+| The site reaches the internet from several public addresses | The site publishes them in a DNS TXT record (`_aaplcache._tcp`, key `prs` or `prn`); devices read it and tell Apple's locator | Treats those addresses as one site: an iPhone or iPad coming from any of them is matched to the caches registered from any of them |
+| Some caches are to be preferred | A second record (`fss` or `fsn`) names the favored caches' LAN addresses; while one is up, devices use no other | Judges a device only against the favored caches it would really use |
+| More than one cache on the network | They become peers and hand each other content before asking Apple | A file held by a peer counts: `COMPLETE on peer <name>`, and it is left out of the preheat plan |
+
+Macs need nothing new: their "Servers Found" EA already reports the caches macOS chose, whatever
+the addresses. It now also marks a cache `favored`, and adds one line when the network's DNS has
+Apple's records, `dns: public 203.0.113.10-203.0.113.19; favored 10.0.0.30`. That line is how the
+admin script learns a site's addresses with no configuration: any Mac on the site reports them,
+including the cache server itself. Where no Mac reports them:
+
+    python3 admin/readiness-check.py --platforms all --dns-domain corp.example.com          # read the TXT records, as devices do
+    python3 admin/readiness-check.py --platforms all --public-ranges "203.0.113.10-203.0.113.19,198.51.100.7"   # or state them; repeat per site
+
+Peers are the ones a cache reports itself (macOS 27, through DDM status). `--assume-peers` also
+treats caches that share a public address and a subnet as peers; it is off by default because a
+wrong guess would call a site READY when it is not. A peer that is not running is not counted.
+Parents are reported and not counted: a parent is usually at another site, so its content still
+crosses a WAN link.
+
+Try it without a network of that kind:
+
+    python3 admin/readiness-check.py --inventory-json admin/sample-inventory-large-site.json --platforms all
+
+**What has been tested, and what has not (2026-09-27).** Peers, on two real caches: a second Mac
+with content caching on became a peer of the lab cache within minutes, each reported the other
+through DDM, and a 179 MB file asked of the new cache, which held nothing, came entirely from its
+peer: 179.4 MB "from peers", nothing from Apple. The readiness check then left everything the
+peer held out of the new cache's preheat plan. Several public addresses and favored caches have
+run against the sample only; the TXT record formats, text and packed, against Apple's published
+examples. Not yet seen: a DNS TXT record read by a real Mac, so the exact form in which macOS
+reports the ranges is handled three ways, none confirmed. `doctor.py` lists the sites and peers
+it finds, which is the quickest way to see whether a real network is being read correctly.
+
+## Live status from the cache itself (macOS 27)
+A cache server on macOS 27 reports its own state through declarative device management: switched
+on, running, registered with Apple, address and port, parents and peers. Jamf Pro keeps these
+status items and its API returns them, each with the time it last changed. They change when the
+cache changes state, so they are newer than inventory whenever something happened in between.
+
+`readiness-check.py` and `doctor.py` read them when they are there:
+
+    ### cache-hq  [HQ]  guid ...  Active; ...
+        reported by the Mac itself (DDM, 2026-09-26 23:02): running, registered with Apple, address 10.0.0.2 port 49152
+
+- A cache that is switched off, not running or not registered is **NOT READY**, whatever its
+  file list says, with the reason and the time: `NOT READY cache is down: content caching is
+  switched off since 2026-09-26 22:53`. The files may be on disk; no device can get them.
+- If the cache changed state after its last inventory, both scripts say that the file list is
+  older than the change.
+- Nothing to set up. With an older macOS on the server, an older Jamf Pro, or an API role that
+  cannot read DDM status, the scripts find no status items and use inventory alone, as before.
+
+**A cache server that goes silent.** A server that is switched off, or off the network, reports
+nothing: no inventory arrives, so its record in Jamf stays as it was, no Smart Group changes and
+no alert is sent. Jamf goes on showing an Active, READY cache that no device can reach. So the
+readiness check also looks at when Jamf last heard from each cache server in any way (a check-in,
+an inventory update or a DDM status report). Past the limit the verdict is
+`NOT READY cache server silent since 2026-09-28 19:18`, which the "Not ready" group and its email
+pick up, and `doctor.py` reports the same. The limit is three times your check-in frequency and at
+least 30 minutes. If the API role cannot read the frequency (it needs Read Computer Check-In) the
+limit is 180 minutes, which is safe for the longest check-in Jamf Pro allows; `--silent-minutes N`
+sets it and 0 switches the check off. It can only warn you if the
+check runs on a schedule.
+
+Two limits, as of 2026-09-26. The size figures among the status items (used, free) are only
+refreshed when the content caching declaration sets `DeclarativeStatusInterval`, so the scripts
+do not use them. And the states above were read from a healthy cache and one that had been
+switched off; how a suspended cache (see [Thin links and outages](FINDINGS.md#thin-links-and-outages)) reports itself is not yet tested.
+
+Jamf Pro also collects cache statistics on its own, in the Content Caching section of a Mac's
+inventory: state, limit, used, free, and the served and fetched counters. It does not list what
+the cache holds, which devices use it, or whether it is ready; that is what the EAs add.
+
+## Why did this Mac download an update at 1 pm?
+Apple posts releases at about 10:00 Pacific. A Mac with a software update enforcement declaration
+starts downloading the moment the release posts, deadline or not, and App Store automatic updates
+do the same. Fifty Macs pulling the same file at 1 pm Eastern on a release day is the release, and
+it is what a content cache exists to absorb: one download from Apple, the rest from the LAN.
+
+Three places answer "why, and when" for one Mac, fastest first.
+
+1. **Jamf Pro's DDM status for the Mac**: `GET /api/v1/ddm/<managementId>/status-items`.
+   `softwareupdate.install-reason.reason` reads `declaration` when a Blueprint caused it, with
+   `softwareupdate.pending-version.*` and the time each item changed. No log needed; the API role
+   must be able to read DDM status.
+2. **The cache's log**, if the site has one: every request from every device by time, and by
+   device with Log client identity on (see [Blueprints](BLUEPRINTS.md)):
+   `/usr/bin/log show --last 2h --info --predicate 'subsystem == "com.apple.AssetCache"'`.
+3. **The Mac's own log.** The broad predicate (`process == "softwareupdated"`) runs to tens of
+   thousands of lines an hour; this one keeps the lines that tell the story:
+
+       /usr/bin/log show --start "2026-09-28 12:45" --end "2026-09-28 13:25" --info --style compact \
+         --predicate '(process == "softwareupdated" AND (
+              eventMessage CONTAINS "Starting scan with options"
+           OR eventMessage CONTAINS "Adding SUCoreDDMDeclaration"
+           OR eventMessage CONTAINS "Found DDM enforced install"
+           OR eventMessage CONTAINS ">E> RequestDownloadUpdate"
+           OR eventMessage CONTAINS "ACSLocateCachingServer ->"))
+         OR (process == "mobileassetd" AND eventMessage CONTAINS "Sending download result"
+             AND eventMessage CONTAINS "MacSoftwareUpdate.")'
+
+   On a Mac that downloaded because of a declaration it reads like this:
+
+       13:17:46  Adding SUCoreDDMDeclaration (DeclarationKey:com.apple.RemoteManagement.SoftwareUpdateExtension/...)
+       13:17:46  Starting scan with options: Background=0, MDMInitiated=1, requestedPMV=27.0.1
+       13:17:51  >S> ReadyToBegin >E> RequestDownloadUpdate
+       13:18:05  ACSLocateCachingServer -> newURL http://<cache>:49419/...MacSoftwareUpdate/...
+       13:18:33  Sending download result 0 (MADownloadSuccessful) ... MacSoftwareUpdate.<hash>
+       13:21:19  Found DDM enforced install
+
+   `MDMInitiated=1` within seconds of `Adding SUCoreDDMDeclaration` means the declaration did it;
+   the `ACSLocateCachingServer` line says the bytes came from a cache, and which one. Only
+   `Background=1` scans before the download means the Mac did it on its own schedule; nothing from
+   `softwareupdated` at all means look at `appstoreagent`.
+
+Three cautions. `--info` is required or the lines are missing. An OS install clears the log, so
+take it before the Mac updates. The strings are macOS 27's and were not checked on earlier systems.
+
+## Hardware coverage
+The scripts take the model list from AppleDB and the answers from Apple's own lookup service, so
+they are not limited to hardware anyone here owns. Checked on 2026-09-20 against every model
+released since 2013: 330 of 346 get an answer, each the newest OS that model can run (an Intel
+iMac from 2019 is offered macOS 15.8, an iPhone 8 iOS 16.7, an iPad from 2018 iPadOS 17.7), full
+image or delta from any earlier release. The 16 without an answer are obsolete (2013 Macs, Apple
+TV 3rd generation, iPhone 5c, first Apple Watch), not yet shipping, or regional variants AppleDB
+lists under a board Apple does not answer for.
+
+| Platform | Readiness (needs Jamf inventory) | `--preheat-models` and decoded names |
+|---|---|---|
+| Mac, Apple silicon and Intel | yes | yes |
+| iPhone, iPad, Apple TV, Vision Pro | yes, with `--platforms` | yes |
+| Apple Watch, HomePod | no: Jamf does not inventory them | yes (`Watch7,1`, `AudioAccessory6,1`) |
+
+Two things that are easy to get wrong, both handled: Intel Macs with a T2 chip (2018 to 2020)
+report a `Mac-xxxx` board ID, but Apple answers for the T2's own board in capitals
+(MacBookPro16,1 is J152FAP); asked with `Mac-xxxx` it offers only macOS 11. The admin script
+makes that substitution from AppleDB. And a lookup with no
+real source version must still send a plausible one: "0" is refused for HomePod and "1.0"
+returns nothing for Apple TV. The T2 substitution was inferred from Apple's answers and later corroborated: the activation
+predicates Jamf Blueprints generates for software updates identify the same Macs by the same
+capitalised T2 board IDs (J152FAP and the rest). It has still not been tried on a T2 Mac; a tester
+with one is welcome.
+
+## Where this plugs into the rest of the Jamf platform
+The readiness EA and the Smart Groups are the interface; everything below consumes them.
+
+- **Alerts with no code.** Nine groups are worth alerting on:
+
+  | Group | An email means |
+  |---|---|
+  | Content Caching - Servers | a Mac started or **stopped** being a cache server. A cache that loses its storage volume switches itself off and leaves this group; no other group sees that |
+  | Content Caching - Inactive or broken | caching is on but not serving (suspended, not registered) |
+  | Content Caching - Low on space | the cache volume is nearly full or missing: content is about to be evicted, or already cannot be stored |
+  | Content Caching - Wiped recently | the cache deleted its content (see "A refused registration wipes the cache" under [Caveats](CAVEATS.md#caveats)) |
+  | Content Caching - Not ready | a cache holds none of what its devices will ask for, or the cache is down, or the server has gone silent (off, or off the network). The one to act on before a push |
+  | Content Caching - Ready for OS push | safe to release wave two |
+  | Content Caching - Low benefit | a cache nobody is reaching |
+  | Content Caching - On but not chosen | a Mac is caching that nobody chose as a server (see [Configuring the cache servers themselves with a Blueprint](BLUEPRINTS.md#configuring-the-cache-servers-themselves-with-a-blueprint-macos-27)) |
+  | Content Caching - Chosen but not caching | a chosen server has caching off |
+
+  Groups change when inventory arrives, so an alert is as fresh as the cache server's last
+  inventory update. Simplest: tick "Send
+  email notification on membership change" on the Smart Group itself (needs SMTP set up in
+  Jamf Pro, and "Smart Computer Group Membership Change" ticked under your own account's
+  Notifications). Verified: a readiness value written by the API triggers the email; no
+  inventory submission is needed. With **Jamf Routines** (Business and Enterprise plans) the same membership
+  change posts to Slack, Teams or Webex from a template. Any other destination works via a
+  Jamf Pro webhook.
+
+![Email alert on Smart Group membership change](images/not-ready-email.png)
+
+*The built-in group emails: one when the server entered "Content Caching - Not ready", one two minutes later when it left.*
+- **Jamf Pro webhooks + JAWA** ([jamf/JAWA](https://github.com/jamf/JAWA)): the
+  SmartGroupComputerMembershipChange webhook can trigger the readiness check itself, so a
+  cache server entering "Content Caching - Servers" or a Blueprint's wave-one group finishing
+  its downloads re-evaluates readiness immediately instead of on a timer.
+- **Scheduling the check**: a launchd job on an admin Mac, or a GitHub Actions workflow on
+  a cron with the three credentials as repository secrets. Both only need outbound HTTPS to
+  Jamf Pro, gdmf.apple.com and AppleDB.
+- **Terraform.** The `terraform/` folder installs everything in [Setup](SETUP.md) (the seven EAs, the ten Smart
+  Groups, the labels script and its policy) with one `terraform apply`, using Jamf's own provider
+  [jamf/jamfplatform](https://registry.terraform.io/providers/jamf/jamfplatform). It reads the EA
+  and script bodies from `ea/` and `admin/`, so it is also how a script change reaches Jamf.
+  `terraform/import.sh` brings a tenant that was set up by hand under management. See
+  [`terraform/README.md`](../terraform/README.md); it needs a Platform API integration from Jamf Account, and has not yet
+  been applied to a tenant.
+- **jamf-cli** ([Jamf-Concepts/jamf-cli](https://github.com/Jamf-Concepts/jamf-cli)): a
+  unified CLI for the Jamf Platform; the API calls in `admin/` could be rebuilt on it.
+- **ddm-companion** ([Jamf-Concepts/ddm-companion](https://github.com/Jamf-Concepts/ddm-companion)):
+  real-time visibility into DDM declarations landing on devices, the natural companion to
+  the two-wave rollout: watch wave one's declarations arrive, then check readiness.
+- **scope-map** ([Jamf-Concepts/scope-map](https://github.com/Jamf-Concepts/scope-map)):
+  visualises what a Blueprint is scoped to; useful for sanity-checking the per-office groups.
+- **Jamf Protect Unified Logging.** Protect's log filters take the same predicate as
+  [Why did this Mac download an update at 1 pm?](#why-did-this-mac-download-an-update-at-1-pm).
+  Added as a filter, it streams from every Mac the moment a declaration triggers a download, and
+  the `ACSLocateCachingServer` line that says whether the bytes came from a cache, and which one.
+  One search in the log destination then answers "who downloaded what, why, and from where" for
+  the whole site on release day: the per-Mac effectiveness measure the EAs cannot give. Not yet
+  tested here.
+- **agent-skills / MCP** ([Jamf-Concepts/agent-skills](https://github.com/Jamf-Concepts/agent-skills),
+  [Jamf-Concepts/mcp-hub](https://github.com/Jamf-Concepts/mcp-hub)): a packaged skill for
+  "is office X's cache ready?" would let an AI agent answer from the EAs directly; a
+  candidate contribution once this project stabilises.
diff --git a/sales/preheat/docs/SETUP.md b/sales/preheat/docs/SETUP.md
new file mode 100644
index 0000000..51640f0
--- /dev/null
+++ b/sales/preheat/docs/SETUP.md
@@ -0,0 +1,178 @@
+# Preheat: Setup
+
+[Preheat](../README.md) > Setup
+
+What a new installation needs, and how to install it.
+
+## Requirements
+What a new installation needs, from nothing. Nothing here is specific to the lab this was built in.
+
+**Jamf Pro**
+- Jamf Pro 11.31 or later (the Terraform provider is built against 11.31; the admin scripts use
+  the modern API and were run against 11.32). Cloud-hosted or on-premises: everything goes
+  through the API and the built-in inventory, nothing is installed on the server.
+- Computers enrolled and submitting inventory, including every cache server. Mobile devices too,
+  if you want iPhone, iPad, Apple TV or Vision Pro readiness.
+- The "Calculate sizes" inventory option turned off if any Mac has a cloud drive in its home
+  folder (see [Caveats](CAVEATS.md#caveats)): it hangs the inventory that carries these EAs.
+
+**A Jamf Pro API role and client** (Settings > System > API roles and clients), for the admin
+scripts. The privilege table under [Jamf setup](#jamf-setup) lists exactly what each feature needs; for
+everything, that is: Read and Update Computers; Create, Read and Update Computer Extension
+Attributes; Read and Update Mobile Devices; Read Mobile Device Extension Attributes; Read and
+Create Smart Computer Groups; Read Static Computer Groups; Read and Create Smart Mobile Device
+Groups; Read Static Mobile Device Groups; Create, Read and Update Scripts; Create and Read
+Policies. Nothing that writes to profiles, users or settings.
+
+**A Jamf Account API integration** (account.jamf.com), only if you use the Terraform module or
+want Blueprints managed through the Platform API. It is a different credential from the one
+above, registered against your platform environment; [`terraform/README.md`](../terraform/README.md) lists its permissions.
+
+**An admin Mac** (or a CI runner) to run the admin scripts from:
+- macOS with Python 3.8 or later. The system `/usr/bin/python3` is fine once the Xcode Command
+  Line Tools are installed (`xcode-select --install`). No third-party Python packages.
+- Outbound HTTPS to your Jamf Pro, to `gdmf.apple.com` (Apple's software lookup service) and to
+  `api.appledb.dev` (the public model and build list).
+- Terraform 1.8 or later, only for the Terraform module.
+
+**The cache servers**
+- Any Mac running content caching (System Settings > General > Sharing > Content Caching), with
+  enough space for what it must hold: about 18 GB per macOS release, 8 to 10 GB per iPhone or
+  iPad model per release, more for deltas from several source versions (see [What one OS release looks like in a cache](FINDINGS.md#what-one-os-release-looks-like-in-a-cache)).
+- The Xcode Command Line Tools, so `/usr/bin/python3` is real: the labels policy and
+  `preheat.sh` run Python on the server.
+- A fixed address (DHCP reservation on the hardware MAC), no VPN client that connects at boot,
+  and either FileVault off or someone to unlock it after a restart. Each of these, when wrong,
+  costs the server its cache or its reachability (see [Caveats](CAVEATS.md#caveats)).
+- Optional: Jamf Protect, to refuse every removable drive but the cache's own (see [Caveats](CAVEATS.md#caveats)).
+- Enrolled in Jamf Pro like any other Mac. Nothing else is installed on it: the policy delivers
+  the labels script at run time.
+
+**Devices, for the parts that need them**
+- The readiness verdict and the plans work for any device Jamf inventories: Macs (Apple silicon
+  and Intel), iPhone, iPad, Apple TV, Vision Pro.
+- DDM software update enforcement (Blueprints) needs iOS/iPadOS 17 or macOS 14; the Software
+  Update Settings declaration needs iOS/iPadOS 18 or macOS 15 and supervision. Devices that do
+  not qualify are still counted and preheated for; they update on their own schedule.
+- Devices reach a cache only when they share its public IP and are not behind a full-tunnel
+  VPN. Per-app ZTNA is fine (see [Caveats](CAVEATS.md#caveats)).
+
+**Optional**
+- SMTP configured in Jamf Pro, for the Smart Group membership emails.
+- Jamf Routines, a webhook receiver or Jamf Pro webhooks, for alerts beyond email.
+
+## EA definitions, as the Jamf form asks for them
+All of them: Data Type = String, Inventory Display = Extension Attributes. Script EAs take the
+whole file named here as the script. `python3 admin/sync-eas.py --create` creates and
+updates the five script EAs for you; the two Text Field EAs are made by hand. The names are
+exact: the admin scripts and the Smart Groups find each EA by its name.
+
+| Display name | Input type | Description |
+|---|---|---|
+| Content Caching - Status | Script, `ea/ea-content-cache-status.sh` | Whether this Mac runs Apple content caching. "Not a content cache", or "Active; guid <GUID>; ip <LAN address>; port <port>; public <public address>; free <GB>; used <GB>; status OK", or "Inactive (<reason>); guid <GUID>" when caching is on and not serving. A cache whose storage volume went missing switches itself off; it reads "Inactive (LOWSPACE; caching switched itself off)". First word is the contract for Smart Groups. |
+| Content Caching - Servers Found | Script, `ea/ea-content-cache-servers-found.sh` | Which content caching server(s) this Mac would use, as macOS itself decides via Apple's locator service, remembered for 90 days. One line per server: "<server GUID> <host:port> healthy reachable" when found now, "<server GUID> <host:port> last-seen YYYY-MM-DD" when seen within the window. "None found" means nothing in 90 days. |
+| Content Caching - macOS Assets | Script, `ea/ea-content-cache-macos-assets.sh` | On cache servers only: one line per cached OS update, installer, Xcode simulator runtime, Metal toolchain or Aerial video, "COMPLETE <GB> <date> <path>" or "PARTIAL nn% ...". Read from the cache database; complete means every byte is on disk. "Not a content cache" elsewhere. |
+| Content Caching - Server (Mobile Device EA) | Text Field | Written by admin/readiness-check.py --write, not collected by the device. The content caching server(s) this iPad, iPhone or Apple TV would use, matched by public IP the way Apple's locator does and remembered for 90 days: "<server name> guid <GUID> seen YYYY-MM-DD" or "None found". Only needed with --platforms; basis for the Smart Mobile Device Groups. |
+| Content Caching - Effectiveness | Script, `ea/ea-content-cache-effectiveness.sh` | On cache servers only: of everything the cache delivered to devices, the share that did not have to be downloaded from Apple, from the cache's own counters. "GOOD" 70% or more, "FAIR" 30 to 69%, "LOW" under 30% (few devices use it, or devices cannot reach it: VPN, wrong network), "NEW" under 10 GB delivered so far. For 3 days after the cache loses more than 90% of its content between two inventory updates the value starts "WIPED <date> (held <GB>)": a cache that flushed itself goes straight back to looking healthy, and this is the only sign. Also what it holds by type, and cache pressure (near 1 means it is evicting content to make room). Counters restart when the cache is reset or flushed; the value says since when. A preheat counts as one delivery and one download, so a freshly preheated cache reads LOW until devices start using it. |
+| Content Caching - Cached Updates | Script, `ea/ea-content-cache-decoded.sh` | On cache servers only: human-readable version of "Content Caching - macOS Assets", one line per cached OS asset with version, build, full or delta, and the models it serves. Names come from a local labels file kept current by the policy "Preheat - Refresh cache labels" (admin/preheat-labels.py); a file not named yet shows as "unidentified ... (labels refresh pending)". If you leave this EA as a Text Field instead, admin/readiness-check.py --write fills it, but only when that script runs. |
+| Content Caching - macOS Readiness | Text Field | Written by admin/readiness-check.py, not collected by the Mac. Says whether this content caching server already holds the macOS update every hardware/build combination among the Macs that use it would download. READY = every combination cached and complete. PARTIAL = some cached. NOT READY = none. "combos" = distinct hardware family + current OS build pairs; "devices" = devices covered. Ends with the date of the last check. |
+
+## Jamf setup
+1. Create the computer EAs. Easiest: do step 2 first, then `python3 admin/sync-eas.py --create`,
+   which creates the five script EAs from the files in `ea/` (and updates them whenever a file
+   changes). By hand: five EAs, data type String, input type Script, with the names in the
+   table above, exactly. Then one more by hand, "Content Caching - macOS Readiness", input type
+   Text Field; the admin script fills it through the API. For mobile devices, also create one
+   Mobile Device EA, "Content Caching - Server", input type Text Field (see [iOS, iPadOS, tvOS and visionOS](REFERENCE.md#ios-ipados-tvos-and-visionos)).
+   Description to paste into the readiness EA:
+       Written by admin/readiness-check.py, not collected by the Mac. Says whether this content
+       caching server already holds the macOS update every hardware/build combination among
+       the Macs that use it would download. READY = every combination cached and complete.
+       PARTIAL = some cached. NOT READY = none. "combos" = distinct hardware family + current
+       OS build pairs; "devices" = devices covered. Ends with the date of the last check.
+   Every Mac that should count must be enrolled in Jamf and submitting inventory, including
+   the cache servers themselves.
+   Jamf runs the script text stored in the EA definition, so when a script in `ea/` changes,
+   the EA in Jamf must be updated too: run `python3 admin/sync-eas.py` again, or paste it.
+2. Create an API role and client. Grant only what you will use:
+
+   | To do this | Privileges |
+   |---|---|
+   | Readiness report and `--write` for Macs | Read Computers, Read Computer Extension Attributes, Update Computers |
+   | `--platforms` (iPhone, iPad, Apple TV, Vision Pro) | Read Mobile Devices, Update Mobile Devices, Read Mobile Device Extension Attributes |
+   | `sync-eas.py` | Create and Update Computer Extension Attributes |
+   | `create-smart-groups.py` | Read and Create Smart Computer Groups, Read and Create Smart Mobile Device Groups |
+   | `--cohort` | Read Smart and Static Computer Groups, Read Smart and Static Mobile Device Groups |
+   | The silent-server limit, from your check-in frequency (optional) | Read Computer Check-In |
+   | `create-labels-policy.py` | Create, Read and Update Scripts; Create and Read Policies |
+3. Run the check:
+
+   Store the credentials once in the macOS login keychain (the secret is typed, not echoed,
+   and never passes through a shell argument):
+
+        python3 admin/readiness-check.py --store-credentials
+
+   Every script then reads them from the keychain. For CI or a one-off run, the environment
+   variables JAMF_URL, JAMF_CLIENT_ID and JAMF_CLIENT_SECRET take precedence when set. Never
+   put them in a script, an EA, or a file inside the project.
+
+        python3 admin/readiness-check.py            # report only, newest version Apple offers
+        python3 admin/readiness-check.py --target 27.1 --write        # a specific version
+        python3 admin/readiness-check.py --target-build 26B123 --write  # the build a declaration pins
+        python3 admin/readiness-check.py --max-age-days 0              # include Macs not seen in 30+ days
+        python3 admin/readiness-check.py --platforms all               # add iOS, iPadOS, tvOS, visionOS
+        python3 admin/readiness-check.py --group-by building   # if the locator EA isn't deployed yet
+        python3 admin/readiness-check.py --cohort "Hold on 26=26"      # a group held on the previous OS (see the DDM section)
+
+4. Smart Groups (Computers > Smart Computer Groups > New). In the criteria picker the EAs sit
+   among Jamf's own "Content Caching - ..." criteria; take the names in this table, which are
+   the EAs (see [Where each fact comes from](REFERENCE.md#where-each-fact-comes-from-jamf-inventory-eas-ddm) for why not Jamf's). `python3 admin/create-smart-groups.py`
+   makes all of them, and with `--update` brings an older installation's groups to these rules.
+
+   | Name | Description | Criteria | Operator | Value |
+   |---|---|---|---|---|
+   | Content Caching - Servers | Macs running content caching, serving or not | Content Caching - Status | like | Active |
+   | Content Caching - Ready for OS push | Cache servers whose local devices' update is fully cached | Content Caching - macOS Readiness | like READY **and** not like NOT READY | (two criteria: "NOT READY" also contains "READY") |
+   | Content Caching - Partially ready | Some needed assets cached | Content Caching - macOS Readiness | like | PARTIAL |
+   | Content Caching - Not ready | Cache servers still missing assets | Content Caching - macOS Readiness | like | NOT READY |
+   | Content Caching - Inactive or broken | Caching not serving: not registered, suspended, storage gone | Content Caching - Status | like | Inactive |
+   | Content Caching - Low on space | The cache volume is nearly full, missing or renamed | Content Caching - Status | like | LOWSPACE |
+   | Content Caching - Low benefit | Caches that re-serve under 30% of what they download | Content Caching - Effectiveness | like | LOW |
+   | Content Caching - Wiped recently | Caches that lost over 90% of their content in the last 3 days | Content Caching - Effectiveness | like | WIPED |
+   | Macs served by <office> cache | Macs that will download through that office's server | Content Caching - Servers Found | like | <that server's GUID: Server GUID in the Content Caching section of its inventory record> |
+   | Macs with no content cache | Macs that will pull updates straight from Apple | Content Caching - Servers Found | is | None found |
+   | Mobile devices served by <office> cache (Smart Mobile Device Group) | iPads, iPhones, Apple TVs that will download through that office's server | Content Caching - Server | like | <that server's GUID> |
+   | Mobile devices with no content cache (Smart Mobile Device Group) | Mobile devices that will pull updates straight from Apple | Content Caching - Server | is | None found |
+
+   "like" means contains. The per-office group is the natural scope for a staged update policy:
+   push to the office whose server is READY, hold the others.
+
+![Criteria of the per-office Smart Group](images/smart-group-criteria.png)
+
+*A per-office group is one rule: the servers-found EA contains that server's GUID.*
+   Add `--served-by "Office X" <GUID>` to `create-smart-groups.py` to get both per-office groups.
+
+5. Keep the decoded EA current: `python3 admin/create-labels-policy.py` uploads
+   `preheat-labels.py` and creates the policy "Preheat - Refresh cache labels" (recurring
+   check-in, ongoing, Update Inventory, scoped to "Content Caching - Servers"). Each cache server
+   then names its own files at check-in, with no Jamf credentials on it. The same policy makes
+   each cache server send inventory at every check-in, whatever the fleet's inventory schedule
+   is: hourly with 60-minute check-ins, and on cache servers only. Ordinary Macs can stay on
+   weekly or monthly inventory, because the cache they report is remembered for 90 days.
+   Cache servers need
+   `/usr/bin/python3`, which is only a stub until the Xcode Command Line Tools are installed
+   (`xcode-select --install`, or a Jamf policy that installs them).
+6. Check your work: `python3 admin/doctor.py` reads everything back and says what is missing.
+7. Schedule step 3 with `--write` (hourly is plenty): readiness needs the inventory join, so
+   it runs centrally. See "Scheduling the check" in [the list of what Preheat plugs into](REFERENCE.md#where-this-plugs-into-the-rest-of-the-jamf-platform).
+
+## Where things live
+Nothing is installed by hand on any Mac.
+
+| What | Where | Notes |
+|---|---|---|
+| EA scripts, `preheat-labels.py`, `preheat.sh` (when run from a policy) | inside Jamf Pro | Jamf delivers them at run time and removes them afterwards; there is nothing to copy to a Mac |
+| A cache server's or client's own state: `labels.json`, `servers-seen.json`, `cache-state.json` | `/Library/Application Support/preheat/` | written by the EAs and the labels script as root; safe to delete, it rebuilds |
+| The admin scripts | wherever you cloned this repository | they run from there; nothing goes in `/usr/local/bin` |
+| Admin-side download caches (model list, build list, update catalog, decoded names) | `~/Library/Caches/preheat/` | per user, safe to delete |
+| Jamf credentials | the macOS login keychain, service `preheat` | or environment variables in CI |
diff --git a/sales/preheat/docs/USAGE.md b/sales/preheat/docs/USAGE.md
new file mode 100644
index 0000000..dee9741
--- /dev/null
+++ b/sales/preheat/docs/USAGE.md
@@ -0,0 +1,330 @@
+# Every script and its options
+
+Generated by `admin/make-usage.sh` from each script's own `--help`. Do not edit by hand.
+Every script answers `--help` (or `-h`) and changes nothing when asked.
+
+## readiness-check.py
+
+```
+usage: readiness-check.py [-h] [--target TARGET] [--target-build TARGET_BUILD]
+                          [--max-age-days MAX_AGE_DAYS] [--platforms PLATFORMS]
+                          [--group-by {locator,building,subnet}] [--subnet-bits SUBNET_BITS]
+                          [--sticky-days STICKY_DAYS] [--write] [--preheat-plan FILE]
+                          [--cohort GROUP=VERSION] [--preheat-models MODELS] [--from VERSIONS]
+                          [--preheat-xcode VERSION] [--xcode-platforms XCODE_PLATFORMS]
+                          [--xcode-betas] [--preheat-installers VERSIONS]
+                          [--preheat-aerials CATEGORIES] [--preheat-server NAME_OR_GUID]
+                          [--inventory-json INVENTORY_JSON] [--public-ranges RANGES]
+                          [--dns-domain DOMAIN] [--record-answers] [--silent-minutes N]
+                          [--assume-peers] [--store-credentials]
+
+Content cache macOS update readiness check, per cache server  (admin-side, NOT an EA script)
+
+Question answered: for each content caching server, is it ready for the Macs that actually
+use it, i.e. does it already hold the macOS update every hardware/build combination on its
+network would download?
+
+Data sources (all from Jamf Pro inventory)
+  every Mac        model identifier -> board          hardware family key Apple uses (J413AP ...), from AppleDB
+  every Mac        EA "Content Caching - Servers Found" which cache server(s) this Mac would use (GUID host:port ...)
+  cache servers    Jamf's Content Caching inventory   activated, active, server GUID (the join key), port, addresses
+                   (and EA "Content Caching - Status", the same facts worked out during inventory, for Smart Groups)
+  cache servers    EA "Content Caching - macOS Assets"  cached macOS assets with COMPLETE / PARTIAL
+  every Mac        model identifier, OS version, OS build, site, building
+
+Steps
+  1. Group Macs by the cache server they report (or by building with --group-by building).
+  2. For each server, for each distinct (board, model, version, build) among ITS Macs, ask
+     Apple's lookup service (gdmf.apple.com) which asset that Mac would download.
+  3. Check that asset against the server's cached assets.
+  4. Print a per-server report; with --write store "READY / PARTIAL / NOT READY ..." in the
+     server's EA "Content Caching - macOS Readiness" for Smart Groups.
+
+Auth: the macOS login keychain (store once with --store-credentials), or the environment
+      variables JAMF_URL, JAMF_CLIENT_ID, JAMF_CLIENT_SECRET for CI and one-off runs.
+Offline test:  --inventory-json admin/sample-inventory.json
+Python 3 standard library only.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --target TARGET       macOS version to check readiness for (default: newest Apple offers)
+  --target-build TARGET_BUILD
+                        exact build to check for (e.g. 26B123), as pinned in a DDM declaration;
+                        overrides --target
+  --max-age-days MAX_AGE_DAYS
+                        ignore Macs whose last Jamf inventory is older than this (default 30);
+                        they are not on the network. 0 = keep all
+  --platforms PLATFORMS
+                        add mobile platforms: a comma list of ios,ipados,tvos,visionos, or 'all'.
+                        Macs are always included
+  --group-by {locator,building,subnet}
+                        how a device is matched to a server. locator: the Mac reports which server
+                        it uses (Macs only; mobile devices fall back to same-public-IP-as-server,
+                        which is Apple's own rule, then subnet, then building). building: same
+                        Jamf building as the server. subnet: device IP in the server's subnet
+  --subnet-bits SUBNET_BITS
+                        prefix length for subnet matching (default 24)
+  --sticky-days STICKY_DAYS
+                        a device stays 'served by' a cache server for this many days after it was
+                        last seen using it (default 90)
+  --write               store the summary in each cache server's readiness EA
+  --preheat-plan FILE   write a JSON plan of every MISSING/PARTIAL asset per server, for
+                        admin/preheat.sh
+  --cohort GROUP=VERSION
+                        devices in this Jamf group (computer or mobile, Smart or Static) are
+                        judged against this version instead of --target: '26' = the newest 26.x
+                        Apple offers them, '26.7' = exactly that, 'same' = the newest within each
+                        device's current major version (what a Blueprint set to Ignore major
+                        versions enforces). Repeat for more groups; the first match wins. For
+                        fleets where one group holds on the previous OS while the rest move on
+  --preheat-models MODELS
+                        with --preheat-plan: also plan for hardware that is not in inventory yet,
+                        a list of model identifiers, e.g. "iPhone18,3 Mac17,5" (commas or spaces
+                        between them both work), or a whole family: all, mac, iphone, ipad,
+                        appletv, visionpro. Without --from these are treated as new hardware: full
+                        images
+  --from VERSIONS       the OS version(s) the --preheat-models devices will be on, e.g. 26.7 or
+                        26.6,26.7 (or 26.7:23H24 to name the build). Devices download a delta from
+                        their current build, so this picks the right file
+  --preheat-xcode VERSION
+                        with --preheat-plan: also plan the simulator runtimes and Metal toolchain
+                        this Xcode version wants (27.0, or latest), for developer Macs on each
+                        server's network. iOS by default; --xcode-platforms adds tvos, watchos,
+                        visionos. Uses Apple's public simulator index, so Xcode need not be
+                        installed here
+  --xcode-platforms XCODE_PLATFORMS
+                        comma list for --preheat-xcode: ios, tvos, watchos, visionos, or all
+                        (default ios)
+  --xcode-betas         let --preheat-xcode pick beta simulator runtimes
+  --preheat-installers VERSIONS
+                        with --preheat-plan: also plan full macOS installers
+                        (InstallAssistant.pkg, what softwareupdate --fetch-full-installer and Jamf
+                        installer packages download), for erase-and-install and rebuild work.
+                        'latest' = the newest of each major Apple still offers; '27' = the newest
+                        27.x; '27.0,26.7' = exactly those; 'all' = every one
+  --preheat-aerials CATEGORIES
+                        with --preheat-plan: also plan Aerial screen saver videos (164 in all,
+                        about 80 GB; 0.5 GB on average, the largest 1.5 GB): a comma list of
+                        categories (landscapes, cities, underwater, space, mac, dynamic), or all
+  --preheat-server NAME_OR_GUID
+                        limit --preheat-models to cache servers whose name or GUID contains this
+                        (default: every server)
+  --inventory-json INVENTORY_JSON
+                        use this JSON list of normalized computers instead of Jamf
+  --public-ranges RANGES
+                        for a site that reaches the internet from more than one public address:
+                        all of them, as in the site's DNS TXT record, e.g.
+                        "203.0.113.10-203.0.113.19,198.51.100.7". A mobile device coming from any
+                        of them is matched to the caches registered from any of them. Repeat for
+                        each site. Not needed where Macs on the site report the ranges themselves
+                        (servers-found EA, 'dns:' line)
+  --dns-domain DOMAIN   read a site's public and favored ranges from Apple's content caching TXT
+                        records in this DNS domain (_aaplcache._tcp.DOMAIN), the way devices do.
+                        Needs dig or nslookup, and a Mac that can see that DNS. Repeat for each
+                        site
+  --record-answers      with --inventory-json: ask Apple now and store its answers in that file.
+                        From then on the file gives the same result whatever Apple releases, which
+                        is what a sample or a test needs
+  --silent-minutes N    a cache server Jamf has not heard from for this long (no check-in,
+                        inventory or status report) is NOT READY: it is off or off the network,
+                        and nothing else in Jamf will say so. Default: three times your check-in
+                        frequency and at least 30; 180 if the API role cannot read the frequency.
+                        0 = do not check
+  --assume-peers        treat cache servers that share a public address (or site) and a subnet as
+                        peers even when they do not report each other. Peers hand each other
+                        content, so a file on any of them counts. Without this, only peers a cache
+                        reports itself (macOS 27) are used
+  --store-credentials   prompt for the Jamf URL, API client ID and secret and store them in the
+                        macOS login keychain, then exit
+```
+
+## preheat.sh
+
+```
+preheat.sh: pull the OS update assets a cache server is missing THROUGH that cache, so it is
+warm for hardware families nobody on site owns. Reads a plan written by
+  python3 admin/readiness-check.py --preheat-plan plan.json
+
+Run ON the cache server (default: talks to the local cache, finds its own GUID and port):
+  sudo bash preheat.sh plan.json
+  bash preheat.sh https://your.host/plan.json        # plan can be a URL (e.g. a Jamf policy parameter)
+Or from any Mac on the server's network:
+  bash preheat.sh plan.json --server 10.0.0.2:49152 --guid <server GUID>
+Options: --dry-run (list only)   --max-gb N (stop after N GB)   --platform mac|ios|ipados|tvos|visionos|xcode|installer|aerial
+
+Jamf policy use: script parameter 4 = plan URL, 5 = extra options; scope to the "Content Caching - Servers" Smart Group.
+```
+
+## doctor.py
+
+```
+usage: doctor.py [-h] [--offline]
+
+doctor.py: check a Preheat installation end to end and say, in plain words, what to fix next.
+Read-only: it never changes anything in Jamf, on a Mac or in a cache.
+
+    python3 admin/doctor.py            # everything
+    python3 admin/doctor.py --offline  # only the parts that need no Jamf (Apple's lookup service, AppleDB, Python)
+
+Each line is PASS, WARN (works, but something is worth a look) or FAIL (a feature will not work until fixed),
+followed by what to do. Exit status 1 if anything failed. Credentials as for readiness-check.py.
+
+optional arguments:
+  -h, --help  show this help message and exit
+  --offline   skip everything that needs Jamf
+```
+
+## preheat-labels.py
+
+```
+usage: preheat-labels.py [-h] [--paths PATHS] [--out OUT] [--all] [--max-builds MAX_BUILDS]
+
+preheat-labels.py: name the OS update files a content cache holds. Runs ON the cache server, as root,
+from a Jamf policy (recurring check-in, ongoing, with Update Inventory). Needs NO Jamf credentials.
+
+The cache stores updates under opaque paths. Apple's public lookup service (gdmf.apple.com) is the only
+way to turn a path into "iOS 27.0 (24A437) full for iPhone17,3". This script asks that service on behalf
+of every device model (list from AppleDB), and writes what it learns to
+    /Library/Application Support/preheat/labels.json      {"labels": {"<path>": "<human label>"}}
+The EA script ea-content-cache-decoded.sh reads that file at inventory time, so the EA itself stays
+local-only. A path's label never changes, so labels are kept forever and the network is only used when
+the cache holds a path that has no label yet.
+
+Passes, each only if unlabelled paths remain:
+  1. full installers (InstallAssistant.pkg) from Apple's software update catalog
+  2. every model with no source build: full images, and every tvOS delta
+  3. every model of the platforms still unlabelled, per released build (newest first): deltas.
+     iOS only offers a delta when the source version AND build both match a real release (AppleDB supplies the pair)
+
+Usage:  preheat-labels.py [--paths FILE] [--out FILE] [--all] [--max-builds N]
+  --paths FILE   read cached paths from FILE (one per line, or raw assets EA text) instead of the cache database
+  --all          label everything Apple offers, not just what this cache holds (passes 1-2)
+Python 3 standard library only.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --paths PATHS
+  --out OUT
+  --all
+  --max-builds MAX_BUILDS
+                        pass 3 rounds: how many earlier builds per model to try
+```
+
+## sync-eas.py
+
+```
+usage: sync-eas.py [-h] [--create]
+
+Push the EA scripts in ea/ into their Jamf Pro computer extension attribute definitions. Jamf runs
+the script text stored in the EA, so after editing a file here, run this. Needs the API client
+privilege "Update Computer Extension Attributes" (and "Create ..." to add missing ones).
+Credentials: login keychain (readiness-check.py --store-credentials) or env JAMF_URL,
+JAMF_CLIENT_ID, JAMF_CLIENT_SECRET. Usage: python3 admin/sync-eas.py [--create]
+
+optional arguments:
+  -h, --help  show this help message and exit
+  --create    create EAs that do not exist yet
+```
+
+## create-smart-groups.py
+
+```
+usage: create-smart-groups.py [-h] [--dry-run] [--update] [--served-by LABEL GUID]
+
+Create the Smart Computer Groups this project recommends, skipping any that already exist.
+Needs API client privileges: Read / Create Smart Computer Groups.
+Credentials: login keychain (readiness-check.py --store-credentials) or env JAMF_URL, JAMF_CLIENT_ID, JAMF_CLIENT_SECRET.
+Usage: python3 admin/create-smart-groups.py [--dry-run] [--update]
+       python3 admin/create-smart-groups.py --served-by "Office X" <server GUID>   # add a per-office group
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --dry-run             print what would be created or updated
+  --update              also bring existing groups of these names to the rules in this script (for
+                        installations made before a rule changed)
+  --served-by LABEL GUID
+                        also create 'Macs served by <LABEL> cache' for that server GUID
+```
+
+## create-labels-policy.py
+
+```
+usage: create-labels-policy.py [-h] [--group GROUP] [--disabled]
+
+Put admin/preheat-labels.py into Jamf Pro as a script, and create the policy that runs it on cache servers:
+  General: trigger Recurring Check-in, frequency Ongoing     Scripts: preheat-labels.py
+  Maintenance: Update Inventory                              Scope: Smart Group "Content Caching - Servers"
+So at every check-in a cache server names any new files it holds, then sends inventory, and the decoded EA
+(ea-content-cache-decoded.sh) is current without anyone running the admin script. Disable the policy to stop.
+Run again after editing preheat-labels.py: the script in Jamf is updated, the policy is left alone.
+Needs API privileges: Create/Read/Update Scripts, Create/Read Policies, Read Smart Computer Groups.
+Usage: python3 admin/create-labels-policy.py [--group "Content Caching - Servers"] [--disabled]
+
+optional arguments:
+  -h, --help     show this help message and exit
+  --group GROUP
+  --disabled     create the policy switched off
+```
+
+## cache-collect.sh
+
+```
+cache-collect.sh  --  READ-ONLY inspection of an Apple content caching server.
+
+Purpose: gather everything needed to design a Jamf Pro Extension Attribute that
+reports which macOS updates are cached. Makes NO changes: the cache database is
+copied to a temp folder before it is queried, and the service is never touched.
+
+Run on the caching Mac:   sudo bash admin/cache-collect.sh
+Output: /Users/Shared/cache-report-<date>.txt  (plus a .json of macOS-update rows)
+
+```
+
+## troubleshoot-server.sh
+
+```
+troubleshoot-server.sh: is this content cache registered, scoped and reachable? Read-only.
+
+  sudo bash admin/troubleshoot-server.sh
+
+Prints the server's public address, the status fields that decide whether clients can find
+it, the settings that decide which clients it serves, whether it is listening, and the
+last two hours of registration, refusal and request lines from its log. Pair it with
+troubleshoot-client.sh on a Mac that does not see the cache.
+
+What to look for:
+  Activated or Active false     the service is off (System Settings, General, Sharing, Content Caching)
+  RegistrationStatus 0          cannot reach Apple's registration service: needs outbound HTTPS to
+                                Apple (17.0.0.0/8) with no proxy or TLS inspection in the path
+  LocalSubnetsOnly true         the default; only the server's own subnet is served. Set Clients to
+                                "all networks" or add ranges when clients sit on other VLANs or Wi-Fi
+  Port                          random by default; fix it if a firewall or ACL is in the way
+  PublicAddress                 must equal the clients' public address
+  no "Received GET" lines       no client has asked: they never found it, or the port is blocked
+```
+
+## troubleshoot-client.sh
+
+```
+troubleshoot-client.sh: why does this Mac not see the content cache? Read-only; no root needed.
+
+  bash admin/troubleshoot-client.sh [server LAN address] [port]
+
+Prints this Mac's public address, what Apple's locator returns for it, whether the
+server's port answers (when the address and port are given), and any tunnel that could
+change the route. Pair it with troubleshoot-server.sh on the caching Mac.
+
+Read the public address first: if it differs from the server's, nothing else matters until
+the two leave for the internet from the same place. "Found 0 content caches" with a matching
+address means Apple has no registration for it (check the server). "Found 1" with the port
+BLOCKED means a firewall, an ACL between VLANs or client isolation on the Wi-Fi network.
+A client remembers a located result for about an hour; this script always asks afresh.
+```
+
+## make-usage.sh
+
+```
+make-usage.sh: write docs/USAGE.md from every script's own --help, so the page cannot drift from the code.
+Run after changing any option:   bash admin/make-usage.sh
+Needs nothing but this repository: --help never contacts Jamf or Apple.
+```
diff --git a/sales/preheat/docs/images/.gitkeep b/sales/preheat/docs/images/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/sales/preheat/docs/images/blueprint-content-cache-settings.png b/sales/preheat/docs/images/blueprint-content-cache-settings.png
new file mode 100644
index 0000000..9f0d80a
Binary files /dev/null and b/sales/preheat/docs/images/blueprint-content-cache-settings.png differ
diff --git a/sales/preheat/docs/images/blueprint-scope-before-after.png b/sales/preheat/docs/images/blueprint-scope-before-after.png
new file mode 100644
index 0000000..60185fa
Binary files /dev/null and b/sales/preheat/docs/images/blueprint-scope-before-after.png differ
diff --git a/sales/preheat/docs/images/blueprints-deployed.png b/sales/preheat/docs/images/blueprints-deployed.png
new file mode 100644
index 0000000..1ffe45a
Binary files /dev/null and b/sales/preheat/docs/images/blueprints-deployed.png differ
diff --git a/sales/preheat/docs/images/cache-server-extension-attributes.png b/sales/preheat/docs/images/cache-server-extension-attributes.png
new file mode 100644
index 0000000..49fe6e9
Binary files /dev/null and b/sales/preheat/docs/images/cache-server-extension-attributes.png differ
diff --git a/sales/preheat/docs/images/client-mac-extension-attributes.png b/sales/preheat/docs/images/client-mac-extension-attributes.png
new file mode 100644
index 0000000..0ce5561
Binary files /dev/null and b/sales/preheat/docs/images/client-mac-extension-attributes.png differ
diff --git a/sales/preheat/docs/images/content-caching-inventory.png b/sales/preheat/docs/images/content-caching-inventory.png
new file mode 100644
index 0000000..88e1087
Binary files /dev/null and b/sales/preheat/docs/images/content-caching-inventory.png differ
diff --git a/sales/preheat/docs/images/dashboard-smart-groups.png b/sales/preheat/docs/images/dashboard-smart-groups.png
new file mode 100644
index 0000000..3bd1073
Binary files /dev/null and b/sales/preheat/docs/images/dashboard-smart-groups.png differ
diff --git a/sales/preheat/docs/images/decoded-ea-full-fleet.png b/sales/preheat/docs/images/decoded-ea-full-fleet.png
new file mode 100644
index 0000000..a063940
Binary files /dev/null and b/sales/preheat/docs/images/decoded-ea-full-fleet.png differ
diff --git a/sales/preheat/docs/images/decoded-ea-real-devices.png b/sales/preheat/docs/images/decoded-ea-real-devices.png
new file mode 100644
index 0000000..c05569b
Binary files /dev/null and b/sales/preheat/docs/images/decoded-ea-real-devices.png differ
diff --git a/sales/preheat/docs/images/decoded-ea-whole-list.png b/sales/preheat/docs/images/decoded-ea-whole-list.png
new file mode 100644
index 0000000..1d255dd
Binary files /dev/null and b/sales/preheat/docs/images/decoded-ea-whole-list.png differ
diff --git a/sales/preheat/docs/images/effectiveness-ea.png b/sales/preheat/docs/images/effectiveness-ea.png
new file mode 100644
index 0000000..5fb8dca
Binary files /dev/null and b/sales/preheat/docs/images/effectiveness-ea.png differ
diff --git a/sales/preheat/docs/images/not-ready-email.png b/sales/preheat/docs/images/not-ready-email.png
new file mode 100644
index 0000000..4ad25f0
Binary files /dev/null and b/sales/preheat/docs/images/not-ready-email.png differ
diff --git a/sales/preheat/docs/images/protect-drive-denied.png b/sales/preheat/docs/images/protect-drive-denied.png
new file mode 100644
index 0000000..d10ec04
Binary files /dev/null and b/sales/preheat/docs/images/protect-drive-denied.png differ
diff --git a/sales/preheat/docs/images/readiness-check-output.png b/sales/preheat/docs/images/readiness-check-output.png
new file mode 100644
index 0000000..5c793a1
Binary files /dev/null and b/sales/preheat/docs/images/readiness-check-output.png differ
diff --git a/sales/preheat/docs/images/smart-group-criteria.png b/sales/preheat/docs/images/smart-group-criteria.png
new file mode 100644
index 0000000..cba29c4
Binary files /dev/null and b/sales/preheat/docs/images/smart-group-criteria.png differ
diff --git a/sales/preheat/ea/ea-board-id.sh b/sales/preheat/ea/ea-board-id.sh
new file mode 100755
index 0000000..e8aba26
--- /dev/null
+++ b/sales/preheat/ea/ea-board-id.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - Board ID
+# Data type: String.  Runs on every Mac.
+# Apple silicon: hw.target gives the board ID Apple's update service keys on (e.g. J413AP).
+# Intel: fall back to the board-id from the device tree (e.g. Mac-7BA5B2D9E42DDD94).
+#   Intel Macs with a T2 chip: Apple's service keys on the T2's board, not this one; admin/readiness-check.py
+#   substitutes it from the model identifier (lookup_board), so this EA stays as it is.
+B=$(/usr/sbin/sysctl -n hw.target 2>/dev/null)
+if [[ -z "$B" ]]; then
+  B=$(/usr/sbin/ioreg -p IODeviceTree -r -n / -d 1 2>/dev/null | /usr/bin/awk -F'"' '/board-id/{print $4}')
+fi
+echo "<result>${B:-Unknown}</result>"
diff --git a/sales/preheat/ea/ea-content-cache-decoded.sh b/sales/preheat/ea/ea-content-cache-decoded.sh
new file mode 100644
index 0000000..c619362
--- /dev/null
+++ b/sales/preheat/ea/ea-content-cache-decoded.sh
@@ -0,0 +1,61 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - Cached Updates (decoded)
+# Data type: String.  Runs as root at inventory time on a Mac running content caching.
+#
+# The human-readable twin of ea-content-cache-macos-assets.sh: the same lines, with Apple's opaque path
+# replaced by what the file is, e.g.
+#   COMPLETE 9.1GB 2026-09-20 iOS 27.0 (24A437) full for iPhone17,3
+#   PARTIAL 40% 12.0GB 2026-09-20 macOS 27.0 (26A428) delta from 26.7 (25G229) for all Macs (55 models)
+# Labels come from /Library/Application Support/preheat/labels.json, written by admin/preheat-labels.py
+# (run it on the cache server from a recurring Jamf policy). This EA makes no network calls; a file the
+# labels script has not seen yet shows as "unidentified ... (labels refresh pending)".
+# The raw-path EA stays the machine key; never build Smart Groups on this one.
+set -u
+if [[ $EUID -ne 0 ]]; then echo "<result>Must run as root</result>"; exit 0; fi
+SETTINGS=$(/usr/bin/AssetCacheManagerUtil -j settings 2>/dev/null)
+ACTIVATED=$(/usr/bin/AssetCacheManagerUtil isActivated 2>&1)
+if [[ "$ACTIVATED" != *"is activated"* ]]; then echo "<result>Not a content cache</result>"; exit 0; fi
+DATA=$(/usr/bin/python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("result",{}).get("DataPath") or "")' "$SETTINGS" 2>/dev/null)
+[[ -z "$DATA" ]] && DATA="/Library/Application Support/Apple/AssetCache/Data"
+DB="$DATA/AssetInfo.db"
+if [[ ! -f "$DB" ]]; then echo "<result>No database at $DB</result>"; exit 0; fi
+W=$(/usr/bin/mktemp -d /tmp/ea-decoded.XXXXXX); trap 'rm -rf "$W"' EXIT
+/bin/cp "$DB" "$W/db"; [[ -f "$DB-wal" ]] && /bin/cp "$DB-wal" "$W/db-wal"; [[ -f "$DB-shm" ]] && /bin/cp "$DB-shm" "$W/db-shm"
+ROWS=$(/usr/bin/sqlite3 -readonly -json "$W/db" "
+  select ZGUID, ZTOTALBYTES, ZCREATIONDATE, ZURI from ZASSET
+  where ZURI like '%/InstallAssistant.pkg'
+     or ZURI like '%com_apple_MobileAsset_MacSoftwareUpdate/%'
+     or ZURI like '%com_apple_MobileAsset_SoftwareUpdate/%'
+     or ZURI like '%SimulatorRuntime/%'
+     or ZURI like '%com_apple_MobileAsset_MetalToolchain/%'
+     or ZURI like '/itunes-assets/Aerials%'
+     or ZURI like '%.ipsw'
+     or ZURI like '%macOSUpd%.pkg'
+  order by ZCREATIONDATE desc;" 2>/dev/null)
+OUT=$(/usr/bin/python3 - "$DATA" "${ROWS:-[]}" <<'PY'
+import json,sys,os,datetime
+data=sys.argv[1]; rows=json.loads(sys.argv[2] or "[]")
+try: labels=json.load(open("/Library/Application Support/preheat/labels.json")).get("labels",{})
+except Exception: labels={}
+lines=[]
+for r in rows:
+    total=r.get("ZTOTALBYTES") or 0; guid=r.get("ZGUID") or ""
+    ondisk=0; d=os.path.join(data,guid)
+    if guid and os.path.isdir(d):
+        for root,_,fs in os.walk(d):
+            for f in fs:
+                try: ondisk+=os.path.getsize(os.path.join(root,f))
+                except OSError: pass
+    if total and ondisk>=total: state="COMPLETE"
+    else: state=f"PARTIAL {100*ondisk/total:.0f}%" if total else "PARTIAL"
+    created=datetime.datetime.fromtimestamp((r.get("ZCREATIONDATE") or 0)+978307200, datetime.timezone.utc).strftime("%Y-%m-%d")
+    uri=r.get("ZURI","")
+    kind="macOS update" if "MacSoftwareUpdate" in uri else "full installer" if uri.endswith(".pkg") else "Xcode component" if ("SimulatorRuntime" in uri or "MetalToolchain" in uri) else "Aerial screen saver" if uri.startswith("/itunes-assets/Aerials") else "OS update"
+    lines.append(f"{state} {total/1e9:.1f}GB {created} "+labels.get(uri, f"unidentified {kind} {os.path.basename(uri)[:12]}... (labels refresh pending)"))
+print("\n".join(lines) if lines else "No OS update assets cached")
+PY
+)
+echo "<result>${OUT}</result>"
diff --git a/sales/preheat/ea/ea-content-cache-effectiveness.sh b/sales/preheat/ea/ea-content-cache-effectiveness.sh
new file mode 100644
index 0000000..7657f98
--- /dev/null
+++ b/sales/preheat/ea/ea-content-cache-effectiveness.sh
@@ -0,0 +1,60 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - Effectiveness
+# Data type: String.  Runs at inventory time on a Mac running content caching. No network calls.
+#
+# Is this cache earning its keep? From the cache's own counters: of everything it delivered to devices, how much did
+# NOT have to be downloaded from Apple. A cache that serves each file once saves nothing; a busy healthy one serves
+# each file many times.
+#   GOOD 87% from cache; served 1840.2 GB, fetched from Apple 239.1 GB, saved 1601.1 GB since 2026-06-01; holds iCloud 8.9 GB, iOS 0.7 GB, Mac 18.5 GB, other 47.3 GB; pressure 0.2
+# First word is the contract for Smart Groups:  GOOD (70% or more)  FAIR (30 to 69%)  LOW (under 30%)
+#   NEW = under 10 GB delivered since the counters started, too little to judge.
+#   WIPED = the cache lost more than 90% of its content between two inventory updates. Content caching deletes
+#     everything about two minutes after a failed registration with Apple (a VPN on the server, blocked egress, a changed
+#     public IP), and then carries on looking healthy. Shown first for 3 days, with the date and how much was lost:
+#       WIPED 2026-09-20 (held 499.4 GB); NEW 0% from cache; served ...
+#     Remembered in /Library/Application Support/preheat/cache-state.json (this EA runs as root at inventory time).
+# "since" is when the counters last reset (the cache restarts them when it is reset or flushed, and when the Mac restarts).
+# "pressure" is the cache's own MaxCachePressureLast1Hour: near 1 means it is evicting content to make room.
+# Values: "Not a content cache" | "Inactive" | the line above.
+J=$(/usr/bin/AssetCacheManagerUtil -j status 2>/dev/null)
+if [[ -z "$J" ]]; then echo "<result>Unknown (AssetCacheManagerUtil failed)</result>"; exit 0; fi
+OUT=$(/usr/bin/python3 - "$J" <<'PY'
+import json,sys,os,datetime
+r=json.loads(sys.argv[1]).get("result",{})
+if not r.get("Activated"): print("Not a content cache"); sys.exit()
+STATE="/Library/Application Support/preheat/cache-state.json"; WIPED_DAYS=3
+try: st=json.load(open(STATE))
+except Exception: st={}
+used_now=r.get("ActualCacheUsed", r.get("CacheUsed")) or 0; today=datetime.date.today()
+prev=st.get("used") or 0
+if prev>=5e9 and used_now<prev*0.1: st["wiped"]={"on":today.isoformat(),"lost":prev}      # eviction never takes 90% at once
+st["used"]=used_now; st["since"]=r.get("TotalBytesAreSince")
+try:
+    os.makedirs(os.path.dirname(STATE),exist_ok=True); json.dump(st,open(STATE,"w"))
+except Exception: pass
+w=st.get("wiped") or {}
+wiped=""
+try:
+    if w and (today-datetime.date.fromisoformat(w["on"])).days<=WIPED_DAYS: wiped=f"WIPED {w['on']} (held {w['lost']/1e9:.1f} GB); "
+except Exception: pass
+if not r.get("Active"): print(f"{wiped}Inactive"); sys.exit()
+gb=lambda b: f"{(b or 0)/1e9:.1f} GB"
+served=sum(r.get(k) or 0 for k in ("TotalBytesReturnedToClients","TotalBytesReturnedToChildren","TotalBytesReturnedToPeers"))
+fetched=r.get("TotalBytesStoredFromOrigin") or 0
+since=(r.get("TotalBytesAreSince") or "?")[:10]
+try: since=datetime.datetime.strptime(r["TotalBytesAreSince"],"%Y-%m-%d %H:%M:%S %z").astimezone().date().isoformat()   # the cache reports UTC; WIPED uses the local date
+except Exception: pass
+pct=max(0,round(100*(1-fetched/served))) if served else 0
+grade="NEW" if served<10e9 else "GOOD" if pct>=70 else "FAIR" if pct>=30 else "LOW"
+d=r.get("CacheDetails") or {}
+known={"iCloud":"iCloud","iOS Software":"iOS","Mac Software":"Mac"}
+holds=", ".join(f"{lbl} {gb(d.get(k))}" for k,lbl in known.items() if d.get(k))
+other=sum(v for k,v in d.items() if k not in known)
+if other: holds=(holds+", " if holds else "")+f"other {gb(other)}"
+print(f"{wiped}{grade} {pct}% from cache; served {gb(served)}, fetched from Apple {gb(fetched)}, saved {gb(max(0,served-fetched))} since {since}; holds {holds or 'nothing'}; pressure {r.get('MaxCachePressureLast1Hour','?')}")
+PY
+)
+echo "<result>${OUT:-Unknown}</result>"
diff --git a/sales/preheat/ea/ea-content-cache-macos-assets.sh b/sales/preheat/ea/ea-content-cache-macos-assets.sh
new file mode 100755
index 0000000..80d0980
--- /dev/null
+++ b/sales/preheat/ea/ea-content-cache-macos-assets.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - macOS Assets
+# Data type: String.  Runs as root at inventory time on a Mac running content caching.
+#
+# One line per cached OS update / installer asset (macOS, and iOS/iPadOS/tvOS/visionOS/watchOS OTA), plus Xcode
+# simulator runtimes and Metal toolchains:
+#   <COMPLETE|PARTIAL nn%> <size GB> <created yyyy-mm-dd> <path>
+# Path is the origin URL path with no host, exactly as the cache stores it, e.g.
+#   /content/downloads/52/44/142-16670-A_.../InstallAssistant.pkg           (full installer, Intel + Apple silicon)
+#   /2026FallFCS/<uuid>/com_apple_MobileAsset_MacSoftwareUpdate/<sha1>.zip    (Apple silicon macOS OTA update)
+#   /2026FallFCS/<uuid>/com_apple_MobileAsset_SoftwareUpdate/<sha1>.zip|.aea   (iOS/iPadOS/tvOS/visionOS/watchOS OTA)
+# Values: "Not a content cache" | "No macOS assets cached" | the list above.
+set -u
+if [[ $EUID -ne 0 ]]; then echo "<result>Must run as root</result>"; exit 0; fi
+SETTINGS=$(/usr/bin/AssetCacheManagerUtil -j settings 2>/dev/null)
+ACTIVATED=$(/usr/bin/AssetCacheManagerUtil isActivated 2>&1)
+if [[ "$ACTIVATED" != *"is activated"* ]]; then echo "<result>Not a content cache</result>"; exit 0; fi
+DATA=$(/usr/bin/python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("result",{}).get("DataPath") or "")' "$SETTINGS" 2>/dev/null)
+[[ -z "$DATA" ]] && DATA="/Library/Application Support/Apple/AssetCache/Data"
+DB="$DATA/AssetInfo.db"
+if [[ ! -f "$DB" ]]; then echo "<result>No database at $DB</result>"; exit 0; fi
+W=$(/usr/bin/mktemp -d /tmp/ea-cache.XXXXXX); trap 'rm -rf "$W"' EXIT
+/bin/cp "$DB" "$W/db"; [[ -f "$DB-wal" ]] && /bin/cp "$DB-wal" "$W/db-wal"; [[ -f "$DB-shm" ]] && /bin/cp "$DB-shm" "$W/db-shm"
+ROWS=$(/usr/bin/sqlite3 -readonly -json "$W/db" "
+  select ZGUID, ZTOTALBYTES, ZCREATIONDATE, ZURI from ZASSET
+  where ZURI like '%/InstallAssistant.pkg'
+     or ZURI like '%com_apple_MobileAsset_MacSoftwareUpdate/%'
+     or ZURI like '%com_apple_MobileAsset_SoftwareUpdate/%'
+     or ZURI like '%SimulatorRuntime/%'
+     or ZURI like '%com_apple_MobileAsset_MetalToolchain/%'
+     or ZURI like '/itunes-assets/Aerials%'
+     or ZURI like '%.ipsw'
+     or ZURI like '%macOSUpd%.pkg'
+  order by ZCREATIONDATE desc;" 2>/dev/null)
+OUT=$(/usr/bin/python3 - "$DATA" "${ROWS:-[]}" <<'PY'
+import json,sys,os,datetime
+data=sys.argv[1]; rows=json.loads(sys.argv[2] or "[]")
+lines=[]
+for r in rows:
+    total=r.get("ZTOTALBYTES") or 0; guid=r.get("ZGUID") or ""
+    ondisk=0; d=os.path.join(data,guid)
+    if guid and os.path.isdir(d):
+        for root,_,fs in os.walk(d):
+            for f in fs:
+                try: ondisk+=os.path.getsize(os.path.join(root,f))
+                except OSError: pass
+    if total and ondisk>=total: state="COMPLETE"
+    else: state=f"PARTIAL {100*ondisk/total:.0f}%" if total else "PARTIAL"
+    created=datetime.datetime.fromtimestamp((r.get("ZCREATIONDATE") or 0)+978307200, datetime.timezone.utc).strftime("%Y-%m-%d")
+    lines.append(f"{state} {total/1e9:.1f}GB {created} {r.get('ZURI','')}")
+print("\n".join(lines) if lines else "No OS update assets cached")
+PY
+)
+echo "<result>${OUT}</result>"
diff --git a/sales/preheat/ea/ea-content-cache-servers-found.sh b/sales/preheat/ea/ea-content-cache-servers-found.sh
new file mode 100755
index 0000000..ca409df
--- /dev/null
+++ b/sales/preheat/ea/ea-content-cache-servers-found.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - Servers Found
+# Data type: String.  Runs on every Mac.
+# Asks macOS which content caches THIS Mac would use for shared content (OS updates, apps),
+# and remembers every server seen in the last STICKY_DAYS so a Mac that goes home for a week
+# still counts as served by its office's cache.
+# One line per server:
+#   <server GUID> <host:port> healthy|unhealthy reachable|unreachable [favored]   (found right now)
+#   <server GUID> <host:port> last-seen YYYY-MM-DD                                 (seen within STICKY_DAYS)
+# "favored" = this network's DNS names that cache as one to prefer (Apple's fss TXT record): while it is up, this Mac uses no other.
+# Where the network's DNS has Apple's content caching TXT records (_aaplcache._tcp), one more line, last:
+#   dns: public <ranges>; favored <ranges>
+# "public" is every public address the site reaches the internet from; the admin script uses it to match
+# iPhones and iPads, which cannot run this, to the site's caches.
+# Values: exactly "None found" when nothing has been seen within the window.
+# The GUID matches the Server GUID in the Content Caching section of the cache server's inventory record.
+STICKY_DAYS=90
+STATE_DIR="/Library/Application Support/preheat"
+[[ -w "/Library/Application Support" || -d "$STATE_DIR" ]] || STATE_DIR="${TMPDIR:-/tmp}/preheat"   # non-root test runs
+/bin/mkdir -p "$STATE_DIR" 2>/dev/null
+J=$(/usr/bin/AssetCacheLocatorUtil -j 2>/dev/null)
+OUT=$(/usr/bin/python3 - "$J" "$STATE_DIR/servers-seen.json" "$STICKY_DAYS" <<'PY'
+import json, sys, datetime, os, re
+raw, state_path, days = sys.argv[1], sys.argv[2], int(sys.argv[3])
+today = datetime.date.today()
+try: state = json.load(open(state_path))
+except Exception: state = {}
+try: d = json.loads(raw)
+except Exception: d = {}
+res = d.get("results", {}); sysr = res.get("system", {})
+servers = (sysr.get("refreshed servers") or sysr.get("saved servers") or {}).get("shared caching") or []
+reach = set(res.get("reachability") or [])
+now = {}
+for s in servers:
+    g = s.get("guid") or "?"; hp = s.get("hostport", "")
+    now[g] = f"{g} {hp} {'healthy' if s.get('healthy') else 'unhealthy'} {'reachable' if hp in reach else 'unreachable'}" + (" favored" if s.get("favored") else "")
+    state[g] = {"hostport": hp, "last_seen": today.isoformat()}
+lines = list(now.values())
+for g, e in sorted(state.items()):
+    try: seen = datetime.date.fromisoformat(e.get("last_seen", ""))
+    except ValueError: continue
+    if (today - seen).days > days: continue
+    if g not in now: lines.append(f"{g} {e.get('hostport','')} last-seen {seen.isoformat()}")
+state = {g: e for g, e in state.items() if e.get("last_seen", "") >= (today - datetime.timedelta(days=days)).isoformat()}
+try: json.dump(state, open(state_path, "w"))
+except Exception: pass
+def ranges(v):
+    """The tool's range lists, whatever their nesting, as 'a-b,c'."""
+    ip = lambda x: isinstance(x, str) and re.fullmatch(r"[0-9A-Fa-f.:]+(-[0-9A-Fa-f.:]+)?(/\d+)?", x.strip())
+    out = []
+    def walk(x):
+        if ip(x): out.append(x.strip())
+        elif isinstance(x, dict):
+            first = next((x[k] for k in ("first", "start", "low", "begin", "from") if ip(x.get(k))), None)
+            last = next((x[k] for k in ("last", "end", "high", "to") if ip(x.get(k))), None)
+            if first: out.append(first if not last or last == first else f"{first}-{last}")
+            else:
+                for val in x.values(): walk(val)
+        elif isinstance(x, (list, tuple)):
+            if len(x) == 2 and all(ip(i) and "-" not in i for i in x): out.append(f"{x[0]}-{x[1]}" if x[0] != x[1] else x[0])
+            else:
+                for i in x: walk(i)
+    walk(v)
+    return ",".join(dict.fromkeys(out))
+pub = ranges(sysr.get("refreshed public IP address ranges")) or ranges(sysr.get("saved public IP address ranges"))
+fav = ranges(sysr.get("refreshed favored server ranges")) or ranges(sysr.get("saved favored server ranges"))
+if lines and (pub or fav):
+    lines.append("dns: " + "; ".join(x for x in (f"public {pub}" if pub else "", f"favored {fav}" if fav else "") if x))
+print("\n".join(lines) if lines else "None found")
+PY
+)
+echo "<result>${OUT:-Unknown}</result>"
diff --git a/sales/preheat/ea/ea-content-cache-status.sh b/sales/preheat/ea/ea-content-cache-status.sh
new file mode 100644
index 0000000..3b8f222
--- /dev/null
+++ b/sales/preheat/ea/ea-content-cache-status.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# Jamf Pro Extension Attribute: Content Caching - Status
+# Data type: String.  Runs as root at inventory time.
+# Values:  "Not a content cache"
+#        | "Active; guid <GUID>; ip 10.0.0.2; port 49152; public 203.0.113.5; free 511 GB; used 18.4 GB; status OK"
+#        | "Inactive (<reason>); guid <GUID>"      caching is on and not serving: not registered, suspended, LOWSPACE
+#        | "Inactive (LOWSPACE; caching switched itself off); guid <GUID>"      its storage volume is missing, renamed or full
+# First word is the contract for Smart Groups: Active, Inactive, Not.
+# Jamf collects the same facts on its own (the Content Caching section of the inventory record), but with a command it
+# sends just after inventory, so a Smart Group on Jamf's criteria is one inventory behind. This EA is worked out during
+# inventory: the groups that raise alerts are built on it. The admin scripts read Jamf's section and DDM as well.
+# The guid is what client Macs report in "Content Caching - Servers Found", so the two can be joined.
+J=$(/usr/bin/AssetCacheManagerUtil -j status 2>/dev/null)
+if [[ -z "$J" ]]; then echo "<result>Unknown (AssetCacheManagerUtil failed)</result>"; exit 0; fi
+OUT=$(/usr/bin/python3 - "$J" <<'PY'
+import json,sys
+r=json.loads(sys.argv[1]).get("result",{})
+gb=lambda b: f"{(b or 0)/1e9:.1f} GB"
+guid=r.get("ServerGUID") or "?"
+if not r.get("Activated"):
+    # A Mac that never was a cache reports status OK. One whose storage vanished switches itself off and reports a problem.
+    st=r.get("CacheStatus") or "OK"
+    print("Not a content cache" if st=="OK" else f"Inactive ({st}; caching switched itself off); guid {guid}"); sys.exit()
+if not r.get("Active"):
+    why="; ".join(x for x in (r.get("CacheStatus") or "?", r.get("RegistrationError") or r.get("StartupStatus") or "") if x and x!="OK") or "not running"
+    print(f"Inactive ({why}); guid {guid}"); sys.exit()
+ips=",".join(r.get("PrivateAddresses") or []) or "?"
+print(f"Active; guid {r.get('ServerGUID','?')}; ip {ips}; port {r.get('Port') or '?'}; public {r.get('PublicAddress') or '?'}; free {gb(r.get('CacheFree'))}; used {gb(r.get('ActualCacheUsed', r.get('CacheUsed')))}; status {r.get('CacheStatus')}")
+PY
+)
+echo "<result>${OUT:-Unknown}</result>"
diff --git a/sales/preheat/terraform/README.md b/sales/preheat/terraform/README.md
new file mode 100644
index 0000000..d4f53ba
--- /dev/null
+++ b/sales/preheat/terraform/README.md
@@ -0,0 +1,55 @@
+<!-- Copyright 2026, Jamf Software LLC. -->
+# Preheat as a Terraform module
+
+Everything [Jamf setup](../docs/SETUP.md#jamf-setup) does by hand or with the `admin/*.py`
+scripts, as one `terraform apply`: the six computer extension attributes (five scripts, one text
+field), the mobile device extension attribute, the ten Smart Groups, the labels script and its
+policy. The EA and script bodies are read from `ea/` and `admin/` at plan time, so this folder is
+also how a change to a script reaches Jamf.
+
+Uses Jamf's own provider, [jamf/jamfplatform](https://registry.terraform.io/providers/jamf/jamfplatform),
+which talks to the Jamf Platform API gateway, not to your Jamf Pro server. So the credential is
+not a Jamf Pro API role and client: it is an **API integration registered in Jamf Account**
+([account.jamf.com](https://account.jamf.com)). Register it against your **platform environment**
+(the scope cannot be changed afterwards, and it is the only scope that can also reach Blueprints),
+note the client ID, secret and environment ID, and tick these permissions. Jamf Account's picker
+lists them by category and name with a box per action:
+
+| Category | Permission | Actions | For |
+|---|---|---|---|
+| Inventory | Device extension attributes | Create, Read, Update, Delete | the seven EAs |
+| Inventory | Device groups | Create, Read, Update, Delete | the Smart Groups |
+| Admin identity and access | LDAP / cloud IdP | Read | the provider reads this when saving a smart computer group |
+| Deployment | Scripts | Create, Read, Update, Delete | the labels script |
+| Deployment | Policies | Create, Read, Update, Delete | the labels policy |
+| Deployment | Blueprints | Create, Read, Update, Delete | only if you add Blueprints to the module later |
+
+The `admin/*.py` scripts keep using the Jamf Pro API client described in [Setup](../docs/SETUP.md); the
+two credentials are unrelated, and `import.sh` needs both.
+
+    export JAMFPLATFORM_BASE_URL=https://us.api.jamfcloud.com      # or eu, apac
+    export JAMFPLATFORM_CLIENT_ID=...
+    export JAMFPLATFORM_CLIENT_SECRET=...
+    export JAMFPLATFORM_ENVIRONMENT_ID=...
+    cd terraform
+    cp terraform.tfvars.example terraform.tfvars
+    terraform init
+    terraform plan
+    terraform apply
+
+**A tenant that already has Preheat installed** (by hand, or by the admin scripts): run
+`bash import.sh` after `terraform init` and before the first `plan`. It looks each object up by name
+through the Jamf Pro API and imports it, so the first apply reconciles instead of failing on
+duplicate names. Expect a small diff on descriptions.
+
+**Per-office groups**: once a cache server shows its Server GUID in Jamf (Content Caching section of its inventory), add it to `cache_servers`
+in `terraform.tfvars` and apply again; the two "served by" groups appear.
+
+Not managed here, on purpose: the API client itself (a chicken-and-egg problem: Terraform needs
+credentials to make credentials), the Blueprints (they are yours to design per rollout; the
+provider has `jamfplatform_blueprints_blueprint` when you want them in code too), and the SMTP and
+notification settings.
+
+Status: written 2026-09-24 against the provider's published schemas, not yet applied to a tenant,
+because this lab has no Platform API integration yet. `terraform validate` needs the provider
+downloaded (`terraform init`), which needs no credentials.
diff --git a/sales/preheat/terraform/extension_attributes.tf b/sales/preheat/terraform/extension_attributes.tf
new file mode 100644
index 0000000..2019a0c
--- /dev/null
+++ b/sales/preheat/terraform/extension_attributes.tf
@@ -0,0 +1,58 @@
+# The five script extension attributes, each one the file of the same name in ea/.
+# Jamf runs the copy stored in the EA, so a change to a file here is a change to the EA on the next apply.
+
+locals {
+  # The name of each EA in Jamf. The admin scripts find them by these names; do not change them.
+  ea_names = {
+    "content-cache-status"          = "Content Caching - Status"
+    "content-cache-servers-found"   = "Content Caching - Servers Found"
+    "content-cache-macos-assets"    = "Content Caching - macOS Assets"
+    "content-cache-decoded"         = "Content Caching - Cached Updates"
+    "content-cache-effectiveness"   = "Content Caching - Effectiveness"
+    "content-cache-macos-readiness" = "Content Caching - macOS Readiness"
+    "content-cache-server"          = "Content Caching - Server"
+  }
+  ea_scripts = {
+    "content-cache-status"        = "ea-content-cache-status.sh"
+    "content-cache-servers-found" = "ea-content-cache-servers-found.sh"
+    "content-cache-macos-assets"  = "ea-content-cache-macos-assets.sh"
+    "content-cache-decoded"       = "ea-content-cache-decoded.sh"
+    "content-cache-effectiveness" = "ea-content-cache-effectiveness.sh"
+  }
+  ea_descriptions = {
+    "content-cache-status"        = "Whether this Mac runs content caching: Active with guid, addresses, port and space, or Inactive with the reason. Worked out during inventory, so the Smart Groups that raise alerts are built on it."
+    "content-cache-servers-found" = "Which cache server(s) this Mac would use, as macOS decides, remembered for 90 days."
+    "content-cache-macos-assets"  = "On cache servers: one line per cached OS update file, COMPLETE or PARTIAL nn%, with Apple's path. The machine key."
+    "content-cache-decoded"       = "On cache servers: the same list with human names (version, build, full or delta, models), from labels.json kept current by the labels policy."
+    "content-cache-effectiveness" = "On cache servers: GOOD/FAIR/LOW/NEW share of delivered bytes that did not come from Apple; WIPED for 3 days after the cache lost its content."
+  }
+}
+
+resource "jamfplatform_pro_computer_extension_attribute" "script" {
+  for_each          = local.ea_scripts
+  name              = local.ea_names[each.key]
+  description       = local.ea_descriptions[each.key]
+  data_type         = "STRING"
+  input_type        = "SCRIPT"
+  inventory_display = "EXTENSION_ATTRIBUTES"
+  enabled           = true
+  script            = file("${path.module}/../ea/${each.value}")
+}
+
+# Filled by admin/readiness-check.py --write, not collected by the Mac.
+resource "jamfplatform_pro_computer_extension_attribute" "readiness" {
+  name              = local.ea_names["content-cache-macos-readiness"]
+  description       = "Written by admin/readiness-check.py: READY / PARTIAL / NOT READY for the devices this cache server serves, then details and the time of the last check."
+  data_type         = "STRING"
+  input_type        = "TEXT"
+  inventory_display = "EXTENSION_ATTRIBUTES"
+}
+
+# Mobile devices cannot run scripts; the admin script writes which server each one matched.
+resource "jamfplatform_pro_mobile_device_extension_attribute" "server" {
+  name              = local.ea_names["content-cache-server"]
+  description       = "Written by admin/readiness-check.py --write: the cache server(s) this device would use, matched by public IP the way Apple's locator does, remembered for 90 days; or None found."
+  data_type         = "STRING"
+  input_type        = "TEXT"
+  inventory_display = "EXTENSION_ATTRIBUTES"
+}
diff --git a/sales/preheat/terraform/import.sh b/sales/preheat/terraform/import.sh
new file mode 100755
index 0000000..3ec595e
--- /dev/null
+++ b/sales/preheat/terraform/import.sh
@@ -0,0 +1,40 @@
+#!/bin/bash
+# Copyright 2026, Jamf Software LLC.
+# This work is licensed under the terms of the Jamf Source Available License
+# https://github.com/jamf/scripts/blob/main/LICENCE.md
+# import.sh: bring a Jamf Pro tenant that already has Preheat's objects (created by hand or by the
+# admin/*.py scripts) under Terraform, so the first apply changes nothing instead of failing on
+# duplicate names. Read-only against Jamf; writes only Terraform state.
+#   cd terraform && terraform init && bash import.sh
+# Needs the same Jamf Pro API client the admin scripts use (keychain or JAMF_* env vars), with the
+# Read privileges the doctor checks, plus the Platform API credentials Terraform itself needs.
+set -u
+cd "$(dirname "$0")"
+python3 - <<'PY'
+import os, sys, subprocess, json, urllib.parse
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(".")), "admin")); rc = __import__("readiness-check")
+j = rc.jamf_from_credentials()
+def imp(addr, id_):
+    if not id_: print(f"skip   {addr}: not in Jamf"); return
+    r = subprocess.run(["terraform", "import", addr, str(id_)], capture_output=True, text=True)
+    print(("import " if r.returncode == 0 else "FAILED ") + f"{addr} <- {id_}" + ("" if r.returncode == 0 else "\n" + r.stderr[-300:]))
+eas = {e["name"]: e["id"] for e in j.call("/api/v1/computer-extension-attributes?page=0&page-size=500")["results"]}
+for k, name in (("content-cache-status", rc.EA_STATUS), ("content-cache-servers-found", rc.EA_FOUND), ("content-cache-macos-assets", rc.EA_ASSETS),
+                ("content-cache-decoded", rc.EA_DECODED), ("content-cache-effectiveness", rc.EA_EFFECT)):
+    imp(f'jamfplatform_pro_computer_extension_attribute.script["{k}"]', eas.get(name))
+imp("jamfplatform_pro_computer_extension_attribute.readiness", eas.get(rc.EA_READY))
+meas = {e["name"]: e["id"] for e in j.call("/api/v1/mobile-device-extension-attributes?page=0&page-size=500")["results"]}
+imp("jamfplatform_pro_mobile_device_extension_attribute.server", meas.get(rc.EA_MOBILE_SERVER))
+groups = {g["name"]: g["id"] for g in j.call("/api/v2/computer-groups/smart-groups?page=0&page-size=1000")["results"]}
+for n in ("Content Caching - Servers", "Content Caching - Ready for OS push", "Content Caching - Partially ready", "Content Caching - Not ready",
+          "Content Caching - Inactive or broken", "Content Caching - Low on space", "Content Caching - Low benefit", "Content Caching - Wiped recently", "Macs with no content cache"):
+    imp(f'jamfplatform_pro_smart_computer_group.preheat["{n}"]', groups.get(n))
+mg = {(g.get("groupName") or g.get("name")): (g.get("groupId") or g.get("id")) for g in j.call("/api/v2/mobile-device-groups/smart-groups?page=0&page-size=1000")["results"]}
+imp("jamfplatform_pro_smart_mobile_device_group.no_cache", mg.get("Mobile devices with no content cache"))
+scripts = {s["name"]: s["id"] for s in j.call("/api/v1/scripts?page=0&page-size=500")["results"]}
+imp("jamfplatform_pro_script.labels", scripts.get("preheat-labels.py"))
+pols = {p["name"]: p["id"] for p in j.call("/JSSResource/policies")["policies"]}
+imp("jamfplatform_pro_policy.labels", pols.get("Preheat - Refresh cache labels"))
+print("\nPer-office 'served by' groups are keyed by the label you give in var.cache_servers; import them by hand, e.g.\n"
+      "  terraform import 'jamfplatform_pro_smart_computer_group.served_by[\"Office X\"]' <group id>")
+PY
diff --git a/sales/preheat/terraform/labels_policy.tf b/sales/preheat/terraform/labels_policy.tf
new file mode 100644
index 0000000..2445568
--- /dev/null
+++ b/sales/preheat/terraform/labels_policy.tf
@@ -0,0 +1,30 @@
+# The script that names cached files, and the policy that runs it on every cache server at check-in.
+# No Jamf credentials on the server: the script only asks Apple's public lookup service.
+
+resource "jamfplatform_pro_script" "labels" {
+  name            = "preheat-labels.py"
+  info            = "Names the OS update files a content cache holds. No Jamf credentials. See the preheat README."
+  notes           = "Managed by Terraform (preheat/terraform)."
+  priority        = "AFTER"
+  script_contents = file("${path.module}/../admin/preheat-labels.py")
+}
+
+resource "jamfplatform_pro_policy" "labels" {
+  general = {
+    name            = "Preheat - Refresh cache labels"
+    enabled         = var.labels_policy_enabled
+    frequency       = "Ongoing"
+    trigger_checkin = true
+  }
+  scope = {
+    targets = {
+      computer_group_ids = [jamfplatform_pro_smart_computer_group.preheat["Content Caching - Servers"].id]
+    }
+  }
+  scripts = {
+    scripts = [{ id = jamfplatform_pro_script.labels.id, priority = "After" }]
+  }
+  maintenance = {
+    update_inventory = true
+  }
+}
diff --git a/sales/preheat/terraform/outputs.tf b/sales/preheat/terraform/outputs.tf
new file mode 100644
index 0000000..fac8b0d
--- /dev/null
+++ b/sales/preheat/terraform/outputs.tf
@@ -0,0 +1,13 @@
+output "extension_attribute_ids" {
+  description = "Jamf Pro IDs of the computer EAs, by short name."
+  value       = merge({ for k, ea in jamfplatform_pro_computer_extension_attribute.script : k => ea.id }, { "content-cache-macos-readiness" = jamfplatform_pro_computer_extension_attribute.readiness.id })
+}
+
+output "smart_group_ids" {
+  description = "Jamf Pro IDs of the Smart Computer Groups, by name."
+  value       = { for k, g in jamfplatform_pro_smart_computer_group.preheat : k => g.id }
+}
+
+output "labels_policy_id" {
+  value = jamfplatform_pro_policy.labels.id
+}
diff --git a/sales/preheat/terraform/provider.tf b/sales/preheat/terraform/provider.tf
new file mode 100644
index 0000000..e7443ff
--- /dev/null
+++ b/sales/preheat/terraform/provider.tf
@@ -0,0 +1,3 @@
+# Credentials come from the environment (JAMFPLATFORM_BASE_URL, _CLIENT_ID, _CLIENT_SECRET, _ENVIRONMENT_ID);
+# the block only has to exist. A Platform API integration from Jamf Account, not a Jamf Pro API client.
+provider "jamfplatform" {}
diff --git a/sales/preheat/terraform/smart_groups.tf b/sales/preheat/terraform/smart_groups.tf
new file mode 100644
index 0000000..c02101c
--- /dev/null
+++ b/sales/preheat/terraform/smart_groups.tf
@@ -0,0 +1,92 @@
+# The Smart Groups the dashboard, alerts and Blueprints read. Every rule matches a word of an EA value,
+# which is why those words never change. Jamf's own "Content Caching - ..." criteria are not used:
+# Jamf collects that section just after inventory, so a group built on it is one inventory behind.
+
+locals {
+  ea_status  = jamfplatform_pro_computer_extension_attribute.script["content-cache-status"].name
+  ea_found   = jamfplatform_pro_computer_extension_attribute.script["content-cache-servers-found"].name
+  ea_effect  = jamfplatform_pro_computer_extension_attribute.script["content-cache-effectiveness"].name
+  ea_ready   = jamfplatform_pro_computer_extension_attribute.readiness.name
+  ea_mserver = jamfplatform_pro_mobile_device_extension_attribute.server.name
+
+  computer_groups = {
+    "Content Caching - Servers" = {
+      description = "Macs running Apple content caching, serving or not (status EA starts with Active or Inactive)."
+      criteria    = [{ name = local.ea_status, search_type = "like", value = "Active" }]
+    }
+    "Content Caching - Ready for OS push" = {
+      description = "Cache servers whose local devices' next OS update is fully cached (readiness EA READY)."
+      criteria = [
+        { name = local.ea_ready, search_type = "like", value = "READY" },
+        { name = local.ea_ready, search_type = "not like", value = "NOT READY", and_or = "and" },
+      ]
+    }
+    "Content Caching - Partially ready" = {
+      description = "Cache servers with some, not all, needed OS files cached."
+      criteria    = [{ name = local.ea_ready, search_type = "like", value = "PARTIAL" }]
+    }
+    "Content Caching - Not ready" = {
+      description = "Cache servers missing every needed OS file."
+      criteria    = [{ name = local.ea_ready, search_type = "like", value = "NOT READY" }]
+    }
+    "Content Caching - Inactive or broken" = {
+      description = "Caching turned on but not serving (registration failed, low space, data path missing)."
+      criteria    = [{ name = local.ea_status, search_type = "like", value = "Inactive" }]
+    }
+    "Content Caching - Low on space" = {
+      description = "Caches that report LOWSPACE: the cache volume is nearly full, missing or renamed. A cache that loses its volume switches itself off, and still shows here."
+      criteria    = [{ name = local.ea_status, search_type = "like", value = "LOWSPACE" }]
+    }
+    "Content Caching - Low benefit" = {
+      description = "Cache servers that re-serve under 30% of what they download: few devices use them, or devices cannot reach them (VPN, wrong network)."
+      criteria    = [{ name = local.ea_effect, search_type = "like", value = "LOW " }]
+    }
+    "Content Caching - Wiped recently" = {
+      description = "Cache servers that lost more than 90% of their content in the last 3 days: almost always a failed registration with Apple (VPN on the server, blocked egress, changed public IP)."
+      criteria    = [{ name = local.ea_effect, search_type = "like", value = "WIPED " }]
+    }
+    "Macs with no content cache" = {
+      description = "Macs that will download OS updates straight from Apple (locator found no cache in 90 days)."
+      criteria    = [{ name = local.ea_found, search_type = "is", value = "None found" }]
+    }
+  }
+}
+
+resource "jamfplatform_pro_smart_computer_group" "preheat" {
+  for_each    = local.computer_groups
+  name        = each.key
+  description = each.value.description
+  site_id     = var.site_id
+  criteria = [
+    for i, c in each.value.criteria : {
+      name        = c.name
+      search_type = c.search_type
+      value       = c.value
+      and_or      = i == 0 ? null : lookup(c, "and_or", "and")
+    }
+  ]
+}
+
+resource "jamfplatform_pro_smart_mobile_device_group" "no_cache" {
+  name        = "Mobile devices with no content cache"
+  description = "iPads, iPhones and Apple TVs that will download OS updates straight from Apple."
+  site_id     = var.site_id
+  criteria    = [{ name = local.ea_mserver, search_type = "is", value = "None found" }]
+}
+
+# One pair per office, from var.cache_servers.
+resource "jamfplatform_pro_smart_computer_group" "served_by" {
+  for_each    = var.cache_servers
+  name        = "Macs served by ${each.key} cache"
+  description = "Macs whose locator reports cache server ${each.value.guid}."
+  site_id     = var.site_id
+  criteria    = [{ name = local.ea_found, search_type = "like", value = each.value.guid }]
+}
+
+resource "jamfplatform_pro_smart_mobile_device_group" "served_by" {
+  for_each    = var.cache_servers
+  name        = "Mobile devices served by ${each.key} cache"
+  description = "Mobile devices matched (by public IP) to cache server ${each.value.guid}."
+  site_id     = var.site_id
+  criteria    = [{ name = local.ea_mserver, search_type = "like", value = each.value.guid }]
+}
diff --git a/sales/preheat/terraform/terraform.tfvars.example b/sales/preheat/terraform/terraform.tfvars.example
new file mode 100644
index 0000000..db66da1
--- /dev/null
+++ b/sales/preheat/terraform/terraform.tfvars.example
@@ -0,0 +1,10 @@
+# Copy to terraform.tfvars and edit. Credentials go in the environment, never here:
+#   export JAMFPLATFORM_BASE_URL=https://us.api.jamfcloud.com
+#   export JAMFPLATFORM_CLIENT_ID=...  JAMFPLATFORM_CLIENT_SECRET=...  JAMFPLATFORM_ENVIRONMENT_ID=...
+
+# One entry per office once its cache server's status EA has reported a guid.
+cache_servers = {
+  # "Office X" = { guid = "AAAA1111-2222-3333-4444-0FF1CE000001" }
+}
+
+labels_policy_enabled = true
diff --git a/sales/preheat/terraform/variables.tf b/sales/preheat/terraform/variables.tf
new file mode 100644
index 0000000..171e60e
--- /dev/null
+++ b/sales/preheat/terraform/variables.tf
@@ -0,0 +1,19 @@
+variable "cache_servers" {
+  description = "Per-office cache servers to make \"served by\" groups for: label (used in the group name) and the server GUID from the Content Caching section of its inventory. Leave empty on first apply and fill in once the status EA has reported."
+  type = map(object({
+    guid = string
+  }))
+  default = {}
+}
+
+variable "labels_policy_enabled" {
+  description = "Whether the policy that names cached files on each cache server is enabled."
+  type        = bool
+  default     = true
+}
+
+variable "site_id" {
+  description = "Jamf Pro site for every object, -1 for none."
+  type        = string
+  default     = "-1"
+}
diff --git a/sales/preheat/terraform/versions.tf b/sales/preheat/terraform/versions.tf
new file mode 100644
index 0000000..6f7921b
--- /dev/null
+++ b/sales/preheat/terraform/versions.tf
@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.8"
+  required_providers {
+    jamfplatform = {
+      source  = "jamf/jamfplatform"
+      version = ">= 0.29"
+    }
+  }
+}