docs(rules): document observability limits of the ZTD known-issue rules

The agent is normally installed by an IME platform script AFTER MDM
enrollment succeeded, so pre-enrollment failures (enrollment blockers,
TPM attestation) are invisible in the normal flow — no enrollment means
no agent and no authenticable session. Await-enrollment mode does not
help either: the binary only polls for the MDM certificate and cannot
authenticate without it. Only bootstrap-token deployments (one pilot
customer) can report pre-MDM.

- New Observability section in docs/agent/autopilot-ztd-diagnostics.md
  with a per-rule visibility matrix (normal / bootstrap / await) and the
  follow-up option of backfilling Autopilot-channel error records
- ANALYZE-ENRL-003/004 descriptions state the limitation explicitly so
  portal users understand why these rules rarely fire

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/agent/autopilot-ztd-diagnostics.md

@@ -84,6 +84,28 @@ blank cache.
 | `*.microsoftaik.azure.net` (+ per-vendor EK cert URLs) | TPM attestation for self-deploying/pre-provisioning. | not probed |
 | `lgmsapeweu.blob.core.windows.net` | Intune automatic diagnostics upload. | deliberately not probed (decision 2026-07-16: not mission-critical) |
 
+# Observability — when the agent can actually see these errors
+
+The agent's install timing bounds what the known-issue rules can ever observe. In the
+normal deployment model the agent is installed by an **Intune platform script via IME —
+i.e. only AFTER MDM enrollment succeeded**. Everything that happens before that point
+(profile download, TPM attestation in self-deploying/pre-provisioning, the MDM enrollment
+handshake itself) is over before our process exists.
+
+| Failure class | Normal flow (IME install) | Bootstrap token mode | Await-enrollment mode |
+| --- | --- | --- | --- |
+| Enrollment blocked (0x80180014/18, 0xC1036501, 0x801C03F3 → ANALYZE-ENRL-004) | **Invisible** — no enrollment ⇒ no agent, no session. | **Visible** — the bootstrap token exists precisely to report pre-MDM (as of 2026-07: one customer piloting). | **Invisible to the backend** — the agent binary is present but only polls for the MDM certificate; without the cert it cannot authenticate, and monitoring starts only after the cert appears. A hard blocker ends in the await timeout (default 480 min) with nothing uploaded. |
+| TPM attestation (ANALYZE-ENRL-003) | **Almost never live** — attestation precedes enrollment. Retry-then-success leaves the earlier errors in the Autopilot channel, but the continuous watcher is live-only and the startup backfill targets ManagementService 509 only, so they are not forwarded. | Visible. | Same limits as normal flow once monitoring starts. |
+| Hybrid-join 0x80004005 (ANALYZE-ENRL-005) | **Visible** — the ODJ/hybrid phase runs during device ESP while the agent is active. | Visible. | Visible after cert arrival. |
+| Clock skew (ANALYZE-DEV-007) | **Always** — ntp_time_check is our own event. | Always. | Always. |
+
+The rules stay enabled despite the narrow normal-flow windows: they are evidence-gated
+(zero cost when the codes never appear) and they future-proof the bootstrap and
+await-enrollment paths. Known follow-up option: extend the ModernDeploymentTracker
+startup backfill to also replay Autopilot-channel Error-level records (807/809/815/908,
+171/172) from before agent start — that would make the retry-then-success TPM case and
+late-visible ZTD errors observable in the normal flow too.
+
 # Schema — Error codes (backend known-issue map)
 
 Codes documented in the known-issues / troubleshooting-FAQ pages that appear in ESP/enrollment

rules/analyze/ANALYZE-ENRL-003.json

@@ -2,7 +2,7 @@
   "$schema": "../schema/analyze-rule.schema.json",
   "ruleId": "ANALYZE-ENRL-003",
   "title": "TPM Attestation Failure — Known Error Code",
-  "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+  "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Observability: attestation precedes MDM enrollment, so in the normal deployment model (agent installed via IME after enrollment) these codes are rarely visible — the rule primarily serves bootstrap-token deployments. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
   "severity": "high",
   "category": "enrollment",
   "version": "1.0.0",

rules/analyze/ANALYZE-ENRL-004.json

@@ -2,7 +2,7 @@
   "$schema": "../schema/analyze-rule.schema.json",
   "ruleId": "ANALYZE-ENRL-004",
   "title": "MDM Enrollment Blocked — Known Error Code",
-  "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+  "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Observability: a blocked MDM enrollment normally means no agent gets installed at all (IME install happens after enrollment) — this rule can realistically only fire for bootstrap-token deployments (pre-MDM reporting) or mixed retry scenarios. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
   "severity": "high",
   "category": "enrollment",
   "version": "1.0.0",

rules/dist/analyze-rules.json

@@ -1317,7 +1317,7 @@
     {
       "ruleId": "ANALYZE-ENRL-003",
       "title": "TPM Attestation Failure — Known Error Code",
-      "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+      "description": "A TPM-attestation-related error code documented in the Microsoft Autopilot known-issues list was observed (0x800705B4, 0x801C03EA, 0x81039001, 0x81039023, 0x81039024, 0x80070490). These block self-deploying and pre-provisioning deployments during 'Securing your hardware'. Observability: attestation precedes MDM enrollment, so in the normal deployment model (agent installed via IME after enrollment) these codes are rarely visible — the rule primarily serves bootstrap-token deployments. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
       "severity": "high",
       "category": "enrollment",
       "version": "1.0.0",
@@ -1402,7 +1402,7 @@
     {
       "ruleId": "ANALYZE-ENRL-004",
       "title": "MDM Enrollment Blocked — Known Error Code",
-      "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+      "description": "An enrollment-blocking error code documented in the Microsoft Autopilot known-issues/troubleshooting pages was observed (0x80180014, 0x80180018, 0xC1036501, 0x801C03F3, 0x80070774). Each has a specific, documented cause and fix. Observability: a blocked MDM enrollment normally means no agent gets installed at all (IME install happens after enrollment) — this rule can realistically only fire for bootstrap-token deployments (pre-MDM reporting) or mixed retry scenarios. See docs/agent/autopilot-ztd-diagnostics.md (Observability section).",
       "severity": "high",
       "category": "enrollment",
       "version": "1.0.0",