Agent Host changes for agents/gather-rule-exitcode-info-update (#151 )

Agent Host changes for agents/improve-changelog-promotion-ui (#152 )
Agent Host changes for agents/timeline-search-enhancement (#150 )
2026-10-25 05:00:07 +00:00 · 2026-09-08 14:57:30 +02:00 · 2026-09-08 14:57:11 +02:00 · 2026-09-08 14:47:30 +02:00 · 2026-09-08 14:46:15 +02:00 · 2026-09-08 13:07:51 +02:00
1664 changed files with 157783 additions and 36401 deletions
@@ -1,37 +1,42 @@
 # Agent Directives

- **Plan first.** Enter plan mode for any non-trivial task (3+ steps or an architectural decision) and write the spec before building. If something goes sideways, stop and re-plan instead of pushing on.
+- **Plan first.** Enter plan mode for any non-trivial task (3+ steps or an architectural decision) and write the spec before building. The plan file is `internal/work/plans/<slug>.md` from the first draft; the harness plan folder outside the repo is never the storage place, at most a copy for the approval dialog. If something goes sideways, stop and re-plan instead of pushing on.
 - **Use subagents liberally** for research, exploration, and parallel analysis — one focus each — to keep the main context clean.
 - **Verify before claiming done.** Run the tests, check the logs, show the evidence. Diff against `main` where behaviour could regress.
 - **Fix bugs autonomously.** Given a report, a failing test, or an error, resolve it — no hand-holding.
- **Capture corrections.** After any correction from the user, record the pattern and a preventing rule in `tasks/lessons.md`; review it at session start.
 - Read files over 500 LOC in chunks. Never treat one grep as proof of absence.

-Codex reviews your output once you are done.
+## Where knowledge lives
+
+| Content | Location | Rule |
+|---|---|---|
+| Customer documentation | separate repo `autopilotmonitor-docs` (GitBook; baked into the MCP `search_docs` corpus) | Any change ⇒ MCP redeploy. Commit in that repo (`cd` first). |
+| Technical concept docs (OKF bundle) | `internal/` — private submodule, entry point `internal/docs/index.md` | Read the index first. Concept docs only for invariants, mechanisms and architecture a later change could silently break. |
+| Decisions, including "we will not build X" | `internal/decisions.md` | One entry per decision: date, decision, why, applies-to, status. |
+| Working files, lessons, plans | `internal/work/` | Rules in `internal/CLAUDE.md`. |
+| Agent review criteria | `internal/docs/agent/architecture-principles.md` | Check every agent change against it. |
+| Private operator instructions | `internal/CLAUDE.md` | Imported at the end of this file. Absent for contributors without submodule access; nothing in it may be copied into this public repo. |
+| Infrastructure and operator scripts | `infra/` — private submodule | Bicep plus deploy/backup/migration scripts. Scripts never carry credentials; secrets come from env or a gitignored file next to the script. |
+| Skills | `.claude/commands/` — private submodule | Each skill's frontmatter says when to use it. |
+| Claude auto-memory | outside the repo, per machine | Private notes only. Anything the project must keep goes into `internal/`. |
+
+## Hard rules
+
+- Agent projects stay on .NET Framework 4.8.
+- .NET build warnings are errors; only the NU1901–NU1904 advisories remain warnings.
+- Never put real customer domains, tenant names or tenant IDs into code, tests, commits, comments or public docs.
+- Deploy order is Backend → Web → MCP. Backend deploys are `workflow_dispatch` only. Verify the deployed version before claiming anything is live.
+- Submodules (`internal/`, `infra/`, `.claude/commands/`): commit inside the submodule first, then bump the gitlink here.
+- Stage explicit file lists; never `git add -A` or a directory. Pushing is the user's call.
+- New API responses need a typed DTO plus the parity fact. MCP vocabularies are generated from the wire types, never retyped.
+- Every route belongs in the route policy catalog; every new event type goes into the MCP resource catalog.
+- The about, terms and privacy pages under `src/Web/autopilot-monitor-web/app/` state facts customers rely on: verify every claim against the code before writing it and update them in the same change as the fact they describe.

 ## Code Quality

 - Simplicity first: minimal, targeted changes. No temporary fixes — find the root cause.
 - Where architecture is flawed, state is duplicated, or patterns are inconsistent, propose and implement the structural fix. Ask what a perfectionist reviewer would reject, and fix that too.
 - On non-trivial changes, ask whether there is a more elegant way before presenting. Skip it for simple fixes — don't over-engineer.
+- English for code comments and everything that carries knowledge.

-## Task Management
-
-Keep the plan in `tasks/todo.md` as checkable items, confirm it before implementing, tick items off as you go, and add a review section when done.
-
-## Customer-Facing Claims
-
-`src/Web/autopilot-monitor-web/app/{about,terms,privacy}/page.tsx` and `autopilotmonitor-docs/trust/*` state facts customers and security reviewers rely on. They drift silently.
-
- Verify every claim against the code before writing it — never carry one forward because it was already on the page.
- Update them in the same change as: runtime/framework versions, roles, notification providers, agent deployment or lifecycle, diagnostics payload, isolation/delegation model, retention caps, sub-processors, or any default governing what is collected.
- Describe only what customers can actually use; operator-only infrastructure is not a feature.
- Trust pages: durable phrasing over exact figures, and bump their "Last reviewed" date.
-
-## Technical Docs — OKF Bundle (`docs/`)
-
-Contributor/AI-facing docs (customer docs live in the `autopilotmonitor-docs` repo). Start at `docs/index.md` before opening individual files.
-
- New durable knowledge (architecture decisions, flows, non-obvious mechanisms) → an OKF concept doc with YAML frontmatter: `type` (mandatory), plus `title`, `description`, `resource`, `tags`, `timestamp`.
- Register it in `docs/index.md`, note the change in `docs/log.md` (ISO date). `index.md` and `log.md` are reserved names.
- English, structural markdown (`# Schema`, `# Examples`, `# Citations`). Links between docs are RELATIVE — never `/`-prefixed, that breaks GitHub navigation.
+Private half of these instructions (process, working files, technical docs, operations): @../internal/CLAUDE.md
@@ -1,136 +0,0 @@
-# Autopilot-Monitor — Agent Architecture Principles
-
-The principles are **not nice-to-haves**, they are review criteria: any code
-change that violates a principle is either (a) a bug, (b) a reason to change the principle
-(with user sign-off), or (c) an explicitly documented exception with rationale.
-
---
-
-## L.1 Truth Hierarchy (immutable)
-
-`SignalLog` (input) → `Journal` (decisions) → `Snapshot` (cache) → `Projections` (derivable).
-No projection patches backwards into the journal or the signal log. On inconsistency, the
-lower layer always wins (e.g. discard the snapshot, do not "repair" the signal log).
-
-## L.2 Event Sourcing as Foundation
-
-`SignalLog` is the only input truth. The reducer is pure:
-`(oldState, signal) → (newState, transition, effects)`. The backend can re-derive at any
-time from `SignalLog`. Replay yields the same `Journal` content.
-
-## L.3 Immutable State
-
-All DTOs in the decision core are `sealed` with get-only properties. No in-place mutation.
-"Change" = new instance via `With…` method. This is the difference between "purely testable"
-and "subtle heisenbugs".
-
-## L.4 Hypothesis Model instead of Flow Plugins
-
-Fuzziness is constitutive (White-Glove, enrollment type, device-only). A single reducer with
-hypothesis fields (`Unknown/Weak/Strong/Confirmed/Rejected`), organized by scenario in partial
-classes. **No** plugin runtime, because clean flow boundaries do not match reality.
-
-## L.5 Evidence Determinism
-
-Signal-log determinism is guaranteed: same log → same outcome. Every signal carries an
-`Evidence` record with `Kind` (Raw / Derived / Synthetic) and mandatory fields. A signal
-without evidence = adapter rejection = bug.
-
-## L.6 Signal Schema Versioning
-
-Every `DecisionSignalKind` has a `SchemaVersion`. The reducer dispatches on
-`(Kind, SchemaVersion)` — old versions stay replay-capable. A new version or a new kind
-without a replay fixture in `tests/fixtures/signal-kinds/{kind}-v{n}.json` = merge block.
-
-## L.7 Timer Monopoly
-
-Only the Deadline Scheduler (the EffectRunner role) holds decision-relevant timers. Collectors,
-signal adapters and the orchestrator must not. `Task.Delay` or `new Timer(...)` in those
-layers with session-state impact = merge block. `IClock` interface + virtual clock for
-testability.
-
-## L.8 Classifier as Post-Hook Kernel Service
-
-`IClassifier` interface, swappable. The `ClassifierVerdict` flows back into the log as a
-synthetic `ClassifierVerdictIssued` signal. `InputHash` (SHA256 over classifier-relevant
-snapshot fields) is the anti-loop guard. Classifiers are not baked into the state machine.
-
-## L.9 Clean-Agent Principle on Refactors
-
-For structural refactors: build the new project in parallel to the legacy one, do not flag-
-route inside the same process. Strict separation rule: no direct reference to legacy
-projects. Code is copied, not shared. Legacy runs out, then gets removed.
-
-## L.10 Generic Telemetry Transport
-
-One spool for all telemetry types (events, signals, decision transitions). `TelemetryItemId`
-is the type-agnostic upload cursor; the type-specific counters (`Event.Sequence`,
-`SignalOrdinal`, `StepIndex`) remain storage / UI / reducer semantics. Drain guarantee:
-"coordinated + idempotent + resumable" — **not** cross-table atomic, which is not achievable
-with three separate tables anyway.
-
-## L.11 Separation: Agent Lifecycle vs Session State
-
-`DecisionState` is session-pure. Agent-process flags (crash, admin actions, boot time,
-heartbeat status) live separately in `agent-lifecycle.json`, managed by the orchestrator,
-never by the reducer. Prevents replay dilution by lifecycle events.
-
-## L.12 Flush-on-Append Persistence
-
-No batching of append operations. `FileOptions.WriteThrough` plus an explicit
-`FlushAsync(flushToDisk: true)` per append. Every successful `Append` return means: on disk.
-Durability > performance in the crash-prone OOBE context.
-
-## L.13 UI Primacy — End-Users vs Dev Tooling
-
-Product views (EventTimeline, PhaseTimeline) stay slim and stable. Debug / analysis tools
-(Inspector with DecisionGraph, SignalStream, VerifierReport) live on their own subpage behind
-an `adminMode` gate. The session-detail page does not get overloaded with dev components.
-
-## L.14 Forward Compatibility by Default
-
-Enums via `StringEnumConverter` + `UnknownFallbackEnumConverter` (unknown values → default,
-never crash). New schema fields are nullable. The `ReducerVersion` stamp per journal row
-allows older backends to read newer rows. Deletions only after a major version bump with
-user sign-off.
-
-## L.15 Test Discipline
-
-Flow / scenario tests are prioritized over structural tests. Coverage targets per component
-(DecisionCore ≥95 %, classifier 100 %, backend functions ≥85 %). A missing fixture for a
-scenario = merge block. CI threshold check is a build failure, not a warning.
-
-## L.16 Fail-Safe Reducer Exceptions
-
-Exception in the reducer → `DecisionTransition` with `DeadEndReason=reducer_exception`, state
-unchanged (fail-safe, never destroy state). Signal counts as processed (no retry loop). After
-five consecutive exceptions → the orchestrator emits
-`enrollment_failed(reason=reducer_instability)`.
-
-## L.17 Effect Error Handling by Class
-
-Three effect classes with their own strategy:
-
- **Transient** (retry with exponential backoff 100 ms / 400 ms / 1600 ms):
-  `EmitEventTimelineEntry`, `PersistSnapshot`
- **Critical** (session abort, e.g. on timer-register failure): `ScheduleDeadline`,
-  `CancelDeadline`
- **Optional** (best-effort, classifier exception → `Inconclusive` verdict, no abort):
-  `RunClassifier`
-
-Every effect failure is logged as a `DecisionTransition`.
-
-## L.18 Implementation Discipline
-
- **R1** Pre-flight plan check before every work step
- **R2** Delegate self-contained sub-tasks **and exploration** to subagents (Anthropic
-  recommendation: preserve main-context window on large refactors — quality assurance)
- **R3** Real verification (DB round-trip, index dual-write, agent signal emission) — no
-  "it compiles and runs"
- **R4** The plan is authority — deviations require user sign-off
- **R5** Out-of-scope items land in `tasks/todo.md`, not in memory
- **R6** High test coverage is a prerequisite for future refactorability, not a nice-to-have
- **R7** Code-structure discipline: small files (guideline ≤300 LoC), clear folders, partial
-  classes by scenario, check in with the user on any uncertainty (placement, naming, scope)
-
---
@@ -0,0 +1,49 @@
+name: Bug report
+description: Something does not work as documented.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Please redact tenant IDs, device names, serial numbers, and anything personal before posting.
+        For a failed enrollment in your own tenant, the fastest path is the **Report Session** button in the portal — it attaches the session context for support without exposing it here.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      options:
+        - Web portal
+        - Agent (on device)
+        - Bootstrap script / Intune deployment
+        - MCP server / AI integration
+        - Analysis rules / log patterns
+        - Backend / API
+        - Documentation
+        - Not sure
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. …
+        2. …
+  - type: input
+    id: version
+    attributes:
+      label: Agent version / portal date
+      description: Agent version from the session details, or the date you saw it in the portal.
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Relevant excerpts only, redacted. Paste text rather than screenshots of text where possible.
+      render: text
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or idea
+    url: https://github.com/okieselbach/AutopilotMonitor/discussions
+    about: Ask how something works or float a feature idea before it becomes a request.
+  - name: Documentation
+    url: https://docs.autopilotmonitor.com
+    about: Setup guides, troubleshooting, and the security FAQ.
+  - name: Security vulnerability
+    url: https://github.com/okieselbach/AutopilotMonitor/security/advisories/new
+    about: Report privately. Please never open a public issue for a security finding.
@@ -0,0 +1,34 @@
+name: Feature request
+description: Propose something Autopilot Monitor should do.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the situation, not the solution. What are you doing today instead?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: What would you like to see? Rough is fine.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Web portal
+        - Agent (on device)
+        - Analysis rules / diagnostics
+        - MCP server / AI integration
+        - Notifications / integrations
+        - Reporting
+        - Other
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
@@ -0,0 +1,55 @@
+<!doctype html>
+<html><head><meta charset="utf-8">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+<style>
+  html,body{margin:0;padding:0;}
+  body{width:1280px;height:640px;overflow:hidden;font-family:Inter,system-ui,-apple-system,"Segoe UI",sans-serif;color:#0f172a;
+    background:
+      radial-gradient(900px 600px at 105% 110%, #dcfce7 0%, rgba(220,252,231,0) 60%),
+      radial-gradient(700px 500px at -10% -10%, #e0f2fe 0%, rgba(224,242,254,0) 60%),
+      linear-gradient(180deg,#ffffff 0%,#f6f8f7 100%);
+    position:relative;}
+  .grid{position:absolute;inset:0;background-image:linear-gradient(rgba(15,23,42,.045) 1px,transparent 1px),linear-gradient(90deg,rgba(15,23,42,.045) 1px,transparent 1px);background-size:40px 40px;mask-image:linear-gradient(180deg,rgba(0,0,0,.7),rgba(0,0,0,0) 85%);}
+  .left{position:absolute;left:72px;top:0;height:640px;width:520px;display:flex;flex-direction:column;justify-content:center;z-index:2;}
+  .brand{display:flex;align-items:center;gap:14px;margin-bottom:26px;}
+  .brand svg{width:44px;height:40px;}
+  .brand span{font-size:22px;font-weight:600;letter-spacing:-.01em;color:#0f172a;}
+  h1{margin:0 0 18px;font-size:50px;line-height:1.06;font-weight:800;letter-spacing:-.035em;}
+  h1 em{font-style:normal;color:#16a34a;}
+  p.tag{margin:0 0 30px;font-size:20px;line-height:1.45;color:#475569;font-weight:400;max-width:480px;}
+  .chips{display:flex;flex-wrap:wrap;gap:10px;margin-bottom:34px;}
+  .chip{display:inline-flex;align-items:center;gap:8px;padding:8px 14px;border-radius:999px;background:#fff;border:1px solid #e2e8f0;box-shadow:0 1px 2px rgba(15,23,42,.05);font-size:15px;font-weight:500;color:#1e293b;}
+  .chip i{width:8px;height:8px;border-radius:50%;background:#22c55e;display:inline-block;}
+  .chip.b i{background:#3b82f6}.chip.p i{background:#8b5cf6}
+  .foot{display:flex;align-items:center;gap:14px;font-size:15px;color:#64748b;font-weight:500;}
+  .foot b{color:#0f172a;font-weight:600;}
+  .foot .dot{width:4px;height:4px;border-radius:50%;background:#cbd5e1;}
+  .shot{position:absolute;left:600px;top:76px;width:1000px;height:640px;border-radius:14px;background:#fff;
+    box-shadow:0 30px 80px -20px rgba(15,23,42,.35),0 0 0 1px rgba(15,23,42,.08);overflow:hidden;z-index:1;}
+  .bar{position:relative;z-index:2;height:34px;background:#f8fafc;border-bottom:1px solid #e2e8f0;display:flex;align-items:center;padding:0 14px;gap:7px;}
+  .bar i{width:10px;height:10px;border-radius:50%;background:#e2e8f0;display:inline-block;}
+  .bar .url{margin-left:12px;flex:0 0 auto;height:20px;padding:0 10px;border-radius:6px;background:#fff;border:1px solid #e2e8f0;font-size:11px;line-height:20px;color:#64748b;}
+  .shot img{position:absolute;left:-214px;top:-16px;width:1440px;height:900px;transform-origin:top left;transform:scale(.94);}
+</style></head>
+<body>
+<div class="grid"></div>
+<div class="left">
+  <div class="brand">
+    <svg viewBox="0 0 209 191" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0 180.201L208.401 190.502L188.157 76.2438L5.48363e-06 0L0 180.201Z" fill="#33B161"/></svg>
+    <span>Autopilot Monitor</span>
+  </div>
+  <h1>See every Windows<br>enrollment <em>as it happens</em></h1>
+  <p class="tag">Live session timelines, fleet health, and on-demand diagnostics for Windows Autopilot and Intune.</p>
+  <div class="chips">
+    <span class="chip"><i></i>Live session timeline</span>
+    <span class="chip b"><i></i>Fleet health</span>
+    <span class="chip p"><i></i>MCP server for AI troubleshooting</span>
+  </div>
+  <div class="foot"><b>autopilotmonitor.com</b><span class="dot"></span>Open source<span class="dot"></span>Free Community plan</div>
+</div>
+<div class="shot">
+  <div class="bar"><i></i><i></i><i></i><span class="url">portal.autopilotmonitor.com/dashboard</span></div>
+  <img src="social-preview-dashboard.png" alt="">
+</div>
+</body></html>
@@ -1,5 +1,10 @@
 version: 2

+# Grouping: every ecosystem gets one batched PR for minor/patch version
+# updates and one batched PR for security updates. Groups apply to version
+# updates only by default, so the security-updates groups are declared
+# explicitly — otherwise every advisory lands as its own PR.
+
 updates:
  - package-ecosystem: nuget
    directory: /
@@ -10,6 +15,9 @@ updates:
      dotnet:
        patterns: ['*']
        update-types: [minor, patch]
+      dotnet-security:
+        applies-to: security-updates
+        patterns: ['*']

  - package-ecosystem: npm
    directory: /src/Web/autopilot-monitor-web
@@ -20,6 +28,9 @@ updates:
      web:
        patterns: ['*']
        update-types: [minor, patch]
+      web-security:
+        applies-to: security-updates
+        patterns: ['*']
    # Major bumps are breaking and reviewed deliberately, not auto-PR'd.
    # Security updates ignore this filter, so the Security tab stays clean.
    ignore:
@@ -35,6 +46,9 @@ updates:
      mcp:
        patterns: ['*']
        update-types: [minor, patch]
+      mcp-security:
+        applies-to: security-updates
+        patterns: ['*']
    # Major bumps are breaking and reviewed deliberately, not auto-PR'd.
    # Security updates ignore this filter, so the Security tab stays clean.
    ignore:
@@ -45,3 +59,9 @@ updates:
    directory: /
    schedule:
      interval: monthly
+    groups:
+      actions:
+        patterns: ['*']
+      actions-security:
+        applies-to: security-updates
+        patterns: ['*']
@@ -65,7 +65,7 @@ function Read-Counter {
        $resp = Invoke-WebRequest -Uri $CounterUrl -Method Get -UseBasicParsing
    } catch {
        if ((Get-HttpStatus $_) -eq 404) {
-            throw "Counter blob not found at $CounterUrl. Seed it once with the last used build number: PUT the plain integer with 'x-ms-blob-type: BlockBlob' and 'If-None-Match: *'. See docs/versioning.md."
+            throw "Counter blob not found at $CounterUrl. Seed it once with the last used build number: PUT the plain integer with 'x-ms-blob-type: BlockBlob' and 'If-None-Match: *'. See internal/docs/versioning.md."
        }
        throw
    }
@@ -27,6 +27,10 @@ on:
        required: false
        type: boolean
        default: false
+      release_notes:
+        description: 'Customer-facing notes for the GitHub Release (Markdown bullets). Empty = generic fallback linking to the docs changelog'
+        required: false
+        type: string

 permissions:
  contents: write
@@ -76,12 +80,23 @@ jobs:
      - name: Reserve build number (counter blob CAS)
        id: version
        shell: pwsh
+        # Input and secret reach the script only as environment variables, never as script
+        # text: ${{ }} is substituted before pwsh parses the block, so a crafted
+        # build_number could otherwise break out of the quotes and run arbitrary code.
+        env:
+          BUILD_NUMBER_OVERRIDE: ${{ inputs.build_number }}
+          AGENT_SAS_TOKEN: ${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}
        run: |
          $override = 0
-          if ('${{ inputs.build_number }}' -ne '') { $override = [int]'${{ inputs.build_number }}' }
+          if ($env:BUILD_NUMBER_OVERRIDE -ne '') {
+            if ($env:BUILD_NUMBER_OVERRIDE -notmatch '^\d+$') {
+              throw "build_number must be a positive integer, got '$($env:BUILD_NUMBER_OVERRIDE)'"
+            }
+            $override = [int]$env:BUILD_NUMBER_OVERRIDE
+          }

          $counterUrl = "https://autopilotmonitoreu.blob.core.windows.net/agent/buildcounter-v$($env:LINE_MAJOR).txt"
-          $buildNumber = & ./.github/scripts/Request-BuildNumber.ps1 -CounterUrl $counterUrl -SasToken '${{ secrets.AZURE_BLOB_AGENT_SAS_TOKEN }}' -Override $override
+          $buildNumber = & ./.github/scripts/Request-BuildNumber.ps1 -CounterUrl $counterUrl -SasToken $env:AGENT_SAS_TOKEN -Override $override

          $csproj = Get-Content $env:CSPROJ_PATH -Raw
          if ($csproj -match '<VersionPrefix>(\d+\.\d+)</VersionPrefix>') {
@@ -313,25 +328,26 @@ jobs:
          name: version-metadata
          path: ${{ env.MANIFEST_NAME }}

+      # First-party `gh` instead of a third-party action: this job holds contents:write,
+      # id-token:write and attestations:write, so no code we do not control runs here.
+      # The "What's new" section comes ONLY from the release_notes input -- CI never
+      # composes customer-facing text from commits. An empty input writes a generic
+      # fallback that links to the docs changelog and carries the HTML-comment marker
+      # below; the operator tooling scans release bodies for that marker to find the
+      # last release with real notes, so the next noted release covers the gap.
+      # Never rename the marker. --generate-notes is not used: it lists pull requests
+      # only (Dependabot noise); the compare link to the previous tag replaces it.
      - name: Create GitHub Release
        if: inputs.create_release
-        uses: softprops/action-gh-release@v3
-        with:
-          tag_name: ${{ steps.version.outputs.tag }}
-          name: Autopilot Monitor Agent ${{ steps.version.outputs.version }}
-          body: |
-            ## Autopilot Monitor Agent ${{ steps.version.outputs.version }}
-
-            ### Installation
-            1. Download `AutopilotMonitor-Agent-v${{ steps.version.outputs.version }}.zip`
-            2. Extract to `C:\ProgramData\AutopilotMonitor\Agent\`
-            3. Run `AutopilotMonitor.Agent.exe --install` to register the Scheduled Task
-
-            ### Included Components
-            - **AutopilotMonitor.Agent.exe** - Monitoring agent (V2 release line)
-            - **AutopilotMonitor.SummaryDialog.exe** - Enrollment summary dialog (WPF)
-            - **version-v2.json** - Per-line version manifest
-
+        shell: pwsh
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ steps.version.outputs.tag }}
+          RELEASE_NAME: Autopilot Monitor Agent ${{ steps.version.outputs.version }}
+          RELEASE_PRERELEASE: ${{ inputs.prerelease }}
+          RELEASE_ZIP: ${{ steps.artifact.outputs.versioned_zip_release }}
+          RELEASE_NOTES: ${{ inputs.release_notes }}
+          RELEASE_BODY_TAIL: |
            ### Version Info
            - **Version:** ${{ steps.version.outputs.version }}
            - **Build Number:** ${{ steps.version.outputs.build_number }}
@@ -344,9 +360,42 @@ jobs:
            ```
            gh attestation verify AutopilotMonitor-Agent-v${{ steps.version.outputs.version }}.zip --repo okieselbach/AutopilotMonitor
            ```
-          draft: false
-          prerelease: ${{ inputs.prerelease }}
-          files: |
-            ${{ steps.artifact.outputs.versioned_zip_release }}
-            ${{ env.MANIFEST_NAME }}
-          generate_release_notes: true
+        run: |
+          $ErrorActionPreference = 'Stop'
+
+          $notes = "$env:RELEASE_NOTES".Trim()
+          if ($notes -eq '') {
+            $notes = "Minor enhancements and bug fixes. See the [Agent Changelog](https://docs.autopilotmonitor.com/changelog/agent-changelog) for details.`n<!-- release-notes: none -->"
+          }
+
+          # Previous release for the compare link. Fail-soft: the first release has none,
+          # and a listing hiccup must never fail a release.
+          $prevTag = ''
+          $eap = $ErrorActionPreference
+          $ErrorActionPreference = 'Continue'
+          try {
+            $prevTag = "$(gh release list --repo $env:GITHUB_REPOSITORY --limit 1 --exclude-drafts --json tagName -q '.[0].tagName' 2>$null)".Trim()
+          } catch { $prevTag = '' }
+          $ErrorActionPreference = $eap
+          $compare = ''
+          if ($prevTag -ne '' -and $prevTag -ne $env:RELEASE_TAG) {
+            $compare = "`n`n**Full changelog:** https://github.com/$env:GITHUB_REPOSITORY/compare/$prevTag...$env:RELEASE_TAG`n"
+          }
+
+          $body = "### What's new`n$notes`n`n" + "$env:RELEASE_BODY_TAIL".TrimEnd() + $compare
+          $notesFile = Join-Path $env:RUNNER_TEMP 'release-notes.md'
+          Set-Content -Path $notesFile -Value $body -Encoding utf8 -NoNewline
+
+          $ghArgs = @(
+            'release', 'create', $env:RELEASE_TAG,
+            $env:RELEASE_ZIP, $env:MANIFEST_NAME,
+            '--repo', $env:GITHUB_REPOSITORY,
+            '--target', $env:GITHUB_SHA,
+            '--title', $env:RELEASE_NAME,
+            '--notes-file', $notesFile
+          )
+          if ($env:RELEASE_PRERELEASE -eq 'true') { $ghArgs += '--prerelease' }
+
+          & gh @ghArgs
+          if ($LASTEXITCODE -ne 0) { throw "gh release create failed with exit code $LASTEXITCODE" }
+          Write-Host "Release $env:RELEASE_TAG created"
@@ -7,12 +7,78 @@ name: CI
 # The deploy workflows build but never test, so this is the only place the suites
 # actually run. It does not gate anything — main is deliberately unprotected, so a
 # red run reports rather than blocks. Read the result and follow up.
-
+#
+# Path filters: commits that only bump a private submodule gitlink (internal/, infra/,
+# .claude/commands), touch prose or edit another workflow cannot change anything the
+# suites cover, so they are skipped instead of burning ~15 runner-minutes each. A gitlink bump reports the bare
+# path ('internal', no trailing slash), which 'internal/**' does NOT match — both forms
+# are listed. GitHub skips only when EVERY changed path matches; a commit that touches
+# docs AND code still runs.
 on:
  push:
    branches: [main]
+    paths-ignore:
+      - 'internal'
+      - 'internal/**'
+      - 'infra'
+      - 'infra/**'
+      - '.claude/**'
+      - '.gitmodules'
+      - '**/*.md'
+      - 'LICENSE'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/FUNDING.yml'
+      - '.github/dependabot.yml'
+      - '.github/assets/**'
+      - '.github/codeql/**'
+      - '.github/scripts/**'
+      # Every other workflow: nothing here builds or tests anything CI covers. paths-ignore
+      # cannot negate, so they are listed one by one; ci.yml itself stays out of the list
+      # so a change to CI runs CI. A new workflow file is opt-in — add it here too.
+      - '.github/workflows/bootstrap-script-gates.yml'
+      - '.github/workflows/build-agent.yml'
+      - '.github/workflows/build-msi.yml'
+      - '.github/workflows/codeql.yml'
+      - '.github/workflows/combine-rules.yml'
+      - '.github/workflows/deploy-backend.yml'
+      - '.github/workflows/deploy-mcp.yml'
+      - '.github/workflows/deploy-web.yml'
+      - '.github/workflows/indexnow-notify.yml'
+      - '.github/workflows/oidc-login-test.yml'
+      - '.github/workflows/pester.yml'
+      - '.github/workflows/publish-scripts.yml'
  pull_request:
    branches: [main]
+    paths-ignore:
+      - 'internal'
+      - 'internal/**'
+      - 'infra'
+      - 'infra/**'
+      - '.claude/**'
+      - '.gitmodules'
+      - '**/*.md'
+      - 'LICENSE'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/FUNDING.yml'
+      - '.github/dependabot.yml'
+      - '.github/assets/**'
+      - '.github/codeql/**'
+      - '.github/scripts/**'
+      # Every other workflow: nothing here builds or tests anything CI covers. paths-ignore
+      # cannot negate, so they are listed one by one; ci.yml itself stays out of the list
+      # so a change to CI runs CI. A new workflow file is opt-in — add it here too.
+      - '.github/workflows/bootstrap-script-gates.yml'
+      - '.github/workflows/build-agent.yml'
+      - '.github/workflows/build-msi.yml'
+      - '.github/workflows/codeql.yml'
+      - '.github/workflows/combine-rules.yml'
+      - '.github/workflows/deploy-backend.yml'
+      - '.github/workflows/deploy-mcp.yml'
+      - '.github/workflows/deploy-web.yml'
+      - '.github/workflows/indexnow-notify.yml'
+      - '.github/workflows/oidc-login-test.yml'
+      - '.github/workflows/pester.yml'
+      - '.github/workflows/publish-scripts.yml'
  workflow_dispatch:

 permissions:
@@ -41,16 +107,16 @@ jobs:
        run: dotnet build AutopilotMonitor.sln --configuration Release --no-restore

      - name: Backend tests
-        run: dotnet test src/Backend/AutopilotMonitor.Functions.Tests --configuration Release --no-build --verbosity quiet
+        run: dotnet test src/Backend/AutopilotMonitor.Functions.Tests --configuration Release --no-build --verbosity quiet --logger "console;verbosity=minimal"

      - name: Agent V2 Core tests
-        run: dotnet test src/Agent/AutopilotMonitor.Agent.V2.Core.Tests --configuration Release --no-build --verbosity quiet
+        run: dotnet test src/Agent/AutopilotMonitor.Agent.V2.Core.Tests --configuration Release --no-build --verbosity quiet --logger "console;verbosity=minimal"

      - name: Decision Core tests
-        run: dotnet test src/Agent/AutopilotMonitor.DecisionCore.Tests --configuration Release --no-build --verbosity quiet
+        run: dotnet test src/Agent/AutopilotMonitor.DecisionCore.Tests --configuration Release --no-build --verbosity quiet --logger "console;verbosity=minimal"

      - name: Summary Dialog tests
-        run: dotnet test src/Agent/AutopilotMonitor.SummaryDialog.Tests --configuration Release --no-build --verbosity quiet
+        run: dotnet test src/Agent/AutopilotMonitor.SummaryDialog.Tests --configuration Release --no-build --verbosity quiet --logger "console;verbosity=minimal"

  web:
    name: Web (typecheck + tests)
@@ -143,3 +209,29 @@ jobs:
            git diff --stat
            exit 1
          fi
+
+  shared-manifests-in-sync:
+    name: Generated wire types match shared-manifests.json
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      # JSON ↔ C# parity is the dotnet job's SharedManifestParityTests; this job pins
+      # JSON ↔ generated TS (shared-manifests.generated.ts, wire-types.generated.ts and the
+      # MCP's wire-types + wire-vocabularies copies - the vocabularies are what the MCP
+      # tool input schemas derive their z.enum() from).
+      - name: Regenerate
+        run: node scripts/generate-shared-manifest-types.js
+        working-directory: src/Web/autopilot-monitor-web
+
+      - name: Fail if the generated files drifted
+        run: |
+          if ! git diff --quiet -- src/Web/autopilot-monitor-web/utils/shared-manifests.generated.ts src/Web/autopilot-monitor-web/utils/wire-types.generated.ts src/McpServer/autopilot-monitor-mcp/src/generated/wire-types.generated.ts src/McpServer/autopilot-monitor-mcp/src/generated/wire-vocabularies.generated.ts; then
+            echo "::error::Generated wire types are out of date. Run 'npm run generate:manifests' in src/Web/autopilot-monitor-web and commit the result."
+            git diff --stat
+            exit 1
+          fi
@@ -1,22 +1,75 @@
 name: CodeQL

-# Documentation-only changes cannot affect what CodeQL analyzes (C# and
-# TypeScript), so they are filtered out rather than spending ~10 minutes to
-# re-report an unchanged result. A commit that touches docs AND code still runs:
-# GitHub skips only when EVERY changed path matches the filter.
+# Documentation-only changes and private-submodule gitlink bumps (internal/, infra/,
+# .claude/commands) cannot affect what CodeQL analyzes (C# and TypeScript), so they
+# are filtered out rather than spending ~10 minutes to re-report an unchanged result.
+# A gitlink bump reports the bare path ('internal', no trailing slash), which
+# 'internal/**' does NOT match — both forms are listed. A commit that touches docs
+# AND code still runs: GitHub skips only when EVERY changed path matches the filter.
+# Same list as ci.yml except that each file leaves itself out; keep them in step.
 on:
  push:
    branches: [main]
    paths-ignore:
-      - 'docs/**'
+      - 'internal'
+      - 'internal/**'
+      - 'infra'
+      - 'infra/**'
+      - '.claude/**'
+      - '.gitmodules'
      - '**/*.md'
      - 'LICENSE'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/FUNDING.yml'
+      - '.github/dependabot.yml'
+      - '.github/assets/**'
+      - '.github/scripts/**'
+      # Every other workflow: none of them changes the C# or TypeScript CodeQL analyzes.
+      # paths-ignore cannot negate, so they are listed one by one; codeql.yml itself and
+      # .github/codeql/ stay out of the list. A new workflow file is opt-in — add it here too.
+      - '.github/workflows/bootstrap-script-gates.yml'
+      - '.github/workflows/build-agent.yml'
+      - '.github/workflows/build-msi.yml'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/combine-rules.yml'
+      - '.github/workflows/deploy-backend.yml'
+      - '.github/workflows/deploy-mcp.yml'
+      - '.github/workflows/deploy-web.yml'
+      - '.github/workflows/indexnow-notify.yml'
+      - '.github/workflows/oidc-login-test.yml'
+      - '.github/workflows/pester.yml'
+      - '.github/workflows/publish-scripts.yml'
  pull_request:
    branches: [main]
    paths-ignore:
-      - 'docs/**'
+      - 'internal'
+      - 'internal/**'
+      - 'infra'
+      - 'infra/**'
+      - '.claude/**'
+      - '.gitmodules'
      - '**/*.md'
      - 'LICENSE'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/FUNDING.yml'
+      - '.github/dependabot.yml'
+      - '.github/assets/**'
+      - '.github/scripts/**'
+      # Every other workflow: none of them changes the C# or TypeScript CodeQL analyzes.
+      # paths-ignore cannot negate, so they are listed one by one; codeql.yml itself and
+      # .github/codeql/ stay out of the list. A new workflow file is opt-in — add it here too.
+      - '.github/workflows/bootstrap-script-gates.yml'
+      - '.github/workflows/build-agent.yml'
+      - '.github/workflows/build-msi.yml'
+      - '.github/workflows/ci.yml'
+      - '.github/workflows/combine-rules.yml'
+      - '.github/workflows/deploy-backend.yml'
+      - '.github/workflows/deploy-mcp.yml'
+      - '.github/workflows/deploy-web.yml'
+      - '.github/workflows/indexnow-notify.yml'
+      - '.github/workflows/oidc-login-test.yml'
+      - '.github/workflows/pester.yml'
+      - '.github/workflows/publish-scripts.yml'
  schedule:
    # Weekly, so advisories published after a merge still surface. Deliberately
    # unfiltered — it re-analyzes the whole tree regardless of what changed, which
@@ -57,7 +110,7 @@ jobs:
          dotnet-version: '10.0.x'

      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4.37.3
+        uses: github/codeql-action/init@v4.37.9
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
@@ -68,6 +121,6 @@ jobs:
        run: dotnet build AutopilotMonitor.sln --configuration Release

      - name: Analyze
-        uses: github/codeql-action/analyze@v4.37.3
+        uses: github/codeql-action/analyze@v4.37.9
        with:
          category: /language:${{ matrix.language }}
@@ -54,14 +54,32 @@ jobs:
            ajv validate -s rules/schema/ime-log-pattern.schema.json -d "$f" --spec=draft2020 -c ajv-formats
          done

+      # guardrails.json values are baked verbatim into generated TypeScript that is
+      # auto-committed to main and shipped to the portal - the schema forbids control
+      # and line-terminator characters so a "data" PR can never become code.
+      - name: Validate Guardrails
+        run: ajv validate -s rules/schema/guardrails.schema.json -d rules/guardrails.json --spec=draft2020 -c ajv-formats
+
      - name: Combine rules into dist/
        run: node rules/scripts/combine.js

+      # Plain git instead of a third-party action: this step runs with contents:write on
+      # main, so no code we do not control gets to push. Checkout leaves the job's
+      # GITHUB_TOKEN in the remote credential helper, which is all `git push` needs.
+      # NOTE: combine.js writes THREE outputs; committing only dist/ would silently discard
+      # the two generated TS modules and leave the guardrails-in-sync CI check red.
      - name: Commit generated outputs
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-        uses: stefanzweifel/git-auto-commit-action@v7
-        with:
-          commit_message: "chore: regenerate rules/dist + generated TS from individual files"
-          # combine.js writes THREE outputs; committing only dist/ would silently discard
-          # the two generated TS modules and leave the guardrails-in-sync CI check red.
-          file_pattern: "rules/dist/* src/Web/autopilot-monitor-web/utils/guardrails.generated.ts src/McpServer/autopilot-monitor-mcp/src/rule-authoring.generated.ts"
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -- rules/dist/ \
+            src/Web/autopilot-monitor-web/utils/guardrails.generated.ts \
+            src/McpServer/autopilot-monitor-mcp/src/rule-authoring.generated.ts
+          if git diff --cached --quiet; then
+            echo "Generated outputs unchanged - nothing to commit"
+            exit 0
+          fi
+          git commit -m "chore: regenerate rules/dist + generated TS from individual files"
+          git push origin HEAD:main
@@ -22,7 +22,7 @@ jobs:
      - uses: actions/checkout@v7

      - name: Login to Azure (OIDC)
-        uses: azure/login@v3
+        uses: azure/login@7ddb5af1ef8758cf1353cf3b42f940aee27ba21c # v3
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -65,7 +65,7 @@ jobs:
        run: dotnet publish ${{ env.CSPROJ_PATH }} --configuration Release --output ./publish --no-build -p:SourceRevisionId=${{ github.sha }} -p:BuildNumber=${{ steps.version.outputs.build_number }} -p:BuildTimestampUtc=${{ steps.version.outputs.build_utc }}

      - name: Deploy to Azure Functions
-        uses: Azure/functions-action@v1
+        uses: Azure/functions-action@c5060b3b8bb1ebbcb531abd00c822ecbaa8ea656 # v1
        with:
          app-name: ${{ env.FUNCTION_APP }}
          package: ./publish
@@ -11,7 +11,11 @@ env:
  ACR_NAME: autopilotmonitoreuacr
  CONTAINER_APP_NAME: autopilotmonitor-mcp
  RESOURCE_GROUP: ${{ secrets.AZURE_MCP_RESOURCE_GROUP }}
-  IMAGE_TAG: ${{ github.sha }}
+  # Unique per RUN, not per commit: the docs corpus is baked into the image, so a
+  # docs-only redeploy at an unchanged code sha must still produce a new image
+  # reference — with a sha-only tag `az containerapp update` saw the same image
+  # and silently created no revision (2026-08-28).
+  IMAGE_TAG: ${{ github.sha }}-${{ github.run_number }}
  HEALTH_URL: https://mcp.autopilotmonitor.com/health
  VERSIONS_CONTAINER: https://autopilotmonitoreu.blob.core.windows.net/versions
  PACKAGE_JSON: src/McpServer/autopilot-monitor-mcp/package.json
@@ -28,8 +32,9 @@ jobs:
      # baked into the image as the search_docs corpus (see the Dockerfile). No
      # token is needed. Checking it out here rather than vendoring it keeps the
      # docs single-sourced — but it also means EDITING THE DOCS DOES NOT UPDATE A
-      # RUNNING SERVER; this workflow must be re-run. /health reports the SHA
-      # captured below so that staleness is checkable.
+      # RUNNING SERVER; this workflow must be re-run (IMAGE_TAG is per run so the
+      # re-run actually rolls a new revision). /health reports the SHA captured
+      # below so that staleness is checkable.
      - name: Check out documentation bundle
        uses: actions/checkout@v7
        with:
@@ -41,7 +46,7 @@ jobs:
        run: echo "sha=$(git -C mcp-docs rev-parse HEAD)" >> "$GITHUB_OUTPUT"

      - name: Login to Azure (OIDC)
-        uses: azure/login@v3
+        uses: azure/login@7ddb5af1ef8758cf1353cf3b42f940aee27ba21c # v3
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -1,5 +1,13 @@
 name: Deploy Web (Static Web App)

+# Build here, upload with the pinned SWA CLI. No third-party action sees the deploy token
+# (the CLI is Microsoft-published npm code at an exact version), the build runs on the same
+# path ci.yml tests (setup-node 22 + npm ci + next build) instead of Oryx guessing inside the
+# action's container, and the exported site is attested like the agent ZIP and the MSI.
+#
+# PR preview environments were dropped with the action: their per-PR URLs are never
+# registered as redirect URIs, so nobody could log in on them anyway.
+
 on:
  push:
    branches:
@@ -8,39 +16,61 @@ on:
      - 'src/Web/autopilot-monitor-web/**'
      - '.github/workflows/deploy-web.yml'
  workflow_dispatch:
-  pull_request:
-    types: [opened, synchronize, reopened, closed]
-    branches:
-      - main
-    paths:
-      - 'src/Web/autopilot-monitor-web/**'
-      - '.github/workflows/deploy-web.yml'
+
+permissions:
+  contents: read
+  id-token: write      # keyless Sigstore signing (artifact attestation)
+  attestations: write  # store the provenance attestation

 env:
  PORTAL_VERSION_URL: https://portal.autopilotmonitor.com/version.json
  VERSIONS_CONTAINER: https://autopilotmonitoreu.blob.core.windows.net/versions
+  WEB_DIR: src/Web/autopilot-monitor-web
+  # Exact version: `npx --package` resolves from the registry at run time, so the pin is the
+  # only thing that keeps the deploy step's code fixed. Bump deliberately.
+  SWA_CLI_VERSION: 2.0.10

 jobs:
  build_and_deploy_job:
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
-    # Dependabot PRs run without repo secrets, so the deploy token is absent.
-    # Surface it as an env var so the deploy step can gate on it — secrets
-    # cannot be referenced directly in an `if:` expression.
-    env:
-      DEPLOY_TOKEN: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
    steps:
      - uses: actions/checkout@v7
        with:
          lfs: false
          fetch-depth: 0  # Full history needed for git-based sitemap lastmod dates
-      - name: Build And Deploy
-        id: builddeploy
-        # Skip (green) instead of failing when the token is missing (Dependabot
-        # PRs); real deploys on main and internal PRs still have it.
-        if: env.DEPLOY_TOKEN != ''
-        uses: Azure/static-web-apps-deploy@v1
+
+      # The customer docs repo is the single source of the "What's new" panel: the prebuild
+      # step (scripts/whats-new/build-whats-new.js) turns changelog/*.md into
+      # public/whats-new.json and dates every bullet via git blame — hence the full history.
+      # Public repo, no token. Editing the docs does NOT update the live panel until this
+      # workflow runs again (push under src/Web/** or a manual dispatch); versions/web.json
+      # records which docs commit is live.
+      - name: Check out documentation bundle
+        uses: actions/checkout@v7
+        with:
+          repository: autopilotmonitor/autopilotmonitor-docs
+          path: whats-new-docs
+          fetch-depth: 0
+
+      - name: Resolve docs commit
+        id: docs
+        run: echo "sha=$(git -C whats-new-docs rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: ${{ env.WEB_DIR }}/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ${{ env.WEB_DIR }}
+        run: npm ci
+
+      # next.config output:'export' -- `next build` writes the static site to out/
+      # (prebuild: sync-error-codes, generate-lastmod, generate-version, whats-new).
+      - name: Build
+        working-directory: ${{ env.WEB_DIR }}
        env:
          NEXT_PUBLIC_ENTRA_CLIENT_ID: ${{ vars.NEXT_PUBLIC_ENTRA_CLIENT_ID }}
          # Dual app-reg window: previous app registration (unset = single-app behaviour)
@@ -55,28 +85,53 @@ jobs:
          # Build stamp for public/version.json (scripts/generate-version.js in prebuild);
          # the verify step below polls the deployed file for exactly this commit.
          GITHUB_SHA: ${{ github.sha }}
-        with:
-          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
-          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
-          action: "upload"
-          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
-          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
-          app_location: "src/Web/autopilot-monitor-web" # App source code path
-          api_location: "" # Api source code path - optional
-          # Static export (next.config output:'export'): Oryx runs `npm run build`
-          # and uploads the exported out/ directory as plain static files — no
-          # managed SSR runtime is provisioned anymore. (No is_static_export
-          # input on this action version; Oryx detects the export from
-          # next.config + output_location.)
-          output_location: "out" # Built app content directory - optional
-          ###### End of Repository/Build Configurations ######
+          # Docs checkout for public/whats-new.json; the prebuild fails in CI without it.
+          WHATS_NEW_DOCS_DIR: ${{ github.workspace }}/whats-new-docs
+        run: |
+          npm run build
+          test -f out/version.json || { echo "out/version.json missing - export did not run"; exit 1; }
+          test -f out/whats-new.json || { echo "out/whats-new.json missing - whats-new prebuild did not run"; exit 1; }

-      # The SWA action reporting success proves the upload, not that the production host
-      # serves the new build — verify against the live /version.json (Cache-Control:
-      # no-store via staticwebapp.config.json) before publishing the version manifest.
-      # PR builds deploy to per-PR preview environments, so only main deploys are verified.
+      # One archive of the exact bytes that get uploaded, so the attestation has a single subject.
+      - name: Package export
+        id: package
+        run: |
+          archive="portal-${GITHUB_SHA::7}.tar.gz"
+          tar -C "$WEB_DIR/out" -czf "$archive" .
+          echo "archive=$archive" >> "$GITHUB_OUTPUT"
+          sha256sum "$archive"
+
+      # Sigstore keyless provenance: binds the export digest to this workflow run (repo, ref,
+      # commit, workflow file) in a public transparency log.
+      # Verify: gh attestation verify portal-<sha>.tar.gz --repo okieselbach/AutopilotMonitor
+      - name: Attest build provenance (portal export)
+        uses: actions/attest-build-provenance@v4
+        with:
+          subject-path: ${{ steps.package.outputs.archive }}
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: portal-${{ github.sha }}
+          path: ${{ steps.package.outputs.archive }}
+
+      # Upload only -- out/ is already built. --swa-config-location points at the app root,
+      # where staticwebapp.config.json lives (next export does not copy it into out/).
+      - name: Deploy to Static Web App
+        env:
+          SWA_CLI_DEPLOYMENT_TOKEN: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
+        run: |
+          npx --yes --package "@azure/static-web-apps-cli@${SWA_CLI_VERSION}" swa deploy \
+            --app-location "$WEB_DIR" \
+            --output-location out \
+            --swa-config-location "$WEB_DIR" \
+            --env production \
+            --no-use-keychain
+
+      # The CLI reporting success proves the upload, not that the production host serves the
+      # new build -- verify against the live /version.json (Cache-Control: no-store via
+      # staticwebapp.config.json) before publishing the version manifest.
      - name: Verify deployed portal build is live
-        if: env.DEPLOY_TOKEN != '' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
        shell: pwsh
        run: |
          $expectedCommit = '${{ github.sha }}'.Substring(0, 7)
@@ -100,10 +155,10 @@ jobs:

          throw "Portal did not serve commit $expectedCommit within 5 minutes -- deployment not verified, version manifest NOT published"

-      # Cross-component deploy record, written last and only on a verified deploy —
-      # same contract as versions/backend.json and versions/mcp.json.
+      # Cross-component deploy record, written last and only on a verified deploy --
+      # same contract as versions/backend.json and versions/mcp.json. docsCommit says which
+      # docs revision the live What's new panel was generated from (as for the MCP corpus).
      - name: Publish version manifest
-        if: env.DEPLOY_TOKEN != '' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
        shell: pwsh
        run: |
          $manifest = [ordered]@{
@@ -111,6 +166,7 @@ jobs:
            commit      = '${{ github.sha }}'.Substring(0, 7)
            deployedUtc = [DateTime]::UtcNow.ToString('o')
            runId       = '${{ github.run_id }}'
+            docsCommit  = '${{ steps.docs.outputs.sha }}'.Substring(0, 7)
          } | ConvertTo-Json

          $sas = '${{ secrets.AZURE_BLOB_VERSIONS_SAS_TOKEN }}'.TrimStart('?')
@@ -119,22 +175,3 @@ jobs:
          Invoke-RestMethod -Uri $url -Method Put -Headers @{ 'x-ms-blob-type' = 'BlockBlob'; 'x-ms-blob-cache-control' = 'no-cache' } -Body $manifest -ContentType 'application/json' | Out-Null
          Write-Host "Published versions/web.json"
          Write-Host $manifest
-
-  close_pull_request_job:
-    if: github.event_name == 'pull_request' && github.event.action == 'closed'
-    runs-on: ubuntu-latest
-    name: Close Pull Request Job
-    env:
-      DEPLOY_TOKEN: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
-    steps:
-      - name: Close Pull Request
-        id: closepullrequest
-        if: env.DEPLOY_TOKEN != ''
-        uses: Azure/static-web-apps-deploy@v1
-        with:
-          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_DEPLOY_TOKEN }}
-          action: "close"
-
-
-
-
@@ -15,7 +15,7 @@ jobs:
    name: Federated login + read check
    steps:
      - name: Login to Azure (OIDC)
-        uses: azure/login@v3
+        uses: azure/login@7ddb5af1ef8758cf1353cf3b42f940aee27ba21c # v3
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
@@ -15,7 +15,7 @@ bld/
 [Ll]ogs/

 # Build counter files: the authoritative counter is the shared blob
-# (agent container, buildcounter-v{N}.txt, ETag-CAS — see docs/agent/build-counter-blob.md).
+# (agent container, buildcounter-v{N}.txt, ETag-CAS — see internal/docs/agent/build-counter-blob.md).
 # The local file is only an offline fallback for -SkipUpload/bare-dotnet smoke builds.
 buildcounter.txt

@@ -114,17 +114,10 @@ tmpclaude-*-cwd
 # Claude skills and scripts are now in a private submodule (.claude/commands/)
 # No individual file ignores needed — the submodule handles everything

-# Deployment scripts (local only — contain tokens + SAS URLs)
-scripts/Deployment/
-
-# Migration tooling (local only, vorerst) — cross-tenant storage/cert migration scripts
-scripts/Migration/
-
 # Infra: tracked. The Bicep templates carry no credentials — every secret is a
 # @secure() parameter with an empty default, injected at deploy time, and image
 # pull runs on managed identity. Keep it that way: never commit a resolved secret
 # value or a *.parameters.json holding one.
-infra/*.parameters.json

 # M2 — local raw session fixtures before anonymization (plan §4 M2)
 tests/fixtures/enrollment-sessions-local/
@@ -135,22 +128,15 @@ tests/fixtures/enrollment-sessions-local/
 TODO.txt
 tools/orphan-analysis.py
 tools/export-session-fixture.mjs
-tasks/

 # Azure Table cleanup backups (dry-run exports + delete manifests)
-# Produced by /cleanup-table skill — never commit deletion payloads
+# Produced by operator tooling — never commit deletion payloads
 db-backups/
 plans/REFACTOR_AGENT_V2.md
 .claude/scheduled_tasks.lock
 .claude/plans/health-script-remediation-fix.md
-
-# Operator-local Azure setup helper — applies lifecycle policy + container
-# creation against a live storage account. Not portable across environments
-# (storage account name, resource group are operator-specific) so it stays
-# out of the repo. Each operator keeps their own copy.
-scripts/Backup/setup-backup-container.ps1
-docs/Introduction-AutopilotMonitor.pptx
-docs/~$Introduction-AutopilotMonitor.pptx
+internal/docs/Introduction-AutopilotMonitor.pptx
+internal/docs/~$Introduction-AutopilotMonitor.pptx

 # Playwright MCP browser artifacts (snapshots, screenshots, console logs)
 .playwright-mcp/
@@ -159,8 +145,11 @@ docs/~$Introduction-AutopilotMonitor.pptx
 # changes each run) and served at /version.json from the static export.
 src/Web/autopilot-monitor-web/public/version.json

+# What's new payload: generated by scripts/whats-new/build-whats-new.js from the docs
+# checkout on every build and served at /whats-new.json from the static export.
+src/Web/autopilot-monitor-web/public/whats-new.json

-# Local IME binaries scratch used by the /ime-decompile skill (MSI + msiexec-
-# extracted payload per version, for grepping in binaries). Decompilates live in
-# the private ime-decompiles repo, MSIs in the ime-archive blob - this stays local.
+
+# Local IME installer scratch (MSI + extracted payload per version, for grepping
+# in binaries). Operator-only, never committed.
 ime-files/
@@ -1,3 +1,9 @@
 [submodule ".claude/commands"]
 	path = .claude/commands
 	url = https://github.com/okieselbach/Autopilot-Monitor-dotclaude.git
+[submodule "docs"]
+	path = internal
+	url = https://github.com/okieselbach/Autopilot-Monitor-internal.git
+[submodule "infra"]
+	path = infra
+	url = https://github.com/okieselbach/Autopilot-Monitor-infra.git
@@ -0,0 +1,19 @@
+# Code of Conduct
+
+This applies to all project spaces: issues, pull requests, discussions, and the documentation repository.
+
+## Expectations
+
+- Be respectful and constructive. Disagree with ideas, not with people.
+- Assume good intent. Most confusion is a documentation gap, not malice.
+- Keep discussions on topic and searchable: clear titles, reproducible steps, text instead of screenshots of text where possible.
+- Never post customer data, tenant IDs, device identifiers, tokens, or log excerpts containing personal data in public issues or discussions. Redact first.
+
+## Not acceptable
+
+Harassment, personal attacks, discriminatory language, publishing others' private information, and sustained disruption of discussions.
+
+## Enforcement
+
+The maintainers may edit, hide, or delete content and may block accounts that violate this code. To raise a concern, contact the maintainers privately through
+[GitHub](https://github.com/okieselbach) rather than in a public thread.
@@ -0,0 +1,17 @@
+# Feedback and Issues
+
+Autopilot Monitor is developed and operated by its maintainers. The source is published so that customers and security reviewers can see what runs on their devices and with their data. This page explains where feedback goes.
+
+| I want to… | Go to |
+|---|---|
+| Report a bug | [New issue → Bug report](https://github.com/okieselbach/AutopilotMonitor/issues/new/choose) |
+| Suggest a feature | [New issue → Feature request](https://github.com/okieselbach/AutopilotMonitor/issues/new/choose) |
+| Ask a question or discuss an idea | [Discussions](https://github.com/okieselbach/AutopilotMonitor/discussions) |
+| Report a security issue | [SECURITY.md](SECURITY.md) — privately, never as a public issue |
+| Read how the product works | [docs.autopilotmonitor.com](https://docs.autopilotmonitor.com) |
+
+## Reporting a problem in your own tenant
+
+For a failed or odd enrollment, the **Report Session** button in the portal is the fastest path. It hands the session context to support without exposing any of it publicly. Use a GitHub issue for problems that are reproducible and not tied to your data.
+
+Please redact tenant IDs, device names, serial numbers, and anything personal before posting in a public issue or discussion.
@@ -1,39 +1,673 @@
-Autopilot Monitor - Split License
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007

-Copyright (c) 2026 Autopilot Monitor Contributors
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>

-This project uses a split licensing model. Different components are
-licensed under different terms:
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.

-## MIT License
+                            Preamble

-The following components are licensed under the MIT License:
+The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.

- src/Agent/    - The Autopilot Monitor Agent (deployed to devices)
- src/Shared/   - Shared DTOs, enums, and constants
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains
+free software for all its users.

-See src/Agent/LICENSE and src/Shared/LICENSE for the full MIT license text.
+When we speak of free software, we are referring to freedom, not price.
+Our General Public Licenses are designed to make sure that you have the
+freedom to distribute copies of free software (and charge for them if
+you wish), that you receive source code or can get it if you want it,
+that you can change the software or use pieces of it in new free
+programs, and that you know you can do these things.

-## GNU Affero General Public License v3.0 (AGPL-3.0)
+Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.

-The following components are licensed under the AGPL-3.0:
+A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.

- src/Backend/   - Azure Functions backend
- src/Web/       - Next.js web frontend
- src/McpServer/ - MCP Server
+The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.

-See src/Backend/LICENSE for the full AGPL-3.0 license text.
+An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing
+under this license.

-## Why Split Licensing?
+The precise terms and conditions for copying, distribution and
+modification follow.

-The Agent runs on end-user devices and is licensed under MIT to allow
-unrestricted use, modification, and distribution without copyleft
-obligations.
+                       TERMS AND CONDITIONS

-The server-side components (Backend, Web, McpServer) are licensed under
-AGPL-3.0 to ensure that modifications to the server infrastructure
-remain open source, especially when deployed as a network service.
+0. Definitions.

-The Shared library is MIT-licensed because it is a dependency of the
-MIT-licensed Agent. Using AGPL for Shared would effectively make the
-Agent AGPL as well.
+"This License" refers to version 3 of the GNU Affero General Public
+License.
+
+"Copyright" also means copyright-like laws that apply to other kinds
+of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of
+an exact copy.  The resulting work is called a "modified version" of
+the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user
+through a computer network, with no transfer of a copy, is not
+conveying.
+
+An interactive user interface displays "Appropriate Legal Notices" to
+the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+
+The "source code" for a work means the preferred form of the work for
+making modifications to it.  "Object code" means any non-source form
+of a work.
+
+A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that is
+widely used among developers working in that language.
+
+The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can
+regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same
+work.
+
+2. Basic Permissions.
+
+All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey,
+without conditions so long as your license otherwise remains in force.
+You may convey covered works to others for the sole purpose of having
+them make modifications exclusively for you, or provide you with
+facilities for running those works, provided that you comply with the
+terms of this License in conveying all material for which you do not
+control copyright.  Those thus making or running the covered works for
+you must do so exclusively on your behalf, under your direction and
+control, on terms that prohibit them from making any copies of your
+copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the
+conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such
+circumvention is effected by exercising rights under this License with
+respect to the covered work, and you disclaim any intention to limit
+operation or modification of the work as a means of enforcing, against
+the work's users, your or third parties' legal rights to forbid
+circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the
+code; keep intact all notices of the absence of any warranty; and give
+all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these
+conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under
+    section 7.  This requirement modifies the requirement in section
+    4 to "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not used
+to limit the access or legal rights of the compilation's users beyond
+what the individual works permit.  Inclusion of a covered work in an
+aggregate does not cause this License to apply to the other parts of
+the aggregate.
+
+6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of
+sections 4 and 5, provided that you also convey the machine-readable
+Corresponding Source under the terms of this License, in one of these
+ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the Corresponding
+    Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in
+    accord with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to
+    the Corresponding Source in the same way through the same place
+    at no further charge.  You need not require recipients to copy
+    the Corresponding Source along with the object code.  If the
+    place to copy the object code is a network server, the
+    Corresponding Source may be on a different server (operated by
+    you or a third party) that supports equivalent copying
+    facilities, provided you maintain clear directions next to the
+    object code saying where to find the Corresponding Source.
+    Regardless of what server hosts the Corresponding Source, you
+    remain obligated to ensure that it is available for as long as
+    needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission,
+    provided you inform other peers where the object code and
+    Corresponding Source of the work are being offered to the general
+    public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for
+incorporation into a dwelling.  In determining whether a product is a
+consumer product, doubtful cases shall be resolved in favor of
+coverage.  For a particular product received by a particular user,
+"normally used" refers to a typical or common use of that class of
+product, regardless of the status of the particular user or of the way
+in which the particular user actually uses, or expects or is expected
+to use, the product.  A product is a consumer product regardless of
+whether the product has substantial commercial, industrial or
+non-consumer uses, unless such uses represent the only significant
+mode of use of the product.
+
+"Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to
+install and execute modified versions of a covered work in that User
+Product from a modified version of its Corresponding Source.  The
+information must suffice to ensure that the continued functioning of
+the modified object code is in no case prevented or interfered with
+solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or
+updates for a work that has been modified or installed by the
+recipient, or for the User Product in which it has been modified or
+installed.  Access to a network may be denied when the modification
+itself materially and adversely affects the operation of the network
+or violates the rules and protocols for communication across the
+network.
+
+Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+7. Additional Terms.
+
+"Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright
+holders of that material) supplement the terms of this License with
+terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material,
+    or requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors
+    or authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions
+    of it) with contractual assumptions of liability to the recipient,
+    for any liability that these contractual assumptions directly
+    impose on those licensors and authors.
+
+All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions; the
+above requirements apply either way.
+
+8. Termination.
+
+You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally terminates
+your license, and (b) permanently, if the copyright holder fails to
+notify you of the violation by some reasonable means prior to 60 days
+after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+
+You are not required to accept this License in order to receive or run
+a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+
+Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+11. Patents.
+
+A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+A contributor's "essential patent claims" are all patent claims owned
+or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the
+patent license to downstream recipients.  "Knowingly relying" means
+you have actual knowledge that, but for the patent license, your
+conveying the covered work in a country, or your recipient's use of
+the covered work in a country, would infringe one or more identifiable
+patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+A patent license is "discriminatory" if it does not include within the
+scope of its coverage, prohibits the exercise of, or is conditioned on
+the non-exercise of one or more of the rights that are specifically
+granted under this License.  You may not convey a covered work if you
+are a party to an arrangement with a third party that is in the
+business of distributing software, under which you make payment to the
+third party based on the extent of your activity of conveying the
+work, and under which the third party grants, to any of the parties
+who would receive the covered work from you, a discriminatory patent
+license (a) in connection with copies of the covered work conveyed by
+you (or copies made from those copies), or (b) primarily for and in
+connection with specific products or compilations that contain the
+covered work, unless you entered into that arrangement, or that patent
+license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+
+If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey
+a covered work so as to satisfy simultaneously your obligations under
+this License and any other pertinent obligations, then as a
+consequence you may not convey it at all.  For example, if you agree
+to terms that obligate you to collect a royalty for further conveying
+from those to whom you convey the Program, the only way you could
+satisfy both those terms and this License would be to refrain entirely
+from conveying the Program.
+
+13. Remote Network Interaction; Use with the GNU General Public
+License.
+
+Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your
+version supports such interaction) an opportunity to receive the
+Corresponding Source of your version by providing access to the
+Corresponding Source from a network server at no charge, through some
+standard or customary means of facilitating copying of software.  This
+Corresponding Source shall include the Corresponding Source for any
+work covered by version 3 of the GNU General Public License that is
+incorporated pursuant to the following paragraph.
+
+Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+14. Revised Versions of this License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Affero General Public License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever
+published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions
+of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
+PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE
+DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
+CORRECTION.
+
+16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
+CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
+NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
+LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+
+If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                 END OF TERMS AND CONDITIONS
+
+    How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as
+    published by the Free Software Foundation, either version 3 of the
+    License, or (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public
+    License along with this program.  If not, see
+    <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper
+mail.
+
+If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application,
+its interface could display a "Source" link that leads users to an
+archive of the code.  There are many ways you could offer source, and
+different solutions will be better for different programs; see section
+13 for the specific requirements.
+
+You should also get your employer (if you work as a programmer) or
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  For more information on this, and how to apply and follow
+the GNU AGPL, see <https://www.gnu.org/licenses/>.
@@ -1,46 +1,93 @@
-# <img src="docs/images/logo.svg" height="28" alt="" /> AutopilotMonitor
+# <img src=".github/assets/logo.svg" height="28" alt="Autopilot Monitor logo" /> Autopilot Monitor

 [![Status](https://img.shields.io/badge/status-live-brightgreen)](https://www.autopilotmonitor.com)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20AGPL--3.0-blue)](LICENSE)
 [![Website](https://img.shields.io/badge/website-autopilotmonitor.com-2ea44f)](https://www.autopilotmonitor.com)

-Advanced monitoring and troubleshooting solution for Windows Autopilot deployments. Gain full visibility into every enrollment session with a detailed event timeline, fleet health dashboards, and session reporting. Define custom analysis rules to automatically detect issues and gather rules to collect targeted evidence. Retrieve diagnostics packages on demand, configure agent settings like auto-reboot behavior and automatic timezone adjustment — all managed centrally from the web dashboard.
+Autopilot Monitor is an open-source, real-time monitoring and troubleshooting platform for **Windows Autopilot** and **Microsoft Intune** enrollment. It records enrollment events, application installations, policies, device state, and diagnostics while provisioning is still running, instead of collecting logs by hand after a failure. Administrators get live enrollment tracking, Enrollment Status Page (ESP) visibility, detailed session timelines, automated issue detection, on-demand diagnostics, fleet health analytics, and AI-assisted troubleshooting through a hosted Model Context Protocol (MCP) server.
+
+The platform supports classic Windows Autopilot and modern Intune provisioning scenarios, including **Windows Autopilot Device Preparation**.

 ## Availability

 Autopilot Monitor is **publicly available** — the Community plan is free. Sign in with your work account at **[autopilotmonitor.com](https://www.autopilotmonitor.com)**; new organizations complete a short activation step after first sign-in.

 <p align="center">
-  <img src="docs/images/SessionList.png" width="45%" />
-  <img src="docs/images/FleetHealth.png" width="45%" />
+  <img src=".github/assets/SessionList.png" width="45%" alt="Autopilot Monitor dashboard showing live Windows Autopilot and Intune enrollment sessions" />
+  <img src=".github/assets/FleetHealth.png" width="45%" alt="Autopilot Monitor fleet health dashboard with Windows Autopilot enrollment analytics and success metrics" />
 </p>
 <p align="center">
-  <img src="docs/images/SessionDetails.png" width="45%" />
-  <img src="docs/images/SessionTimeline.png" width="45%" />
+  <img src=".github/assets/SessionDetails.png" width="45%" alt="Autopilot Monitor session details showing device information, diagnostics, apps, policies, and enrollment status" />
+  <img src=".github/assets/SessionTimeline.png" width="45%" alt="Windows Autopilot enrollment timeline showing ESP phases, application installs, policies, events, and errors" />
 </p>

-## Overview
+## Key Features

-Autopilot Monitor provides real-time tracking, intelligent diagnostics, and automated troubleshooting for Windows Autopilot enrollment processes. It consists of:
+- **Real-time Windows Autopilot monitoring** — follow device provisioning while enrollment is still running
+- **Detailed enrollment timelines** — correlate Autopilot, ESP, Intune Management Extension, apps, policies, device state, and system events
+- **Enrollment Status Page visibility** — see which phase, application, or policy is delaying provisioning
+- **Automated issue detection** — define custom analysis rules that identify known failure patterns
+- **Targeted evidence collection** — gather registry values, event log entries, files, log-parser matches, and allow-listed commands when specific conditions are detected
+- **On-demand diagnostics** — request diagnostics packages from enrolled devices remotely
+- **Fleet health analytics** — success rates, deployment duration, device models, applications, errors, and recurring issues
+- **Session reporting** — inspect and share detailed enrollment information for individual devices
+- **Windows Autopilot Device Preparation support** — monitor Device Preparation deployments alongside classic Autopilot scenarios
+- **Centralized agent configuration** — control diagnostic behavior, automatic reboots, timezone adjustment, and other monitoring settings from the web dashboard
+- **AI-assisted troubleshooting** — query enrollment data through the built-in Model Context Protocol server

- **Bootstrap Script** — PowerShell script deployed via Intune that starts monitoring early in the enrollment process
- **Monitoring Agent** — Lightweight .NET application that collects telemetry and evidence during enrollment
+## How it works
+
+Autopilot Monitor consists of several components working together throughout Windows enrollment:
+
+- **Bootstrap Script** — PowerShell script deployed through Microsoft Intune that starts monitoring early in the provisioning process
+- **Monitoring Agent** — lightweight .NET application that collects telemetry and evidence during enrollment
 - **Backend API** — Azure Functions-based ingestion and processing pipeline
- **Web Dashboard** — Next.js application for real-time monitoring and fleet analytics
+- **Web Dashboard** — Next.js application for real-time monitoring, troubleshooting, and fleet analytics
+- **MCP Server** — Model Context Protocol server that lets AI assistants query Autopilot Monitor data in natural language

-## Architecture
+## Windows Autopilot and Intune Troubleshooting

-For detailed information about the system architecture, components, and data flow, see [Architecture Documentation](docs/architecture.md).
+Autopilot Monitor helps investigate common Windows provisioning and enrollment problems such as:
+
+- Windows Autopilot deployments that fail or appear stuck
+- Enrollment Status Page (ESP) delays and unusually long deployment phases
+- Win32 application installation failures and slow application downloads
+- Intune Management Extension problems
+- Microsoft Entra join, Hybrid Join, and device registration issues
+- policies that block or delay provisioning
+- inconsistent behavior across hardware models and recurring failures affecting multiple devices
+
+Because telemetry is collected during enrollment, many problems can be investigated without reproducing the issue or manually collecting logs from the affected device.
+
+## AI Integration (MCP)
+
+Autopilot Monitor ships a hosted **[Model Context Protocol](https://modelcontextprotocol.io)** server. Connect Claude Desktop, VS Code, or any MCP client that speaks Streamable HTTP with OAuth, and ask questions like:
+
+- *"Show me all failed enrollments from the last 24 hours and group them by failure reason."*
+- *"Why did session X fail, and which app install caused the delay?"*
+- *"Which devices had unusually long ESP application phases this week?"*
+- *"Which device models have the highest Autopilot failure rate?"*
+- *"Which devices in my fleet are affected by CVE-2024-30078?"*
+
+Server URL: `https://mcp.autopilotmonitor.com/mcp` — sign-in runs through your existing work account, access is scoped to your tenant exactly like in the portal, and the MCP server stores no credentials. Setup guide: **[AI Integration (MCP)](https://docs.autopilotmonitor.com/integrations/ai-integration-mcp)**.

 ## Documentation

-Full admin documentation is available at **[docs.autopilotmonitor.com](https://docs.autopilotmonitor.com)**
+Full admin documentation is available at **[docs.autopilotmonitor.com](https://docs.autopilotmonitor.com)** — deployment, configuration, monitoring, diagnostics, troubleshooting, analysis and gather rules, integrations, and AI-assisted troubleshooting.
+
+## Open Source
+
+Autopilot Monitor is developed openly on GitHub. The source is published so that customers and security reviewers can see what runs on their devices and with their data: the repository contains the device agent, shared library, backend, web dashboard, and MCP server.
+
+## Feedback
+
+Bug reports and feature requests go through [Issues](https://github.com/okieselbach/AutopilotMonitor/issues/new/choose), questions and ideas through [Discussions](https://github.com/okieselbach/AutopilotMonitor/discussions). Security issues are reported privately, see [SECURITY.md](SECURITY.md). For a problem in your own tenant, the **Report Session** button in the portal is the fastest path.

 ## License

-This project uses a **split licensing model**:
+This project uses a **split licensing model**. The root [LICENSE](LICENSE) is AGPL-3.0, which covers the server-side components; the device-side components carry their own MIT license file:

- **MIT License** — Agent (`src/Agent/`) and Shared library (`src/Shared/`) — unrestricted use on end-user devices
- **AGPL-3.0** — Backend (`src/Backend/`), Web Dashboard (`src/Web/`), and MCP Server (`src/McpServer/`) — server-side components remain open source
+- **MIT License** — Agent ([`src/Agent/`](src/Agent/LICENSE)) and Shared library ([`src/Shared/`](src/Shared/LICENSE)) — unrestricted use on end-user devices, no copyleft obligations
+- **AGPL-3.0** — Backend ([`src/Backend/`](src/Backend/LICENSE)), Web Dashboard ([`src/Web/`](src/Web/LICENSE)), and MCP Server ([`src/McpServer/`](src/McpServer/LICENSE)) — modifications to server-side components remain open source, especially when deployed as a network service

-See [LICENSE](LICENSE) for full details.
+The Shared library is MIT because it is a dependency of the MIT-licensed Agent. The license file inside each component directory is authoritative for that component.
@@ -0,0 +1,37 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues **privately** through
+[GitHub Security Advisories](https://github.com/okieselbach/AutopilotMonitor/security/advisories/new).
+Private vulnerability reporting is enabled, so a report reaches the maintainers without ever being public.
+
+Please do not open a public issue, post on social media, or send email for security findings.
+
+## What to expect
+
+- An acknowledgement and an initial severity assessment.
+- A fix or a mitigation plan, with a shared view of timing before anything is disclosed.
+- Credit in the advisory if you want it, and none if you prefer to stay anonymous.
+
+Reports are read by the maintainers directly. There is no guaranteed response time and no bug bounty.
+
+## Scope and rules of engagement
+
+Security research against the hosted service is welcome and is not a violation of the
+[Terms of Use](https://www.autopilotmonitor.com/terms). While testing, please:
+
+- do not access data of tenants you do not own,
+- do not degrade the service for others,
+- do not run automated scanners against production.
+
+## Supported versions
+
+The hosted service always runs the current `main`. For the on-device agent, only the
+[latest release](https://github.com/okieselbach/AutopilotMonitor/releases/latest) receives fixes.
+
+## More
+
+The [Security FAQ](https://docs.autopilotmonitor.com/trust-and-security/security-faq) and
+[Data Flows](https://docs.autopilotmonitor.com/trust-and-security/data-flows) pages describe the security model,
+data handling, and isolation in detail.
@@ -1,166 +0,0 @@
-<#
-.SYNOPSIS
-    Build script for Autopilot Monitor solution.
-
-.DESCRIPTION
-    Builds all .NET projects and optionally the web UI.
-    Run this after cloning or when you want to rebuild everything.
-
-.PARAMETER Configuration
-    Build configuration: Debug or Release (default: Debug)
-
-.PARAMETER IncludeWeb
-    Also build the web UI (requires Node.js)
-
-.PARAMETER Clean
-    Clean before building
-
-.EXAMPLE
-    .\build.ps1
-    Builds all .NET projects in Debug mode
-
-.EXAMPLE
-    .\build.ps1 -Configuration Release -IncludeWeb
-    Builds everything in Release mode including web UI
-#>
-
-[CmdletBinding()]
-param(
-    [ValidateSet("Debug", "Release")]
-    [string]$Configuration = "Debug",
-
-    [switch]$IncludeWeb,
-
-    [switch]$Clean
-)
-
-$ErrorActionPreference = "Stop"
-
-Write-Host "============================================" -ForegroundColor Cyan
-Write-Host " Autopilot Monitor Build Script" -ForegroundColor Cyan
-Write-Host "============================================" -ForegroundColor Cyan
-Write-Host ""
-
-$rootPath = $PSScriptRoot
-$slnPath = Join-Path $rootPath "AutopilotMonitor.sln"
-
-# Check prerequisites
-Write-Host "[1/4] Checking prerequisites..." -ForegroundColor Yellow
-
-# Check .NET SDK
-try {
-    $dotnetVersion = & dotnet --version
-    Write-Host "  ✓ .NET SDK version: $dotnetVersion" -ForegroundColor Green
-}
-catch {
-    Write-Host "  ✗ .NET SDK not found. Please install .NET 10 SDK." -ForegroundColor Red
-    exit 1
-}
-
-# Check Node.js if building web
-if ($IncludeWeb) {
-    try {
-        $nodeVersion = & node --version
-        Write-Host "  ✓ Node.js version: $nodeVersion" -ForegroundColor Green
-    }
-    catch {
-        Write-Host "  ✗ Node.js not found. Please install Node.js 18+." -ForegroundColor Red
-        exit 1
-    }
-}
-
-Write-Host ""
-
-# Clean if requested
-if ($Clean) {
-    Write-Host "[2/4] Cleaning solution..." -ForegroundColor Yellow
-    & dotnet clean $slnPath -c $Configuration
-    Write-Host "  ✓ Clean completed" -ForegroundColor Green
-    Write-Host ""
-}
-else {
-    Write-Host "[2/4] Skipping clean (use -Clean to clean first)" -ForegroundColor Gray
-    Write-Host ""
-}
-
-# Restore packages
-Write-Host "[3/4] Restoring NuGet packages..." -ForegroundColor Yellow
-& dotnet restore $slnPath
-
-if ($LASTEXITCODE -ne 0) {
-    Write-Host "  ✗ Restore failed" -ForegroundColor Red
-    exit 1
-}
-
-Write-Host "  ✓ Restore completed" -ForegroundColor Green
-Write-Host ""
-
-# Build solution
-Write-Host "[4/4] Building solution ($Configuration)..." -ForegroundColor Yellow
-& dotnet build $slnPath -c $Configuration --no-restore
-
-if ($LASTEXITCODE -ne 0) {
-    Write-Host "  ✗ Build failed" -ForegroundColor Red
-    exit 1
-}
-
-Write-Host "  ✓ Build completed" -ForegroundColor Green
-Write-Host ""
-
-# Build web if requested
-if ($IncludeWeb) {
-    Write-Host "[BONUS] Building web UI..." -ForegroundColor Yellow
-    $webPath = Join-Path $rootPath "src\Web\autopilot-monitor-web"
-
-    Push-Location $webPath
-    try {
-        Write-Host "  Installing npm packages..." -ForegroundColor Gray
-        & npm install --silent
-
-        if ($LASTEXITCODE -ne 0) {
-            Write-Host "  ✗ npm install failed" -ForegroundColor Red
-            exit 1
-        }
-
-        Write-Host "  Building Next.js app..." -ForegroundColor Gray
-        & npm run build
-
-        if ($LASTEXITCODE -ne 0) {
-            Write-Host "  ✗ Web build failed" -ForegroundColor Red
-            exit 1
-        }
-
-        Write-Host "  ✓ Web build completed" -ForegroundColor Green
-    }
-    finally {
-        Pop-Location
-    }
-    Write-Host ""
-}
-
-# Summary
-Write-Host "============================================" -ForegroundColor Cyan
-Write-Host " Build Completed Successfully!" -ForegroundColor Green
-Write-Host "============================================" -ForegroundColor Cyan
-Write-Host ""
-Write-Host "Output locations:" -ForegroundColor White
-Write-Host "  Agent:     src\Agent\AutopilotMonitor.Agent.V2\bin\$Configuration\net48\" -ForegroundColor Gray
-Write-Host "  Functions: src\Backend\AutopilotMonitor.Functions\bin\$Configuration\net10.0\" -ForegroundColor Gray
-
-if ($IncludeWeb) {
-    Write-Host "  Web UI:    src\Web\autopilot-monitor-web\.next\" -ForegroundColor Gray
-}
-
-Write-Host ""
-Write-Host "Next steps:" -ForegroundColor White
-Write-Host "  1. Start Azurite: azurite --silent --location c:\azurite" -ForegroundColor Gray
-Write-Host "  2. Start Functions: cd src\Backend\AutopilotMonitor.Functions && func start" -ForegroundColor Gray
-
-if ($IncludeWeb) {
-    Write-Host "  3. Start Web UI: cd src\Web\autopilot-monitor-web && npm run dev" -ForegroundColor Gray
-    Write-Host "  4. Test Agent: cd src\Agent\AutopilotMonitor.Agent.V2\bin\$Configuration\net48 && .\AutopilotMonitor.Agent.exe --console" -ForegroundColor Gray
-}
-else {
-    Write-Host "  3. Test Agent: cd src\Agent\AutopilotMonitor.Agent.V2\bin\$Configuration\net48 && .\AutopilotMonitor.Agent.exe --console" -ForegroundColor Gray
-}
-
@@ -1,177 +0,0 @@
---
-type: Reference
-title: Autopilot ZTD Diagnostics — Event IDs, Registry Surfaces, Endpoints, Error Codes
-description: Windows' own diagnostic surfaces for the Autopilot profile-download (ZTD) flow and known deployment error codes — what the agent reads, what each identifier means, and where the knowledge comes from.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/ZtdEvidence.cs
-tags:
-  - agent
-  - autopilot
-  - ztd
-  - diagnostics
-  - event-log
-  - troubleshooting
-timestamp: 2026-07-16T00:00:00+02:00
---
-
-# Autopilot ZTD Diagnostics
-
-Windows documents its own diagnostic surfaces for the Autopilot profile-download flow
-(the Zero-Touch Deployment / "ZTD" service round-trip during OOBE). The agent consumes
-three of them to turn the `autopilot_profile_missing` warning from a guess into an
-evidence-backed verdict, and the backend rule engine uses the error-code map for
-known-issue enrichment.
-
-Windows 365 Cloud PC exception: on Cloud PCs (`CloudPcDetector.DetectIsCloudPc()`)
-`ProfileAvailable=0` is the expected state — Cloud PCs are provisioned by the Windows 365
-service, not by Autopilot. The event is still emitted with the full evidence payload plus
-an `isCloudPc` marker, but as severity Info with a "this is expected" message instead of
-a Warning (`DeviceInfoCollector.ResolveAutopilotProfileMissingPresentation`). The portal's
-Autopilot Profile card mirrors this: a neutral note for Cloud PC sessions
-(`session.isCloudPc` or the event marker), the amber warning otherwise.
-
-Consumers in this repo:
-
-* `ZtdEvidence.cs` (agent) — one-shot event-log query + `Diagnostics\Autopilot` registry
-  dump + deployment-service reachability probe on the profile-missing path.
-* `ModernDeploymentTracker.cs` (agent) — continuous watcher of the same channel,
-  Level ≤ 3 only (Warning/Error/Critical) plus targeted Info IDs.
-* Analyze rules (backend) — HRESULT/known-issue map (see [Error codes](#schema--error-codes)).
-
-# Schema — ModernDeployment Autopilot event channel
-
-Channel: `Microsoft-Windows-ModernDeployment-Diagnostics-Provider/Autopilot`
-(Event Viewer: Application and Services Logs → Microsoft → Windows →
-ModernDeployment-Diagnostics-Provider → Autopilot).
-
-| Event ID | Level | Meaning | Agent verdict mapping (`ztdVerdict`) |
-| --- | --- | --- | --- |
-| 100 | Warning | "Autopilot policy [name] not found" — temporary, device is waiting for the profile download. Windows can log hundreds of these per minute (harmless-rollup in `ModernDeploymentTracker`). | `waiting_for_profile_no_internet_confirmation` (when nothing else was logged) |
-| 101/103/109/111 | Info | Profile settings retrieval/processing details. | not queried |
-| 153 | Info | `ProfileState_Unknown → ProfileState_Available` — a profile was downloaded and is ready. | `profile_downloaded` |
-| 160 | Info | Profile settings acquisition beginning. | context only |
-| 161 | Info | Profile download succeeded. | `profile_downloaded` |
-| 163 | Info | Download not required — device already provisioned (typically after `Sysprep /Generalize`, i.e. Autopilot-for-existing-devices images). | `already_provisioned` |
-| 164 | Info | Internet available to attempt policy download — the authoritative witness that the ZTD round-trip could run at OOBE time. | with no 161: `download_attempted_no_profile_returned` (the assignment-gap signature, session 423b5360) |
-| 171 | Error | TPM identity confirmation failed (HRESULT in payload) — self-deploying/pre-prov attestation. | context only (`inconclusive` if alone) |
-| 172 | Error | Failed to set profile as available — usually follows 171. | context only |
-| 807 | Error | `ZtdDeviceIsNotRegistered` — hardware hash not registered in Autopilot. | `device_not_registered` |
-| 809 | Error | `ZtdDeviceHasNoAssignedProfile` — the assigned profile was deleted without cleanup. | `assigned_profile_deleted` |
-| 815 | Error | `ZtdDeviceHasNoAssignedProfile` — no profile assigned and no tenant default profile. | `no_profile_assigned` |
-| 908 | Error | `SerialNumberMismatch` / `ProductKeyIdMismatch` between Autopilot registration and physical hardware. | `serial_or_product_key_mismatch` |
-
-Verdict priority: error IDs are authoritative (807 → 908 → 809 → 815), then the Info-flow
-reconstruction (161/153 → 163 → 164 → 100). Implemented in
-`ZtdEvidence.ComputeZtdVerdict`, pinned by `ZtdEvidenceVerdictTests`.
-
-# Schema — Diagnostics registry key
-
-`HKLM\SOFTWARE\Microsoft\Provisioning\Diagnostics\Autopilot` — written by the ZTD client,
-dumped verbatim by the agent into the `autopilot_profile` event (`diagnosticsRegistry`):
-
-| Value | Meaning |
-| --- | --- |
-| `AadTenantId` | GUID of the tenant the user signed into. |
-| `CloudAssignedTenantDomain` | Tenant the device is registered with; **blank = not registered with Autopilot**. |
-| `CloudAssignedTenantId` | GUID matching `CloudAssignedTenantDomain`; blank when not registered. |
-| `IsAutopilotDisabled` | 1 = device not registered **or** profile download failed (network/firewall/timeout) — Microsoft's own catch-all indicator. **Casing caveat:** Windows actually writes `IsAutoPilotDisabled` (capital P; observed session e7dbac7a, 24H2) while the FAQ documents `IsAutopilotDisabled` — all agent lookups are case-insensitive for this reason. |
-| `TenantMatched` | 0 = user's tenant ≠ registration tenant → the "username belongs to another organization" OOBE error. |
-| `CloudAssignedOobeConfig` | Bitmap of configured OOBE settings (SkipCortanaOptIn=1, OobeUserNotLocalAdmin=2, SkipExpressSettings=4, SkipOemRegistration=8, SkipEula=16). |
-
-The profile cache itself lives in `HKLM\SOFTWARE\Microsoft\Provisioning\AutopilotPolicyCache`
-(`PolicyJsonCache`, `ProfileAvailable`) — `ProfileAvailable=0` plus an empty
-`ZeroTouchConfig` is the "blank profile cached" state the troubleshooting FAQ describes
-when no profile exists at check time. A reboot re-runs the download and can replace the
-blank cache.
-
-# Schema — Endpoints
-
-| Endpoint | Purpose | Agent behavior |
-| --- | --- | --- |
-| `https://ztd.dds.microsoft.com` | Autopilot Deployment Service — profile delivery during OOBE. | Reachability probe on profile-missing (any HTTP status = reachable). **Note:** several third-party blogs cite `ztd.ssd.microsoft.com`; the official requirements page says `ztd.dds.microsoft.com`. |
-| `https://login.live.com` | Second Deployment-Service URL; also needed by the Microsoft Sign-in Assistant (`wlidsvc`) — a policy that disables wlidsvc breaks profile download. | not probed |
-| `*.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) | **Visible via error backfill** — attestation precedes enrollment, but the startup error backfill (below) replays Autopilot-channel Level 1-2 records from the last 4h, so retry-then-success attempts surface as `backfilled=true` events. | Visible. | Visible via error backfill 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.
-
-## Startup error backfill (ModernDeploymentTracker)
-
-At agent start (backfill enabled), the tracker replays Autopilot-channel **Level 1-2**
-records from the last **4 hours** through the normal emission pipeline — this is what makes
-pre-install errors (TPM attestation retries, ZTD errors 807/809/815/908) visible in the
-normal IME deployment flow. Spam containment, in order:
-
-1. **Errors only** — the Warning-level 100 heartbeat storm is excluded by the XPath.
-2. **Harmless-ID downgrade + burst rollup** still applies to backfilled records.
-3. **Cap** of 25 records per scan (newest first; the tail is logged, not emitted).
-4. **RecordId watermark** (`autopilot-error-backfill.json`, advanced by both the backfill
-   scan and the live watcher) — restarts never re-emit records a previous run forwarded.
-5. Backfilled events carry `backfilled: true` plus the original `timeCreated` in their
-   payload; the event's own timestamp is the emission time, so the session's `StartedAt`
-   (which the backend aligns to the earliest event) is not dragged backwards.
-
-Presentation (2026-07-28, customer feedback — an unannounced wall of pre-agent Error
-events read like a live failure):
-
- The scan buffers the (capped) record set, first emits an **Info summary event**
-  (`modern_deployment_log`, payload `backfillSummary: true` + `replayedCount` /
-  `droppedOverCap` / `lookbackMinutes`) announcing the replay block, then replays the
-  records **oldest-first** so the timeline sequence follows event-log chronology.
- The web timeline (`EventTimeline.tsx`) badges `backfilled: true` events („⟲ Backfilled",
-  slate, explanatory tooltip) and renders the original `timeCreated` as the row time with a
-  "(reported …)" suffix; the expanded metadata block gains a `Recorded` line. Severity is
-  deliberately **not** downgraded — unresolved pre-agent errors must still surface in the
-  Error filter.
-
-# Schema — Error codes (backend known-issue map)
-
-Codes documented in the known-issues / troubleshooting-FAQ pages that appear in ESP/enrollment
-failures we can observe:
-
-| Code | Meaning / context | Actionable guidance |
-| --- | --- | --- |
-| `0x800705B4` | Timeout; in self-deploying mode usually "device is not TPM 2.0 capable" (e.g. a VM). | Don't use self-deploying on VMs / non-TPM-2.0 hardware. |
-| `0x801C03EA` | TPM attestation failed → Entra join with device token failed. | TPM/firmware issue; check attestation endpoints. |
-| `0x81039001` | `E_AUTOPILOT_CLIENT_TPM_MAX_ATTESTATION_RETRY_EXCEEDED` (intermittent, "Securing your hardware"). | Retry provisioning; persistent → firmware. |
-| `0x81039023` | TPM attestation failure on Windows 11 (pre-prov/self-deploy). | Fixed by KB5013943 (21H2) or later CU. |
-| `0x81039024` | TPM has known vulnerabilities → attestation refused. | Update TPM firmware from OEM. |
-| `0x80070490` | TPM attestation failure on AMD ASP fTPM platforms. | Update AMD firmware. |
-| `0xC1036501` | Automatic MDM enrollment impossible — multiple MDM configurations in Entra ID. | Consolidate MDM configs. |
-| `0x801C03F3` | Entra device object for the Autopilot device was deleted (logged in `Microsoft-Windows-User Device Registration/Admin`). | Deregister + re-register the device (recreates the object). |
-| `0x80180014` | Device-record reuse in self-deploying/pre-prov mode, or Windows MDM enrollment disabled ("Enrollment blocked for AP device by SDM One Time Limit Check"). | Intune → Autopilot device → **Unblock device**, or allow Windows (MDM) in enrollment restrictions. |
-| `0x80180018` | MDM enrollment refused — licensing (missing Intune/EMS license) or device cap. | Check user license + device limits. |
-| `0x80070774` | Hybrid-join ESP failure — domain mismatch between Intune Connector for AD and device targeting. | Install/configure the connector in the matching domain. |
-| `0x80004005` | Hybrid-join deployment timeout — **build-dependent known issue**, fixed in KB5065789 (25H2, ≥ 26200.6725), KB5065426 (24H2, ≥ 26100.6584), KB5070312 (23H2, ≥ 22631.6276). | Update the image / install the KB. |
-
-Related non-code known issues worth remembering: clock skew of minutes causes TPM
-attestation errors and ESP timeouts (`w32tm /resync /force`; the agent's `ntp_time_check`
-event carries the measured offset); multiple/unexpected OOBE reboots can delete kiosk
-autologon registry entries (fixed in 24H2 KB5058411); ESP does not support mixing LOB and
-Win32 apps ("Another installation is in progress").
-
-# Citations
-
-* [Windows Autopilot troubleshooting FAQ](https://learn.microsoft.com/en-us/autopilot/troubleshooting-faq) — event IDs, registry values, process flow. (Checked 2026-07-16.)
-* [Windows Autopilot known issues](https://learn.microsoft.com/en-us/autopilot/known-issues) — error codes, KB fixes. (Checked 2026-07-16.)
-* [Windows Autopilot requirements — Networking](https://learn.microsoft.com/en-us/autopilot/requirements?tabs=networking) — endpoint list incl. `ztd.dds.microsoft.com`. (Checked 2026-07-16.)
-* Re-check cadence: both Learn pages change regularly (known-issues carries an RSS feed:
-  `https://learn.microsoft.com/api/search/rss?search=%22Be+informed+about+known+issues+that+might+occur+during+Windows+Autopilot+deployment.%22&locale=en-us&%24filter=`).
-  When new event IDs / error codes appear, update `ZtdEvidence.cs`, the backend rule map,
-  and this document together.
@@ -1,65 +0,0 @@
---
-type: Concept
-title: Agent Build Numbers — Shared Counter Blob with ETag-CAS
-description: Why agent build numbers come from a public counter blob reserved before the build, how the compare-and-swap protocol works, and what the repo's buildcounter.txt still does.
-resource: /.github/workflows/build-agent.yml
-tags:
-  - agent
-  - build
-  - ci
-  - release
-  - versioning
-timestamp: 2026-07-17T00:00:00+02:00
---
-
-# Agent Build Numbers — Shared Counter Blob
-
-Agent (V2 line) build numbers — the `<n>` in `2.0.<n>` — are minted from a single
-shared counter blob so that **local builds (`scripts/Deployment/build.ps1`) and CI
-builds (`.github/workflows/build-agent.yml`) can never collide**. Both build paths
-stay first-class: local daily-ops builds remain possible, CI builds add provenance
-attestation on top.
-
-# Schema
-
-The reserve-before-build CAS protocol itself is shared with the backend and the MCP
-server and is documented once in [Version Contract](../versioning.md); the single
-implementation is `.github/scripts/Request-BuildNumber.ps1`. Agent-specific:
-
- **Counter blob**: `https://autopilotmonitoreu.blob.core.windows.net/agent/buildcounter-v{LINE}.txt`
-  — one per release line, analogous to `version-v{LINE}.json`, and kept in the `agent`
-  container next to the artifacts it numbers rather than in `versions/`. Content: the
-  **last used** build number as plain text. Public-read like the rest of the container
-  (the number is visible in `version-v{LINE}.json` anyway); writes require the SAS.
- The reserved number reaches the build as `BUILD_NUMBER` in the environment. The
-  csproj honors it and then skips its `PersistBuildCounter` target, so the repo file
-  is not touched.
- **CI manual override** (`build_number` input): numbers `<=` counter are re-builds
-  and leave the blob unchanged; numbers `>` counter advance it (monotonic guard).
- V2 was seeded with `1356` on 2026-07-17.
-
-# Consequences
-
- `src/Agent/AutopilotMonitor.Agent.V2/buildcounter.txt` is now only an **offline
-  fallback** for `-SkipUpload` smoke builds and bare `dotnet build` (where the version
-  does not matter). It is never committed anymore; the CI step that pushed counter
-  bumps to `main` was removed.
- `AdminConfiguration.LatestAgentV2*` (backend hash-oracle) is updated **only on
-  stable cutover** (`publish_as_stable` / default `build.ps1` run without
-  `-VersionedOnly`/`-Dev`) — it must never point at a build that is not actually in
-  the stable namespace.
- CI builds additionally attest build provenance for the release ZIP via
-  `actions/attest-build-provenance` (Sigstore keyless, bound to the workflow OIDC
-  identity). The digest covers the identical bytes uploaded to blob, so one
-  attestation covers all copies. Verify:
-  `gh attestation verify <zip> --repo okieselbach/AutopilotMonitor`. Local builds
-  cannot produce this attestation — provenance is a CI-only property.
-
-# Citations
-
- [Version Contract](../versioning.md) — the shared CAS protocol and manifest format
- `.github/workflows/build-agent.yml` — "Reserve build number (counter blob CAS)" step
- `.github/scripts/Request-BuildNumber.ps1` — the shared implementation
- `scripts/Deployment/build.ps1` (gitignored, contains SAS) — local build path
- `src/Agent/AutopilotMonitor.Agent.V2/AutopilotMonitor.Agent.V2.csproj` —
-  `BUILD_NUMBER` property + `PersistBuildCounter` target
@@ -1,114 +0,0 @@
---
-type: Concept
-title: Continue-Anyway Observation Mode — Device-Phase ESP Failure Defang
-description: Operator-set tenant opt-in that turns an immediate Device-phase ESP terminal failure on a Continue-Anyway-enabled profile into a bounded 60-minute observation; the DAD-validated real-user desktop plus the Hello gate detect the true end, and the session completes as Succeeded with an esp-soft-failure marker.
-resource: /src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Edge.cs
-tags:
-  - agent
-  - decision-engine
-  - esp
-  - continue-anyway
-  - soft-failure
-  - tenant-config
-timestamp: 2026-08-08T00:00:00+02:00
---
-
-# Continue-Anyway Observation Mode
-
-## Problem
-
-A Classic user-driven enrollment whose Device ESP hits the configured terminal timeout
-(`syncFailureTimeoutMinutes`, typically 30) fails **before AccountSetup is ever entered**.
-The classic advisory defang (`HandleEspTerminalFailureV1`) requires
-`AccountSetupEnteredUtc != null`, so these sessions hard-fail immediately — even when the
-ESP profile allows "Continue anyway" and users demonstrably dismiss the failure screen and
-reach a working desktop. A fleet held at the timeout wall by one slow blocking app then
-shows ~100% Failed (tenant c9787ba2: 948/1000 `esp_terminal_failure`, culprit "Encompass
-Hybrid Installer"), which tells the tenant nothing.
-
-## Mechanism
-
-Opt-in flow (default off — absence keeps the immediate hard fail):
-
-1. **Tenant setting** `EnableEspContinueAnywayObservation` (`TenantConfiguration`,
-   operator-set only, NOT exposed in the tenant admin settings UI; the toggle lives in
-   the Global-Admin tenant management modal next to Bootstrap Token / Unrestricted Mode,
-   and the field is GA-gated on both write paths — the generic PUT silently reverts it
-   for tenant admins, the field patch rejects it with 400) → served via `agent/config`
-   (`AgentConfigResponse`, ConfigVersion 37).
-2. **Agent** stamps `espContinueAnywayObservationEnabled=true` into the
-   `EspConfigDetected` signal payload (both emitters: the orchestrator FirstSync
-   bootstrap and `DeviceInfoCollector.PostEspConfigDetectedSignal`) — only when enabled,
-   so the kernel stays config-free and replay/recovery reconstruct the fact from the
-   signal log.
-3. **Engine** (`HandleEspTerminalFailureV1`): a terminal ESP failure is defanged into an
-   `esp_failure_advisory` (`advisoryReason=esp_failure_defanged_continueanyway_observation`)
-   when ALL hold: profile allows Continue-Anyway, observation opt-in observed,
-   `AccountSetupEnteredUtc == null`, and the scenario is Classic/Unknown with
-   `PreProvisioningSide=None` and no registry self-deploying marker (WhiteGlove /
-   SelfDeploying / DevicePreparation have no interactive user to press the button).
-4. **Observation window**: the shared `AdvisoryCompletion` deadline is armed with a
-   **60-minute** window (classic advisory: 30) — long enough for failure screen →
-   Continue anyway → sign-in → desktop, or a full device-phase re-run via "Try again".
-
-## Detecting the real end
-
-The active-advisory-without-AccountSetup shape is unique to this arming site, so
-`IsContinueAnywayObservationActive(state)` (advisory recorded ∧ not resolved ∧
-AccountSetup never entered) needs no separate opt-in re-check. Three outcomes:
-
-* **Continue anyway** — the DAD-validated real-user desktop arrives (defaultuser0/SYSTEM
-  excluded at the detector) and the Hello gate is satisfied (resolved, or policy
-  explicitly disabled without an observed wizard): `HandleDesktopArrivedV1` completes
-  eagerly through Finalizing (trigger `DesktopArrived:ContinueAnywayObservation`) — the
-  session end reflects the real end, not the window edge. The IME user-session gate is
-  deliberately waived: it anchors on `AccountSetupEnteredUtc`, which is structurally
-  absent here. The terminal `enrollment_complete` carries `espSoftFailure=true`,
-  `completionSource=continue_anyway_observation` and the failed category; the backend
-  stamps `EspSoftFailure`/`CompletionSource` on the Sessions row (+ SessionsIndex
-  mirror) and the web renders the amber "with issues" badge plus a detail banner.
-  Sessions completing under the CLASSIC advisory (AccountSetup entered) carry the same
-  marker with `completionSource=continue_anyway_post_accountsetup`.
-* **Try again** — the ESP re-runs the failed category; `DeviceSetupProvisioningComplete`
-  resolves the advisory via the 4910a5a5 recovery hook (`esp_failure_advisory_resolved`)
-  and the session continues on the normal rails, completing clean (no marker).
-* **Nothing** — the window expires: un-defang to `enrollment_failed` with the original
-  `esp_terminal_failure` reason and
-  `advisoryReason=continue_anyway_observation_window_expired_without_completion_evidence`;
-  `LastFailureTrigger=EspTerminalFailure` keeps the likely-stuck app promotion on. Every
-  observed session therefore still gets a terminal verdict ≤ ~60 min after the failure.
-
-Deadline-fire edge cases mirror the classic paths: desktop + unknown Hello promotes to
-`AwaitingHello` with the HelloSafety window (never-observed promote), and enforcement
-progress since arming re-arms the window (30-min re-arm, convergent) instead of failing a
-device mid-"Try again".
-
-## Status semantics
-
-No new terminal status: the session is `Succeeded` + `EspSoftFailure=true` (user
-decision 2026-08-08). Success-rate conventions stay untouched; honesty lives in the
-badge, the detail banner, and ANALYZE-ESP-004 (which continues to fire on the un-defang
-expiry path via `mayHaveContinuedAnyway`).
-
-# Examples
-
-Session `53d1e9f6-4eef-4f3b-a999-c63e96c5148d` (tenant c9787ba2, 2026-08-07) is the
-motivating shape: DeviceSetup/Certificates failed at the 30-min wall while "Encompass
-Hybrid Installer" was still installing, AccountSetup 0/5, Continue-Anyway allowed —
-hard-failed under the default semantics.
-
-Tests: `ContinueAnywayObservationTests` (DecisionCore.Tests) — defang, 60-min arming,
-opt-out/scenario regressions, eager desktop completion with marker, clean-completion
-marker absence, expiry un-defang, hello promotes, category recovery.
-
-# Citations
-
-* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Edge.cs` — arming site,
-  observation branches in `HandleAdvisoryCompletionDeadlineFired`,
-  `IsContinueAnywayObservationActive`.
-* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Classic.cs` —
-  `HandleDesktopArrivedV1` observation completion, `BuildEnrollmentCompleteEffect`
-  soft-failure marker.
-* `src/Backend/AutopilotMonitor.Functions/Services/EventIngestProcessor.Classification.cs`
-  / `TableStorageService.Sessions.cs` — session stamping + index mirror.
-* `src/Web/autopilot-monitor-web/components/SessionStatusBadge.tsx` — amber badge.
@@ -1,196 +0,0 @@
---
-type: Reference
-title: V2 Agent — Decision Engine (DecisionCore)
-description: The pure-reducer state machine that decides enrollment completion/failure — signals, state, effects, the A/B/C completion arms, and its invariants.
-resource: /src/Shared/AutopilotMonitor.DecisionCore
-tags:
-  - agent
-  - decision-engine
-  - reducer
-  - completion
-timestamp: 2026-07-11T00:00:00+02:00
---
-
-# V2 Agent — Decision Engine (DecisionCore)
-
-DecisionCore (`src/Shared/AutopilotMonitor.DecisionCore`, netstandard2.0) is a **pure
-reducer**: a deterministic state machine with no I/O, no clock reads, no threads. The
-agent feeds it an ordered stream of *signals*; it returns a new immutable state plus a
-list of *effects* the host must execute. Because it is pure, the same persisted signal
-stream always reproduces the same journal and terminal outcome — that is what makes
-crash recovery a replay instead of a guess (determinism guarantee "L.5",
-`Engine/IDecisionEngine.cs`).
-
-# The reducer contract
-
-```
-DecisionStep step = engine.Reduce(DecisionState oldState, DecisionSignal signal)
-// DecisionStep = { NewState, Transition, Effects[] }
-```
-
- `Reduce` never throws: a handler exception advances only bookkeeping and journals a
-  `reducer_exception` dead-end (fail-safe L.16).
- Dispatch is a switch on `(signal.Kind, signal.KindSchemaVersion)`; unknown pairs
-  become journaled dead-ends, never crashes.
- Every step yields a `DecisionTransition` journal record: `Taken` (state change vs
-  dead-end + reason), `StepIndex`, `FromStage/ToStage`, `Trigger`, `Guards`,
-  `ReducerVersion`.
-
-# State
-
-`DecisionState` (schema **v4**) is an immutable value object; "change" = builder copy.
-Key content:
-
- Identity + progress: `SessionId`, `TenantId`, `Stage`, `Outcome`, `StepIndex`,
-  `LastAppliedSignalOrdinal`, `AgentBootUtc` (replay-safety anchor).
- **Facts** as `SignalFact<T>` — value **plus** `SourceSignalOrdinal` provenance, e.g.
-  `AccountSetupEnteredUtc`, `EspFinalExitUtc`, `DesktopArrivedUtc`, `HelloResolvedUtc`,
-  `ImeUserSessionCompletedUtc`, `HelloPolicyEnabled`, `HelloOutcome`.
- Aggregates: `AppInstallFacts`, `ScenarioProfile` + `ScenarioObservations`
-  (enrollment-scenario classification, monotonic), `ClassifierOutcomes`, `RealmJoinFacts`.
- `Deadlines` — active timers the host has been asked to arm.
-
-Stages: `SessionStarted → EspDeviceSetup → EspAccountSetup → AwaitingHello →
-AwaitingDesktop → Finalizing → Completed` (plus `Failed`, `WhiteGloveCandidate/Sealed`,
-`AwaitingDeviceOnlyEsp` for self-deploying, and edge stages). Terminal =
-`Completed | Failed | WhiteGloveSealed`. `Finalizing` is deliberately non-terminal
-(grace window). Outcomes: `EnrollmentComplete`, `EnrollmentFailed`,
-`WhiteGlovePart1Sealed`, `Aborted`, `AdminPreempted`.
-
-# Signals
-
-`DecisionSignal` is the only input. Fields: `Kind` + `KindSchemaVersion` (dispatch key),
-`SessionSignalOrdinal` (monotonic, assigned **only** by the ingress worker — never by
-collectors), `OccurredAtUtc`, mandatory `Evidence` (classified `Raw | Derived |
-Synthetic` — a signal without evidence is a bug), `Payload` (string dict) and
-`TypedPayload` (structured sidecar).
-
-Signal kinds by family (`Signals/DecisionSignalKind.cs`):
-
- **Raw observations**: `EspPhaseChanged`, `EspExiting`, `EspResumed`,
-  `EspTerminalFailure`, `DesktopArrived`, `HelloResolved`, `ImeUserSessionCompleted`,
-  `DeviceSetupProvisioningComplete`, `AccountSetupProvisioningComplete`,
-  `AppInstallCompleted/Failed`, `AadUserJoinedLate`, `SystemRebootObserved`,
-  `EspConfigDetected`, `HelloPolicyDetected`, WhiteGlove + RealmJoin kinds, …
- **Synthetic**: `DeadlineFired` (scheduler timer), `ClassifierVerdictIssued`,
-  `EffectInfrastructureFailure`.
- **Lifecycle**: `SessionStarted`, `SessionAborted`, `AdminPreemptionDetected`.
- **`InformationalEvent`** — the single-rail pass-through: telemetry that must appear
-  on the Events timeline but never influences decisions.
-
-**Ordering is the ingest ordinal, never wall-clock.** Replayed IME/CMTrace lines carry
-backdated source timestamps; all before/after comparisons in the reducer therefore
-compare `SourceSignalOrdinal`s (e.g. "final exit after AccountSetup entry").
-
-# Effects — the only side-channel
-
-`DecisionEffect` kinds and how the host's `EffectRunner` treats failures:
-
-| Kind | Purpose | Failure class |
-| --- | --- | --- |
-| `ScheduleDeadline` / `CancelDeadline` | arm/cancel OS timers that come back as `DeadlineFired` | **critical** — failure aborts the session (a lost timer means silent parking) |
-| `EmitEventTimelineEntry` | timeline events incl. terminal `enrollment_complete` / `enrollment_failed` | transient — retried 100/400/1600 ms |
-| `PersistSnapshot` | hint to write the recovery snapshot | transient |
-| `RunClassifier` | scenario classification; verdict returns as a `ClassifierVerdictIssued` signal | optional — exception ⇒ Inconclusive, never aborts |
-
-Terminal and state-changing timeline effects carry a structured **audit trail** in
-`TypedPayload` (built by `DecisionAuditTrailBuilder`): `decisionSource`, `trigger`,
-`sessionStage`, `stepIndex`, `signalsSeen`, `signalEvidence`, `signalTimestamps`,
-`scenario` — so every completion/failure in the portal is explainable from its own
-event payload.
-
-# Completion logic
-
-## The A/B/C arms
-
-The arms are **not** three pipelines — they are three alternative sufficient conditions
-inside one guard, `ShouldTransitionToAwaitingHello`
-(`Engine/DecisionEngine.Shared.cs`), which gates promotion out of the ESP stages toward
-Hello/desktop completion:
-
- **Arm A — registry-strong AccountSetup success**: `AccountSetupProvisioningSucceededUtc`
-  is set (the ESP registry reported `categorySucceeded`). Merely *entering* AccountSetup
-  is insufficient — Shell-Core 62407 fires at every ESP page transition.
- **Arm B — SkipUser flow**: `ScenarioObservations.SkipUserEsp == true` — with no
-  User-ESP page, the first `esp_exiting` *is* the genuine final exit.
- **Arm C — 4-fact eager completion** (all four mandatory):
-  1. AccountSetup was entered, and
-  2. a post-AccountSetup ESP final exit occurred (ordinal-ordered), and
-  3. a *genuine* IME user-session completion (at-or-after the AccountSetup anchor —
-     guards against the `defaultuser0` ghost), and
-  4. a DAD-validated real-user desktop arrival.
-  Arm C applies eagerly the same conjunction the 30-minute `AdvisoryCompletion`
-  backstop would eventually trust.
-
-**Layering note:** Arm C's app-install hardening lives in the **adapter**, not the
-reducer. `ImeLogTrackerAdapter` defers posting `ImeUserSessionCompleted` while required
-user-ESP Install-intent apps are still pending (IME logs "Completed user session" per
-*pass*, not once per session — sessions 14690fc2/6cb01530). The reducer stays free of
-app-pending guards; adapters sanitize evidence before it becomes a signal.
-
-## Completion attempt sites and sequence
-
-Completion can be attempted from whichever fact arrives last: `HelloResolved`,
-`DesktopArrived` (including the Hello-disabled fast-path when `HelloPolicyEnabled ==
-false` and an arm holds), `EspExiting`, `ImeUserSessionCompleted`,
-`AccountSetupProvisioningComplete`, the Hello safety deadline, or the 30-minute
-advisory backstop. All routes converge on `CompleteThroughFinalizingOrDefer`:
-
-1. **Completion gates** (currently only the RealmJoin AND-gate): if RealmJoin was
-   detected and has no terminal outcome yet, completion is *deferred* — the session
-   stays in stage and emits `completion_waiting`. Three terminals open the gate:
-   `Resolved` (DeploymentPhase 110), `FirstDeploymentIncomplete` (phase left the
-   first-deployment window 100/101 for 200/210 without 110 — the RJ ESP was aborted,
-   typically by an interactive logon reclassifying the run as secondary-user; emits
-   the `realmjoin_first_deployment_incomplete` Warning, session 224b2087), and
-   `Timeout` (hard 60-min deadline). The abort rule reads the *persisted*
-   `RealmJoinFacts.LastDeploymentPhase` (updated by the typed `RealmJoinPhaseChanged`
-   signal), so it survives agent restarts — the `RealmJoinDetected` replay path
-   evaluates it too. A first observation of 210 does **not** release (RJ may have
-   completed before agent boot and deploy afterwards).
-2. `Finalizing` stage + ~5 s `FinalizingGrace` deadline.
-3. Grace fires → `Completed`, `EnrollmentComplete` outcome, `enrollment_complete`
-   timeline event with full audit payload.
-
-**Self-deploying/kiosk** is a separate rail: no Hello, no user desktop —
-`AwaitingDeviceOnlyEsp` with a detection deadline as the sole terminal entry, protected
-by stale-fire and race guards. A registry-confirmed self-deploying profile also waives
-IME false-positive AccountSetup entries.
-
-# Invariants (violating any of these is a bug)
-
- **Post-terminal dispatch guard**: after `Completed`/`Failed`, every signal is a
-  bookkept dead-end — **except `InformationalEvent`** (single-rail pass-through must
-  keep flowing). `WhiteGloveSealed` is unguarded on purpose (Part 2 resumes fresh).
- **`InformationalEvent` never mutates decision state** — exactly one pass-through
-  timeline effect, payload copied 1:1.
- **`AadUserJoinedLate` is observation-only** — never completion evidence.
- **Hello policy is orthogonal to completion** — `HelloPolicyEnabled` tunes wait
-  cadence, never gates the outcome.
- **Raw IME "Completed user session" is weak evidence** — can run under `defaultuser0`;
-  only meaningful with a real-user desktop and the AccountSetup anchor (Arm C).
- **Deadline bases are floored at `AgentBootUtc`** — replayed backdated signals must
-  not arm past-due timers at boot.
- **Reducer-side deadline cancels need an explicit `CancelDeadline` effect** — a
-  builder-only removal leaves the OS timer live.
- **No silent parking**: a non-terminal post-AccountSetup session must always hold a
-  resolution-capable deadline; a 10-min dwell tripwire emits
-  `session_parked_without_deadline`.
-
-# Hosting & threading (inside the agent)
-
-Wired by `EnrollmentOrchestrator.Start` (`src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/`):
-
- `SignalIngress` — bounded queue (256, back-pressure) + **one** worker thread. Per
-  signal, in order: assign ordinals → `SignalLog.Append` (durable, *before* reducing;
-  append failure ⇒ reducer does not run, no ordinal gap) → `engine.Reduce` →
-  `DecisionStepProcessor.ApplyStep`.
- `DecisionStepProcessor.ApplyStep` (same thread, no locks): journal append (the only
-  hard-throwing path; 3 consecutive failures escalate to quarantine) → effects run
-  synchronously via `EffectRunner` → best-effort snapshot → advance `CurrentState` →
-  one-shot terminal-stage hook (raises the agent's `Terminated` event off-thread).
- The `DeadlineScheduler`'s `Fired` event loops back in as synthetic `DeadlineFired`
-  signals.
- On restart, `RecoveryCoordinator` folds the persisted signal log through a transient
-  `new DecisionEngine()` before the live pipeline starts — see
-  [logs & persistence](logs-and-persistence.md).
@@ -1,88 +0,0 @@
---
-type: Concept
-title: Agent Endpoint Migration — Config-Channel Re-Home
-description: How the backend re-homes agents to a new API base URL (backend move or per-tenant region move) via MigrateToApiBaseUrl on the agent config response, and why HTTP redirects were rejected.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/EndpointMigration.cs
-tags:
-  - agent
-  - backend
-  - config
-  - migration
-  - security
-timestamp: 2026-07-18T00:00:00+02:00
---
-
-# Problem
-
-The agent's API base URL is compiled into the binary (`Constants.ApiBaseUrl`). No DNS/domain
-indirection is possible in front of the API: mTLS client-cert auth does not survive a reverse
-proxy (Front Door), and Flex Consumption custom-domain TLS is broken. A backend move (like the
-2026-07-18 WEU→GWC subscription migration) therefore hard-cuts every deployed agent still
-pointing at the old hostname. In-flight agents self-terminate safely (local MaxLifetime watchdog
-+ CleanupService), but their sessions are lost and a per-tenant region move (EU→US) has no
-mechanism at all.
-
-# Mechanism
-
-`AgentConfigResponse.MigrateToApiBaseUrl` — served on `GET /api/agent/config` (incl. the
-bootstrap wrapper), the same control channel as the kill switch, fetched at every agent
-process start.
-
-Agent flow (`Program.RunAgent`, Phase 4):
-
-1. Config fetched from the compiled-in (old) base URL.
-2. Kill-switch check runs FIRST — **kill wins over migrate**.
-3. `AgentRuntimeConfig.Resolve` detects the migration signal directly after the fetch and
-   returns early, BEFORE merge / binary-integrity / bootstrap-cleanup — none of those side
-   effects may run against a config from the backend being abandoned (a migration stub may
-   advertise stale agent hashes; a spurious `IntegrityCheckFailed` + force-update would be
-   harmful).
-4. `Program.RunAgent` swaps `AgentConfiguration.ApiBaseUrl`, disposes the old client stack,
-   rebuilds Phase 3 (auth clients) and re-runs Phase 4 against the new URL —
-   `allowEndpointMigration: false`, so the new backend's config **cannot chain a second hop**.
-5. Kill-switch check runs again on the NEW backend's config; startup continues normally
-   (Phase 5+ builds mTLS/telemetry clients from the updated base URL).
-
-# Hardening (mirrors the kill switch)
-
-* **Live fetch only** — the on-disk config cache strips `MigrateToApiBaseUrl` on write AND
-  read (`RemoteConfigService.CacheConfig` / `LoadCachedConfig`); `EndpointMigration.ResolveTarget`
-  re-checks `LastFetchOutcome == Succeeded` as defence-in-depth. A planted cache file can
-  never re-home an agent.
-* **Allowlist validated on BOTH sides** — `AgentEndpointMigrationRules` (Shared, single
-  source): https only, host must end in `.azurewebsites.net` on a label boundary, no
-  path/query/userinfo/port. The backend refuses to serve an invalid admin value
-  (`AgentMigrateRejected` warning); the agent refuses to honour one even if the backend was
-  compromised.
-* **One hop, no loops** — second Resolve pass never migrates; a target equal to the current
-  base URL is a no-op (steady state during the migration window).
-
-# Operation
-
-Global admin settings (`AdminConfiguration`, admin portal → Global Settings):
-
-* `AgentMigrateApiBaseUrl` — global target, set on the backend being **abandoned**; clear it
-  after the migration window.
-* `AgentMigrateTenantOverridesJson` — JSON object `tenantId → URL` for per-tenant moves.
-  An entry with an **empty string** pins that tenant against the global target (staged rollout).
-  Overrides win over the global value.
-
-Delivery evidence: every served target logs `AgentMigrateServed` (Warning — reaches App
-Insights) with tenant, serial, agent version and target. Agent-side, the re-home is logged as
-`Endpoint migration: backend re-homed this agent from … to …`.
-
-Reach limitation: agents that cannot complete an authenticated config fetch (e.g. cert-broken
-devices) never see the signal — they fall back to the local MaxLifetime/emergency-break
-lifecycle. During a migration window the old backend must keep running as a serving stub;
-keeping the old `*.azurewebsites.net` name parked afterwards also prevents hostname
-re-registration by third parties while stragglers drain.
-
-# Citations
-
-* `src/Shared/AutopilotMonitor.Shared/Services/AgentEndpointMigrationRules.cs` — shared validation rules
-* `src/Shared/AutopilotMonitor.Shared/Models/Config/AgentConfigResponse.cs` — wire field
-* `src/Backend/AutopilotMonitor.Functions/Functions/Config/GetAgentConfigFunction.cs` — `ResolveMigrateTarget` + serving (ConfigVersion 33)
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/EndpointMigration.cs` — agent-side evaluation
-* `src/Agent/AutopilotMonitor.Agent.V2/Runtime/AgentRuntimeConfig.cs` — early return before merge/integrity
-* `src/Agent/AutopilotMonitor.Agent.V2/Program.cs` — one-hop rebuild in `RunAgent`
-* Tests: `AgentEndpointMigrationTests` (backend), `EndpointMigrationTests` + `RemoteConfigServiceCacheHardeningTests` (agent)
@@ -1,151 +0,0 @@
---
-type: Concept
-title: ESP Policy-Provider Stall Detection — the no-timeout Setup/Apps wait and the co-management Sidecar gap
-description: Why the ESP's Apps wait is keyed to the Intune-registered "Sidecar" provider by name — a foreign provider (ConfigMgr) with TrackingPoliciesCreated=1 does not satisfy it — plus the classic never-completes stall, and how the always-on two-arm esp_policy_provider_stalled tripwire (reason=provider_incomplete | sidecar_provider_missing, 15-min wall-clock dwell, StartupEventGate cross-restart dedup) surfaces both.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/EspPolicyProviderProbe.cs
-tags:
-  - agent
-  - esp
-  - enrollment-status-tracking
-  - co-management
-  - stall-detection
-timestamp: 2026-07-24T00:00:00+02:00
---
-
-# ESP Policy-Provider Stall Detection
-
-## Schema
-
-The Enrollment Status Page decides when its "Apps" category may progress from
-"Identifying" using the **EnrollmentStatusTracking CSP**
-(<https://learn.microsoft.com/en-us/windows/client-management/mdm/enrollmentstatustracking-csp>),
-mirrored in the registry under
-`HKLM\SOFTWARE\Microsoft\Windows\Autopilot\EnrollmentStatusTracking\{Device|<UserSID>}\…`.
-Two contracts matter:
-
-1. **`Setup/Apps/PolicyProviders/<Name>`** — per the CSP doc: *"Existence of this node
-   indicates to the ESP that it shouldn't show the tracking status message until the
-   TrackingPoliciesCreated node has been set to true."* This wait has **no timeout**. A
-   registered provider that never sets `TrackingPoliciesCreated=1` parks the ESP at
-   "Apps (Identifying)" indefinitely — observed for days in the field. Exists in device
-   scope (`Device`) and user scope (`S-<SID>`, appears at sign-in).
-2. **`DevicePreparation/PolicyProviders/<Name>/InstallationState`** — must reach 2
-   (NotRequired) or 3 (Completed); 1=NotInstalled, 4=Error. Device scope only. The ESP
-   applies a default 15-minute timeout here, so these stalls self-surface as ESP errors —
-   the detector still records them for the diagnostic trail.
-
-Known provider names: **`Sidecar` is the Intune Management Extension** (the CSP doc names
-"Intune's agents, such as SideCar"); **`ConfigMgr`** is the Configuration Manager client,
-registered during Autopilot-into-co-management — the troubleshooting section of
-<https://learn.microsoft.com/en-us/intune/configmgr/comanage/autopilot-enrollment> queries
-exactly these registry paths. The same document states that ESP policy providers **are not
-aware of each other** and that **pre-provisioning is unsupported** with Autopilot into
-co-management.
-
-## The field case (issue #106)
-
-A tenant pre-provisions devices and installs the ConfigMgr client as a blocking app.
-Occasionally the user-phase ESP reaches "Apps (Identifying)" and never leaves it — for
-hours to days. On those devices `Device\Setup\Apps\PolicyProviders` contains **only a
-`ConfigMgr` key (no `Sidecar`)** — and, per the customer's follow-up, **`TrackingPoliciesCreated=1`
-IS set under it**. The provider is "complete" by the CSP value contract, yet the ESP
-still waits. Manually renaming the key to `Sidecar` — which creates no tracking entries,
-only satisfies the name — unblocks the ESP instantly.
-
-The naive CSP-doc reading ("any provider with TrackingPoliciesCreated=1 satisfies the
-wait") is therefore wrong for this case. What the evidence supports instead: provider
-nodes are registered **by the Intune service at enrollment**, and its ESP-policy WAP
-payload always registers `Sidecar` (ConfigMgr joins only via a co-management settings
-policy — see the payload documented by Niehaus). The ESP waits on the provider it
-expects **by name**; a foreign provider occupying the slot does not satisfy it,
-regardless of its completion values. On the affected devices the CM client (installed
-as a plain Win32 app, no co-management settings policy) evidently displaced the
-Sidecar node — consistent with Microsoft's warning that providers "aren't currently
-aware of others" and that pre-provisioning is unsupported with co-management. The exact
-CloudExperienceHost mechanism is not publicly documented; the registry signature —
-setupApps providers present, `Sidecar` absent — is deterministic either way.
-
-## Detection
-
-`EspPolicyProviderProbe` (fail-soft, static, `ScopedOverride` test seam — structural clone
-of `EspTrackingInfoProbe`) enumerates all providers in both kinds and scopes.
-`EspPolicyProviderStallDetector` evaluates a pure transition function on a 60-second tick
-from the always-on `EspPolicyProviderStallHost` — **two arms**, same 15-minute wall-clock
-dwell, one shared event type discriminated by `reason`:
-
-* **Arm 1, `reason=provider_incomplete`** — a provider **continuously incomplete for
-  ≥ 15 minutes**. The dwell clock starts at first incomplete observation and resets on
-  completion or disappearance. Missing values parse as incomplete
-  (fail-toward-observation). Catches e.g. Sidecar itself never reporting.
-* **Arm 2, `reason=sidecar_provider_missing`** — **≥ 1 `Setup\Apps` provider registered
-  but none named `Sidecar`**, continuously for ≥ 15 minutes. Deliberately ignores
-  provider completeness (the field case had `TrackingPoliciesCreated=1`). Sidecar
-  registering later — the legitimate startup ordering — clears the condition and resets
-  the clock. DevicePreparation-only snapshots don't activate it.
-* When both arms cross in the same round, ONE event is emitted and
-  `sidecar_provider_missing` wins as `reason` (it explains the hang regardless of the
-  foreign provider's state).
-* Missing root key / empty provider list = normal early enrollment: clears all dwell
-  state (both arms), never fires.
-* One `esp_policy_provider_stalled` **Warning** per newly stalled condition set
-  (`ImmediateUpload`), one-shot per condition in-process, cross-restart deduped via a
-  `StartupEventGate` fingerprint over the sorted currently-active fired conditions
-  (provider keys + a `sidecarMissing` sentinel) — a restart into the same stall stays
-  silent, a new condition joining re-reports.
-* Payload: `reason`, `providers[]` (full table: name, scope, kind, raw values, complete
-  flag), `stalledProviders[]` with `stalledForMinutes`, `sidecarMissingForMinutes`
-  (arm 2 only), `sidecarRegistered`, `dwellMinutes`.
-* **Purely observational**: emitted via `InformationalEventPost` (dispatch-guard exempt
-  pass-through) — never touches decision state. No config toggle, no ConfigVersion bump
-  (precedent: `disk_space_low`).
-
-Deliberately **not** built on `StallProbeCollector` (its idle clock resets on any session
-activity — a provider stall coexists with a chatty session) and not on the periodic
-collectors (idle-stopped after 15 minutes — exactly the dormant window the dwell must
-observe).
-
-## Guardrail companion
-
-`rules/guardrails.json` allow-lists `SOFTWARE\Microsoft\Windows\Autopilot` (category
-"Autopilot / OOBE / Setup") so tenants can build their own gather rules on the subtree —
-e.g. a `not_exists` registry rule on the `Sidecar` provider key. The subtree carries
-deployment state only (provider registrations, tracking lists, app IDs, per-user SIDs);
-sensitivity is at or below existing entries. Enforcement is agent-side (embedded
-resource), so both the detector and the guardrail change ship with the agent release.
-
-## Examples
-
-Customer-case event (abbreviated) — note the provider is "complete" by CSP values, the
-hang is carried entirely by `reason=sidecar_provider_missing`:
-
-```json
-{
-  "eventType": "esp_policy_provider_stalled",
-  "severity": "Warning",
-  "data": {
-    "reason": "sidecar_provider_missing",
-    "dwellMinutes": 15,
-    "sidecarRegistered": false,
-    "sidecarMissingForMinutes": 15.0,
-    "providers": [
-      { "name": "ConfigMgr", "scope": "device", "kind": "setupApps",
-        "trackingPoliciesCreated": 1, "installationState": null, "complete": true }
-    ],
-    "stalledProviders": []
-  }
-}
-```
-
-`reason=sidecar_provider_missing` is the co-management signature;
-`reason=provider_incomplete` with `sidecarRegistered=true` covers a stalled Sidecar or
-third-party provider — the generalized contract violation.
-
-# Citations
-
-* EnrollmentStatusTracking CSP — <https://learn.microsoft.com/en-us/windows/client-management/mdm/enrollmentstatustracking-csp>
-* Windows Autopilot into co-management (requirements, provider-conflict warning, troubleshooting registry paths) — <https://learn.microsoft.com/en-us/intune/configmgr/comanage/autopilot-enrollment>
-* Troubleshoot the ESP (models app tracking exclusively via the `Sidecar` subkey) — <https://learn.microsoft.com/en-us/troubleshoot/mem/intune/device-enrollment/understand-troubleshoot-esp>
-* Niehaus: the Intune ESP-policy WAP payload registering the provider nodes (`Sidecar` always, `ConfigMgr` only with a co-management settings policy) — <https://oofhours.com/2023/08/25/run-an-sccm-task-sequence-during-autopilot/>
-* Niehaus: ESP tracks arbitrarily named providers when they are properly registered — <https://oofhours.com/2023/09/18/track-anything-using-esp/>
-* Agent code: `EspPolicyProviderProbe.cs`, `EspPolicyProviderStallDetector.cs`, `EspPolicyProviderStallHost.cs` (SystemSignals / Orchestration.Hosts)
-* Related: [MDM Reboot Coalescing](mdm-reboot-coalescing.md), [Gather-Rule Guardrails](../rules/gather-rule-guardrails.md)
@@ -1,126 +0,0 @@
---
-type: Concept
-title: Gather Rule Debug Log — the per-tenant evaluation trace for rules that produce nothing
-description: EnableGatherRuleDebugLog (ConfigVersion 36) makes the agent write a local trace file explaining every gather-rule evaluation decision — scope skips, missing intervalSeconds, on_change suppression, empty collector results, logparser position/parse-mode/no-match outcomes — so customers can self-diagnose rules that never show up in the timeline.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleDebugLog.cs
-tags:
-  - agent
-  - gather-rules
-  - diagnostics
-  - tenant-configuration
-timestamp: 2026-07-28T00:00:00+02:00
---
-
-# Gather Rule Debug Log
-
-## Schema
-
-### The problem
-
-A gather rule that produces no timeline events is indistinguishable from a rule that
-never ran. The pipeline has many *silent-nothing* exits — before this feature, none of
-them were visible to the customer:
-
-| # | Decision point | Where |
-|---|---|---|
-| 1 | Rule delivered but `Enabled=false` | `GatherRuleExecutor.UpdateRules` |
-| 2 | `trigger=interval` without `intervalSeconds` — never runs | `UpdateRules` timer filter |
-| 3 | Interval timer's first tick comes only after one **full** interval | `UpdateRules` timer creation |
-| 4 | Out of phase scope (`activePhases` / `activeFromPhase` not latched); incl. `currentPhase=Unknown` before the first phase signal | `IsRuleInScopeLocked` |
-| 5 | phase_change / phase_exit dedup — once per (rule, phase) | `OnPhaseChanged` |
-| 6 | Collector returned an **empty** result (e.g. `emitOnlyIfExists=true` and target absent) | `ExecuteRule` |
-| 7 | `emit_mode=on_change` — result hash unchanged, emit suppressed | `ShouldEmitOnChange` |
-| 8 | Guard blocked the target (emits `security_warning`, but the rule yields no data) | `GatherRuleContext.EmitSecurityWarning` |
-| 9 | logparser: no files matched, position tracker says nothing new, regex no-match, plain-text file parsed in default `cmtrace` mode, `maxLines` cap, wildcard capped at 20 files | `LogParserCollector` |
-| 10 | Rule execution threw (agent log had only the message, no stack) | `ExecuteRule` catch |
-
-### The setting
-
-`TenantConfiguration.EnableGatherRuleDebugLog` (`bool?`, default null→false), served to the
-agent as `AgentConfigResponse.EnableGatherRuleDebugLog` — **ConfigVersion 36**. Portal:
-Settings → Agent → Settings, toggle "Gather Rule Debug Log", stored via the usual
-tenant-config roundtrip (`TableConfigRepository` Store+Map). Also shown in the admin
-tenant-config report.
-
-`RemoteConfigMerger` projects the bool onto a runtime path (same pattern as
-`EnableImeMatchLog`): `true` → `Constants.GatherRuleDebugLogPath` =
-`%ProgramData%\AutopilotMonitor\Logs\gather-rules-debug.log`; `false` → null, unless a
-`--gather-debug-log <path>` CLI override supplied a non-default path. The field is not
-security-sensitive and deliberately **survives the offline config cache**.
-
-### The trace file
-
-`GatherRuleDebugLog` is an append-only writer held by `GatherRuleExecutor` and exposed
-to collectors via `GatherRuleContext.DebugLog(ruleId, stage, message)` (null-safe no-op
-when disabled — zero cost on the normal path). Line format:
-
-```
-2026-07-28T09:15:02.123Z | RULE-ID | stage | message
-```
-
-Stages: `config` (registration summary per rule, header, zero-rules note), `phase`
-(enrollment-phase transition marker `phase change: Old -> New`, ruleId `-` — every
-rule-level line below it reads against the new phase), `trigger` (timer scheduled,
-phase/event fired, dedup), `scope` (skips with reason incl. current phase), `exec`
-(execution start), `collector` (null/empty results with likely cause), `guard`
-(allowlist block), `emit` (event emitted, hash change), `suppress` (on_change
-suppression with hash prefix + streak), `logparser` (per-file outcome: lines read,
-position range, match count, parse failures, regex timeouts, mode; plus the
-`format=text` hint when every line fails CMTrace parsing; plus one line **per regex
-match** — line number, matched text, capture groups — capped at 10 per file per run),
-`error` (full exception **with stack trace** — the agent log keeps only the message;
-an invalid logparser regex is reported here including the offending pattern string).
-
-Volume control: 10 MB cap with a single `.old` rotation generation (~20 MB worst case).
-Every write failure is swallowed — tracing must never break gathering. The trace never
-leaves the device on its own — but because it lives in the agent log folder
-(`Constants.LogDirectory`), the diagnostics package (`DiagnosticsPackageService`,
-`*.log` pattern, `AgentLogs/` section) picks it up automatically, so a customer-initiated
-diagnostics upload hands the trace to support without manual copying.
-
-### Semantics
-
-* **No hot-reload** — the flag is consumed once when `DefaultComponentFactory` builds
-  the `GatherRuleExecutorHost` at session start (per-enrollment lifecycle, same as
-  `EnableImeMatchLog`). Enable it in the tenant, then the *next* enrollment writes the
-  trace.
-* **Zero-rules case is traced too** — flag on + backend delivered no gather rules →
-  a one-shot standalone `config` line, so the file is never just absent.
-* **`--run-gather-rules` always traces** (operator diagnostic mode; CLI override or
-  default path) and mirrors every line to the console under `--console`.
-
-## Examples
-
-A logparser rule with `emit_mode=on_change` that "delivers nothing" becomes:
-
-```
-... | LP-01 | config | registered: trigger=interval, collector=logparser, target=C:\...\app.log, unscoped, emitMode=on_change, interval=300s
-... | LP-01 | trigger | interval timer scheduled every 300s (first run after one full interval — no immediate execution)
-... | -     | phase | phase change: DeviceSetup -> AccountSetup
-... | LP-01 | exec | executing: collector=logparser, target=C:\...\app.log
-... | LP-01 | logparser | app.log: read 1000 lines from position 0->81234, matched 0, parseFailures=1000, regexTimeouts=0, mode=cmtrace
-... | LP-01 | logparser | every line failed CMTrace parsing — if this is a plain-text log, set parameter format=text
-```
-
-— the answer ("plain-text log parsed in CMTrace mode") is in the file.
-
-A matching rule shows *how* it matched (capped at 10 per-match lines per file per run):
-
-```
-... | LP-02 | logparser | setupact.log: line 42 matched "Error 0x80070005" — groups: code="0x80070005"
-... | LP-02 | logparser | setupact.log: read 500 lines from position 0->40123, matched 1, parseFailures=0, regexTimeouts=0, mode=text
-```
-
-and a broken regex names itself:
-
-```
-... | LP-03 | error | invalid regex pattern '([unclosed' — rule can never match: Invalid pattern '([unclosed' at offset 10. Not enough )'s.
-```
-
-## Citations
-
-* Executor + trace points: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs`
-* Writer: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleDebugLog.cs`
-* Config projection: `../../src/Agent/AutopilotMonitor.Agent.V2.Core/Configuration/RemoteConfigMerger.cs`
-* Backend serve + ConfigVersion: `../../src/Backend/AutopilotMonitor.Functions/Functions/Config/GetAgentConfigFunction.cs`
-* Phase scoping / emit mode background: `../rules/gather-rule-phase-scoping.md`
@@ -1,108 +0,0 @@
---
-type: Concept
-title: Hello Wizard Un-Skip — vetoing the policy-disabled Hello shortcut
-description: Why a single "WHfB disabled" policy read is not trusted for completion decisions — the HelloWizardStarted signal (prevention + cure) and the HelloTracker confirmation second read.
-resource: /src/Shared/AutopilotMonitor.DecisionCore
-tags:
-  - agent
-  - decision-engine
-  - hello
-  - completion
-  - whfb
-timestamp: 2026-07-13T00:00:00+02:00
---
-
-# Hello Wizard Un-Skip
-
-Session `772fe502` (2026-07-13) completed as *Succeeded* while the user was inside the
-Windows Hello wizard. Cause: the user-scoped WHfB CSP value
-(`HKLM\SOFTWARE\Microsoft\Policies\PassportForWork\{tenant}\{scope}\Policies\UsePassportForWork`)
-**flip-flops** during User-ESP while Intune policy sync is still writing. A single read
-caught "disabled", the engine set `HelloPolicyEnabled=false` (set-once, poll stops), and
-the arm-C completion synthesized `HelloOutcome="Skipped"` → 5 s `finalizing_grace` →
-`enrollment_complete` — 230 ms *after* Shell-Core event 62404 (CXID `AADHello`) proved
-the wizard had launched. The wizard-start was previously an `InformationalEvent` only
-(timeline pass-through, no state mutation).
-
-Two independent defense layers fix this:
-
-# Layer 1 — `DecisionSignalKind.HelloWizardStarted` (engine)
-
-Shell-Core 62404 with CXID `AADHello`/`NGC` is a **genuine wizard-lifecycle observation**
-(unlike the unreliable `hello_provisioning_willlaunch` registry snapshot). It is now a
-dedicated signal: `ShellCoreTracker.HelloWizardStarted` event → coordinator forward
-(`EspAndHelloTracker`, timestamp mirror) → `EspAndHelloTrackerAdapter` (fire-once) →
-reducer. The startup backfill also replays 62404 (5-min lookback), so an agent restart
-mid-wizard does not lose the observation. The reducer records the set-once fact
-`DecisionState.HelloWizardStartedUtc`.
-
-**Prevention** — every "may policy-disabled stand in for a Hello resolution?" decision
-routes through one predicate (`DecisionEngine.Completion.cs`):
-
-```
-HelloPolicyDisabledWithoutWizard = HelloPolicyEnabled == false && HelloWizardStartedUtc == null
-HelloSatisfiedForCompletion     = HelloResolvedUtc != null || HelloPolicyDisabledWithoutWizard
-```
-
-Once a wizard start is on record, the policy-disabled shortcut is vetoed at all five
-Skipped-synthesis sites (EspExiting DeferredCompletion, DesktopArrived fast-path,
-ImeUserSessionCompleted arm-C, AdvisoryCompletion deadline, AccountSetupProvisioningComplete
-DeferredCompletion) *and* in the `completion_waiting` missing-prerequisites computation.
-Sessions then take their pessimistic path: promote to `AwaitingHello` + arm HelloSafety
-(300 s). The AdvisoryCompletion handler needed a dedicated
-`HelloWizardObservedPromote` branch — its fallthrough is re-arm-or-**fail**, and
-prevention alone would have failed a live-wizard session there.
-
-**Cure** — `HandleHelloWizardStartedV1` (`DecisionEngine.Classic.cs`): when the state
-already carries the engine-synthesized skip, the handler retracts it — cancel
-`finalizing_grace` (if armed), null `HelloResolvedUtc`/`HelloOutcome`, back to
-`AwaitingHello`, arm HelloSafety, emit `completion_waiting` (trigger
-`HelloWizardStarted:UnSkip`). A real `HelloResolved` — or the HelloSafety timeout —
-then decides the session.
-
-Two deliberate design points:
-
-1. **Synthetic-outcome discriminator.** The engine's synthesized outcomes are exact-case
-   `"Skipped"` / `"Timeout"` (constants `SyntheticHelloOutcomeSkipped`/`...Timeout`);
-   the tracker vocabulary is all-lowercase (`completed`, `skipped`, `not_configured`,
-   `timeout`, `wizard_not_started`). The cure only ever retracts the exact-case
-   `"Skipped"` — tracker-posted resolutions and the deliberate HelloSafety `"Timeout"`
-   are never touched.
-2. **First fact-nulling reducer.** DecisionState facts are otherwise set-once/monotonic.
-   The retraction is legal exactly here because the fact is provably engine-synthesized
-   and provably wrong (the wizard it claimed would never appear is running). The cure is
-   **stage-agnostic** (guarded by the synthetic outcome, not by `Stage==Finalizing`):
-   a synthetic skip can also sit parked behind a closed RealmJoin completion gate, whose
-   release path completes on `HelloResolvedUtc != null` — the same bug through another
-   door.
-
-# Layer 2 — confirmation second read (HelloTracker)
-
-`HelloTracker.ApplyPolicyRead` (extracted state machine, `HelloTracker.cs`):
-
-| Read | Effect |
-|------|--------|
-| `enabled` (first) | commit immediately (pessimistic direction; `confirmedReads=1`) |
-| `disabled` (first) | mark pending only; 10 s poll timer stays alive |
-| `disabled` while pending | commit disabled (`confirmedReads=2`) |
-| `enabled` while pending | commit enabled + `flipFlopDetected=true` (the 772fe502 catch) |
-| `null` while pending | clear pending, keep polling (a vanished value is flip-flop evidence) |
-
-While pending, `_isPolicyConfigured` stays false, so the Hello wait timers use the
-longer policy-unknown cadence — the safe direction. The confirmation audit fields ride
-on the `hello_policy_detected` event `Data`.
-
-# Residual risk
-
-A wizard that starts only *after* `Completed` (agent already terminal + shut down) is
-still not catchable — the dispatch guard dead-ends post-terminal signals by design. The
-confirmation read shrinks the window for the stale-disabled commit; the wizard signal
-closes it for every ordering where 62404 fires before the 5 s grace elapses.
-
-# Citations
-
- Reducer handler + prevention predicate: `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Classic.cs` (`HandleHelloWizardStartedV1`), `.../DecisionEngine.Completion.cs` (`HelloSatisfiedForCompletion`), `.../DecisionEngine.Edge.cs` (`HelloWizardObservedPromote`)
- Agent signal path: `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ShellCoreTracker.cs` (62404 + backfill), `EspAndHelloTracker.cs`, `SignalAdapters/EspAndHelloTrackerAdapter.cs`
- Confirmation read: `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/HelloTracker.cs` (`ApplyPolicyRead`)
- Fixtures: `tests/fixtures/signal-kinds/hello-wizard-started-v1.json`, `tests/fixtures/enrollment-sessions/userdriven-hello-wizard-unskip-v1.jsonl`
- Related: [Decision Engine](decision-engine.md)
@@ -1,12 +0,0 @@
-# V2 Agent
-
-How the on-device agent works:
-
-* [Runtime Overview](overview.md) - lifecycle (install → boot guards → runtime → termination), collector hosts, the single-rail event pipeline to the backend, config & kill switch, on-disk layout.
-* [Decision Engine](decision-engine.md) - the pure-reducer state machine (DecisionCore): signals, state, effects, the A/B/C completion arms, invariants, threading.
-* [Logs, Persistence & Crash Recovery](logs-and-persistence.md) - every persisted file and why it exists; signal log vs spool; snapshot/journal; the replay-based recovery flow and quarantine.
-* [Hello Wizard Un-Skip](hello-wizard-unskip.md) - why a single "WHfB disabled" policy read never decides completion: the HelloWizardStarted signal (prevention + cure) and the HelloTracker confirmation second read.
-* [Autopilot ZTD Diagnostics](autopilot-ztd-diagnostics.md) - Windows' own diagnostic surfaces for the profile-download flow: ModernDeployment event IDs (807/815/164/...), the Diagnostics\Autopilot registry key, deployment-service endpoints, and the known-issue error-code map.
-* [MDM Reboot Coalescing](mdm-reboot-coalescing.md) - attributing the mid-ESP coalesced reboot ("second sign-in") to the device-assigned policy URIs that forced it: aggregated 2800 observations (neutral, flush-time watermark) + ANALYZE-ESP-005 gated on an actually-observed reboot.
-
-Reading order for newcomers: overview → decision engine → persistence.
@@ -1,141 +0,0 @@
---
-type: Reference
-title: V2 Agent — Logs, Persistence & Crash Recovery
-description: Every file the agent persists under %ProgramData%\AutopilotMonitor, why each exists (especially the signal log), and the exact recovery/replay flow after a crash or reboot.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/RecoveryCoordinator.cs
-tags:
-  - agent
-  - persistence
-  - signal-log
-  - recovery
-  - durability
-timestamp: 2026-07-11T00:00:00+02:00
---
-
-# V2 Agent — Logs, Persistence & Crash Recovery
-
-An enrollment spans multiple reboots and can be killed at any moment (app-forced
-restart, self-update, crash, power loss). The agent therefore persists three distinct
-tiers of state — each answers a different question:
-
-1. **Decision truth** (`State\`): *what did the decision engine see and decide?*
-   Signal log + journal + snapshot. Must be deterministic and replayable.
-2. **Transport** (`Spool\`): *what telemetry still has to reach the backend?*
-   Durable upload queue + cursor. Best-effort; the backend dedups.
-3. **Diagnostics** (`Logs\`, `Crashes\`): *what happened, for humans?* Trace log and
-   crash dumps. Never allowed to affect decisions.
-
-Plus small markers (session identity, completion, quarantine) that steer the next
-process start.
-
-# Why a signal log AND an event spool?
-
-They look similar (both JSONL) but serve opposite masters:
-
- The **signal log** is the *input* truth of the decision engine. Recovery rebuilds
-  decision state by replaying it; the snapshot is only a cache. An append failure here
-  **blocks the reducer** — a signal that was never durably logged must not change state,
-  or a post-crash replay would diverge from what the live run decided (determinism L.1/L.5).
- The **spool** is a *projection* for upload. Writing it is best-effort — a spool
-  failure must never break ingress, and a lost non-critical item is acceptable because
-  the backend dedups on `(PartitionKey, RowKey)`.
-
-Same data, two files, because durability requirements differ: the signal log fsyncs
-every line; the spool fsyncs only items flagged `RequiresImmediateFlush`.
-
-# Artifact inventory
-
-| Artifact | Path | Format | fsync | Rotation/cap |
-| --- | --- | --- | --- | --- |
-| Signal log | `State\signal-log.jsonl` | JSONL (`DecisionSignal`/line) | every append (WriteThrough + Flush, bufferSize=1) | none (per-enrollment lifecycle) |
-| Journal | `State\journal.jsonl` | JSONL (`DecisionTransition`/line) | every append | atomic truncate only (phantom tail) |
-| Snapshot | `State\snapshot.json` | JSON + SHA-256 checksum envelope | temp-write + `File.Replace` | single file |
-| Event sequence | `State\event-sequence.json` | `{ LastAssignedSequence }` | atomic | none; survives WhiteGlove Part-2 resume |
-| Spool | `Spool\spool.jsonl` | JSONL (`TelemetryItem`/line) | only `RequiresImmediateFlush` items | none — never truncated, cursor skips uploaded items |
-| Upload cursor | `Spool\upload-cursor.json` | `{ LastUploadedItemId }` | atomic | idempotent, never regresses |
-| Agent trace log | `Logs\agent.log` (segments `agent-NNN.log`) | text `[utc] [LEVEL] msg` | no | 50 MB → suffix rotation; consumed by `/diag-agent-log` |
-| Crash dump + record | `Crashes\<stem>.dmp` + `.json` | MiniDump + JSON | n/a (process dying) | 5 files / 7 days |
-| Startup-event gate | `State\startup-event-state.json` | JSON dict | no (atomic) | cross-reboot dedup of one-shot probes |
-| Bandwidth state | `State\bandwidth-state.json` | JSON samples/counters | no (atomic) | reboot-survivor for the DO bandwidth estimate |
-| Session identity | `session.id`, `session.created`, `whiteglove.complete` (root) | text | no | drives emergency-break age check + WG resume |
-| Markers | `clean-exit.marker` (root), `enrollment-complete.marker` (State), `quarantine-requested.marker` (State) | text | no | consumed at next start |
-| Config cache | `Config\remote-config.json` | JSON | no | security-sensitive fields stripped |
-
-Per-collector state files (`OfficeInstallStatePersistence`, IME tracker state, script
-execution state, log-file positions) follow the same fail-soft atomic-replace pattern.
-Cleanup (`CleanupService`) removes the agent dirs on self-destruct but **keeps `Logs\`**
-for forensics.
-
-# The decision-truth triad
-
-## Signal log — authoritative input
-
- Written by the single ingress worker, one line per accepted signal, **before** the
-  reducer runs. Monotonic-ordinal guard on append.
- `bufferSize: 1` is load-bearing: session `b9b92d89` (2026-07-09) was killed mid-append
-  by a self-update `Environment.Exit`; the default 4096-byte buffer flushed the same
-  buffered line twice → byte-identical duplicate → non-monotonic ordinal → **recovery
-  crash-loop**. Fixes (commits `57e4334b` + `a0238a4b`):
-  - unbuffered append (nothing left for `Dispose` to re-flush),
-  - read-side tolerance: a byte-identical *consecutive* duplicate line is skipped as a
-    known crash artifact,
-  - self-update restarts now route through graceful shutdown (full drain, bounded 15 s
-    hard-exit fallback) instead of `Environment.Exit`,
-  - poison-replay quarantine (below) so a corrupt log can never loop the agent again.
- Corrupt-tail rule: readers stop at the first unparsable line (a torn final write is
-  expected, not fatal).
-
-## Journal — authoritative applied-transition record
-
-One `DecisionTransition` per reducer step, appended in `ApplyStep` step 1 — the **only**
-persistence path that hard-throws. Three consecutive append failures escalate to a
-quarantine request. Used during recovery to detect BEHIND/AHEAD crash windows against
-the snapshot; AHEAD phantom entries are truncated to `.quarantine\<ts>\journal-phantom-tail.jsonl`.
-
-## Snapshot — recovery cache, never truth
-
-Full `DecisionState` (schema **v4**) in a checksum envelope, written best-effort after
-meaningful steps (stage transition / non-telemetry effect) or every 100 pass-through
-steps. Atomic temp-write + `File.Replace`; a crash mid-save leaves the old file intact.
-Load returns `null` on any doubt (missing, IO error, checksum mismatch) — recovery then
-falls back to full signal-log replay. Aborted/phantom states are never snapshotted.
-
-# Recovery flow on restart
-
-`RecoveryCoordinator.Recover` runs before the live pipeline; order is load-bearing:
-
-1. **Death-rattle peek**: if the previous exit was unclean, read the prior snapshot
-   *non-mutatingly* (`TryReadRaw`) for the `previous_crash_detected` context — before
-   the pipeline may quarantine it.
-2. **Quarantine marker** (`quarantine-requested.marker`, written mid-run when the
-   journal became unappendable): quarantine all segments + snapshot *now*, at a moment
-   when no writer holds them. Marker is deleted only on full success.
-3. **WhiteGlove Part-2 resume**: prior stage `WhiteGloveSealed` → archive the reducer
-   segments to `.part1-<ts>\` but **preserve `event-sequence.json`** (the Web UI splits
-   Part 1/2 on the sequence).
-4. **Open writers** — each scans its file for the last ordinal/step, stopping at the
-   first unparsable line.
-5. **Pick seed + replay stream**:
-   - snapshot loads → seed from it, re-stamp `AgentBootUtc` to *now* (replayed signals
-     must not arm past-due deadlines), replay only the signal-log **tail**
-     (`ordinal > snapshot.LastAppliedSignalOrdinal`);
-   - snapshot corrupt → quarantine snapshot only, replay the full signal log;
-   - log head-corrupt → total-loss quarantine of everything, fresh Initial seed.
-6. **Journal alignment**: truncate AHEAD phantoms to the seed's `StepIndex`.
-7. **Replay + backfill**: fold the stream through a transient `DecisionEngine`,
-   re-appending any missing journal entries (closes the BEHIND window).
-8. **Poison guard**: if replay itself throws, quarantine snapshot + all segments and
-   reseed Initial — the agent keeps running with fresh state instead of crash-looping.
-
-**Duplicate avoidance, end to end**: monotonic append guards (signal log + journal) →
-consecutive-duplicate skip on read → tail-replay past the snapshot ordinal → AHEAD
-truncation → backend `(PartitionKey, RowKey)` dedup for re-uploaded spool items.
-
-**Quarantine semantics**: files are *moved*, never deleted, into
-`State\.quarantine\<utc-ts>\` with a `reason.txt` sidecar — evidence survives for
-diagnostics ZIPs while the agent restarts from clean state.
-
-# Related
-
- Pipeline that produces these files: [runtime overview](overview.md)
- What replay must reproduce deterministically: [decision engine](decision-engine.md)
@@ -1,100 +0,0 @@
---
-type: Concept
-title: MDM Reboot Coalescing — attributing the mid-ESP reboot and second sign-in to policy URIs
-description: How the agent observes reboot-required MDM policy flags (DM-Enterprise EventID 2800, aggregated) and how ANALYZE-ESP-005 attributes an actually-observed enrollment reboot to them — including why the raw events stay neutral and why the Shell-Core RebootCoalescing match was removed.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals
-tags:
-  - agent
-  - esp
-  - reboot
-  - policy-attribution
-  - second-sign-in
-timestamp: 2026-07-20T00:00:00+02:00
---
-
-# MDM Reboot Coalescing
-
-Device-assigned MDM policies whose CSP URIs match the OS reboot-required catalog
-(`HKLM\SOFTWARE\Microsoft\Provisioning\SyncML\RebootRequiredURIs`) force a **coalesced
-reboot at the end of ESP DeviceSetup** — the user sees an unexpected restart and a
-**second sign-in screen** before AccountSetup. Invisible in the Intune console; most
-admins live with it, not knowing that reassigning the profiles to user groups removes the
-reboot entirely. Source research: Patch My PC,
-["Avoid the second sign-in screen after Autopilot"](https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/).
-
-The session already counts reboots (`system_reboot_detected` → `session.rebootCount`);
-this feature adds the **cause attribution**.
-
-# Verified signal facts (session b2e890c1, 2026-07-20)
-
-* **EventID 2800**, `Microsoft-Windows-DeviceManagement-Enterprise-Diagnostics-Provider/Admin`,
-  one record per URI, verified description shape:
-  `The following URI has triggered a reboot: (./Device/Vendor/MSFT/Policy/Config/ServiceControlManager/SvchostProcessMitigation).`
-  Records arrive in sub-second bursts during policy sync.
-* **Timing semantics (the critical nuance)**: 2800 fires at EVERY policy sync. Only URIs
-  applied **during ESP DeviceSetup** are coalesced into the forced mid-ESP restart. In the
-  verified session the flags fired during AccountSetup (after DeviceSetup completed) —
-  **no reboot occurred**, and `omadmRebootRequiredFlag` read `false`. A detector that
-  claims "reboot incoming" on every 2800 is therefore wrong.
-* **Shell-Core 62407 "RebootCoalescing" — REMOVED as a signal.** The token appears in the
-  ROUTINE bootstrap marker on every enrollment:
-  `Name: 'CommercialOOBE_BootstrapStatusCategory_SubcategoryProcessing_Started', Value: '{"message":"BootstrapStatus: Starting subcategory DeviceSetup.RebootCoalescing...","errorCode":0}'`
-  — the ESP merely *processes* the RebootCoalescing subcategory (which checks whether a
-  reboot is needed). A substring match on it is a false positive by construction. If a
-  real coalesced-reboot record is ever captured on the E2E VM, a precise pattern can be
-  added then.
-
-# Detector — `MdmRebootPolicyTracker` (`MdmRebootPolicyWatcherHost`)
-
-Live `EventLogWatcher` on the DM-Enterprise Admin channel (EventID 2800) + startup
-backfill (default 60 min lookback). Records are **buffered and debounced (10 s)**, then
-flushed as **ONE aggregated `mdm_policy_reboot_required` event** per burst:
-
-* `Severity=Info`, neutral message ("Windows flagged N MDM policy URIs as
-  reboot-required: … (+N more)") — the raw event never claims a reboot.
-* `Data`: `rebootUris` (distinct, sorted, capped 20), `uriCount` (uncapped distinct),
-  `firstRebootUri` (record-time order, drives rule interpolation), `recordCount`,
-  `unparsedCount`/`sampleDescription` (extraction diagnostics), `backfilled` (all-backfill),
-  fail-soft `omadmRebootRequiredFlag` probe of
-  `HKLM\SOFTWARE\Microsoft\Provisioning\OMADM\SyncML\RebootRequired` (null = unknown).
-* `Timestamp` = earliest record time (backfilled bursts land at their historical instant);
-  `ImmediateUpload=true` (one event per burst is cheap, and a DeviceSetup burst precedes a
-  reboot that kills the agent).
-* **Watermark is persisted at FLUSH, not at claim** (`mdm-reboot-watermark.json`): if the
-  coalesced reboot kills the process before the debounced emit, nothing is marked — the
-  post-restart backfill re-reads and emits the burst. A flushed burst is never repeated.
-
-URI extraction: EventData values starting with `./` preferred, permissive regex over the
-description as fallback (trailing punctuation trimmed — the verified text wraps the URI in
-parens and ends with a period). Unparsed records still count into the aggregate.
-
-Config (internal steering only, no admin UI — agent-native collector, NOT an
-`IAgentAnalyzer`): `Collectors.MdmRebootPolicyWatcherEnabled` (default true),
-`Collectors.MdmRebootPolicyBackfillLookbackMinutes` (default 60). ConfigVersion 35.
-
-# Advisory — ANALYZE-ESP-005
-
-The reboot **claim** lives here, and only here. Required conditions (BOTH):
-
-1. `mdm_policy_reboot_required.firstRebootUri` exists (→ `{{firstRebootUri}}` interpolation)
-2. `system_reboot_detected` count ≥ 1 — **an actually-observed reboot**
-
-Policy flags alone (e.g. AccountSetup user-policy sync) stay advisory-silent. Optional
-confidence: `uriCount ≥ 2` (+10), `omadmRebootRequiredFlag == true` (+15) on base 70 /
-threshold 70. Remediation: map URIs to Intune profiles, reassign device → user groups (or
-exclude the Autopilot device group), or accept + communicate the restart.
-
-# Non-goals / invariants
-
-* Event type **deliberately distinct from `system_reboot_detected`** — the backend
-  RebootCount matches that string exactly in two places
-  (`EventIngestProcessor.Classification` + terminal recount); attribution must never
-  inflate the reboot count.
-* No session-level field / SessionInfoCard change in this iteration (follow-up candidate).
-* The `RebootRequiredURIs` catalog itself is not read; only the 2800 events (which carry
-  the actually-triggered URIs) are consumed.
-
-# Citations
-
-* [Patch My PC — Avoid the second sign-in screen after Autopilot](https://patchmypc.com/blog/autopilot-unexpected-reboot-autopilot-second-login-screen/)
-* [Microsoft Learn — Enrollment Status Page tracking](https://learn.microsoft.com/en-us/autopilot/enrollment-status)
@@ -1,153 +0,0 @@
---
-type: Component Overview
-title: V2 Agent — Runtime Overview
-description: How the V2 agent boots during Autopilot enrollment, which collectors it runs, how telemetry flows to the backend, and how it decides to stop.
-resource: /src/Agent/AutopilotMonitor.Agent.V2/Program.cs
-tags:
-  - agent
-  - runtime
-  - collectors
-  - telemetry
-timestamp: 2026-07-11T00:00:00+02:00
---
-
-# V2 Agent — Runtime Overview
-
-The agent is a .NET Framework 4.8 executable (`AutopilotMonitor.Agent.exe`) that runs as
-SYSTEM on Windows devices during Autopilot enrollment. It observes the enrollment
-(ESP phases, IME app installs, Hello, desktop arrival, …), streams telemetry to the
-backend, and decides locally — via the [decision engine](decision-engine.md) —
-when the enrollment is complete or failed. When it reaches a terminal decision it shows
-the optional summary dialog, uploads diagnostics, and removes itself.
-
-Projects: `src/Agent/AutopilotMonitor.Agent.V2` (exe) + `AutopilotMonitor.Agent.V2.Core`
-(library) + `src/Shared/AutopilotMonitor.DecisionCore` (portable decision engine).
-
-# Lifecycle
-
-## Install (bootstrap during OOBE)
-
-`AutopilotMonitor.Agent.exe --install` is invoked by the Intune Platform Script
-(bootstrap) and never runs the monitoring runtime
-(`src/Agent/AutopilotMonitor.Agent.V2/Program.InstallMode.cs`):
-
-1. Copy payload to `%ProgramData%\AutopilotMonitor\Agent\`.
-2. Persist `bootstrap-config.json` (bootstrap token, tenant id) and `await-enrollment.json`.
-3. Register the `AutopilotMonitor-Agent` scheduled task (BootTrigger, SYSTEM,
-   `ExecutionTimeLimit=PT0S`, survives battery conditions).
-4. Immediate runtime handoff: WMI `Win32_Process.Create` → `schtasks /Run` fallback →
-   defer to BootTrigger on next reboot. `--install` exits 0 even if both immediate
-   launches fail (fail-soft; the BootTrigger is the net).
-5. Write `HKLM\SOFTWARE\AutopilotMonitor\Deployed` = UTC timestamp — the **bootstrap
-   re-entry lock** read by the install script. Never consulted by the agent itself;
-   intentionally preserved across cleanup.
-
-## Runtime start (each process start / boot)
-
-`Program.Main` → `RunAgent` runs numbered phases (V1-parity exit codes 0–7):
-
-1. **Guards & bootstrap** (`AgentBootstrap.Run`): classify previous exit
-   (`clean` / `exception_crash` / `hard_kill` / `reboot_kill` via `clean-exit.marker`,
-   crash logs, boot event 6009); ghost-restart guard (`enrollment-complete.marker`
-   → cleanup + exit 0); absolute session-age emergency break; optional waits
-   (`--await-enrollment` MDM cert poll, `--tenant-id-wait` registry wait); resolve
-   TenantId from `HKLM:\SOFTWARE\Microsoft\Enrollments`; get-or-create SessionId.
-2. **Auth clients** (mTLS with the Intune MDM device client certificate).
-3. **Remote config** (`GET /api/agent/config`): live fetch → cached
-   `Config\remote-config.json` → built-in defaults. Config-channel **kill switch**
-   checked here, honoured only from a *live* fetch (cache strips all security-sensitive
-   fields).
-4. **Telemetry clients**, **backend session registration**.
-5. **`AgentRuntimeHost.Run`**: builds the `EnrollmentOrchestrator`, starts collector
-   hosts, decision pipeline and upload drain loop, then blocks until shutdown.
-
-## Stop triggers
-
- **Terminal decision** of the engine (Completed / Failed / WhiteGloveSealed) — the normal path.
- **Max-lifetime watchdog**: `AgentMaxLifetimeMinutes` (default 360) — hard cap per session.
- Backend **kill switch** (config channel at start; telemetry channel via upload responses
-  → synthesized `terminate_session` action).
- Auth-failure threshold, self-update restart, Ctrl+C / ProcessExit.
-
-Distinct from agent lifetime: `CollectorIdleTimeoutMinutes` (default 15) stops only the
-periodic collectors (Performance, AgentSelfMetrics) when nothing "real" happens; they
-restart on new activity.
-
-## Termination sequence
-
-On terminal decision (`EnrollmentTerminationHandler`): stop collectors → build
-`FinalStatus` → write `final-status.json` + launch `SummaryDialog` (separate WPF exe in
-the user session, opt-in) → 2 s late-event grace → diagnostics ZIP upload →
-write `enrollment-complete.marker` → optional reboot → self-destruct cleanup
-(skipped for WhiteGlove Part 1, which instead writes the `whiteglove.complete` marker
-and leaves state for Part 2).
-
-# Collector model
-
-Collectors are wrapped in **collector hosts** (`ICollectorHost`, built by
-`DefaultComponentFactory.CreateCollectorHosts`). Each host owns collector/tracker
-classes plus a **signal adapter** that translates raw callbacks into decision signals.
-Main hosts (gating in parentheses; several more are opt-in via remote config):
-
-| Host | Watches |
-| --- | --- |
-| EspAndHelloHost | ESP phases, Shell-Core events, provisioning status, Hello (always) |
-| ImeLogHost | IME log tailer (CMTrace) + IME process watcher — app installs (always) |
-| DesktopArrivalHost | real-user desktop arrival (always) |
-| AadJoinHost | AAD join events + hybrid login pending (always) |
-| DeviceInfoHost | one-shot hardware/OS/network inventory (always) |
-| StallProbeHost | idle/stall probes (config) |
-| WindowsUpdateWatcherHost / OsBuildChangeHost | WU during OOBE, build changes (config / always) |
-| DeliveryOptimizationHost | DO counters for bandwidth estimate (config, dormant until installs run) |
-| OfficeInstallDetectorHost, ConsoleBypassHost, ProvisioningPackageHost, NetworkChangeHost, RealmJoinHost, GatherRuleExecutorHost, … | feature-specific (mixed gating) |
-
-# Event pipeline (single rail)
-
-Everything a collector observes flows through **one** path — no collector emits
-telemetry directly:
-
-```
-Collector callback
-  → SignalAdapter (dual emission: decision signal + InformationalEvent)
-    → SignalIngress.Post()            (bounded queue 256, back-pressure blocks producer)
-      → single worker thread:
-          assign ordinals → SignalLog.Append (durable)   ← source of truth
-          → DecisionEngine.Reduce → apply step/effects
-          → telemetry projection (best-effort)
-            → TelemetrySpool → batch (≤100) → gzip → POST /api/agent/telemetry
-```
-
- Wire model: `EnrollmentEvent` (`EventType` from `Constants.EventTypes`, monotonic
-  `Sequence` = canonical order, `Phase`, `ImmediateUpload` for lifecycle-critical items),
-  wrapped in `TelemetryItem` (Kind = Event / Signal / DecisionTransition, monotonic
-  `TelemetryItemId` as upload cursor).
- Auth per request: client-cert mTLS + hardware headers (`X-Tenant-Id`,
-  `X-Device-Manufacturer/-Model/-SerialNumber`, `X-Bootstrap-Token` pre-MDM-cert,
-  `X-Agent-Version`).
- Retry: 100/400/1600 ms for transient (408/429/5xx); 413 → split batch and halve batch
-  size; unknown 4xx → items retained (cursor holds) unless the backend flags explicit
-  poison row keys; offline → spool keeps everything, backend dedups on re-upload;
-  `DeviceBlocked` pauses the drain until `UnblockAt`.
-
-# Decision integration
-
-Adapters post `DecisionSignal`s; the engine's terminal stage fires
-`Terminated` (off the worker thread) → termination sequence above. Engine *effects*
-(timeline events like `enrollment_complete`, deadline scheduling, classifier runs,
-snapshots) are executed by the `EffectRunner` — the reducer itself is pure. Details:
-[decision engine](decision-engine.md); durability and replay:
-[logs & persistence](logs-and-persistence.md).
-
-# On-disk layout (`%ProgramData%\AutopilotMonitor\`)
-
-| Path | Contents |
-| --- | --- |
-| `\` | `bootstrap-config.json`, `await-enrollment.json`, `clean-exit.marker`, session-id persistence |
-| `\Agent\` | deployed binaries |
-| `\State\` | decision persistence (SignalLog, Journal, Snapshot), `enrollment-complete.marker`, `final-status.json`, self-update state, `.quarantine/`, `.part1-<ts>/` |
-| `\Spool\` | telemetry spool (offline queue) |
-| `\Logs\` | agent trace log (`agent.log`), `crash-*.log`, `ime-pattern-matches.log` |
-| `\Config\` | `remote-config.json` cache |
-| `\Agent-Update\`, `\Updates\` | self-update staging/download |
-
-Per-file details and the recovery flow: [logs & persistence](logs-and-persistence.md).
@@ -1,200 +0,0 @@
---
-type: Concept
-title: ESP Completion Starvation — the sits-d Cloud-PC complex
-description: Why five Windows 365 Cloud PCs finished enrolling but never completed in the product — a SkipUser=true flow produces none of the signals every completion-gate evaluation site hangs off — plus the two adjacent defects fixed alongside (edge-only user-apps-settled synthesis, orphaned Hello-wizard restart replay) and what a Shell-Core replay deliberately does not do.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals
-tags:
-  - agent
-  - esp
-  - completion
-  - skip-user
-  - reboot
-  - recovery
-timestamp: 2026-08-20T00:00:00+02:00
---
-
-# ESP Completion Starvation — the sits-d Cloud-PC complex
-
-Seven Windows 365 Cloud PCs, same tenant, first sign-in the same morning. Two sessions
-succeeded within minutes; five sat at `Completion is waiting on: hello_resolution` from
-second five onward and ran into the six-hour max-lifetime watchdog — verdict `Incomplete`
-on devices whose users were working normally the whole time.
-
-The first diagnosis blamed the mid-ESP reboot (DeviceGuard/DmaGuard, see
-[MDM Reboot Coalescing](mdm-reboot-coalescing.md)): the agent is killed in
-`Stage=EspAccountSetup` and, so the theory went, loses the Shell-Core ESP exit to the
-downtime. The evidence disproved it. `8110e262` ran **six hours uninterrupted** after its
-last reboot with the Shell-Core watcher armed — and Windows never wrote a 62407 in all
-that time, because on these machines **the user ESP page never existed**.
-
-# Schema
-
-## The actual defect — a satisfied gate nobody evaluates
-
-The five stuck machines carried `SkipUserStatusPage=True` in the enrollment `FirstSync`
-key (read 10+ times across three agent processes, `True` on every read — not a stale
-single read). Windows honours it: no user ESP page, hence
-
-* no Shell-Core 62407 (`esp_exiting`) — the page that would exit does not exist,
-* no `AccountSetupCategory` provisioning registry — nothing writes categories for a page
-  that never renders,
-* desktop within seconds of sign-in.
-
-The reducer is *built* for this flow: **arm B** of `ShouldTransitionToAwaitingHello`
-(`SkipUserEsp == true`) declares the gate open, and the missing-prerequisites bookkeeping
-already exempts the AccountSetup gate — which is why the sessions reported only
-`hello_resolution` as missing. But the gate is a predicate, not a process. Something has
-to evaluate it, and every evaluation site hangs off a signal a skip-user flow structurally
-cannot produce:
-
-| Evaluation site | Carrier signal | On SkipUser=true |
-|---|---|---|
-| `HandleEspExitingV1` | Shell-Core 62407 | never fires |
-| `HandleEspPhaseChangedV1(FinalizingSetup)` | Shell-Core 62407 via coordinator | never fires |
-| `HandleDesktopArrivedV1` fast-path | requires Hello policy **disabled** | Hello was enabled |
-| `HandleImeUserSessionCompletedV1` arm-C attempt | requires the recorded final exit | unsatisfiable |
-
-No knock, no promotion, no `HelloSafety` — and the `AdvisoryCompletion` backstop is armed
-exclusively from an `EspExiting` signal, so it never armed either. The session idles to
-the watchdog with an open gate.
-
-## The fix — the observed skip is the exit evidence
-
-`HandleImeUserSessionCompletedV1`'s completion attempt now accepts the observed skip in
-place of the final exit (`skipUserExitEquivalent`): on a flow where no page exists, no
-exit can ever say more than the `FirstSync` read already did. Everything else stays
-mandatory — AccountSetup anchor, genuine (at-or-after-anchor) IME user-session completion,
-DAD-validated real-user desktop — which makes this knock **stricter** than the existing
-Shell-Core-carried arm-B promotion (pinned in `ClassicAwaitingHelloGuardTests`, which
-requires no IME or desktop evidence at all). Hello semantics ride the existing rails:
-enabled-or-unknown promotes to `AwaitingHello` with `HelloSafety` armed (on Cloud PCs
-reached via RDP the Hello wizard never appears, so the synthetic timeout resolves the
-wait), disabled completes directly with the synthetic `Skipped` outcome.
-
-The knock deliberately lives on the IME user-session edge, not on desktop arrival:
-
-* **Ordering-robust against Fix 10.** An `EspPhaseChanged(AccountSetup)` arriving on
-  `AwaitingHello` bounces the stage back and cancels `HelloSafety` (the premature-promotion
-  guard). The IME AccountSetup phase line lands *after* the desktop on this flow, so a
-  desktop-side knock would be undone two signals later. The IME phase line always precedes
-  the user-session-complete line in log order, so a bounced promotion is re-knocked by the
-  very next re-emission — including the restart re-parse.
-* **Right semantics.** The IME user session completes when the required-app processing is
-  done; a desktop-side knock would mark the session `Succeeded` mid-installation.
-* Device Preparation is excluded — WDP keeps its Hello+Desktop conjunction and the
-  `DevicePrepCompletion` backstop.
-
-`ClassicSkipUserEspUserSessionCompletionTests` replays the real `8110e262` signal ordering
-end to end (bootstrap `EspConfigDetected` → Hello enabled → desktop → AccountSetup anchor →
-IME completion → HelloSafety → `enrollment_complete`), including the Fix-10
-bounce-then-re-knock cycle, and pins the negative space (no skip observed / no desktop /
-ghost pre-anchor IME completion / WDP).
-
-Why five of seven identically administered Cloud PCs carried `SkipUserStatusPage=True` is
-a tenant-side question (ESP profile assignment state at each machine's provisioning
-moment); the value did not change during any observed session, and machine age does not
-cleanly explain the split. The agent's job is to complete the flow Windows actually ran —
-which it now does.
-
-## Adjacent defect — the synthesis was edge-triggered
-
-This one is real but belongs to the `SkipUser=false` flow (the two sessions that
-succeeded). The user-apps-settled synthesis
-(`MaybeSynthesizeAccountSetupCompleteFromSettledUserApps`, session `caa6cf50`) ran **only**
-from `OnEspExited`. On a tenant with ~138 required apps the ESP page exits while apps are
-still in flight: the single attempt misses and nothing ever re-checks, even when every
-tracked app reaches a terminal state minutes later.
-
-The ESP exit is an **edge** (happens once); settled user-ESP apps are a **level** (reached
-later). `EspAndHelloTracker` records the edge in `_espExitObserved` and exposes
-`ReevaluateUserAppsSettledSynthesis()`, chained into `ImeLogTracker.OnAppStateChanged` and
-into the post-restore `onStateRestored` callback (a live exit observed before the IME
-state restore completes would otherwise never get a second look). Gate conditions are
-unchanged — no new completion path, only a second opportunity for the existing one. Only a
-**live, confirmed post-AccountSetup** exit may be remembered
-(`IsConfirmedPostAccountSetupExit`, stricter than the `IsIntermediateDeviceEspExit`
-forward guard: unknown counts as not confirmed).
-
-## Adjacent defect — the restart replay was never wired up
-
-`ShellCoreTracker`'s backfill had existed since session `772fe502` with **no caller**; the
-Shell-Core `EventLogWatcher` only delivers records written after `Start()`.
-`EspAndHelloHost.Start()` now calls it as `BackfillRecentHelloWizardStart` — which is
-exactly what it does and all it does:
-
-| Record | Replayed | Why |
-|---|---|---|
-| 62404 Hello-wizard start | **yes** | Conservative: vetoes a premature "Hello is disabled" skip, can never complete a session by itself. The observation `772fe502` was about. |
-| 62407 ESP exit | **no** | Cannot be placed in time — see below. |
-| 62407 ESP failure | **no** | Re-injecting a historic failure as fresh can fail a session that recovered on retry (`ANALYZE-ESP-006`). |
-
-A replayed exit is unusable, and every candidate ordering mechanism fails independently:
-
-1. Windows writes the **identical** description `CommercialOOBE_ESPProgress_Page_Exiting`
-   for the intermediate DeviceSetup→AccountSetup transition and the final exit.
-2. Every post-hoc ordering probe (AccountSetup registry, settled-apps) reads state as it
-   is **now**, not as it was at the event's time.
-3. The reducer orders exits by **ingest ordinal**, not timestamp
-   (`IsPostAccountSetupFinalExit`) — a historic exit replayed today gets a fresher ordinal
-   than reality and reads as post-AccountSetup by construction.
-4. `HandleEspExitingV1` passes `espFinalExitInFlight: true` for every arriving exit; with
-   restored state, arm C would open on a historic intermediate exit.
-
-`ClassicEspExitingOnRestoredStateTests` pins that the reducer *does* open on any arriving
-exit; `ShellCoreTrackerReplayScopeTests` pins that the replay never produces one. Skipped
-62407 records are counted and reported once as an `agent_trace`
-(`reason: replayed_62407_not_orderable`) — silently dropping evidence is how this class of
-bug survives.
-
-**Residual gap, named honestly:** a `SkipUser=false` session whose final exit falls
-exactly into an agent downtime *and* whose AccountSetup category never resolves
-(`1ec8f4c6` shape) still has no completion carrier after the restart. The normal case is
-covered — `ProvisioningStatusTracker` reads the current registry at startup, so a
-category that resolved during the downtime fires arm A. The residual shape is rare,
-surfaced by `ANALYZE-ESP-005` via the `session_stalled` interim trigger, and deliberately
-not patched with a replay that cannot be ordered.
-
-### Sizing the replay window
-
-A constant is provably wrong: the scheduled task has a `BootTrigger` only
-(`Program.InstallMode.BuildScheduledTaskXml`) — after an `exception_crash` the agent does
-not return until the next boot. `ResolveEspExitBackfillLookbackMinutes` reaches back to
-the last moment the previous run is known to have been alive (max of `snapshot.json`
-mtime and `LastBootUtc` for kill-type exits), floored at 5 minutes, capped at 360, off on
-`first_run`, and immune to cross-reboot clock skew (a future timestamp is ignored).
-
-# Examples
-
-Tenant `sits-d.cloud`, 2026-08-19, seven Windows 365 Cloud PCs, first sign-ins the same
-morning. The discriminator is a single registry value:
-
-| Session | SkipUser | `esp_exiting` | AccountSetup registry | Reboots | Outcome |
-|---|---|---|---|---|---|
-| `08fc6bda` | False | yes | yes | 0 | Succeeded (10 min) |
-| `3b9291aa` | False | yes | yes | 0 | Succeeded (2.1 h) |
-| `8110e262` | True | — | — | 2 | Incomplete (6 h watchdog) |
-| `a89aac2d` | True | — | — | 1 | Incomplete |
-| `e7ba63c9` | True | — | — | 1 | Incomplete |
-| `cb4a485a` | True | — | — | 2 | Incomplete |
-| `3d6278fb` | True | — | — | 1 | Incomplete |
-
-The reboot correlation was a red herring: `8110e262` ran six hours live after its final
-reboot and would have seen every signal. `8110e262` and `a89aac2d` both reached
-`138/138 completed, 0 failed` and a genuine IME user-session completion — with the fix,
-all five complete a few minutes after their IME user session settles.
-
-`08fc6bda` exercises the edge-level fix on the same day: ESP page exited normally while
-`categorySucceeded` never confirmed — completed via the user-apps-settled synthesis.
-`3b9291aa` shows the independent starvation visibility gap: 99 `app_install_starved`
-events on a session recorded as `Succeeded` — surfaced from now on by `ANALYZE-APP-016`.
-
-# Citations
-
-* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Classic.cs` — `HandleImeUserSessionCompletedV1`, `skipUserExitEquivalent`
-* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.Shared.cs` — `ShouldTransitionToAwaitingHello` (arm B)
-* `src/Agent/AutopilotMonitor.DecisionCore.Tests/ClassicSkipUserEspUserSessionCompletionTests.cs` — end-to-end replay of the 8110e262 ordering
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ShellCoreTracker.cs` — `BackfillRecentHelloWizardStart`, `ReplayBackfillRecords`
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/EspAndHelloTracker.cs` — `_espExitObserved`, `ReevaluateUserAppsSettledSynthesis`
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/DefaultComponentFactory.cs` — lookback sizing, `OnAppStateChanged` chaining
-* [MDM Reboot Coalescing](mdm-reboot-coalescing.md) — the policy attribution for the reboots themselves
-* [Decision Engine](decision-engine.md) — the AccountSetup gate and completion arms
@@ -1,89 +0,0 @@
---
-type: concept
-title: Registry App-State Second Pillar
-description: Why the agent reads IME's authoritative per-app state straight from the registry (Win32Apps / EspTrackingWin32Apps / StatusServiceReports), how the snapshot-and-diff observer works, and how registry/log reconciliation doubles as the built-in IME log-pattern drift alarm.
-resource: agent
-tags: [ime, registry, win32apps, observability, reconciliation, pattern-drift, wdp]
-timestamp: 2026-08-18
---
-
-# Schema
-
-## Why a second pillar
-
-The 2026-08-17 audit of the decompiled IME (1.97.107 / 1.104.102) proved that IME log
-wording is an unstable contract: Microsoft removed the old V1/V2 processing pipeline
-(killing 9 patterns silently), reworded the post-remediation line, changed the
-report-delta quoting between 1.97 and 1.104, and deleted `[DO TEL]` entirely. The
-registry, by contrast, is IME's *internal product contract* — the ESP page and Intune
-reporting consume it — and cannot drift casually.
-
-Architecture decision (Oliver, 2026-08-17): **hybrid**. Logs stay the narrative
-(downloads, retries, exit codes, scripts — the timeline). The registry is the stable
-truth for terminal state. Divergence between the two IS the alarm that log patterns
-drifted — turning silent data loss into a Warning event.
-
-## Observed surfaces
-
-All under `HKLM\SOFTWARE\Microsoft\IntuneManagementExtension` (64-bit view), verified
-against decompiled IME source:
-
-| Surface | Content |
-|---|---|
-| `Win32Apps\<userGuid>\<appGuid>_<rev>` | `EnforcementStateMessage` JSON (EnforcementState + ErrorCode), `ExitCode`, `Intent`. Device context = `Guid.Empty` user. Non-GUID subkeys (GRS, OperationalState, Reporting, ProvisioningProgress) are skipped. |
-| `EspTrackingWin32Apps\<userGuid>\<appGuid>_<rev>` | Which apps IME registered for ESP tracking, `EspTrackingWin32AppPhase`. |
-| `SideCarPolicies\StatusServiceReports\<userGuid>\<appId>` | The `AppInstallStatusReport` the ESP page renders (`Status`: 1000=Installed, 1001=Installing, 3000=Failed, 2000er=NotApplicable). |
-
-## Mechanism
-
-`ImeRegistryAppStateObserver` + `ImeRegistryAppStateHost` (always-on, no config gate —
-precedent `EspPolicyProviderStallHost`):
-
- **One recursive `RegistryWatcher`** on the IME root covers all three surfaces;
-  changes are debounced (2 s trailing edge) into a tick. A 60-s periodic tick is both
-  the reconciliation-settle evaluator and the poll-only fallback when the watcher
-  fails to arm (`collector_degraded`, once).
- **Snapshot-and-diff**: `RegNotifyChangeKeyValue` gives coalesced key-scope edges
-  only, so every tick re-reads the surfaces and diffs against the previous snapshot.
- **Silent baseline**: the state present at agent start is captured without events.
-  Win32Apps keys survive re-enrollments — replaying them would be the registry twin
-  of the historic-IME-replay bug. Only apps that *change during the session* are
-  reported or judged.
- **`registry_app_state`** (Info): emitted per real field change
-  (enforcementState/errorCode/exitCode/statusServiceStatus/espTracked/espPhase),
-  capped at 200/session (cap announced once as Warning).
- **`app_state_reconciliation`** (Warning, once per app, immediate upload): after a
-  changed entry has been terminal (EnforcementState 1000er=success / 5000er=error,
-  or StatusService 1000er/3000) for ≥ 90 s, its outcome is compared against the
-  log-derived `AppPackageState` from `ImeLogHost.AllKnownPackageStates`. Divergence
-  reasons: `registry_error_log_installed`, `registry_success_log_error`,
-  `app_unknown_to_log_tracking` (only when the tracker is actively tracking apps —
-  an idle tracker is not judgeable).
- **Pure observability**: nothing feeds the DecisionEngine (same rule as
-  oobe-state observability).
-
-## WDP reuse (Paket 3)
-
-The same host archetype (RegistryWatcher subtree + debounce + snapshot-diff) is the
-intended vehicle for WDP live progress: watch
-`HKLM\SOFTWARE\Microsoft\Provisioning\AutopilotSettings\DevicePreparation\BootstrapperAgent`
-(`ProgressUpdates` rows, `ResumeContext.ProvisioningResult` terminal marker) with the
-RealmJoinWatcher appearance-watcher pattern for not-yet-existing keys, plus an
-Event-142 channel watcher (`Microsoft-Autopilot-BootstrapperAgent/BootstrapperAgentServiceLogProvider`,
-channel handling precedent in `DiagnosticsPackageService`). Win32Apps keys are written
-on WDP devices too — the pillar works on both rails unchanged.
-
-# Examples
-
-Timeline evidence of a drifted pattern set: apps install fine (registry says
-EnforcementState 1000) but the timeline shows no `app_install_completed` — each app
-raises one `app_state_reconciliation` with `reason=app_unknown_to_log_tracking`.
-Operator response: run `/ime-pattern-validate` against the session, fix patterns,
-backend-deploy (no agent release needed for pattern fixes).
-
-# Citations
-
- `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ImeRegistryAppStateObserver.cs`
- `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/Hosts/ImeRegistryAppStateHost.cs`
- `tasks/ime-v1-code-audit-2026-08-17.md` (decompiled-source audit; registry surface catalog)
- Decompile archive: `okieselbach/ime-decompiles` (private), `C:\Code\GitHubRepos\ime-decompiles\<version>\decompiled`
@@ -1,100 +0,0 @@
---
-type: Concept
-title: Secure Boot CA-2023 Detection — firmware evidence vs. Windows servicing status
-description: Why ANALYZE-SEC-001 v3 reads the UEFI db/KEK variables directly (GetFirmwareEnvironmentVariableExW + SeSystemEnvironmentPrivilege) instead of trusting the SecureBoot\Servicing registry key, and how the one-sided uefiCa2023FirmwareConfirmed marker plus a not_exists precondition give absence-tolerant rule suppression across old and new agents.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/UefiSecureBootCertReader.cs
-tags:
-  - agent
-  - secureboot
-  - ca2023
-  - analyze-rules
-  - backward-compatibility
-timestamp: 2026-07-23T00:00:00+02:00
---
-
-# Secure Boot CA-2023 Detection
-
-## Schema
-
-Two independent evidence sources describe the Windows UEFI CA 2023 rollout state:
-
-1. **Servicing registry** (`HKLM\SYSTEM\CurrentControlSet\Control\SecureBoot\Servicing\UEFICA2023Status`)
-   — reflects whether the *Windows Update* rollout ran and self-verified. Lags reality:
-   devices whose firmware received the certificate another way (OEM factory image, WinCS
-   CLI, manual deployment) or where WU simply has not run yet show `unknown`/`notfound`.
-2. **Firmware itself** — the UEFI variables `db` (signature database, GUID
-   `{d719b2cb-3d3a-4596-a3bc-dad00e67656f}`) and `KEK` (GUID
-   `{8be4df61-93ca-11d2-aa0d-00e098032b8c}`). Authoritative. Certificate subject CNs are
-   ASCII bytes inside the DER signature lists, so a byte-substring search for
-   `Windows UEFI CA 2023` / `Microsoft Corporation KEK 2K CA 2023` decides presence —
-   the same check `Get-SecureBootUEFI` enables from PowerShell.
-
-`UefiSecureBootCertReader` (agent, `Monitoring/Interop`) reads both variables natively via
-`GetFirmwareEnvironmentVariableExW` — no PowerShell runspace during OOBE. The call needs
-`SeSystemEnvironmentPrivilege`: SYSTEM holds it default-disabled, so the reader enables it
-on the process token (`AdjustTokenPrivileges`) and restores the previous state afterwards.
-Fail-soft contract like `OobeStateReader`: never throws; failures map to status strings
-(`not_uefi` = legacy BIOS via `ERROR_INVALID_FUNCTION`, `variable_not_found`,
-`privilege_denied`, `error_<code>`).
-
-This is the repo's only privilege-adjustment code, so it also carries the ownership rules
-any future one should copy:
-
-* The process token lives in a `SafeHandle` assigned by the P/Invoke marshaler, so the CLR
-  owns it from the moment `OpenProcessToken` returns — the critical finalizer releases it
-  even if `Dispose` never runs (async exception before the instance reaches its `using`).
-* The restore obligation is recorded immediately after the successful `AdjustTokenPrivileges`,
-  and only when the privilege was not *already* enabled; nothing that can throw sits between
-  the adjustment and that assignment. `Dispose` is idempotent, swallows a failed restore, and
-  releases the handle in a `finally`.
-* The privilege is adjusted on the **process** token, so enable → read → restore is a
-  process-wide side effect and runs under a static gate. Without it a concurrent reader would
-  see "already enabled", correctly skip its own restore, and then lose the privilege mid-read
-  when the first reader disposes — a spurious `privilege_denied` on a machine that holds it.
-
-Fields land on the existing `secureboot_status` event (once per agent start,
-restart-deduped by the StartupEventGate): `uefiFirmwareReadStatus`, per-cert booleans
-(`uefiDbHasWindowsUefiCa2023`, `uefiDbHasWindowsProductionPca2011`,
-`uefiKekHasMicrosoftKek2kCa2023`, …) — emitted only when the respective read succeeded —
-plus the marker below.
-
-## The one-sided marker (absence-tolerant suppression)
-
-Rule-engine constraints (pinned by `RuleEnginePreconditionTests`):
-
-* **Conditions** never match on an absent field (null guard) — new fields must stay
-  `required: false` or the rule dies for every old agent.
-* **Preconditions**: `not_exists` passes while the field is absent/empty and fails as soon
-  as the field is present with *any* value; comparison operators fail closed on absence.
-
-A two-sided boolean therefore cannot drive suppression: `not_exists` on
-`uefiDbHasWindowsUefiCa2023` would also suppress the rule when the field is present with
-`false`. Hence the **one-sided marker** `uefiCa2023FirmwareConfirmed = true`, emitted
-ONLY when the db read succeeded AND the 2023 certificate was found — never as `false`.
-ANALYZE-SEC-001 v3 adds a `not_exists` precondition on it:
-
-| Device state | Marker | Rule |
-|---|---|---|
-| Old agent (no firmware fields) | absent | evaluates exactly like v2 |
-| New agent, cert missing or firmware unreadable | absent | evaluates; optional conditions `uefiDbHasWindowsUefiCa2023=false` (+20) / `uefiKekHasMicrosoftKek2kCa2023=false` (+10) raise confidence |
-| New agent, firmware confirms cert | present | silently suppressed (the customer-reported false positive) |
-
-Because the marker exists nowhere until the new agent ships, the v3 rule is safe to seed
-**before** the agent rollout.
-
-## Examples
-
-Customer-equivalent verification from PowerShell (authoritative, matches the reader):
-
-```powershell
-[Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name db).Bytes).Contains('Windows UEFI CA 2023')
-[Text.Encoding]::ASCII.GetString((Get-SecureBootUEFI -Name KEK).Bytes).Contains('Microsoft Corporation KEK 2K CA 2023')
-```
-
-## Citations
-
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Interop/UefiSecureBootCertReader.cs` — native reader
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/DeviceInfoCollector.NetworkAndSecurity.cs` — `CollectSecureBootStatus` / `AppendFirmwareCertFields`
-* `rules/analyze/ANALYZE-SEC-001.json` — v3.0.0 rule definition
-* `src/Backend/AutopilotMonitor.Functions.Tests/RuleEnginePreconditionTests.cs` — pinned precondition semantics + v3 mirror tests
-* Microsoft: [Act now — Secure Boot certificates expire June 2026](https://techcommunity.microsoft.com/blog/windows-itpro-blog/act-now-secure-boot-certificates-expire-in-june-2026/4426856)
@@ -1,108 +0,0 @@
---
-type: concept
-title: WDP Scenario Gates & Completion Backstop
-description: How the agent gates Autopilot/ESP-only machinery off on Windows Device Preparation (WDP) sessions and how a WDP session resolves without any ESP signal.
-resource: agent
-tags: [wdp, device-preparation, decision-engine, collectors, completion]
-timestamp: 2026-08-18
---
-
-# Schema
-
-Windows Device Preparation (Autopilot v2, "WDP") has **no deployment profile and no ESP**.
-Before the afee7ae0 audit (2026-08-18) the agent ran the full Classic apparatus anyway:
-misleading `autopilot_profile_missing` warnings, a ZTD event-log query + HTTP probe,
-`esp_config_detected` "unknown/unknown" noise, an Autopilot-channel noise flood
-(EventIDs 100/417/418/1005, 900+ occurrences per session), a subtree registry watcher
-woken by every WDP progress write, and — worst — no completion path when Hello never
-resolved (park until the 360-min watchdog).
-
-## Detection: deterministic vs. fallback
-
-`EnrollmentRegistryDetector` classifies v2 through three rules. Only the first is
-**deterministic WDP**:
-
-1. `AutopilotSettings\DevicePreparation\BootstrapperAgent` subkey with non-empty
-   `ExecutionContext` → the WDP policy orchestration tree, present before the agent
-   starts. Exposed as `EnrollmentRegistryDetector.IsDeterministicDevicePreparation()`
-   and the `DevicePreparationExecutionContextRule` constant.
-2./3. `CloudAssignedDeviceRegistration == 2` / `CloudAssignedEspEnabled == 0` —
-   profile-derived legacy signals. They imply a REAL Autopilot profile (just ESP-less),
-   so every gate below deliberately ignores them: **gates require the deterministic
-   marker and fail toward Classic behavior.**
-
-## Agent-side gates (all keyed to the deterministic marker)
-
-* `DeviceInfoCollector.CollectAutopilotProfile`: no `autopilot_profile` event, no
-  `autopilot_profile_missing` warning, no ZTD event-log query, no ZTD HTTP probe.
-  `enrollment_type_detected` still fires. (WDP devices DO carry an
-  `AutopilotPolicyCache` with `ProfileAvailable=0` / error 807 `ZtdDeviceIsNotRegistered`
-  — Windows runs the ZTD download regardless — so the probe fired for real before.)
-* `CollectEspConfigurationLocked`: `esp_config_detected` is emitted only when at least
-  one FirstSync value or ESP tracking list exists (generic null-gate, mirrors the
-  orchestrator bootstrap's signal gate) — fixes "unknown/unknown" for WDP AND plain
-  Entra joins.
-* `DefaultComponentFactory`: `EspPolicyProviderStallHost` (60-s poll of the ESP-only
-  `EnrollmentStatusTracking` key) is not created on WDP.
-* `EspAndHelloTracker.Start`: `ProvisioningStatusTracker` is not started on WDP — its
-  subtree watcher sits on `AutopilotSettings`, exactly where WDP's BootstrapperAgent
-  writes progress, so it woke on every write only to read three ESP category values
-  that never exist there.
-* `ModernDeploymentTracker`: `DevicePreparationNoiseEventIds` {100, 417, 418, 1005}
-  are suppressed entirely on WDP (before `FormatDescription()`); Critical (level 1)
-  always passes; genuine WDP diagnostics (e.g. 408) keep flowing. The Autopilot error
-  backfill (807/809/815/908 replay) is skipped — 807 is the EXPECTED state on WDP.
-  The watcher itself stays on: WDP's provisioning stack logs into the same channels.
-* `StallProbeCollector`: skips the ESP category registry scan on WDP and unions the
-  noise IDs into its harmless set; the channel scans remain (they carry genuine WDP
-  diagnostics during a stall).
-* `EnrollmentTerminationHandler`: the `app_install_starved` terminal sweep is skipped
-  on WDP — post-desktop installs are the DESIGNED order there (only DPP-policy apps
-  run during provisioning); per-app data still travels via `app_tracking_summary` and
-  final-status.json.
-
-## DecisionCore: WDP completion without ESP facts
-
-* **Seeding**: `EnrollmentFactsObserved` carries `enrollmentTypeDeterministic`;
-  the deterministic marker seeds `DevicePreparation` at **High** confidence (same
-  registry-determinism standard as the self-deploying OobeConfig bits), the fallback
-  rules stay Medium. The three explicit downgrade guards from d0ab3eee remain as
-  defence in depth.
-* **Arm D** (`ShouldTransitionToAwaitingHello`): on WDP the DAD-validated real-user
-  desktop is a legitimate promotion basis — arms A–C are unsatisfiable by construction
-  (no provisioning categories, no Shell-Core 62407 final exit). With a disabled Hello
-  policy the fast-path now completes at desktop arrival.
-* **Prerequisites**: `completion_waiting` never lists
-  `account_setup_provisioning_complete` on WDP (unsatisfiable; mirrors the
-  `skipUserEsp` exemption).
-* **Backstop**: `DeadlineNames.DevicePrepCompletion` (30 min, replay-safe base) is
-  armed by `HandleDesktopArrivedV1` when a WDP session parks desktop-first with Hello
-  pending. On fire it mirrors the HelloSafety timeout: synthetic
-  `HelloOutcome=Timeout` + completion through Finalizing. This closes the
-  "no Hello → park until watchdog" hole; a timer surviving into a terminal stage is
-  swallowed by the post-terminal dispatch guard.
-* **Tripwire**: `DecisionStepProcessor.IsParkedWithoutDeadline` has a WDP branch
-  (dead-end zone = desktop arrived) so a regression in the backstop becomes visible
-  as `session_parked_without_deadline`.
-
-# Examples
-
-Session afee7ae0 (the audit trigger): Succeeded in 9:32 min, but its timeline carried
-`autopilot_profile` (807), an `autopilot_profile_missing` WARN, `esp_config_detected`
-unknown/unknown, 30 `modern_deployment_log` rollup events and 10 `app_install_starved`
-entries — all structurally meaningless on WDP. After the gates, the same session shape
-emits none of these; completion rode Hello-skipped + desktop as before.
-
-Deliberately NOT changed (open follow-ups, see the WDP audit topic memory): the ESP
-phase vocabulary (`esp_phase_changed`/stage names ride the Classic rails on WDP),
-subscription to the `BootstrapperAgentServiceLogProvider` event channel, and
-`registry_app_state` as the primary WDP app source.
-
-# Citations
-
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Security/EnrollmentRegistryDetector.cs` — deterministic rule + helper
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/DeviceInfo/DeviceInfoCollector.NetworkAndSecurity.cs` — profile/ESP emission gates
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Enrollment/SystemSignals/ModernDeploymentTracker.cs` — `DevicePreparationNoiseEventIds`
-* `src/Shared/AutopilotMonitor.DecisionCore/Engine/DecisionEngine.DevicePreparation.cs` — backstop deadline
-* `src/Shared/AutopilotMonitor.DecisionCore/State/EnrollmentScenarioProfileUpdater.cs` — High/Medium seeding
-* Tests: `DevicePreparationEngineTests`, `ModernDeploymentTrackerDevicePrepTests`, `EnrollmentTerminationHandlerTests.StarvedApps_skipped_on_device_preparation`, `DeviceInfoCollectorEspRefreshTests.NoEspEvidenceAtAll_SuppressesTheEvent`
@@ -1,135 +0,0 @@
---
-type: Architecture Guide
-title: Autopilot Monitor – Architecture Guide
-description: High-level architecture overview and solution layout for contributors.
-tags:
-  - architecture
-  - agent
-  - backend
-  - web
-  - mcp
-timestamp: 2026-07-06T21:39:29+02:00
---
-
-# Autopilot Monitor – Architecture Guide
-
-> High-level architecture overview and solution layout for contributors.
-> Full product documentation lives at https://docs.autopilotmonitor.com.
-
---
-
-## High-Level Overview
-
-```text
-+----------------------------------------------------------------------------------+
-|                         Autopilot Monitor - Architecture                         |
-+----------------------------------------------------------------------------------+
-
- [Admin/User Browser]
-          |
-          | HTTPS
-          v
-+-----------------------------+      OIDC        +-------------------------------+
-| Web App (Next.js)           |<---------------->| Microsoft Identity (Entra ID) |
-| Dashboard / Progress        |                  | Auth / Authorization          |
-+-----------------------------+                  +-------------------------------+
-          ^    ^
-          |    |
-          |    | Live updates
-          |    |
-          |    |                         +---------------------------+
-          |    +-------------------------| SignalR Hub               |
-          |                              | Real-time event stream    |
-          |                              +---------------------------+
-          |                                          ^
-          | REST / API                               |
-          v                                          | events
-+---------------------------+        Data &          |
-| Azure Functions Backend   |------> Integrations ---+
-| APIs / Ingestion / Rules  |               \
-+---------------------------+                \       +---------------------------+
-          ^                                   +----->| Storage Tables            |
-          | mTLS                                     | Sessions / Events / Rules |
-          | telemetry / events                       +---------------------------+
-          |                                          +---------------------------+
-+---------------------------+                        | Notifications             |
-| Agent on Windows Devices  |                        | Teams / Slack / Webhooks  |
-| Enrollment + app progress |                        +---------------------------+
-+---------------------------+
-                                                     +---------------------------+
-                                                     | MCP Server                |
-                                                     | Azure Container App       |
-                                                     +---------------------------+
-```
-
-**Core Data Flow:**
-```
-Device (Agent) ──JSON telemetry+gzip──► Azure Functions ──► Azure Table Storage
-                                      │                     │
-                                      ├── SignalR ─────────►│
-                                      │                     │
-                              Web Dashboard ◄── REST API ◄──┘
-```
-
-| Component | Technology | Purpose |
-|-----------|------------|---------|
-| **Agent** | .NET Framework 4.8 (Windows) | Runs on devices during enrollment, collects telemetry |
-| **SummaryDialog** | .NET Framework 4.8 (WPF) | Post-enrollment summary UI (outcome, app timeline, auto-close) |
-| **Backend** | Azure Functions .NET 8 (Isolated Worker) | REST API, event processing, rule engine, storage |
-| **Web** | Next.js 15 + TypeScript + React 18 | Dashboard, settings, analytics, real-time UI |
-| **Shared** | .NET Standard 2.0 | DTOs, models, enums, constants shared between Agent & Backend |
-| **MCP Server** | Azure Container App | Model Context Protocol server for AI-assisted analysis |
-
---
-
-## Solution Structure
-
-```
-AutopilotMonitor.sln
-├── src/
-│   ├── Shared/
-│   │   ├── AutopilotMonitor.Shared/             (netstandard2.0 – DTOs, models, enums, constants)
-│   │   └── AutopilotMonitor.DecisionCore/       (netstandard2.0 – completion decision engine)
-│   ├── Agent/
-│   │   ├── AutopilotMonitor.Agent.V2/           (net48, Exe – entry point; output named AutopilotMonitor.Agent.exe)
-│   │   ├── AutopilotMonitor.Agent.V2.Core/      (net48, Lib – core logic)
-│   │   ├── AutopilotMonitor.Agent.V2.Core.Tests/ (net48, xUnit – agent unit tests)
-│   │   ├── AutopilotMonitor.DecisionCore.Tests/ (net48, xUnit – decision engine tests)
-│   │   ├── AutopilotMonitor.SummaryDialog/      (net48, WPF – enrollment summary UI)
-│   │   └── AutopilotMonitor.SummaryDialog.Tests/ (net48, xUnit)
-│   ├── Backend/
-│   │   ├── AutopilotMonitor.Functions/          (net8.0, Azure Functions v4)
-│   │   └── AutopilotMonitor.Functions.Tests/    (net8.0, xUnit)
-│   ├── McpServer/
-│   │   └── autopilot-monitor-mcp/               (TypeScript/Node – MCP server; deployed as Azure Container App)
-│   └── Web/
-│       └── autopilot-monitor-web/               (Next.js 15, TypeScript)
-├── rules/
-│   ├── gather/                                   Individual gather rule JSONs
-│   ├── analyze/                                  Individual analyze rule JSONs
-│   ├── ime-log-patterns/                         IME regex pattern JSONs
-│   ├── schema/                                   JSON Schema definitions
-│   ├── guardrails.json                           Gather-rule guardrail allow-lists (source)
-│   ├── scripts/                                  combine.js
-│   └── dist/                                     Combined output (embedded in Functions)
-├── infra/                                        Bicep templates (MCP server)
-├── scripts/
-│   ├── Backup/                                   Table backup/restore tooling
-│   ├── Bootstrap/                                Intune deployment scripts
-│   ├── CustomerSetup/                            Customer onboarding helpers
-│   └── Deployment/                               CI/CD build scripts
-└── .github/workflows/                            CI/CD pipelines
-```
-
-**Project References:**
-```
-Shared + DecisionCore ◄── Agent.V2.Core ◄── Agent.V2
-                                          ◄── Agent.V2.Core.Tests
-Shared + DecisionCore ◄── DecisionCore.Tests
-Shared + DecisionCore ◄── Functions ◄── Functions.Tests
-SummaryDialog ◄── SummaryDialog.Tests   (standalone; compiled alongside the agent build)
-Web (independent – communicates via REST + SignalR)
-McpServer (independent – talks to the backend REST API)
-```
-
---
@@ -1,98 +0,0 @@
---
-type: Concept
-title: App Version Duration Regression Radar
-description: How the radar detects app versions whose median install duration regressed vs. the previous version (median lift ≥2x plus an absolute floor over first-seen-ordered versions), how alert episodes live in the appversionregression tracker keyspace, and which surfaces show them.
-resource: src/Backend/AutopilotMonitor.Functions/Helpers/AppVersionRegressionRadar.cs
-tags:
-  - backend
-  - apps
-  - regression-radar
-  - insights
-timestamp: 2026-08-13T12:00:00+02:00
---
-
-# App Version Duration Regression Radar
-
-Detects "version X made this app's installs much slower" — the concrete, quotable insight
-("median install duration rose from 11 to 29 min after version X") — from the per-(session,
-app) `AppInstallSummaries` rows. Duration only: failure-rate per version is already visible
-in the apps dashboard's `versionBreakdown`, and rate regressions belong to Wilson-interval
-statistics, not medians.
-
-# Schema
-
-## Signal & detection
-
-Per (tenant, app), the MEASURED install population is: `Status == "Succeeded"`, terminal
-state not Skipped/Postponed, `MetricsMath.HasMeasuredDuration` (1s..6h — 0s means the start
-was unobserved, above 6h means back-stamped batches), no `AppIdCollision`, non-empty
-`AppVersion`. Versions are ordered by FIRST-SEEN install time (min `StartedAt`), never by
-string comparison ("9.1" vs "2024.10" would lie). The comparison pair is always the newest
-version (the one with the most recent measured install) vs. the version with the latest
-first-seen strictly before it.
-
-MEDIANS, not means (nearest-rank, shared with the apps dashboard via
-`AppsAnalyticsHelper.Percentile`) — one back-stamped straggler must not fire a fleet alert.
-A regression fires only when ALL hold over the trailing 35-day horizon:
-
-1. both versions have ≥ 10 measured installs;
-2. current median ≥ 2× the previous version's median;
-3. absolute increase ≥ 300 s (a 20s→45s app is noise, not an incident).
-
-## Suppression & limits
-
-* Parallel ring rollouts can make "previous" a concurrently-deployed version — accepted in
-  v1; the episode key (app, current version) still caps it at one bell per version.
-* Platform kill switch: app setting `AppVersionRegressionRadarDisabled=true` skips the
-  radar (fail-open — it only notifies, never mutates data).
-* One cross-tenant install-summary read per pass (the same query the global apps dashboard
-  runs), grouped by tenant; per-tenant failures are non-fatal.
-
-## Alert episodes (tracker keyspace)
-
-An episode lives as `appversionregression|{app-lower}|{version-lower}` (table-key-sanitized;
-raw AppName/CurrentVersion live in columns, the mapper never parses the RowKey) in the
-notification-tracker table, next to the `ruleregression|` keyspace: the row IS the dedup
-(bell + ops event fire exactly once per episode) and the `versionRegressions[]` payload —
-both medians, both sample counts, lift. Numbers refresh on every radar pass while the
-episode stays active; `FirstNotifiedAt` never moves. The episode closes (dedup re-arms) when
-the alerted version drains under 10 measured installs in the horizon or its recomputed
-median falls back under 1.5× the previous version's median; the tracker's 30-day retention
-sweep also re-arms, so a month-old still-burning regression rings once more by design.
-
-## Notification chain (v1: bell + ops event)
-
-* Tenant bell `app_version_duration_regression` (audience: Admin), href
-  `/apps/detail?name={app}&days=35` (canonical `appDetailUrl` shape). Message carries the
-  full numbers so the admin can verify without a portal round-trip.
-* Ops event `AppVersionDurationRegression` (Tenant category, Warning) — dual-registered in
-  the web `OPS_EVENT_TYPES` catalog so operators can wire Telegram/Teams/Slack alert rules.
-
-## Surfaces
-
-* `apps/{appName}/analytics` (+ global twin with `?tenantId=`) responds with
-  `versionRegressions[]` (empty for the cross-tenant aggregate — episodes are per-tenant
-  rows), and `versionBreakdown[]` rows now carry `measuredInstalls` /
-  `medianDurationSeconds` / `p95DurationSeconds`.
-* Apps detail page: amber "↑ Duration regression" banner above the version cards and a
-  "Median Install Duration by Version" bar chart.
-
-# Examples
-
-A tenant ships Contoso VPN 2.4.0 after 2.3.9. 2.3.9 has 40 measured installs, median 660s;
-2.4.0 accumulates 12 measured installs with median 1740s. Lift 2.6×, absolute +1080s →
-episode `appversionregression|contoso vpn|2.4.0` opens, one bell + one ops event fire.
-Subsequent passes refresh the numbers only. When 2.4.1 replaces 2.4.0 and 2.4.0 drains
-below 10 measured installs in the horizon, the episode deletes and the dedup re-arms.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Helpers/AppVersionRegressionRadar.cs` — pure core
-  (gates, first-seen ordering, re-arm).
-* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.AppVersionRegression.cs`
-  — orchestration, kill switch, bell/ops-event emission, wording contract.
-* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableHardwareRejectionNotificationTracker.cs`
-  — episode keyspace, entity round-trip.
-* `src/Shared/AutopilotMonitor.Shared/Models/Metrics/AppVersionRegressionAlert.cs` — persisted
-  alert payload.
-* [Rule Regression Radar](rule-regression-radar.md) — the sibling pattern this radar mirrors.
@@ -1,95 +0,0 @@
---
-type: Concept
-title: Business Timestamps vs. the Azure Tables System Timestamp
-description: Why the system Timestamp is never authoritative, how the 2026-07-18 migration exposed that, and the OccurredUtc + RowKey-decode compensation (mappers, RowKey-range date filters, retention, backfill).
-resource: /src/Backend/AutopilotMonitor.Functions/Helpers/BusinessTimestamp.cs
-tags:
-  - backend
-  - table-storage
-  - audit-log
-  - ops-events
-  - events
-  - migration
-timestamp: 2026-07-20T00:00:00+02:00
---
-
-# Problem
-
-Azure Table Storage's `Timestamp` is a **system property**: the server ignores any supplied
-value on write and stamps the row's *write* time; every row rewrite (storage-account
-migration, MERGE) resets it. Three tables nevertheless treated it as the business event
-time — writes like `["Timestamp"] = evt.Timestamp` were silent no-ops, unnoticed because
-write time ≈ event time in normal operation.
-
-The 2026-07-18 EU storage migration rewrote every row, so all migrated rows in
-**AuditLogs**, **OpsEvents**, and **Events** read as "2026-07-18 ~13:58 UTC": displays were
-wrong, date-window filters matched the wrong rows, and retention froze (nothing older than
-the migration moment) with a mass-delete cliff one retention period later.
-
-# Rule
-
-**The system Timestamp is never authoritative.** Every table that needs an event time
-stores it in the custom column `OccurredUtc` (`BusinessTimestamp.OccurredUtcColumn`).
-Custom columns are copied verbatim by `scripts/Migration/Copy-TableStorage.ps1`, so future
-migrations preserve chronology. Migration checklist: any table whose reads/filters depend
-on a timestamp must carry it as a custom column — audit this before every storage move.
-
-# Recovery sources per table
-
-The original time survives migrations inside the RowKey:
-
-| Table | RowKey scheme | Decodable |
-|---|---|---|
-| AuditLogs | `!{MaxTicks-ticks:D19}_{guid:N}` (since 2026-05-06) | Yes; legacy bare-GUID rows (pre-2026-05) are lost |
-| OpsEvents | `{MaxTicks-ticks:D19}` | Yes, all rows |
-| Events | `{ts:yyyyMMddHHmmssfff}_{seq:D10}` (sanitized agent time) | Yes, all rows (ms precision) |
-
-# Mechanism
-
-`BusinessTimestamp` (Functions/Helpers) is the single source of truth: RowKey decoders,
-the OData clause builders, and `GetUtcDateTime` (datetime columns materialize as
-`DateTimeOffset` *or* `DateTime` depending on payload shape — always read via this helper).
-
-1. **Read mappers** resolve `OccurredUtc` → RowKey decode → system Timestamp (last
-   resort; only audit legacy GUID rows end there). Resolvers:
-   `TableStorageService.ResolveAuditTimestamp`, `TableOpsEventRepository.ResolveTimestamp`,
-   `TableStorageService.ResolveEventTimestamp` (also used by
-   `GetEarliestSessionEventTimestampAsync`, which feeds StartedAt/Duration reconciliation —
-   a system-Timestamp read there would rewrite migrated sessions' derived fields).
-2. **Date-window filters and retention use RowKey ranges**, not property comparisons:
-   OData excludes rows missing a compared property (an `OccurredUtc` filter would drop
-   every not-yet-backfilled row), and RowKey ranges are index-backed. Boundary semantics
-   are tick-exact equivalents of the old `Timestamp ge/le` clauses.
-   **Trap:** audit legacy GUID RowKeys (hex first char) sort *after* all `!`-rows, so
-   every lower bound `RowKey ge '!…'` must be paired with `RowKey lt '"'`
-   (`AuditTimeEncodedUpperBound`) — without the guard, a retention sweep would delete all
-   legacy rows. Pinned by `BusinessTimestampFilterClauseTests`.
-3. **Writes** in all three tables now set `OccurredUtc`; the no-op `["Timestamp"]`
-   entries were removed.
-4. **Backfill** (`POST /api/maintenance/backfill-occurred-utc`, GlobalAdminOnly, dry-run
-   by default, `table=audit|ops`, batched via `maxRows`/`continuation`): MERGE that adds
-   only `OccurredUtc` decoded from the RowKey — deterministic and idempotent. **Events
-   rows are deliberately never backfilled** (read-path decode is sufficient; no bulk
-   mutation of enrollment evidence). Note: a MERGE resets the row's system Timestamp —
-   irrelevant once nothing depends on it.
-5. **Audit retention** runs two passes until ~2027-01: RowKey-range for `!`-rows plus a
-   `RowKey ge '0' and Timestamp lt …` pass that ages legacy GUID rows out via their frozen
-   migration-date system Timestamp (remove after 2027-03-01).
-
-# Consequences
-
-* Audit legacy GUID rows have "unknown date" semantics: excluded from date-filtered
-  views, shown with the (wrong but honest) 2026-07-18 fallback in unfiltered views.
-* Raw endpoints (`/api/raw/*`, `query_table`) intentionally keep showing the raw system
-  Timestamp — they are storage-state inspectors, not business views.
-* Event timestamps for pre-cutover rows resolve to the RowKey's sanitized agent time
-  (ms precision); `ReceivedAt` (server ingest time, rows since 2026-03-19) and
-  `OriginalTimestamp` (pre-clamp agent time, clamped rows only) remain separate fields.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Helpers/BusinessTimestamp.cs` — decoders + clause builders
-* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.Maintenance.cs` — audit write/mapper/filters/retention
-* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableOpsEventRepository.cs` — ops write/mapper/filters/retention
-* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.Sessions.cs` — event writes, `ResolveEventTimestamp`, earliest-event read
-* `src/Backend/AutopilotMonitor.Functions/Services/OccurredUtcBackfillService.cs` + `Functions/Admin/BackfillOccurredUtcFunction.cs` — backfill
@@ -1,142 +0,0 @@
---
-type: Concept
-title: W365 Cloud PC Device Validation — Cert-CN-Bound Fallback Validator
-description: Why Windows 365 Cloud PCs can never pass the Autopilot serial lookup, and how the CloudPc validator admits exactly the tenant's service-provisioned Cloud PCs by binding the MDM certificate's Subject CN (= Intune device id) to the Graph virtualEndpoint/cloudPCs inventory.
-resource: src/Backend/AutopilotMonitor.Functions/Security/CloudPcDeviceValidator.cs
-tags:
-  - backend
-  - security
-  - device-validation
-  - windows365
-  - cloudpc
-  - graph
-timestamp: 2026-08-06T00:00:00+02:00
---
-
-# W365 Cloud PC Device Validation
-
-Windows 365 Cloud PCs are provisioned headless by the Windows 365 service and are
-**structurally never Autopilot-registered** — the serial lookup against
-`windowsAutopilotDeviceIdentities` (and the Corporate Identifier fallback, whose
-serials nobody can pre-import for VMs minted at provisioning time) always misses.
-Before this validator, a Cloud PC agent died in the 403 "Device not registered"
-even though its mTLS cert was perfectly valid, so Cloud PC first-connect
-enrollment (Account Setup, RealmJoin, Hello) could not be monitored.
-
-# Schema — the validator chain
-
-`SecurityValidator.ValidateRequestAsync` stage 4 runs the same chain for every
-device; there is **no device-type routing** and the local W365 markers
-(Windows365 registry key, CloudManagedDesktopExtension service) are never
-consulted for auth — they gain an attacker nothing:
-
-1. **Autopilot serial lookup** (`ValidateAutopilotDevice`) — unchanged primary.
-2. **Corporate Identifier** (`ValidateCorporateIdentifier`) — unchanged fallback.
-3. **CloudPc** (`ValidateCloudPcDevice`, default off) — only reached when 1+2
-   missed. Extracts the Intune device id from the **chain-validated** client
-   certificate's Subject CN (`TryGetIntuneDeviceIdFromCertSubject`: CN present
-   AND canonical GUID, else definitive reject) and requires a `cloudPC` object
-   with `managedDeviceId eq <CN>` in the claimed tenant
-   (`GET /v1.0/deviceManagement/virtualEndpoint/cloudPCs?$filter=…`).
-   `ValidatedBy = ValidatorType.CloudPc (5)`.
-
-Only machines actually provisioned by the Windows 365 service have a `cloudPC`
-object — a regular Intune-enrolled non-Autopilot device still ends in the 403,
-so the "Autopilot devices only" contract of stages 1–2 is not widened. The
-tenant hard gate accepts `ValidateCloudPcDevice` as a third satisfying flag.
-
-## Why the cert CN, not headers or local markers
-
-Field-verified 2026-08-06 on a real W365 Enterprise Cloud PC (gktatooine.net):
-
- MDM client cert Subject `CN=07623d56-…` == Intune `managedDevice.id` ==
-  `cloudPC.managedDeviceId`. The CN cannot be forged without the Intune MDM
-  Device CA (chain pinned to embedded roots, `CustomRootTrust`).
- `$filter=managedDeviceId eq '…'` is supported server-side on **v1.0** — no
-  paging fallback needed.
- `managedDevice.serialNumber` matches local `Win32_BIOS.SerialNumber` exactly;
-  the "Cloud PC Enterprise …" model string exists **only** in Graph, never in
-  local WMI (local WMI reports Manufacturer='Microsoft Corporation',
-  Model='Virtual Machine').
-
-Threat model: a valid Intune cert from a *different* tenant fails (its CN does
-not exist in the claimed tenant's Cloud PC inventory — this is a *tenant
-binding* the serial-based validators do not have); spoofed serial headers and
-faked local W365 markers are irrelevant (never consulted); a rogue enrolled VM
-with doctored SMBIOS cannot mint a `cloudPC` object (service-side state, not
-device-reported inventory — the reason the model-string gate was rejected).
-Retired/deprovisioned Cloud PCs disappear from the inventory and their
-validation dies with them (compensates the absent cert revocation check).
-Residual: a compromised *legitimate* Cloud PC of the tenant — same trust level
-as any tenant device today, rate-limited by cert thumbprint.
-
-## Graph permission plumbing
-
- Optional add-on permission `CloudPC.Read.All` — NOT part of the default
-  consent set. Feature `W365CloudPcValidation` in `GraphFeatureCatalog` →
-  surfaces automatically in the "Optional Graph capabilities" UI (the feature
-  table and grant command are backend-driven) and in
-  `Grant-AutopilotMonitorAddOn.ps1` (`-Features W365CloudPcValidation`).
-  `GraphFeatureCatalogSyncTests` pins C# catalog ↔ grant script (previously
-  comment-only lock-step).
- A Graph **403** (permission not granted) is a definitive negative (cached
-  5 min), NOT transient — a 503 Retry-After loop cannot fix a missing grant.
-  The error message names the add-on feature.
- Same resilience contract as `AutopilotDeviceValidator`: 30/5 min
-  positive/negative cache, 2 attempts, transient → agent-facing 503.
-
-## Bootstrap script interplay (v2.3-dev.3)
-
-The Cloud-PC relax in `Install-AutopilotMonitor-dev.ps1` additionally exempts
-**guard 4** (12 h uptime window): a Cloud PC runs headless for days before the
-user's first connect, and the monitorable phase (Account Setup) only starts at
-that first connect — the single-fresh-profile window (< 15 min) is the time
-anchor there, not boot uptime. The OOBE-restore trigger keeps the uptime guard.
-
-## Agent-side IsCloudPc flag + decision-engine expectation
-
-Same change set, agent side. `CloudPcDetector` (V2.Core) re-uses the bootstrap's
-field-verified marker AND — `HKLM\SOFTWARE\Microsoft\Windows365` key **plus**
-installed `CloudManagedDesktopExtension` service (probed via its
-`HKLM\SYSTEM\CurrentControlSet\Services` key; the agent deliberately has no
-`System.ServiceProcess` dependency). SKIP-safe: any error resolves `false`.
-
-Three independent transport rails, never an auth input:
-
- **Session metadata** — `SessionRegistration.IsCloudPc` →
-  Sessions table (sticky-true OR across re-registrations, like
-  `IsSelfDeployingProfile`) → SessionsIndex full mirror → `SessionSummary` →
-  search filter `isCloudPc` (portal, `/api/search/sessions`, `/api/raw/sessions`,
-  MCP `search_sessions`/`query_raw_sessions`). Agent-reported and unverified —
-  can legitimately disagree with the server-derived `ValidatedBy = CloudPc`
-  (e.g. Cloud PC admitted via a stage that ran earlier).
- **Distress channel** — `DistressReport.IsCloudPc` (captured once at
-  `DistressReporter` construction, `BackendClientFactory`) rides every pre-auth
-  distress report → `DistressReportEntry.IsCloudPc` → the "Devices Not
-  Registered" report aggregates it **sticky-true** per serial
-  (`GetDeviceNotRegisteredFunction`) and the portal insight renders a Cloud PC
-  badge plus a hint pointing at the Cloud PC validation toggle + the
-  `W365CloudPcValidation` add-on. Same UNVERIFIED contract as all distress
-  fields; rows from older agents read false. Fits the existing 1536-byte
-  payload cap without a bump.
- **Decision engine** — the marker rides the `EnrollmentFactsObserved` payload
-  (`isCloudPc`), is recorded set-once for BOTH values in
-  `EnrollmentScenarioObservations.CloudPc`, and annotates the scenario profile
-  reason `cloud_pc_first_connect:no_device_esp_expected`. That is the
-  engine-recorded expectation "no Device ESP phase will appear": Device-ESP ran
-  headless at provisioning, the session starts at Account Setup. Deliberately
-  reason+observation only — no completion arm depends on DeviceSetup, `Mode`
-  is still classified by AccountSetup/IME signals (Classic), and `EspConfig`
-  keeps the *configured* FirstSync semantics. The positive marker surfaces as
-  `cloud_pc_marker` in the terminal audit-trail signal census.
-
-# Citations
-
- `src/Backend/AutopilotMonitor.Functions/Security/CloudPcDeviceValidator.cs`
- `src/Backend/AutopilotMonitor.Functions/Security/SecurityValidator.cs` — stage 4 chain, `TryGetIntuneDeviceIdFromCertSubject`
- `src/Shared/AutopilotMonitor.Shared/Models/Graph/GraphFeatureCatalog.cs` — `W365CloudPcValidation`
- `scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1` — customer-side grant
- `scripts/Bootstrap/Install-AutopilotMonitor-dev.ps1` — Cloud-PC relax + guard-4 exemption
- `src/Backend/AutopilotMonitor.Functions.Tests/CloudPcDeviceValidatorTests.cs`, `SecurityValidatorTests.cs`, `GraphFeatureCatalogSyncTests.cs`
- `src/Agent/AutopilotMonitor.Agent.V2.Core/Security/CloudPcDetector.cs` — agent-side marker AND
- `src/Shared/AutopilotMonitor.DecisionCore/State/EnrollmentScenarioObservations.cs` — `CloudPc` fact; reason annotation in `EnrollmentScenarioProfileUpdater`
@@ -1,122 +0,0 @@
---
-type: Concept
-title: Device Journeys & First-Time-Right (F2)
-description: How a device's terminal enrollment attempts are grouped into journeys (device key, junk-serial exclusion, first-success end, 30-day gap), where the DeviceHistories chain and the daily FTR aggregates are computed, stored and pruned, and which surfaces serve them.
-resource: src/Backend/AutopilotMonitor.Functions/Helpers/DeviceJourneyCalculator.cs
-tags:
-  - backend
-  - metrics
-  - device-history
-  - first-time-right
-  - insights
-timestamp: 2026-07-27T12:00:00+02:00
---
-
-# Device Journeys & First-Time-Right (F2)
-
-Answers "how many devices enrolled right on the first try?" and "show me every attempt
-this device made". Session success rate hides wipe-and-retry loops — every retry that
-eventually succeeds counts as a success; First-Time-Right (FTR) exposes the real pain.
-All grouping semantics live server-side in `DeviceJourneyCalculator` (JourneyVersion 1);
-no consumer re-derives them.
-
-# Schema
-
-## Device key
-
-`(TenantId, normalized serial)` — normalization is trim + lower-case. Junk/placeholder
-serials are excluded entirely (never a chain, never in FTR, disclosed as a per-day
-exclusion count): `System Serial Number`, `To Be Filled By O.E.M.`, `Default string`,
-`0`, `None`, `INVALID`, `Unknown` (the agent's WMI-failure sentinel), empty, or shorter
-than 4 characters. A motherboard swap changes the serial and therefore the device key;
-re-enrollment under a different tenant is a separate key by design.
-
-## Journey
-
-Terminal sessions of a device key ordered by StartedAt. The terminal set is
-**Succeeded / Failed / Incomplete** — `Pending` (a sealed WhiteGlove part 1),
-`AwaitingUser`, `Stalled` and `InProgress` are OPEN sessions and never attempts.
-
-* A journey **ends** with the first terminal success; the next session starts a new
-  journey (redeployment).
-* A gap of **more than 30 days** since the previous attempt's terminal moment
-  (`CompletedAt`, fallback StartedAt) starts a new journey even without a success
-  (device shelved/repurposed). Constant, not a setting — production gaps: median 4.9 h,
-  92 % < 7 d.
-* WhiteGlove part 1 + part 2 share ONE session row, so a completed WG enrollment is ONE
-  attempt; a WG device still waiting for its user session leaves the journey open —
-  never a failed attempt.
-* **Attempt count** = terminal sessions in the journey (`Failed` and `Incomplete` are
-  non-successful attempts).
-* **FTR rate** = completed journeys with attempt count 1 ÷ all completed journeys.
-  Open and gap-abandoned journeys never enter numerator or denominator.
-
-Durations shown for attempts are the sessions' authoritative `DurationSeconds` verbatim
-(WhiteGlove pause excluded; `Incomplete` deliberately has none) — never
-`CompletedAt − StartedAt`, which is later in ~25 % of terminal sessions.
-
-## Persistence & compute
-
-* `DeviceHistories` (PK = TenantId, RK = percent-encoded normalized serial): the chain of
-  the device's terminal session refs `{sessionId, startedAt, completedAt, status,
-  enrollmentType, isPreProvisioned, durationSeconds, adminMarked}` capped at the 20 most
-  recent, plus derived `CurrentJourneyAttempts` (the LAST journey's attempts — the
-  banner's "Attempt N"), `JourneyCount` (chain-scoped) and `JourneyVersion`. Written
-  inline at the session-terminal single-writer seam
-  (`TableSessionRepository.UpdateSessionStatusAsync`, all three terminal statuses,
-  DeletionState-guarded) so the session banner is fresh; healed by the maintenance sweep.
-  Deliberately NOT part of the per-session deletion manifest — the row aggregates many
-  sessions. Wiped on tenant offboarding.
-* Sweep (`SweepDeviceJourneysAsync`, 30-day rolling window, 2h tick): (1) drops chain
-  refs of deleted sessions **tombstone-driven** — every session deletion (cascade and
-  retention both run through the cascade worker) leaves a `SessionTombstones` marker for
-  ~7 days, far longer than the sweep cadence, and even an expired-but-unpruned marker is
-  valid deletion evidence; a chain left empty deletes its row. (2) Merges the window's
-  terminal sessions into their chains (backfill, inline-miss healing, re-terminal
-  reclassifications). (3) Recomputes the daily FTR aggregates idempotently.
-* `DeviceJourneyAggregates` (PK = TenantId or `global`, RK = `{yyyy-MM-dd}`): per day —
-  completed journeys, first-time-right count, attempt histogram, junk-serial exclusion
-  count, `JourneyVersion`. A journey buckets on the StartedAt date of its completing
-  success session (the platform's StartedAt-date convention; late terminals converge via
-  the sweep). All counts are **additive**, so a window rate is the ratio of summed daily
-  rows — there is no rolling-window row (unlike the median-based time-attribution
-  aggregates, which cannot merge). 180-day retention. Rows exist below the ≥20 UI gate
-  on purpose (the UI needs the n for "insufficient data (n=…)").
-
-# Surfaces
-
-* `GET api/metrics/device-history?serialNumber=&sessionId=` (MemberRead + tenant query
-  param — the same route serves the web banner and MCP; a Global Admin passes `tenantId`)
-  — the chain plus, with `sessionId`, that session's server-computed attempt number
-  (live sessions get their would-be position via a virtual non-successful attempt, so the
-  redeploy and gap rules apply). `history: null` = no recorded history.
-* `GET api/metrics/device-journeys?days=` (MemberRead) /
-  `GET api/global/metrics/device-journeys?days=&tenantId=` (GlobalReadOrAdmin) —
-  `{ windowDays, totals, daily, repeatDevices }`. The days selector is honored because
-  counts are additive. Without `tenantId` the global variant serves the cross-tenant
-  aggregate rows and `repeatDevices: null` — a per-device list would require scanning
-  every tenant's partition.
-* Repeat devices (violator list, capped 10): devices whose LAST journey took ≥2 attempts
-  and whose newest terminal session falls inside the window, ordered by attempts then
-  recency; the failure reason comes from the newest failed attempt (bounded point-reads).
-* Web: "Attempt N for this device · View history" banner on session detail (expandable
-  chain); "First-time-right" section on Fleet Health (rate + weekly trend + attempt
-  histogram + repeat devices). MCP: `get_device_history` (serial mode / fleet FTR mode).
-
-# Examples
-
-A device fails ESP twice and succeeds on the third try within one week: one journey,
-three attempts, completed — counts once in the FTR denominator, not in the numerator,
-and the histogram's bucket `3` gains one. The same device redeployed a month later and
-succeeding immediately starts journey 2 with attempt count 1 — first-time-right. A
-device with `serialNumber = "Unknown"` (WMI failure) never gets a chain; its terminal
-sessions surface only as that day's disclosed exclusion count.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Helpers/DeviceJourneyCalculator.cs` — device key, junk list, grouping, attempt numbers (JourneyVersion 1).
-* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.DeviceHistory.cs` — persistence + inline seam entry.
-* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.DeviceJourneys.cs` — sweep, tombstone pruning, daily aggregation.
-* `src/Backend/AutopilotMonitor.Functions/Functions/Metrics/GetDeviceJourneyFunctions.cs` — read surfaces.
-* `src/Backend/AutopilotMonitor.Functions.Tests/DeviceJourneyAndFtrTests.cs` — table-driven grouping/aggregation/attempt-number tests.
-* `tasks/insights-expansion-spec.md` — F2 specification and source-data audit (§0.5).
@@ -1,62 +0,0 @@
---
-type: concept
-title: Lifecycle Manifests & Session Scope Resolution
-description: The enforced completeness nets added by the fragility-audit P5/P6 remediation — table lifecycle buckets, the SessionsIndex field manifest, the single session-scope resolver with its SessionTenantLookup point-read, and the server-side dashboard free-text search.
-resource: backend
-tags: [lifecycle, offboarding, sessionsindex, manifest, scope-resolution, search, performance]
-timestamp: 2026-08-13
---
-
-# Schema
-
-Four mechanisms replace hand-synchronized copies with a declared source plus tests that fail on drift.
-
-## 1. Table lifecycle buckets
-
-Every table in `Constants.TableNames` must belong to at least one deletion lifecycle:
-
-| Bucket | Mechanism | Source of truth |
-|---|---|---|
-| Tenant-offboarding wipe | `TenantOffboardingHandler` bucket arrays (`TenantPartitionTables`, `CompositePartitionTables`, `DiscriminatorTables`, `PropertyOnlyTables`, `RowKeyTables`, `ArchivedRuleTables`) + the one-off `TenantConfiguration` final delete | handler arrays (read via reflection by the test) |
-| Per-session cascade | `DeletionManifestBuilder.BuildAsync` step list (incl. the Final tombstone → Sessions + SessionsIndex) | a real manifest built against an empty-inventory fake |
-| Kept by design | reviewed exception list with per-table reasons | `TableLifecycleBucketTests.KeptByDesign` |
-
-`TableLifecycleBucketTests` (Functions.Tests) asserts: constants set-equal `TableNames.All`, no table unclassified, kept-by-design disjoint from every wipe path, bucket entries are real constants, offboarding buckets disjoint except documented multi-membership (`BootstrapSessions`).
-
-**Not covered mechanically:** whether a bucket's key shape matches the table's writer. That was the UsageMetrics bug (PK=date, RK=tenantId sat in the exact-PK bucket; the wipe matched 0 rows) — SafeWipe **Variant D** (`WipeByRowKeyAsync`, `RowKey eq '{tenantId}'`) now covers RowKey-anchored tables. Read the writer's `new TableEntity(pk, rk)` before classifying a new table.
-
-## 2. SessionsIndex field manifest
-
-`SessionIndexFieldManifest` (Functions/Services) declares the full-mirror column set: `AlwaysProjected` (32, written with defaults on every rebuild), `ConditionallyProjected` (18, written only when present), `PrimaryOnly` (4 — ServerActions + deletion-CAS fields that never touch the index). `SessionIndexFieldManifestTests` pins `BuildSessionIndexEntity` against it bidirectionally (full-row fixture built from a test-local sample table, NOT from the manifest — deriving the fixture from the manifest would make the check circular), pins that every manifest field influences `MapToSessionSummary`, and pins the rebuild's `TableUpdateMode.Replace` (a merge-mode upsert could never clear a conditional column the primary blanked). `MergeSessionIndexAsync` logs a warning for merged keys outside the manifest (fail-soft drift guard).
-
-## 3. Session scope resolution (one implementation)
-
-`RequestContextExtensions.ResolveSessionScopeAsync(ctx, sessionRepo, sessionId, requireGlobalAdmin)` is the single implementation of the former 15-site copy-paste fallback ("which tenant owns this session?"):
-
- Non-global callers always keep the middleware-validated `TargetTenantId`.
- Global-scope callers resolve via `ISessionRepository.ResolveSessionTenantIdAsync` — a point-read on **SessionTenantLookup** (PK=sessionId, RK="tenant") with a legacy cross-partition SessionsIndex scan fallback that self-heals the lookup row, so the scan is paid at most once per pre-table session.
- `requireGlobalAdmin: true` on WRITE paths gates the cross-tenant reach on `IsGlobalAdmin` so a read-only Global Reader can never steer a write into a foreign tenant.
- Unknown session → `TargetTenantId`, leaving each endpoint's own not-found semantics (404 / empty 200 / 400) in charge.
- Delegated (MSP) callers deliberately get NO fallback — extending it to `AllowedTenantIds` is a pending user decision.
-
-The lookup row is written at session registration (fail-soft), deleted by the cascade one step before the tombstone, and rebuildable from Sessions (not in the critical-backup set). The former lazy triggers (`events.Count == 0` → scan) are gone: empty-but-owned results no longer pay a table scan, and endpoints resolve upfront.
-
-Related enforcement added with the migration: `RecomputeTriggerGate` — `?reanalyze=true` and `?rescan=true` on the MemberRead session routes are actions (delete + rewrite stored results) and now 403 for Viewer / Global Reader / cross-tenant tenant roles (Global Admin or own-tenant Admin/Operator only).
-
-## 4. Server-side dashboard search
-
-`q=` on `/api/search/sessions` + `/api/global/search/sessions`: case-insensitive substring over exactly the fields the dashboard's client-side filter searches (device name, serial, manufacturer, model, status, sessionId, geo, agent version, OS fields — NOT the client-derived date/duration/blocked tokens; a server-only field would produce ghost results the client filters back out). Azure Tables has no substring operator, so the scan path backfills whole Azure pages until it has `pageSize` matches (max 10 pages per request, continuation at a page boundary — gap-free). `q` is bound into the pagination fingerprint. The web dashboard's `searchAll()` (useDashboardSessions) follows nextLink up to 10 requests / 50 matches and dedupe-merges results into the loaded list (`mergeSessionsById`), replacing the former `loadAll()` walk that downloaded the entire session history to search it client-side. Delegated callers in cross-tenant mode keep the legacy full sweep (the global search route has no delegated tier).
-
-# Examples
-
-Adding a new table: classify it in one lifecycle path before `TableLifecycleBucketTests` lets it ship — offboarding bucket (check the writer's PK/RK shape first), deletion-manifest step, or `KeptByDesign` with a reason.
-
-Adding a mirrored SessionsIndex field: manifest entry + `BuildSessionIndexEntity` write + `MapToSessionSummary` read + a sample value in the test — any missing step is red.
-
-# Citations
-
- `src/Backend/AutopilotMonitor.Functions.Tests/TableLifecycleBucketTests.cs`
- `src/Backend/AutopilotMonitor.Functions/Services/SessionIndexFieldManifest.cs`
- `src/Backend/AutopilotMonitor.Functions/Helpers/RequestContext.cs` (`ResolveSessionScopeAsync`)
- `src/Backend/AutopilotMonitor.Functions/Services/Offboarding/SafeWipeService.cs` (Variant D)
- `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.AgentApi.cs` (`MatchesFreeText`, backfill loop)
@@ -1,107 +0,0 @@
---
-type: Concept
-title: OOBE Bootstrap go-Code Flow — Always-200 Script Endpoint
-description: The full lifecycle of the bootstrap short-code — created in the portal, typed as `irm go.autopilotmonitor.com/CODE | iex` at Shift+F10, served by GetBootstrapScriptFunction as an always-HTTP-200 PowerShell script — including the two-line injection defense and the rate-limit story behind Front Door.
-resource: src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/GetBootstrapScriptFunction.cs
-tags:
-  - backend
-  - bootstrap
-  - security
-  - oobe
-timestamp: 2026-07-28T00:00:00+02:00
---
-
-# OOBE Bootstrap go-Code Flow
-
-Bootstrap Sessions let a technician install the agent **before** Intune
-enrollment: an admin creates a short-lived session in the portal (Settings →
-Bootstrap Sessions), hands the technician a short URL, and the technician types
-`irm https://go.autopilotmonitor.com/CODE | iex` into a Shift+F10 console
-during OOBE. The URL is deliberately short because it is typed by hand on a
-device that has no clipboard.
-
-# Lifecycle
-
-1. **Create** — `POST /api/bootstrap/sessions` (`BootstrapManagerOrGA`).
-   `BootstrapSessionService.CreateAsync` mints an unambiguous-charset short
-   code + a GUID token, validity clamped 1–168 h. The response's `bootstrapUrl`
-   is built from `Constants.BootstrapGoBaseUrl` — the single producer of the
-   absolute URL (pinned by `CreateBootstrapSessionUrlShapeTests`).
-2. **Serve** — `GET /api/bootstrap/go/{code}` (`GetBootstrapScriptFunction`,
-   `PublicAnonymous`). Customers reach it through the Front Door custom domain
-   `go.autopilotmonitor.com`, whose `/*` route rewrites onto the API path.
-   Validation runs in-process (`ValidateCodeAsync` + the tenant's
-   `BootstrapTokenEnabled` gate) — no HTTP hop to the validate endpoint.
-3. **Install** — the generated script downloads the agent ZIP from
-   `Constants.AgentDownloadBaseUrl`, extracts, and runs
-   `--install --no-auth --bootstrap-token … --tenant-id …`. The agent monitors
-   from OOBE start, switches to certificate auth after Intune enrollment, and
-   self-destructs on completion.
-
-The legacy Next.js `/go/[code]` route (SSR on the SWA) stays alive only for
-URLs issued before the migration and is removed with the static-export PR —
-see the transition rule in [URL Registry](../url-registry.md).
-
-# Always-200 contract
-
-Every response — success, invalid format, unknown/expired code, disabled
-feature, rate limit, internal error — is **HTTP 200 `text/plain`**. The
-consumer is `irm | iex`: a non-2xx status would make `irm` throw an opaque
-exception on the OOBE console, while a 200 error script surfaces the actual
-message via `Write-Host 'ERROR: …'`. Consequences:
-
- Failures are invisible in status-code metrics; the compensating signal is the
-  `LogWarning` per rejection (code + client IP).
- Error messages are capped at 200 chars **before** quote-escaping and
-  single-quote-doubled — a hostile upstream message cannot break out of the
-  `Write-Host` literal.
-
-A disabled tenant returns the **same generic message** as an unknown code — no
-enumeration oracle for whether a code exists.
-
-# Injection defense (two lines)
-
-The script runs as SYSTEM during OOBE, so interpolation is treated as a
-security boundary:
-
-1. **`BootstrapScriptValueValidator`** — tenantId/token must be exact canonical
-   GUIDs, the download URL must be https on an allow-listed host
-   (`AgentDownloadBaseUrl`/`AgentBlobBaseUrl` hosts) with the strict
-   `/agent/….zip` path shape, expiry must be future and ≤ 14 days. No accepted
-   value can contain `$`, quotes, backticks, spaces, or newlines. Kept even
-   though values are produced in-process — defense-in-depth against tampered
-   table data.
-2. **Single-quoted PS literals** — every interpolated value sits inside
-   single-quoted PowerShell strings, which do not expand `$()`, `$var`, or
-   backticks.
-
-The template is a C# raw string with `__TOKEN__` placeholders substituted via
-`Replace` (never `$`-interpolation — the script is full of PS `$vars`).
-`OobeBootstrapScriptGeneratorTests` pins byte parity with the original
-TypeScript template through a golden file, so the legacy route and the backend
-serve identical scripts during the transition.
-
-# Rate limiting behind Front Door
-
-The endpoint self-limits per client IP (`bootstrap-script:{ip}`, 20/min via
-`ClientIpExtractor.GetRateLimitClientIp`) — anonymous routes are skipped by
-`UserRateLimitMiddleware` and must bring their own limiter. Because traffic
-arrives through Front Door, the rightmost X-Forwarded-For hop resolves to AFD
-egress IPs and buckets would collapse (the shared-bucket 429 incident class);
-the AFD-aware extraction therefore honors `X-Azure-ClientIP` only when
-`X-Azure-FDID` matches the `FrontDoorProfileId` app setting (fail-closed to
-the trusted-hop path otherwise). Verified post-deploy 2026-07-29: real client
-IPs are keyed, not AFD egress.
-
-Front Door route caching is DISABLED for this route: the body inlines the
-bearer token, so a cache hit would replay one requester's token to another.
-`NoStoreCacheMiddleware` covers the `/api/bootstrap/go/` prefix.
-
-# Citations
-
- `src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/GetBootstrapScriptFunction.cs`
- `src/Backend/AutopilotMonitor.Functions/Functions/Bootstrap/OobeBootstrapScriptGenerator.cs`
- `src/Backend/AutopilotMonitor.Functions/Security/BootstrapScriptValueValidator.cs`
- `src/Backend/AutopilotMonitor.Functions.Tests/OobeBootstrapScriptGeneratorTests.cs` — golden parity
- `src/Web/autopilot-monitor-web/app/go/[code]/route.ts` — legacy route (transition only)
- [URL Registry](../url-registry.md) — go-URL registry entries + transition rule
@@ -1,112 +0,0 @@
---
-type: Concept
-title: Rule Regression Radar (F3)
-description: How the radar detects analyze rules whose hit rate suddenly rose (7-day window vs 28-day baseline, Wilson-separated), which suppressions keep it quiet, how alert episodes live in the notification tracker, and which surfaces show them.
-resource: src/Backend/AutopilotMonitor.Functions/Helpers/RuleRegressionRadar.cs
-tags:
-  - backend
-  - rules
-  - regression-radar
-  - insights
-timestamp: 2026-07-27T16:00:00+02:00
---
-
-# Rule Regression Radar (F3)
-
-Detects "this analyze rule suddenly fires much more often" before helpdesk volume does, and
-says what the spike correlates with — with honest statistics and honest wording. Analyze
-rules only in v1: their daily stats are audit-verified session-deduplicated
-(`FireCount` ≈ distinct sessions with a hit, `SessionsEvaluated` the same-source
-denominator). Gather rules are excluded until their per-batch stats dedup is fixed —
-never silently included with bad math.
-
-# Schema
-
-## Signal & detection
-
-Per (tenant, ruleId), daily hit rate = `FireCount ÷ SessionsEvaluated` from the
-`RuleStats` rows — RATES, not counts (absolute counts spike with every rollout wave).
-A regression fires only when ALL hold for the trailing 7-day window vs. the prior
-28-day baseline:
-
-1. window has ≥ 5 hit sessions AND ≥ 20 evaluated sessions;
-2. window rate ≥ 2× baseline rate;
-3. the Wilson 95 % intervals are disjoint in the increase direction
-   (`MetricsMath.WilsonInterval` / `RateIncreaseSeparated` — deterministic, unit-pinned),
-   so small-n noise never alerts.
-
-## Suppression (false positives are trust damage)
-
-* Rule entity missing (deleted) — never alerts.
-* Rule younger than baseline + window (`CreatedAt` within 35 days — grace period for new
-  rules; the entity timestamp is the honest gate, a stats-row count would fail on
-  low-volume tenants whose quiet days simply have no rows).
-* Rule edited inside the window (`UpdatedAt` ≥ window start) — edits legitimately change
-  hit rates.
-* Empty baseline denominator (rule disabled throughout the baseline).
-* Platform kill switch: app setting `RuleRegressionRadarDisabled=true` skips the radar
-  (fail-open — it only notifies, never mutates data).
-
-## Alert episodes (tracker keyspace)
-
-An episode lives as `ruleregression|{ruleId}` in the notification-tracker table
-(the `tpmpss|` pattern): the row IS the dedup (bell + ops event fire exactly once per
-episode), the badge state and the `regressions[]` payload — window/baseline counts,
-rates, lift (null for a zero-baseline "new signal" — no finite lift is invented), window
-dates, and the dimension concentration captured at first fire. Numbers refresh on every
-radar pass while the episode stays active; `FirstNotifiedAt` never moves. The episode
-closes (badge clears, dedup re-arms) when the window rate falls back under 1.5× baseline
-or fires stop entirely; the tracker's 30-day retention sweep also re-arms, so a
-month-old still-burning regression rings once more by design.
-
-## Dimension correlation (on fire only)
-
-Hit sessions (RuleResults scan: tenant partition range + RowKey = ruleId + DetectedAt in
-window, intersected with the window's sessions) are compared against all window sessions
-across `osBuild`, `model` (manufacturer + model), `agentVersion` and `imeVersion`. The
-top value by lift is reported with BOTH shares — wording contract: "X % of affected
-sessions are on … vs Y % of all sessions — correlated, not necessarily causal". No value
-with ≥ 5 hit sessions at ≥ 2× lift → "no clear dimension concentration"; a correlation
-failure also yields no claim. App-version correlation for `ANALYZE-APP-*` rules is a
-follow-up (needs rule→app matching semantics), tracked with the gather-rule fix.
-
-## Compute & alert path
-
-Runs in the daily maintenance pass right after the rule-stats aggregation
-(`RunRuleRegressionRadarAsync`), anchored on YESTERDAY — whole days only, a partial
-today would understate the window rate. One 35-day stats read covers all tenants;
-evaluation is the pure `RuleRegressionRadar` core. On a NEW episode:
-
-1. `RuleFrequencyRegression` ops event (category Tenant, Warning) with the full numbers
-   — dual-registered in the web `OPS_EVENT_TYPES` catalog for alert-rule routing.
-2. Tenant bell notification (type `rule_frequency_regression`, Admin audience) with the
-   same numbers and a deep link to the rule's card (`/analyze-rules#rule-card-{ruleId}`).
-   A sessions-list pre-filtered to rule hits needs a rule filter the session search does
-   not have yet — follow-up alongside the gather-rule work.
-3. v1 channel: bell + ops event only. Provider fan-out (webhook/Telegram) follows once
-   alert quality is proven — a noisy first version burns trust permanently.
-
-# Surfaces
-
-* `GET api/metrics/rule-stats` (and the global variant with `tenantId`) carries
-  `regressions[]` — the active episodes. MCP `get_rule_stats` inherits the block.
-* Analyze-rules page: per-rule 30-day fire-count sparkline (densified from the `trend`
-  rows the endpoint already served) and a red "↑ Regression" badge while an episode is
-  active, with the full numbers in the tooltip.
-
-# Examples
-
-A rule firing on 2 % of sessions for a month jumps to 15 % over a week (15/100 vs
-10/500): lift 7.5×, Wilson-separated → one bell, one ops event, badge until the rate
-falls back under 3 %. The same jump on 5/20 sessions with a 12 % baseline stays silent —
-the intervals overlap, so the spike is not statistically real yet. A rule that never
-fired in the baseline and now hits 15 % alerts as a "new signal" with no lift figure.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Helpers/RuleRegressionRadar.cs` — gates, suppression, re-arm, dimension concentration.
-* `src/Backend/AutopilotMonitor.Functions/Helpers/MetricsMath.cs` — Wilson interval + separation primitive.
-* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.RuleRegression.cs` — sweep, episode reconcile, bell/ops wiring.
-* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableHardwareRejectionNotificationTracker.cs` — episode keyspace.
-* `src/Backend/AutopilotMonitor.Functions.Tests/RuleRegressionRadarTests.cs` — hand-computed Wilson vectors + every suppression branch.
-* `tasks/insights-expansion-spec.md` — F3 specification and source-data audit (§0.5).
@@ -1,102 +0,0 @@
---
-type: Concept
-title: ServerActions & On-Demand Diagnostics Collection
-description: The queue-on-session, deliver-on-ingest ServerAction channel (terminate_session / rotate_config / request_diagnostics), the operator-tier authorization split, the portal's Collect Logs flow including the admin quick-config path, and why the offboarding cascade sweeps the hosted diagnostics prefix.
-resource: /src/Backend/AutopilotMonitor.Functions/Functions/Sessions/QueueSessionActionFunction.cs
-tags:
-  - backend
-  - agent
-  - web
-  - server-actions
-  - diagnostics
-  - authorization
-timestamp: 2026-07-24T00:00:00+02:00
---
-
-# Schema
-
-**Channel.** A `ServerAction` (`Type`, `Reason`, `RuleId`, `Params`, `QueuedAt`) is queued onto
-`Sessions.PendingActionsJson` by server-side writers — the admin endpoint
-`POST /api/sessions/{sessionId}/actions`, the RuleEngine, maintenance — and delivered
-piggy-backed on the agent's next ingest response. No polling channel exists; delivery latency
-equals the agent's telemetry cadence (seconds to ~1 minute during enrollment). Delivery is
-at-least-once: the agent's `ServerActionDispatcher` dedups on `Type|RuleId|QueuedAt` and
-processes a batch sequentially in queue order. Unknown types are logged and skipped, so new
-types roll out server-first. Every action emits `server_action_received` and then
-`server_action_executed` or `server_action_failed` into the session timeline.
-
-**Authorization (two layers).** The route sits on `EndpointPolicy.TenantAdminOrOperator`
-(tenant Admin, tenant Operator, or Global Admin — no Viewer, no Global Reader: it is a write
-tier). Because the route serves multiple action kinds, `QueueSessionActionFunction`
-re-gates per type via `IsTypeAllowedForCaller`: Operators may queue only
-`request_diagnostics`; `terminate_session` and `rotate_config` require
-`RequestContext.IsTenantAdmin || IsGlobalAdmin` (403 otherwise). Any route on this tier with
-a multi-kind body MUST follow this same in-function re-gating pattern.
-
-**On-demand collection (`request_diagnostics`).** The dispatcher calls
-`DiagnosticsPackageService.CreateAndUploadAsync(enrollmentSucceeded: false, suffix:
-"server-requested")` — producing `AgentDiagnostics-{sessionId}-{timestamp}-server-requested.zip`.
-Passing `enrollmentSucceeded: false` is what makes on-demand collection work under
-`DiagnosticsUploadMode=OnFailure`; only `Off` (or an unconfigured destination) blocks it,
-surfacing as `server_action_failed`. The `diagnostics_uploaded` event stamps
-`DiagnosticsBlobName` + `Destination` onto the Sessions row (latest wins — an on-demand name
-is later replaced by the terminal package), and the SignalR `sessionUpdate` delta carries the
-field, so the portal's Download button flips live.
-
-**Portal flow (Collect Logs, session detail header).** The button is always rendered; the
-disabled states carry tooltips (inactive session, cross-tenant view, missing role, diagnostics
-not configured) as a deliberate nudge. Members below Admin cannot read the tenant config, so
-the member-readable feature-flags endpoint exposes `diagnosticsUploadConfigured`
-(`mode != Off && (customer SAS present || destination Hosted)`). Progress tracking is
-sequence-based (backend-assigned, monotonic), never timestamp-based — agent clock skew and
-at-least-once redelivery of older actions cannot produce false matches
-(`collectLogsLogic.ts`). Cross-tenant views are gated off because `TenantHelper.GetTenantId`
-resolves the tenant strictly from the caller's JWT.
-
-**Admin quick-config.** For an unconfigured tenant, a Tenant Admin's click opens a dialog
-that switches the tenant to `Destination=Hosted`, `Mode=OnFailure` (GET full config → patch
-exactly those two fields → PUT verbatim), then queues `rotate_config` **before**
-`request_diagnostics` — the dispatcher's sequential ordering guarantees the agent refetches
-the now-enabled config (the `RemoteConfigMerger` applies diagnostics fields live, remote wins)
-before building the package. This works against the already-deployed agent fleet; a
-"one-time override" variant would not, because the `mode=Off` check is client-side in
-`CreateAndUploadAsync` and the deployed handler reads no params.
-
-**Offboarding cascade.** Latest-wins on `DiagnosticsBlobName` means a session can leave more
-hosted blobs behind than the deletion manifest references. The cascade's Hosted branch
-therefore sweeps the canonical prefix `{tenantId}/AgentDiagnostics-{sessionId}-`
-(`HostedDiagnosticsBlobService.DeleteBySessionPrefixAsync`) plus the manifest-named blob as
-belt-and-braces; a non-GUID legacy `SessionId` degrades to the single-name delete instead of
-poisoning the cascade. The CustomerSas branch is unchanged (delete only with the `d`
-permission; the customer's lifecycle rules stay authoritative).
-
-# Examples
-
-Queue an on-demand collection (Admin or Operator, own tenant):
-
-```
-POST /api/sessions/{sessionId}/actions
-{ "type": "request_diagnostics", "reason": "On-demand log collection from portal" }
-→ 202 { "success": true, "queuedAt": "..." }
-```
-
-Operator queueing an admin-only type:
-
-```
-POST /api/sessions/{sessionId}/actions
-{ "type": "terminate_session" }
-→ 403 { "message": "Action type 'terminate_session' requires the Tenant Admin role" }
-```
-
-Timeline for a successful round trip: `server_action_received` → `server_action_executed`
-(with `blobName`) → `diagnostics_uploaded` → Sessions row + SignalR delta carry the new
-`DiagnosticsBlobName`.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Functions/Sessions/QueueSessionActionFunction.cs` — allowed types, per-type caller gate.
-* `src/Backend/AutopilotMonitor.Functions/Security/EndpointAccessPolicyCatalog.cs` — `TenantAdminOrOperator` tier definition.
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Runtime/ServerActionDispatcher.cs` — dedup, sequential dispatch, telemetry contract.
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Runtime/DiagnosticsPackageService.cs` — mode gates, archive build, suffix.
-* `src/Backend/AutopilotMonitor.Functions/Services/Diagnostics/DiagnosticsBlobCascadeDeleter.cs` — hosted prefix sweep.
-* `src/Web/autopilot-monitor-web/app/sessions/[sessionId]/components/collectLogsLogic.ts` — button gating matrix, sequence-based progress evaluation.
@@ -1,122 +0,0 @@
---
-type: Concept
-title: Session Annotations — Role-Separated Human Verdicts
-description: The SessionAnnotations table (PK=tenantId, RK={sessionId}_{lane}) storing per-session human verdicts + notes in three role lanes (operator / tenantadmin / globaladmin), the per-lane write matrix with own-tenant binding, the platform-internal GA lane, the fired-rule-id snapshot that makes annotations rule-quality labels, and the portal/MCP surfaces.
-resource: /src/Backend/AutopilotMonitor.Functions/Functions/Annotations/UpsertSessionAnnotationFunction.cs
-tags:
-  - backend
-  - web
-  - mcp
-  - annotations
-  - authorization
-  - rule-quality
-timestamp: 2026-08-11T00:00:00+02:00
---
-
-# Schema
-
-**Table.** `SessionAnnotations`: PartitionKey = `tenantId`, RowKey = `{sessionId}_{lane}` with
-lane ∈ `operator | tenantadmin | globaladmin` (a closed set — `AnnotationLanes.All`). One row per
-session + lane, edited in place; per-session reads use the RK range `ge '{sid}_' / lt '{sid}_~'`.
-Serialization lives only in `TableSessionAnnotationRepository.StoreAnnotation`/`MapAnnotation`
-(round-trip-pinned; corrupt `RuleIdsJson` degrades to an empty list on read).
-
-**Row.** `Verdict` (nullable: `root_cause_confirmed | analysis_wrong | different_problem |
-inconclusive`), `Note` (nullable, ≤ 4096 chars), `AuthorUpn`/`AuthorDisplayName` (last editor),
-`CreatedByUpn`/`CreatedAtUtc` (first writer, immutable across edits), `UpdatedAtUtc`, and
-`RuleIdsJson` — a **snapshot of the rule ids that had fired for the session at write time**
-(from `IRuleRepository.GetRuleResultsAsync`, fail-soft to empty). The snapshot is what turns an
-annotation into a rule-quality label without a join: filtering annotations by `ruleId` + `verdict`
-yields confirmed vs false-positive counts per rule even after results are re-analyzed or deleted.
-
-**Verdict + note are independently optional**; a PUT with both null **deletes** the lane row
-(there is no DELETE route). Author identity is always stamped server-side from the JWT
-(`TenantHelper.GetUserDisplayName` + `RequestContext.UserPrincipalName`) — a body-supplied
-author never wins (same anti-spoof contract as the gather-rule PUT-upserts).
-
-# Authorization
-
-Routes (all in `EndpointAccessPolicyCatalog`):
-
-| Route | Policy | Notes |
-| --- | --- | --- |
-| `GET sessions/{sessionId}/annotations` | `MemberRead` + QueryParam | handler filters the GA lane |
-| `PUT sessions/{sessionId}/annotations/{lane}` | `TenantAdminOrOperator` + QueryParam | re-gated per lane in-function |
-| `GET global/session-annotations` | `GlobalReadOrAdmin` + QueryParam | evaluation stream; delegated ("MSP") readers are rescue-admitted on a managed `?tenantId=` only |
-
-**Per-lane write matrix** (`UpsertSessionAnnotationFunction.IsLaneWritableByCaller`, an
-`internal static` pure function like `QueueSessionActionFunction.IsTypeAllowedForCaller`):
-`operator` → tenant Operator or tenant Admin; `tenantadmin` → tenant Admin; `globaladmin` →
-Global Admin only. **Own-tenant binding:** the session's tenant is resolved *before* the gate
-(GA cross-tenant fallback via `FindSessionTenantIdAsync`), and tenant-role inputs are zeroed
-when the resolved tenant differs from the caller's JWT tenant — so a GA who is also an admin of
-their home tenant can never write another tenant's operator/tenantadmin lanes. Cross-tenant, a
-GA writes exactly the `globaladmin` lane (the platform labeling flow).
-
-**GA lane is platform-internal.** `GetSessionAnnotationsFunction.FilterLanesForCaller` drops the
-`globaladmin` lane for every caller without `HasGlobalScope` (tenant members and delegated
-admins). Both list endpoints enforce the same rule server-side via the repository's
-`excludeGlobalAdminLane` OData clause — on the global route this matters exactly for the
-delegated-rescue path, which reaches it without global scope. Tenant lanes are readable by all
-members of that tenant.
-
-**Audit.** Non-GA writes/clears log `LogAuditEntryAsync(..., "SessionAnnotation",
-"{sessionId}/{lane}", ...)`; GA writes are skipped (platform-internal labeling must not surface
-in the tenant-visible audit log — same convention as GA session-report submissions).
-
-# Lifecycle
-
-* **Per-session cascade delete**: three exact-RK steps (one per lane) in `DeletionManifestBuilder`
-  (orders 17–19; inventory 20/21, tombstone 22). `ComputePreflightCounts` sums repeated-table
-  steps so the `sessionAnnotations` count covers all lanes.
-* **Tenant offboarding**: `SessionAnnotations` is in the PK=tenantId wipe list — deliberately
-  wiped, unlike `Feedback` (annotations are customer session data, not product feedback).
-* **Backup**: member of `Constants.CriticalBackupTables.All` — hand-labeled data is the most
-  expensive data on the platform to lose.
-* Being in `Constants.TableNames.All` auto-creates the table at startup and exposes it to the
-  raw `list_tables`/`query_table` tools.
-
-# Surfaces
-
-* **Portal**: `SessionAnnotationsCard` on the session detail page (`#section-annotations`, after
-  Analysis; registered in BOTH the section div and the `sessionSections` sidebar registry). The
-  card mirrors the matrix via the pure module `sessionAnnotationLogic.ts` (vitest-pinned) and
-  uses the explicit-Save pattern; the backend re-gates every save. Collapsed by default with a
-  count + verdict-pill summary header.
-* **Portal overview page** `/annotations` (Monitoring sidebar group — deliberately NO new
-  "Insights" group; Fleet Health & co. are insights too and a second analytics group would
-  dilute both): tenant-scoped list backed by `GET sessions/annotations/list`
-  (`ListTenantSessionAnnotationsFunction`, MemberRead + QueryParam). The path sits under the
-  `/api/sessions` client-cert exclusion prefix (rename-over-exclusion convention; the Azure
-  exclusion list is portal-only config) and uses THREE segments because a two-segment literal
-  would be eaten by the `sessions/{sessionId}` route template. The tenant is always the
-  middleware-validated `TargetTenantId`, and for callers without global scope the repository
-  adds a server-side `Lane ne 'globaladmin'` OData clause — hidden rows never consume page
-  budget, and an explicit lane=globaladmin filter self-contradicts to an empty page. Rows
-  deep-link to `sessions?id=…#section-annotations`. The page carries the standard tenant
-  switcher (`useAggregatedAdminScope` + `TenantScopeSelector`): a GA/Reader defaults to the
-  "All tenants" aggregate (the portal twin of MCP's `list_session_annotations`) with per-tenant
-  drill-down, a delegated ("MSP") admin gets the managed subset; cross-tenant scopes route to
-  `GET global/session-annotations`, a tenant column appears, and deep links carry the row's
-  `tenantId`.
-* **MCP read**: `get_session_summary` carries an `annotations` key (4th parallel leg, fail-soft
-  null); `list_session_annotations` (`ga`-gated) is the evaluation stream with `tenantId / lane /
-  verdict / ruleId / dateFrom / dateTo` filters and nextLink pagination. The `ruleId` filter is
-  applied server-side but client-of-Azure (substring on the JSON column), so the backend
-  back-fills short pages by looping the Azure continuation (bounded rounds) — filtered-out rows
-  never consume page budget.
-* **MCP write**: `annotate_session` (`strictGa`-gated, MUTATING) always PUTs the `globaladmin`
-  lane — no lane argument by design. This is the frictionless labeling path after a session-debug.
-* **Session reports**: `SessionReportService.SubmitReportAsync` snapshots ALL lanes into
-  `annotations.json` inside the report ZIP (`annotationCount` in report-metadata.json; fail-soft).
-  Safe because report blobs are readable only through the GA-only session-reports routes, and
-  valuable because the ZIP outlives the session's retention/delete.
-
-# Citations
-
-* `src/Shared/AutopilotMonitor.Shared/Models/SessionAnnotation.cs` — model, lanes, verdicts.
-* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableSessionAnnotationRepository.cs` — Store/Map + query back-fill.
-* `src/Backend/AutopilotMonitor.Functions/Functions/Annotations/` — the three endpoints.
-* `src/Backend/AutopilotMonitor.Functions/Pagination/SessionAnnotationsPagination.cs` — filter-bound continuation tokens.
-* `src/Web/autopilot-monitor-web/app/sessions/components/sessionAnnotationLogic.ts` — portal matrix mirror.
-* `src/McpServer/autopilot-monitor-mcp/src/tools/admin.ts` — `list_session_annotations`, `annotate_session`.
@@ -1,75 +0,0 @@
---
-type: concept
-title: Tenant Activation & the Once-Only Welcome Mail
-description: How a signup becomes an activated tenant (manual approve or auto-approve queue), and how the welcome mail is sent exactly once even though activation and the user-provided address race each other.
-resource: backend
-tags: [activation, auto-approve, welcome-email, preview-whitelist, race]
-timestamp: 2026-08-02
---
-
-# Schema
-
-## Activation
-
-A tenant is **activated** when the row `PartitionKey={tenantId}, RowKey="approved"` exists
-in the `PreviewWhitelist` table (legacy name kept on purpose). Everything else in the
-portal gates on that row via `PreviewWhitelistService.IsApprovedAsync` (5 min positive /
-30 s negative cache).
-
-Two activation routes, one shared implementation
-(`TenantApprovalService.ApproveWithSideEffectsAsync`):
-
-* **Manual**: Global Admin approves in the admin panel (`POST /api/preview/whitelist/{tenantId}`).
-* **Auto**: signup unconditionally enqueues a `tenant-auto-approve` envelope; the queue
-  worker (`TenantAutoApproveHandler`) re-checks the `AutoApproveNewTenants` flag
-  (uncached, fail-closed), the suspension gate (fresh config read), then approves.
-  Typical latency: ~1 minute after signup.
-
-The whitelist add is a **conditional INSERT** (`AddEntityAsync`, 409 = lost) — storage
-arbitrates concurrent activations; exactly one caller runs the side effects
-(TenantAdmin auto-promote of the signup UPN, welcome mail, `TenantAutoApproved` ops event).
-
-## The welcome-mail race
-
-The welcome mail goes to the **notification email** (`RowKey="notification-email"` in the
-same table) — the only reliable address: it is typed by the user on the activation-pending
-page (`PUT /api/preview/notification-email`). The signup admin UPN may have no mailbox and
-`ContactEmail` is merely seeded from the notification email.
-
-That makes activation and address entry concurrent writers. With auto-approve, activation
-usually wins (observed in production: approve at T+64 s, address saved at T+69 s → the
-approval path found no address and the mail was silently skipped).
-
-**Arbitration — write-then-read on both sides plus a send-once marker:**
-
-* The approval path writes the `approved` row, then reads the address.
-* The save path (`SavePreviewNotificationEmail`) writes the address row, then checks
-  approval **fresh** (`IsApprovedFreshAsync` — the 30 s negative cache would hide the
-  activation for exactly this window).
-* Since both do write-then-read, at least one sees both halves and calls
-  `TenantApprovalService.TrySendWelcomeEmailAsync`.
-* There, a conditional insert of `RowKey="welcome-email-sent"` decides who actually
-  sends: at most one wins. The marker is consumed strictly **after** the address check —
-  consuming it without an address would permanently suppress the mail.
-
-Marker lifecycle: revoke (`RevokeAsync`) deletes it (re-approve = fresh activation =
-fresh mail); the offboarding cascade wipes the whole `PreviewWhitelist` partition anyway.
-The Global-Admin resend endpoint (`POST /api/preview/send-welcome-email/{tenantId}`)
-always sends (explicit intent) and consumes the marker best-effort so the automatic
-paths never duplicate afterwards.
-
-# Examples
-
-* Auto-approve wins the race: approve at T+64 s finds no address → logs "deferred to the
-  notification-email save path"; user saves address at T+69 s → save path sees approved
-  (fresh read), wins the marker, sends. Response carries `welcomeEmailSent: true`.
-* Address saved before manual approve (classic shape): approval path finds the address,
-  wins the marker, sends; a later re-save of the same address does not re-send.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Services/TenantApprovalService.cs` — shared activation + `TrySendWelcomeEmailAsync`
-* `src/Backend/AutopilotMonitor.Functions/Services/Activation/TenantAutoApproveHandler.cs` — queue-side gates
-* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/PreviewWhitelistFunction.cs` — save-path trigger, GA resend
-* `src/Backend/AutopilotMonitor.Functions/DataAccess/TableStorage/TableConfigRepository.cs` — conditional inserts (approved / welcome-email-sent)
-* `src/Backend/AutopilotMonitor.Functions.Tests/TenantApprovalServiceTests.cs` — ordering + dedup pins
@@ -1,139 +0,0 @@
---
-type: Concept
-title: Enrollment Time Attribution (F1)
-description: How a terminal session's wall clock is partitioned into named segments with an explicit unattributed remainder, how ESP-blocking apps and reboots are attributed, and where breakdowns and fleet aggregates are computed, stored and served.
-resource: src/Backend/AutopilotMonitor.Functions/Helpers/TimeAttributionCalculator.cs
-tags:
-  - backend
-  - metrics
-  - time-attribution
-  - insights
-timestamp: 2026-07-26T20:00:00+02:00
---
-
-# Enrollment Time Attribution (F1)
-
-Answers "where did the 47 minutes go?" per session and per fleet. Every number is
-traceable to observed events; a missing signal produces "unknown" or an explicit
-unattributed remainder — never a guess, and the partition is never normalized to 100 %.
-
-# Schema
-
-## Invariant
-
-For every computed breakdown:
-
-```
-sum(span seconds) + UnattributedSeconds == WallClockSeconds == session DurationSeconds
-```
-
-`DurationSeconds` is the authoritative wall clock — for WhiteGlove it is part 1 + part 2
-WITHOUT the pause, and re-terminal stamps move `CompletedAt`, so `CompletedAt − StartedAt`
-is never used (it diverges in ~25 % of terminal sessions). Span seconds are floored;
-sub-second dust lands in the unattributed remainder.
-
-## Observation windows
-
-Windows are end-anchored on authoritative timestamps and constructed so their lengths sum
-exactly to `DurationSeconds`:
-
-* Non-WhiteGlove: one window `[CompletedAt − DurationSeconds, CompletedAt]`.
-* WhiteGlove (ONE session row, two windows): part 2 = `[ResumedAt, CompletedAt]`; part 1 =
-  `[part1End − (DurationSeconds − part2), part1End]` where `part1End` is anchored on the
-  `whiteglove_part1_complete` event. The pause between the windows is never attributed.
-  Fallback anchors set the `WhiteGloveAnchorsIncomplete` quality flag.
-
-## Segments
-
-Spans are sliced at phase-declaration events (only declaration events carry
-`Phase != Unknown`) plus `desktop_arrived`, in canonical Sequence order; anchors whose
-timestamp runs backward are dropped (`ClockSkewDropped`).
-
-| EnrollmentPhase | Segment key |
-|---|---|
-| Start / DevicePreparation / DeviceSetup | `device_prep` |
-| AppsDevice | `esp_apps` |
-| AccountSetup / FinalizingSetup | `identity_hello` |
-| AppsUser | `user_esp` |
-| Complete, `desktop_arrived` event | `desktop_handoff` |
-| Failed | attribution ends — tail stays unattributed |
-
-## Quality flags (AttributionVersion 2)
-
-Duration-critical flags (`ClockSkewDropped`, `PartialObservation`,
-`WhiteGloveAnchorsIncomplete`, `PriorEnrollmentResidue`) exclude a breakdown from fleet
-segment statistics with a disclosed count; the blocking-set flags (`BlockingSetUnknown`,
-`BlockingSetTruncated`) only limit per-app evidence and never gate fleet stats.
-
-`PriorEnrollmentResidue` (v2) fires on `historic_ime_replay_detected`: the IME log on disk
-predates the enrollment, so the device was re-enrolled without a wipe — pre-installed apps
-complete as instant detections and pull the phase anchors ahead of the real ESP page
-(session f475e697: AccountSetup anchor 6.5 min early, 457 s misattributed to
-`identity_hello`). `registry_app_baseline` successes are deliberately NOT a trigger — they
-are by-design normal for Windows Device Preparation (DPP Batch-1 apps install before the
-agent exists) and would starve that class's aggregates.
-
-## ESP-blocking apps (positive evidence only)
-
-Per-app intervals use EVENT timestamps (first started/download event → LAST terminal
-event, covering IME retries) — never the agent payload timing, which freezes at the first
-terminal transition. Blocking membership joins the app id against the session's latest
-list-carrying `esp_config_detected` emission: listed ⇒ blocking; absent ⇒ unknown, never
-false (`BlockingSetUnknown` / `BlockingSetTruncated` flags). Critical-path occupancy =
-overlap-merged union of blocking intervals clipped to the `esp_apps` spans;
-`EspAppsOccupancySeconds` is null (unknown) when no lists were observed.
-
-The fleet what-if bound per app X is `max(0, cpEnd − cpEndWithoutX)` (latest interval end
-with vs. without X; the idle gap before X counts — the ESP also waits for X to start).
-It is an upper bound by construction; every consumer says "up to", never "you will save".
-
-## Reboots
-
-`system_reboot_detected` is detection-time-stamped by the NEXT agent run; the real boot
-moment is its `lastBootUtc` payload. Reboot spans are therefore the event-stream gap
-bracketing `lastBootUtc`, deduped per boot, clipped to the observation windows, and carried
-as a cross-cutting annotation (they overlap the segment they started in — never a slice of
-the partition).
-
-## Persistence & compute
-
-* `SessionTimeBreakdowns` (PK = TenantId, RK = SessionId): spans, reboot spans, blocking
-  intervals (top 20 + uncapped count), quality flags, `AttributionVersion`. Written once at
-  the session-terminal single-writer seam (`TableSessionRepository.UpdateSessionStatusAsync`,
-  Succeeded/Failed only — Incomplete deliberately has no duration). Deleted with its session
-  (deletion-manifest step) and on tenant offboarding.
-* Self-healing 30-day maintenance sweep (2h tick): backfills missing breakdowns, folds
-  late-terminating sessions into their StartedAt-date aggregates, and enforces version
-  purity — a stale-version row whose events aged out counts as missing, never mixed.
-* `TimeAttributionAggregates` (PK = TenantId or `global`, RK = `{yyyy-MM-dd}|{class}` and
-  `rolling30|{class}`): per enrollment class (`user_driven`, `whiteglove`, `self_deploying`,
-  `device_preparation` — never mixed) median/p75/p90 per segment over the fixed six-segment
-  stack (incl. `unattributed`; a session without a segment contributes 0), plus top blocking
-  apps (≥5 sessions per app row). Clean/flagged/missing counts are part of every row; rows
-  exist below the ≥20 UI gate on purpose (the UI needs the n for "insufficient data (n=…)").
-  Daily rows retain 180 days; `rolling30` rows are refreshed whole (a median of per-day
-  medians is not the range median — the rolling rows are the honest range statistics).
-
-## Surfaces
-
-* `GET api/sessions/{sessionId}/time-attribution` (MemberRead + tenant query param) —
-  breakdown row or `breakdown: null` (pre-feature / non-terminal / Incomplete = no lane).
-* `GET api/metrics/time-attribution` (MemberRead) / `GET api/global/metrics/time-attribution`
-  (GlobalReadOrAdmin, optional `tenantId`) — `{ windowDays, classes (rolling), daily }`.
-* Web: attribution lane under the session-detail phase timeline; "Time attribution" section
-  on Fleet Health. MCP: `get_time_attribution` (sessionId mode / fleet mode).
-
-# Examples
-
-A 30-minute user-driven session: `device_prep` 5m → `esp_apps` 10m (occupancy 4m by one
-blocking app) → `identity_hello` 8m → `user_esp` 5m → `desktop_handoff` 2m, unattributed 0.
-A WhiteGlove session with a 2-day pause reports wall clock = part1 + part2 only; the resume
-gap before the first part-2 phase declaration is unattributed, not guessed.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Helpers/TimeAttributionCalculator.cs` — calculator + semantics (AttributionVersion 2).
-* `src/Backend/AutopilotMonitor.Functions/Services/TableStorageService.TimeAttribution.cs` — persistence.
-* `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.Aggregation.cs` — sweep + aggregation.
-* `src/Backend/AutopilotMonitor.Functions.Tests/TimeAttributionCalculatorTests.cs` — golden fixtures pinning the invariant.
-* `tasks/insights-expansion-spec.md` — F1 specification and source-data audit (§0.5).
@@ -1,106 +0,0 @@
---
-type: Concept
-title: Drift Guards — SignalR Names, RowKeys, Config Sections, Scoped Routing
-description: The 2026-08 fragility-audit follow-up contracts that turn formerly hand-synchronized mirrors into enforced ones — SignalR message-name catalog, the inverted-tick RowKey codec, tombstone table tagging, the OkAsync ratchet, per-section config PATCH, and the web's scoped-endpoint builders.
-resource: /src/Backend/AutopilotMonitor.Functions.Tests/OkAsyncBaselineGuardTests.cs
-tags:
-  - contracts
-  - guard-tests
-  - signalr
-  - web
-timestamp: 2026-08-13T00:00:00+02:00
---
-
-# Drift Guards
-
-Follow-up to the 2026-08 fragility audit (see [Lifecycle Manifests & Session Scope
-Resolution](backend/lifecycle-manifests-and-session-scope.md) for the earlier rounds).
-Each section below replaces a hand-synchronized mirror with an enforced contract: a
-change on one side now fails a build, a type check, or a test on the other side.
-
-# Schema
-
-## SignalR message names — one catalog, typed on both ends
-
-`Constants.SignalRMessages` (Shared) is the complete catalog of SignalR target names.
-Backend senders (output bindings and the imperative `SignalRNotificationService`)
-reference the constants; the hub name is `SignalRGroupHelper.HubName`. The catalog is
-exported into `shared-manifests.json` (`signalRMessages` section) by
-`SharedManifestParityTests`, and the web's `SignalRContext.on/off` type their event
-name against the generated union (`lib/signalrMessages.ts`) — subscribing to a name
-the backend never sends is a tsc error, not a silent no-op. `newevents` is the one
-legacy lowercase name; it is a persisted wire name, do not "fix" the casing.
-
-## Inverted-tick RowKeys — one codec
-
-`RowKeyCodec` (Functions/Helpers) is the single encoder/decoder for
-`rev(t) = MaxTicks - t.Ticks` RowKeys. Every writer routes through it; the persisted
-per-table shapes (D19 standard, AuditLogs `!`-prefix, UserActivity's legacy D20 width,
-ConfigurationBackups' 28-char truncation) are pinned by `RowKeyCodecTests` and must
-never change — a width/prefix change reorders live tables against their existing rows.
-`BusinessTimestamp` keeps the OData clause builders and delegates decode to the codec.
-
-## Tombstone rows carry their table
-
-`DeletionRowDump.Table` names the source table on FINAL (Tombstone) rows — the one
-step that mixes two tables while `DeletionStep.Table` is null.
-`DeletionTombstoneTables.Resolve` is the only consumer-side resolution (delete +
-restore + dry-run); the historical `Contains('_')` RowKey-shape heuristic survives
-solely as the fallback for manifests written before the field existed and must outlive
-one full manifest-retention cycle.
-
-## Anonymous OkAsync responses — frozen, shrink-only
-
-`OkAsyncBaselineGuardTests` freezes the 44 existing `req.OkAsync(new { … })` call
-sites as a per-file baseline. A new anonymous response (new file or count above
-baseline) fails; converting a site to a typed DTO (Shared response models, picked up
-by the manifest parity tests) fails too until its baseline entry is lowered — the debt
-list stays truthful and only ever shrinks.
-
-## Tenant settings — per-section PATCH
-
-The web's Settings sections no longer PUT the full ~92-field configuration. Each
-section's exact write surface lives in `app/settings/sectionFieldMap.ts` (owned fields
-plus documented `alsoWrites` write-throughs); `saveConfiguration` diffs those fields
-against the loaded config and PATCHes only the changes through
-`PATCH config/{tenantId}/fields` — the transactional endpoint (CAS + fail-closed
-backup + exactly-these-fields verify + auto-rollback) that previously served MCP only.
-The policy line is TenantAdminOrGA; a tenant admin runs on the stricter
-`TenantConfigCallerTier.TenantAdmin` whose deny-list turns GA-only fields into
-explicit 400s. Deploy order: backend before web. `sectionFieldMap.test.ts` pins
-field↔section ownership (each field exactly one owner, all fields on the model, none
-server-denied); backups/revert stay GlobalAdminOnly.
-
-## Scoped endpoint routing — one decision object
-
-`lib/scopedApi.ts` owns the tenant/global endpoint-pair choice: pages pass their scope
-hook object (`routeGlobal`, `selectedTenantId`, `effectiveTenantId`) instead of
-hand-rolling `routeGlobal ? global(..., sel || undefined) : tenant(tid, ...)` with the
-tenant parameter at a different position per pair. `useGlobalAdminScope` is now a thin
-projection over `useAggregatedAdminScope` (one hook, aggregated as a mode) via the
-pure `resolveConcreteScopeView`. `lib/scopedFetch.ts` adds the shared JSON+ok-check
-fetch layer. `lib/navVisibility.ts` extracts the sidebar's roles × nav-config × guard
-logic; its matrix test also ratchets the known "sidebar shows it, guard bounces it"
-mismatches (plain Operator and GlobalReader vs. `/settings` — pending a user decision).
-
-# Examples
-
-Renaming a SignalR message end to end: change the constant in
-`Constants.SignalRMessages` → `AM_WRITE_SHARED_MANIFESTS=1 dotnet test --filter
-SharedManifestParityTests` → `node scripts/generate-shared-manifest-types.js` → tsc
-now flags every stale web subscription literal.
-
-Adding a field to a Settings section: add it to the section in `sectionFieldMap.ts`
-(tsc validates the name against the manifest), wire the form state into the
-`updatedConfig` construction in `TenantConfigContext`, and extend the expected-fields
-list in `sectionFieldMap.test.ts`.
-
-# Citations
-
- `src/Shared/AutopilotMonitor.Shared/Constants.cs` — SignalRMessages catalog
- `src/Backend/AutopilotMonitor.Functions/Helpers/RowKeyCodec.cs` + `RowKeyCodecTests.cs`
- `src/Shared/AutopilotMonitor.Shared/Models/Deletion/DeletionManifest.cs` — `DeletionRowDump.Table`, `DeletionTombstoneTables`
- `src/Backend/AutopilotMonitor.Functions.Tests/OkAsyncBaselineGuardTests.cs`
- `src/Web/autopilot-monitor-web/app/settings/sectionFieldMap.ts` + `__tests__/sectionFieldMap.test.ts`
- `src/Web/autopilot-monitor-web/lib/scopedApi.ts`, `lib/navVisibility.ts`, `hooks/concreteAdminScopeView.ts`
- [Version Contract](versioning.md) — the web `/version.json` stamp + deploy verify added in the same round
@@ -1,73 +0,0 @@
---
-okf_version: "0.1"
---
-
-# Autopilot Monitor — Technical Knowledge Bundle
-
-Contributor-facing technical documentation for Autopilot Monitor, organized as an
-[Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
-knowledge bundle. Customer-facing product documentation lives at
-https://docs.autopilotmonitor.com (separate repository).
-
-# Architecture
-
-* [Architecture Guide](architecture.md) - High-level architecture overview and solution layout for contributors.
-* [Version Contract](versioning.md) - One version shape for agent, backend and MCP: the ETag-CAS counter blob that mints build numbers, and the manifests published only after a deploy is verified live.
-* [Customer Script Publishing](script-publishing.md) - How the customer-facing PowerShell scripts reach download.autopilotmonitor.com/agent/, why publishing is decoupled from agent releases, and the guards keeping the published copy, the version badge and the portal's version oracle in agreement.
-* [URL Registry](url-registry.md) - Every well-known host lives in one registry file per component (Constants.cs / utils/config.ts / src/config.ts), enforced by guard tests; includes the agent-download migration to the download alias and its deploy-order constraint.
-* [Drift Guards](drift-guards.md) - The 2026-08 fragility-audit follow-up contracts: SignalR message-name catalog (typed on both ends), the inverted-tick RowKey codec, tombstone table tagging, the shrink-only OkAsync baseline, per-section config PATCH with the section field map, and the web's scoped-endpoint builders + sidebar visibility matrix.
-
-# Agent
-
-* [V2 Agent](agent/index.md) - How the on-device agent works: [runtime overview](agent/overview.md), [decision engine](agent/decision-engine.md) (reducer, signals, completion arms), [logs & persistence](agent/logs-and-persistence.md) (signal log, snapshot, crash recovery), [Hello wizard un-skip](agent/hello-wizard-unskip.md) (why a single "WHfB disabled" read never decides completion), [Autopilot ZTD diagnostics](agent/autopilot-ztd-diagnostics.md) (event IDs, diagnostic registry, endpoints, error-code map).
-* [Build Counter Blob](agent/build-counter-blob.md) - How agent build numbers are minted: shared counter blob with ETag-CAS so local and CI builds never collide; CI additionally attests build provenance (Sigstore).
-* [Agent Endpoint Migration](agent/endpoint-migration.md) - How the backend re-homes agents to a new API base URL via the config channel (backend move or per-tenant region move): live-fetch-only, allowlist-validated on both sides, one hop, kill wins.
-* [Gather Rule Debug Log](agent/gather-rule-debug-log.md) - EnableGatherRuleDebugLog (ConfigVersion 36): the per-tenant local trace file that explains every gather-rule evaluation decision — scope skips, on_change suppression, empty collector results, logparser position/parse-mode outcomes — for rules that produce no timeline events.
-* [MDM Reboot Coalescing](agent/mdm-reboot-coalescing.md) - Attributing the mid-ESP coalesced reboot ("second sign-in") to the device-assigned policy URIs that forced it: aggregated DM-Enterprise 2800 observations (neutral, flush-time watermark) + the ANALYZE-ESP-005 advisory gated on an actually-observed reboot.
-* [ESP Completion Starvation — the sits-d Cloud-PC complex](agent/post-reboot-completion-recovery.md) - Why a SkipUser=true flow (no user ESP page → no Shell-Core 62407, no AccountSetup registry) left the completion gate satisfied but never evaluated — five Cloud PCs idled six hours at "waiting on: hello_resolution" — and the fix: the observed skip stands in for the final-exit evidence in the IME user-session completion attempt. Plus the two adjacent defects fixed alongside: the edge-only user-apps-settled synthesis (now level-triggered) and the never-wired Shell-Core restart replay (now Hello-wizard-only, with the reasoning why a replayed 62407 must never reach the reducer).
-* [Secure Boot CA-2023 Detection](agent/secureboot-ca2023-detection.md) - Why ANALYZE-SEC-001 v3 reads the UEFI db/KEK variables directly instead of trusting the SecureBoot\Servicing registry, and how the one-sided uefiCa2023FirmwareConfirmed marker plus a not_exists precondition give absence-tolerant suppression across old and new agents.
-* [Continue-Anyway Observation Mode](agent/continue-anyway-observation.md) - EnableEspContinueAnywayObservation (ConfigVersion 37, operator-set): Device-phase ESP terminal failures on Continue-Anyway profiles get a bounded 60-min observation instead of an immediate hard fail; the DAD-validated real-user desktop + Hello gate detect the true end, the session completes Succeeded + EspSoftFailure (amber "with issues" badge), expiry un-defangs to the original esp_terminal_failure.
-* [Registry App-State Second Pillar](agent/registry-app-state-pillar.md) - IME's authoritative per-app state read straight from the registry (Win32Apps EnforcementStateMessage, EspTrackingWin32Apps, StatusServiceReports) via a snapshot-and-diff watcher; registry/log reconciliation doubles as the built-in IME log-pattern drift alarm.
-* [WDP Scenario Gates & Completion Backstop](agent/wdp-scenario-gates.md) - How the agent gates Autopilot/ESP-only machinery off on Windows Device Preparation sessions (deterministic ExecutionContext marker, fail-toward-Classic), which noise it suppresses (ZTD probe, esp_config unknown, ModernDeployment 100/417/418/1005, starved sweep), and the WDP completion model: High-confidence seed, desktop-based arm D, and the 30-min device_prep_completion backstop.
-* [ESP Policy-Provider Stall Detection](agent/esp-policy-provider-stall.md) - The EnrollmentStatusTracking CSP's no-timeout Setup/Apps wait is keyed to the Intune-registered "Sidecar" provider by NAME: co-management's "ConfigMgr" parks the user ESP at "Apps (Identifying)" for days even with TrackingPoliciesCreated=1 (issue #106); the always-on two-arm esp_policy_provider_stalled tripwire (provider_incomplete | sidecar_provider_missing) and the SOFTWARE\Microsoft\Windows\Autopilot gather-rule allowlist entry that surface it.
-
-# Rules
-
-* [Gather Rule Phase Scoping, One-Shot Triggers & Emit-on-Change](rules/gather-rule-phase-scoping.md) - Restricting gather rules to enrollment phases (activePhases / activeFromPhase sticky latch), one-shot collection at a phase's start/end (phase_change / phase_exit), and emitMode "on_change" result-dedup.
-* [Gather Rule Guardrails](rules/gather-rule-guardrails.md) - Why the allowlists in rules/guardrails.json are enforced on the agent and nowhere else, which hard blocks survive unrestricted mode, and the rule that every collector must call a guard and emit security_warning on refusal.
-* [Rule Authoring Surface](rules/rule-authoring-surface.md) - How customer AIs author rules against the real contract: the baked MCP resources (guide/schemas/guardrails via combine.js), the MCP-local validate_rule pre-flight, and the side-effect-free POST rules/analyze/dryrun whose trace twin shares the production evaluators (parity + side-effect-freedom pinned by tests).
-* [Analyze Rule Evaluation Triggers](rules/analyze-rule-triggers.md) - Opt-in `evaluateOn` interim triggers (`whiteglove_sealed`, `on_event:<type>`) so rules can fire before a session is terminal, with RuleResults update-semantics (interim → finalize/resolve, NotifiedAt notification dedupe) replacing the permanent dedupe freeze, KO/stat suppression on interim runs, the ingest-side cached trigger registry, and the authoring lints that keep interim rules monotonic.
-
-# Backend
-
-* [Business Timestamps](backend/business-timestamps.md) - Why the Azure Tables system Timestamp is never authoritative (migrations reset it), and the OccurredUtc + RowKey-decode compensation for AuditLogs/OpsEvents/Events after the 2026-07-18 migration.
-* [OOBE Bootstrap go-Code Flow](backend/oobe-bootstrap-go-flow.md) - The bootstrap short-code lifecycle (portal-created session → `irm go.autopilotmonitor.com/CODE | iex` at Shift+F10 → GetBootstrapScriptFunction), the always-HTTP-200 text/plain contract, the two-line injection defense (GUID/URL/expiry validator + single-quoted PS literals, golden-pinned against the legacy TS template), and the per-IP rate-limit story behind Front Door.
-* [Device Journeys & First-Time-Right](backend/device-journeys.md) - How a device's terminal enrollment attempts are grouped into journeys (trim+casefold device key with junk-serial exclusion, first-success end, 30-day gap, WhiteGlove = one attempt), the DeviceHistories chain with its tombstone-driven deleted-session pruning, the additive daily FTR aggregates, and the banner/fleet/MCP surfaces.
-* [Enrollment Time Attribution](backend/time-attribution.md) - How a terminal session's authoritative wall clock (DurationSeconds, WhiteGlove pause excluded) is partitioned into named segments with an explicit unattributed remainder, ESP-blocking apps as positive evidence with "up to" what-if bounds, reboot spans from event gaps, and the breakdown/aggregate tables the sweep maintains.
-* [Rule Regression Radar](backend/rule-regression-radar.md) - How analyze-rule hit-rate regressions are detected (7-day window ≥2× the 28-day baseline with disjoint Wilson intervals), which suppressions keep the radar quiet (grace period, edit-in-window, kill switch), how alert episodes live in the ruleregression tracker keyspace with re-arm semantics, and the on-fire dimension correlation with its "correlated, not necessarily causal" wording contract.
-* [App Version Duration Regression Radar](backend/app-version-regression-radar.md) - How app versions whose median install duration regressed vs. the previous version are detected (first-seen-ordered versions, median lift ≥2× plus a 5-minute absolute floor over measured installs only), how alert episodes live in the appversionregression tracker keyspace with drain/median re-arm semantics, and the bell/ops-event/analytics surfaces.
-* [Tenant Activation & the Once-Only Welcome Mail](backend/tenant-activation-welcome-mail.md) - How a signup becomes an activated tenant (manual approve or the auto-approve queue), and the write-then-read + conditional-marker arbitration that sends the welcome mail exactly once even though activation and the user-typed notification address race each other.
-* [W365 Cloud PC Device Validation](backend/cloudpc-device-validation.md) - Why Cloud PCs can never pass the Autopilot serial lookup, and the cert-CN-bound CloudPc fallback validator: Subject CN (= Intune device id) matched against the tenant's Graph virtualEndpoint/cloudPCs inventory — admits exactly the service-provisioned Cloud PCs, nothing else.
-* [ServerActions & On-Demand Diagnostics](backend/server-actions-on-demand-diagnostics.md) - The queue-on-session, deliver-on-ingest action channel, the TenantAdminOrOperator tier with in-function per-type re-gating, the portal's Collect Logs flow (quick-config orders rotate_config before request_diagnostics), and the hosted-prefix sweep in the offboarding cascade.
-* [Session Annotations](backend/session-annotations.md) - Role-separated human verdicts on sessions (operator / tenantadmin / globaladmin lanes, one row each): the per-lane write matrix with own-tenant binding, the platform-internal GA lane, the fired-rule-id snapshot that makes annotations rule-quality labels, and the portal card + MCP list/annotate surfaces.
-* [Lifecycle Manifests & Session Scope Resolution](backend/lifecycle-manifests-and-session-scope.md) - The fragility-audit P5/P6 completeness nets: every table classified into a deletion lifecycle (offboarding buckets incl. the RowKey-anchored SafeWipe Variant D, per-session cascade, kept-by-design), the SessionsIndex field manifest with bidirectional builder/reader pinning, the single ResolveSessionScopeAsync helper backed by the SessionTenantLookup point-read, and the server-side dashboard free-text search (q=) with its page-backfill loop.
-
-# MCP Server
-
-* [MCP Docs Corpus](mcp/docs-corpus.md) - How the published customer documentation becomes the `search_docs` corpus: CRLF-safe heading chunking, build-time embedding as a third precomputed section, and why a docs edit needs an MCP redeploy.
-* [MCP Tool Telemetry](mcp/tool-telemetry.md) - The three telemetry layers for judging tool quality: backend App Insights via X-MCP-Tool-Name, the per-user usage table, and the MCP_TOOL_LOGGING stderr lines (soft errors, result size vs. cap, zero-hit searches, Zod rejections).
-
-# Web Portal
-
-* [Portal Navigation Prefetch & the SWA Runtime Bottleneck](web/portal-navigation-prefetch.md) - Why every navigation Link sets `prefetch={false}`: the App Router's viewport prefetch fans out one RSC request per visible link and the Static Web Apps SSR runtime queues them server-side into a multi-minute tail. Records the follow-up measurement (the Standard plan changed nothing; the prefetch storm was an accidental keep-alive), where browser telemetry actually lives, and why this curl build cannot be trusted for HTTP versions.
-
-# Security & Identity
-
-* [MCP OAuth Flow](mcp-oauth-flow.md) - Who authenticates where when connecting an AI client to the MCP server; two identities, three parties plus Entra ID.
-
-# Conventions for this bundle
-
-* Every concept document is a markdown file with YAML frontmatter; `type` is mandatory, `title`, `description`, `resource`, `tags`, and `timestamp` are recommended.
-* Use standard **relative** markdown links between documents (e.g. `agent/overview.md`, `../architecture.md`). Do NOT use the spec's `/`-prefixed bundle-absolute form — GitHub resolves those against the repo root (missing `/docs`) and navigation breaks.
-* Record notable additions and changes in [log.md](log.md).
-* `index.md` and `log.md` are reserved names — never use them for concept documents.
@@ -1,194 +0,0 @@
-# Log
-
-## 2026-08-20
-
-* **Update**: `agent/post-reboot-completion-recovery.md` — retitled to "ESP Completion Starvation — the sits-d Cloud-PC complex" and reframed on the evidence: the reboot was a red herring. The five stuck Cloud PCs carried `SkipUserStatusPage=True` (read 10+ times across three agent processes, `True` every time) and Windows honoured it — no user ESP page, hence no Shell-Core 62407 and no AccountSetup provisioning registry, verified over a six-hour uninterrupted post-reboot run with the watcher armed. Arm B of `ShouldTransitionToAwaitingHello` was open from the bootstrap onward, but every evaluation site hangs off a signal a skip-user flow cannot produce, and the `AdvisoryCompletion` backstop arms exclusively from an `EspExiting` signal — an open gate nobody knocks on. Fix: `HandleImeUserSessionCompletedV1` accepts the observed skip in place of the final-exit evidence (`skipUserExitEquivalent`; anchor + genuine IME completion + real-user desktop stay mandatory, WDP excluded). The knock deliberately lives on the IME edge, not desktop arrival — ordering-robust against Fix 10's AccountSetup bounce-back and semantically "user-phase work finished" rather than mid-install. `ClassicSkipUserEspUserSessionCompletionTests` replays the real 8110e262 ordering end to end. Docs and comments no longer claim an ESP-exit recovery that does not exist (stray duplicate summary in `ShellCoreTracker`, `ImeLogHost` restore-callback comment); the residual `SkipUser=false` exit-in-downtime gap is named honestly and surfaced by `ANALYZE-ESP-005` via `session_stalled` instead of being patched with an unorderable replay.
-
-## 2026-08-19
-
-* **New**: `agent/post-reboot-completion-recovery.md` — a forced mid-ESP reboot (DeviceGuard/DmaGuard) used to cost the session its AccountSetup completion permanently. Two defects: `ShellCoreTracker.BackfillRecentEspExitEvents()` existed but had no caller, so every agent restart dropped an ESP exit (62407) written while it was down; and the user-apps-settled synthesis was edge-triggered on `EspExited` only, so apps settling afterwards never re-opened the gate. `EspAndHelloHost.Start()` now backfills with a lookback sized to the downtime (`previousExit=reboot_kill` → since `LastBootUtc`, clamped to 360 min), and `ReevaluateUserAppsSettledSynthesis()` is chained into `ImeLogTracker.OnAppStateChanged`. No new completion path — the gate conditions are unchanged. Evidence: sits-d Cloud PCs, five `Incomplete` sessions on healthy devices, two of them at `138/138 apps, 0 failed`. Hardened over two review rounds: the remembered edge must be a **live** exit that is **confirmed** post-AccountSetup (a replay carries no evidence of its own position — Shell-Core writes the same `CommercialOOBE_ESPProgress_Page_Exiting` for the intermediate and the final exit, and the registry check reads *now*, not the event's time); the replay hands over the **newest** exit rather than the oldest; the replay is narrowed to the Hello-wizard start (62404) alone — a conservative fact that can only make the agent wait longer. A replayed ESP exit is never re-raised at all: Windows writes the identical description for the intermediate and the final exit, the reducer orders exits by ingest ordinal (fresher than reality for a replay) and `HandleEspExitingV1` passes `espFinalExitInFlight: true` for every arriving exit, so arm C of `ShouldTransitionToAwaitingHello` would open on a historic handoff once the restored state carries AccountSetupEntered + IME user session + desktop. A replayed ESP failure is likewise dropped (it could fail a session that recovered). Skipped records are reported as an `agent_trace`. The window is **measured** from the previous run's last known liveness (snapshot mtime, widened by `LastBootUtc`) instead of a constant — the scheduled task has a BootTrigger only and no restart-on-failure, so a crashed agent returns hours later and five minutes would lose the exit every time. On `first_run` the replay stays off, leaving the happy path untouched.
-
-* **Update**: `rules/analyze-rule-triggers.md` — `on_event:session_stalled` documented as an established interim trigger for the never-terminal stuck session (one emission per session, no throttle needed). `ANALYZE-ESP-005` carries it: both its conditions are monotonic and it has no terminal precondition, and it fires at confidence 95 on the sits-d stalled stream. `ANALYZE-APP-015` deliberately does NOT — it is the worked example of the terminal-precondition trap (lint 1) — and `ANALYZE-ESP-001` does not either, because its `phase_duration` gate on a still-open phase is unverified mid-run. New `ANALYZE-APP-016` ("Required Apps Never Started — ESP Apps Gate Starved") turns the existing `app_install_starved` events into a customer-facing finding and, unlike `ANALYZE-APP-015`, fires even when the session succeeded — session `3b9291aa` was recorded `Succeeded` with 99 required apps that never started installing.
-
-* **New**: `script-publishing.md` — the customer script publishing chain. `.github/scripts/Publish-BootstrapScripts.ps1` becomes the single owner (dev render, version-bump guard, uploads, version oracles, alias verification), called both by the new `publish-scripts.yml` (push to `main` on `scripts/Bootstrap/**` and `scripts/CustomerSetup/**`) and by the `publish_as_stable` branch of `build-agent.yml`. Script publishing no longer waits for an agent release. Blobs are published in a deterministic CRLF/UTF-8-no-BOM form so byte comparisons do not depend on the checkout; the Pester + ASCII gates move into the reusable `bootstrap-script-gates.yml` and block the upload; `AdminConfiguration.LatestBootstrapV2ScriptVersion` now has exactly one writer. The version-bump guard compares a code fingerprint (PowerShell token stream without comments, newlines and line continuations), so only behaviour changes require a `$ScriptVersion` bump — comment and formatting changes publish with a warning.
-
-## 2026-08-18
-
-* **New**: `agent/wdp-scenario-gates.md` — WDP scenario gates (afee7ae0 audit): deterministic ExecutionContext marker as the only gate key (fail-toward-Classic), suppressed Autopilot/ESP-only emissions and hosts (autopilot_profile*/ZTD probe, esp_config unknown null-gate, EspPolicyProviderStallHost, ProvisioningStatusTracker, ModernDeployment noise IDs 100/417/418/1005 + error-backfill skip, starved sweep), and the WDP completion model (High-confidence v2 seed via `enrollmentTypeDeterministic`, desktop-based arm D, 30-min `device_prep_completion` backstop, parked-tripwire WDP branch).
-
-* **Update**: `backend/time-attribution.md` — AttributionVersion 1 → 2: new duration-critical quality flag `PriorEnrollmentResidue` (fires on `historic_ime_replay_detected`; a re-enrollment without wipe pulls the phase anchors ahead of the real ESP page, so the segments are excluded from fleet stats; `registry_app_baseline` successes deliberately not a trigger — by-design normal for WDP). Added the quality-flags section.
-* **Update**: `agent/logs-and-persistence.md`, `agent/overview.md`, `agent/gather-rule-debug-log.md` — log files renamed to unified kebab-case: `agent.log` (date rotation dropped; size segments `agent-NNN.log`), `bootstrap-script.log` (was `bootstrap_agent.log`), `bootstrap-msi.log` (was `msi-bootstrap.log`), `crash-*.log`, `gather-rules-debug.log`, `ime-pattern-matches.log`. Old names still appear in archives from pre-rename agents.
-* **New**: `agent/registry-app-state-pillar.md` — the registry second pillar for IME app state (audit follow-up): snapshot-and-diff watcher on `HKLM\...\IntuneManagementExtension` (Win32Apps / EspTrackingWin32Apps / StatusServiceReports), `registry_app_state` + `app_state_reconciliation` events, silent startup baseline, WDP reuse notes.
-
-## 2026-08-17
-
-* **Update**: `mcp/tool-telemetry.md` — the `tool_call` stderr line now carries `errorMessage` (capped at 300 chars; thrown message or the leading `toolError` text, absent on success), so error drilldowns name the failure class instead of guessing from args. Same change: `get_rule_stats` omits the per-rule daily `trend` rows by default (they drove 50% of calls over the response cap at platform scope); `includeTrends=true` opts back in, the response carries a `trendsNote` marker when stripped.
-
-## 2026-08-14 (later)
-
-* **Update**: `rules/analyze-rule-triggers.md` — status SPEC → IMPLEMENTED. Shipped: `evaluateOn` on the analyze-rule schema (grammar-validated server-side and in validate_rule), `AnalyzeRunContext`-driven engine runs (Terminal/Interim/Reanalyze) with the RuleResult lifecycle columns (FirstDetectedAt/LastEvaluatedAt/IsInterim/ResolvedAt/NotifiedAt), interim rule filtering + KO/stat suppression, resolve/finalize update-semantics, the NotifiedAt one-send-per-(session,rule) notification dedupe (preserved across the manual reanalyze rebuild), the ingest-side `InterimTriggerRegistry` (5-min TTL, fail-soft) gating `interim_trigger` / `whiteglove_sealed` enqueues, the three MCP authoring lints, web preliminary/resolved rendering, and ANALYZE-ID-004 as the first interim-enabled rule.
-
-## 2026-08-14
-
-* **Creation**: Added `rules/analyze-rule-triggers.md` — SPEC for opt-in `evaluateOn` interim evaluation of analyze rules: `enrollment_end` default preserves today's behavior, `whiteglove_sealed` + `on_event:<type>` close the WhiteGlove notification gap and the never-terminal stuck-session gap; RuleResults update-semantics (FirstDetectedAt/IsInterim/ResolvedAt/NotifiedAt) replace the permanent dedupe freeze; interim runs suppress KO + stats, notifications fire on first detection; three new validate_rule lints (terminal-precondition trap, unknown trigger type, KO-on-interim).
-
-## 2026-08-13 (late evening)
-
-* **Creation**: Added `drift-guards.md` — the fragility-audit follow-up contracts (P5.x + P7): SignalR message-name catalog in `Constants.SignalRMessages`, exported through the shared manifest and typed into the web's `SignalRContext.on/off` union; the `RowKeyCodec` single encoder for inverted-tick RowKeys (persisted widths pinned, incl. UserActivity's legacy D20); `DeletionRowDump.Table` on tombstone rows with `DeletionTombstoneTables.Resolve` replacing the duplicated `Contains('_')` heuristic (legacy fallback retained one retention cycle); the shrink-only `OkAsyncBaselineGuardTests` per-file baseline (44 sites frozen); the Settings per-section PATCH (section field map + diff-based `config/{tenantId}/fields` writes on the TenantAdmin caller tier); and the web's `scopedApi` endpoint-pair builders, single admin-scope hook, `navVisibility` matrix and guard-consistency ratchet.
-
-* **Update**: `versioning.md` — the web portal joins the version contract commit-only: `public/version.json` generated at build time from `GITHUB_SHA`, served with `Cache-Control: no-store`, polled by `deploy-web.yml` until the deployed commit matches before `versions/web.json` is published.
-
-## 2026-08-13 (evening)
-
-* **Creation**: Added `backend/lifecycle-manifests-and-session-scope.md` — the fragility-audit P5/P6 completeness nets: (1) `TableLifecycleBucketTests` classifies every `TableNames` constant into offboarding-wipe / per-session-cascade / kept-by-design (fixed en route: UsageMetrics wiped via the new RowKey-anchored SafeWipe Variant D — the exact-PK wipe matched 0 rows; PlatformStats tenant partition + ScriptNameCache added to the tenant-PK bucket); (2) `SessionIndexFieldManifest` as the declared SessionsIndex column set with bidirectional builder/reader test pinning, Replace-mode full rebuilds, and a fail-soft merge-key guard; (3) `ResolveSessionScopeAsync` as the single session-scope fallback (16 former copies), backed by the new `SessionTenantLookup` point-read table (scan fallback + self-heal, cascade step before the tombstone), plus the `RecomputeTriggerGate` 403 for reanalyze/rescan by read-only roles; (4) server-side dashboard free-text search (`q=`) with page-backfill loop and fingerprint binding, replacing the client's full-history loadAll sweep.
-
-* **Creation**: Added `backend/app-version-regression-radar.md` — app-version duration regression radar: per (tenant, app) the newest version's median measured install duration (nearest-rank; population Succeeded + non-skip + `HasMeasuredDuration` + no AppId collision + non-empty AppVersion) is compared against the previous version (first-seen ordering, never string sort); fires at median lift ≥2× AND ≥300s absolute with ≥10 measured installs on both sides. Episodes live as `appversionregression|{app}|{version}` tracker rows (one bell `app_version_duration_regression` + one `AppVersionDurationRegression` ops event per episode, refresh keeps `FirstNotifiedAt`, re-arm on drain/median-recovery/30d retention). Surfaces: `versionRegressions[]` + per-version `measuredInstalls`/`medianDurationSeconds`/`p95DurationSeconds` in the apps analytics responses, amber banner + duration-by-version chart on the apps detail page. Kill switch `AppVersionRegressionRadarDisabled`.
-
-## 2026-08-13
-
-* **Update**: `backend/session-annotations.md` — the `/annotations` portal overview page now carries the standard tenant switcher (GA/Reader: "All tenants" aggregate + per-tenant drill-down via `GET global/session-annotations`; delegated: managed subset), with a tenant column and tenant-qualified session deep links. The global list endpoint now derives `excludeGlobalAdminLane` from `HasGlobalScope`, so delegated-rescue callers on their managed `?tenantId=` path never receive the platform-internal `globaladmin` lane (endpoint-test-pinned).
-
-## 2026-08-12
-
-* **Update**: `agent/autopilot-ztd-diagnostics.md` — Windows 365 Cloud PC exception documented: on Cloud PCs `ProfileAvailable=0` is expected (provisioned by the Windows 365 service, not Autopilot), so `autopilot_profile_missing` is emitted as Info with a Cloud-PC-specific message and an `isCloudPc` payload marker (`ResolveAutopilotProfileMissingPresentation`); the portal's Autopilot Profile card renders a neutral note instead of the amber warning for Cloud PC sessions (`session.isCloudPc` or the event marker).
-
-## 2026-08-11 (later)
-
-* **Creation**: Added `backend/session-annotations.md` — session annotations: the new `SessionAnnotations` table (PK=tenantId, RK=`{sessionId}_{lane}`, lanes operator/tenantadmin/globaladmin) storing structured verdicts (`root_cause_confirmed | analysis_wrong | different_problem | inconclusive`) + notes with server-stamped authorship and a fired-rule-id snapshot for join-free rule-quality evaluation. Per-lane write matrix re-gated in-function with own-tenant binding (a GA writes only the platform-internal `globaladmin` lane cross-tenant; tenant callers never see that lane). Surfaces: portal `SessionAnnotationsCard` (session detail, after Analysis), MCP `list_session_annotations` (ga) + `annotate_session` (strictGa, always the GA lane) + `annotations` key in `get_session_summary`. Lifecycle: per-session cascade steps 17–19, offboarding wipe, critical-backup member.
-
-## 2026-08-11
-
-* **Update**: `rules/gather-rule-guardrails.md` — hard-block mirroring closed across all pre-flight layers: `rules/guardrails.json` now also mirrors `blockedCommandPatterns` + `maxCommandLength` and carries `C:\Windows\System32\config` in `blockedFilePrefixes`; portal (`guardValidation.ts`) and MCP (`rule-validation.ts`) apply them in agent order (before the unrestricted-mode early-return), so a command the agent hard-blocks no longer shows "Allowed" in unrestricted tenants. `GuardrailsParityTests` pins the JSON mirror to the C# constants. MCP `validate_rule` additionally validates `json`/`xml` targets with file semantics (the schema's `collectorType` enum was missing both) and rejects `activePhases`+`activeFromPhase` set together (backend 400 parity). Author stamping extended to PUT-upserts: tenant and global gather-rule updates stamp the caller's JWT display name before the service call, so an upsert of a non-existing ruleId can no longer store a payload-supplied author (true updates still preserve the original author).
-
-## 2026-08-10
-
-* **Update**: `rules/gather-rule-guardrails.md` — WMI matcher generalized from literal prefix matching to shape parsing: `SELECT <* | property-list> FROM <class>` is allowed when the class is derived from the existing `SELECT * FROM <class>` entries (a projection is a strict subset; motivated by `SELECT BatteryStatus FROM Win32_Battery` + `on_change` battery polling that `SELECT *` defeats via fluctuating charge %). Same algorithm mirrored agent/portal/MCP; guardrails.json unchanged. Portal now also gates enabling on the client-side validation (invalid-target custom rules create disabled, cannot be toggled on, force-disable on invalid edit, "Blocked on devices" badge) — UX only, the agent guard stays the boundary. Gather-rule Author is now stamped from the creator's JWT (display name → UPN) at create and immutable on update.
-
-* **New**: `agent/continue-anyway-observation.md` — Continue-Anyway observation mode (`EnableEspContinueAnywayObservation`, ConfigVersion 37, operator-set): Device-phase ESP terminal failures on Continue-Anyway profiles are defanged into a 60-min observation window (Classic/Unknown, non-pre-prov only); real-user desktop + Hello gate complete the session as Succeeded + `EspSoftFailure`/`CompletionSource` (amber "with issues" badge + detail banner), category recovery resolves clean, expiry un-defangs to the original `esp_terminal_failure`. Registered in the Agent index section. Related backend fix (no doc): the auto-analyze enqueue now carries a 30 s `visibilityTimeout` so rule evaluation no longer races the agent's terminal flush (ANALYZE-ESP-004's `{{appName}}` placeholder).
-
-## 2026-08-07 (later)
-
-* **Update**: `backend/cloudpc-device-validation.md` — third `IsCloudPc` transport rail: the pre-auth distress channel. `DistressReport.IsCloudPc` (CloudPcDetector verdict captured at `DistressReporter` construction) → `DistressReportEntry`/table column → "Devices Not Registered" aggregation (sticky-true per serial, same OR semantics as the Sessions merge) → portal Cloud PC badge + actionable hint ("enable Windows 365 Cloud PC Validation + W365CloudPcValidation add-on"). Motivated by the first W365 field run: the rejected Cloud PC showed up as anonymous "Microsoft Corporation / Virtual Machine" with no clue that the fix is the Cloud PC validator, not Autopilot registration. UNVERIFIED like all distress fields; ≤18 bytes, fits the 1536-byte cap.
-
-## 2026-08-07
-
-* **Update**: `backend/cloudpc-device-validation.md` — the "deliberately out of scope" follow-up landed in the same PR: agent-side `IsCloudPc` flag (`CloudPcDetector`, bootstrap-verified marker AND: Windows365 key + CloudManagedDesktopExtension service key, SKIP-safe) rides two rails — `SessionRegistration` → Sessions/Index (sticky-true) → `SessionSummary` + `isCloudPc` search filter (portal/raw/MCP), and the `EnrollmentFactsObserved` payload → `EnrollmentScenarioObservations.CloudPc` (set-once, both values) with profile reason `cloud_pc_first_connect:no_device_esp_expected` + `cloud_pc_marker` in the audit-trail census. Reason+observation only: no completion arm depends on DeviceSetup, Mode stays AccountSetup/IME-classified, EspConfig keeps configured-FirstSync semantics. Never an auth input.
-
-## 2026-08-06
-
-* **Creation**: Added `backend/cloudpc-device-validation.md` — the CloudPc fallback validator (`ValidatorType.CloudPc = 5`, tenant flag `ValidateCloudPcDevice`): W365 Cloud PCs are structurally never Autopilot-registered, so stage 4 gains a third stage that binds the chain-validated MDM cert's Subject CN (= Intune device id, field-verified on a real Cloud PC) to the tenant's `virtualEndpoint/cloudPCs` inventory — admits exactly the service-provisioned Cloud PCs, no device-type routing, local W365 markers never consulted for auth. New optional Graph add-on `W365CloudPcValidation` → `CloudPC.Read.All` (catalog + grant script now pinned by `GraphFeatureCatalogSyncTests`; Graph 403 = definitive "grant missing", not transient). Bootstrap dev script v2.3-dev.3 exempts guard 4 (uptime) while the Cloud-PC relax is active — the fresh-profile window is the time anchor at first connect, not boot uptime. Follow-up deliberately out of scope: agent-side `IsCloudPc` classification + decision-engine "no Device ESP" expectation.
-
-## 2026-08-05 (later)
-
-* **Update**: `rules/rule-authoring-surface.md` — new section `POST /api/rules/gather/test-pattern`: the logparser pattern tester (agent-exact .NET matching: no IgnoreCase, first-match-per-line, cmtrace vs text mode, verbatim format=text hint), motivated by a field incident where a PHP-verified regex behaved differently under .NET. `CmTraceLogParser` moved Agent → `AutopilotMonitor.Shared.Logging` so agent and backend share the ONE parsing implementation (timestamp caveat: AssumeLocal = server TZ on backend, endpoint reports no timestamps). MCP: new `test_log_pattern` tool, logparser lint in `validate_rule`, guide gains the case-sensitivity/engine-mismatch pitfalls.
-
-## 2026-08-05
-
-* **Creation**: Added `mcp/tool-telemetry.md` — the three MCP tool-telemetry layers (App Insights `McpToolName`, per-user usage table, `MCP_TOOL_LOGGING` stderr lines) and the new quality signals: soft-error capture (`toolError` returns instead of throwing, so backend telemetry counted those calls as successes), `resultChars`/`overCap` vs. the inline-size hint, bounded args summaries, caller scope, `search_zero_hit` on the three search tools (unmet-demand signal), and `tool_call_rejected` for JSON-RPC-level Zod/unknown-tool rejections sniffed at the `/mcp` route (previously invisible everywhere). Bicep default for `toolLoggingEnabled` flipped to `true` (documented desired state; live flag set via `az containerapp update`).
-* **Creation**: Added `rules/rule-authoring-surface.md` — the AI-assisted rule-authoring stack: three deterministic MCP resources (`rule_authoring_guide` hand-written, `rule_schemas` + `rule_guardrails` generated into `rule-authoring.generated.ts` by a new combine.js emitter, drift-guarded twice), the MCP-local `validate_rule` (ajv 2020-12 against the single-rule $defs, guardrail pre-flight mirroring GatherRuleGuards matching semantics incl. hard blocks, semantic lint for schema-valid-but-dead rules), and the side-effect-free `POST /api/rules/analyze/dryrun` (TenantAdminOrGlobalReader; `RuleEngine.DryRun.cs` trace twin sharing the production evaluators, all-conditions trace with per-condition evidence + matchingEventCount, parity and side-effect-freedom pinned by RuleEngineDryRunTests). MCP `test_analyze_rule` wraps the endpoint with `{{token}}`-interpolated previews; `author-rule` prompt drives the draft → validate → dry-run loop. Deliberately absent: gather-rule remote execution, rule writes via MCP.
-
-## 2026-08-04
-
-* **Update**: `rules/gather-rule-phase-scoping.md` — new section "Which phase feeds the triggers": `GatherRuleExecutorHost` now drives `phase_change`/`phase_exit`/`on_event` gather triggers (and the phase-scope gates) from the post-reduce `TimelineEventStream` (every emitted event's `(eventType, phase)` published by `EventTimelineEmitter`) instead of the pre-reduce `SignalIngress.SignalPosted` payloads. Trigger: session `32312a32` (RealmJoin tenant rsneuffen.de) — a Phase-Start rule on FinalizingSetup fired at the raw ESP-exit `EspPhaseChanged(FinalizingSetup)` signal, 7 minutes before the engine's RealmJoin-gated `phase_transition(FinalizingSetup)`, reading `HKLM\SOFTWARE\RealmJoin\Custom\BIOS` before the RealmJoin package created it. Phase triggers now fire exactly when the timeline shows the phase; `on_event` additionally sees engine-emitted event types (`enrollment_complete`, `realmjoin_resolved`, …) for the first time in V2, restoring V1 semantics and the documented end-of-enrollment pattern. Other raw-signal hosts (DeviceInfo, keep-awake, PPKG) deliberately unchanged.
-
-## 2026-08-02
-
-* **Creation**: Added `backend/tenant-activation-welcome-mail.md` — triggered by the first production auto-approve (activation at signup+64 s, notification address saved at +69 s → welcome mail silently skipped, since the approval path is the only sender and reads the address once). Fix documented in the doc: the notification-email save path now also triggers the send (`PUT /api/preview/notification-email` → fresh approval check `IsApprovedFreshAsync`, bypassing the 30 s negative cache), and a conditional-insert `welcome-email-sent` marker in `PreviewWhitelist` makes the send once-only across both racing paths (marker consumed strictly after the address check; revoke clears it, offboarding wipes the partition, the GA resend endpoint sends unconditionally and consumes it best-effort).
-
-## 2026-07-29
-
-* **Update**: `agent/gather-rule-debug-log.md` — three trace enrichments: (1) new `phase` stage writing an enrollment-phase transition marker (`phase change: Old -> New`, ruleId `-`) so every rule-level line reads against the current phase; (2) logparser now writes one line per regex match — line number, matched text, capture groups — capped at 10 per file per run (the per-file summary keeps the full count); (3) the invalid-regex `error` line includes the offending pattern string.
-
-* **Update**: `url-registry.md` (+ `web/portal-navigation-prefetch.md` context) — the portal is now a **full static export** (`output: 'export'`, `trailingSlash: true`): the SWA serves plain files, the managed SSR runtime — the portal's last cold-start source ("Backend call failure" > 45 s) — no longer exists. Detail routes moved from path params to query strings (`/sessions?id=`, `/sessions/inspector?id=`, `/diagnosis?id=`, `/apps/detail?name=`, `/admin/backups/detail?id=`, `/admin/customs-archive/detail?tenantId=&rowKey=`) with all 21 link sites going through the new single-definition builders in `lib/routes.ts`; the 9 `[section]` families prerender via `generateStaticParams` server shells (37 pages, `dynamicParams=false`), server `redirect()` index pages became `ClientRedirect` shells. Legacy PATH-shaped deep links (sent Teams/Slack/webhook notifications hold `/sessions/{id}` forever) are preserved permanently: SWA wildcard rewrites serve the family page and the globally mounted `LegacyPathRedirect` rewrites to the canonical query URL (hash + query preserved; mapping pinned by `lib/__tests__/legacyPathRedirect.test.ts`). `middleware.ts` host routing became the client-side `HostRoutingGuard` (prefix list moved to `lib/hostRouting.ts`); the legacy `/go/[code]` route + `bootstrapValidation.ts` are deleted (BootstrapSessions table verified free of pre-cutover active sessions). `staticwebapp.config.json` now carries the 19 docs/marketing redirects (order-sensitive), the legacy rewrites, `404.html` override and ALL security headers incl. the literalized prod CSP — guarded by the new `swaConfig.guard.test.ts`; maintenance mode changed from whole-file swap to a first-routes-entry insert (README rewritten). Backend notification deep links go through the new `Constants.PortalSessionUrl` (query shape, pinned). Deploy: `deploy-web.yml` uploads `out/` with `is_static_export: true`.
-
-* **Creation**: Added `backend/oobe-bootstrap-go-flow.md` (and a `Bootstrap go-URL` section + web-registry update in `url-registry.md`) — the OOBE bootstrap script endpoint moved from the portal's Next.js `/go/[code]` SSR route into the Function App (`GET /api/bootstrap/go/{code}`, `GetBootstrapScriptFunction`), unblocking the portal's static export; the customer URL became **`go.autopilotmonitor.com/{code}`** (Front Door custom domain, `/*` route with origin-path rewrite, caching disabled — the script inlines the bearer token). New `Constants.BootstrapGoBaseUrl` (single producer via `CreateBootstrapSessionFunction`) + web `BOOTSTRAP_GO_URL` (display only); both guard host lists extended. Security invariants ported to C#: `BootstrapScriptValueValidator` (exact-GUID tenantId/token, https + host-allowlist + `/agent/….zip` path, expiry ≤ 14 d) and `OobeBootstrapScriptGenerator` (Replace-token raw-string template, single-quoted PS literals, 200-char error cap before quote-doubling; always-HTTP-200 text/plain contract for `irm | iex`). Endpoint is `PublicAnonymous` in the catalog, `NoStoreCacheMiddleware`-covered, self-rate-limited `bootstrap-script:{ip}` 20/min (rate-limit reply is also a 200 error script). Tests: golden byte-parity against the TS template, validator invariants incl. hostile-URL cases, format-gate table, and the previously missing BootstrapUrl shape pin. Transition: the legacy www route + `middleware.ts` `/go` prefix stay alive for pre-migration URLs (validity ≤ 168 h) and are removed in the static-export PR no earlier than 168 h after the last www URL was issued. Customer docs `network-endpoints.md` gained the `go.` host (device-facing, Bootstrap-Sessions-only).
-
-* **Update**: `agent/autopilot-ztd-diagnostics.md` — presentation layer for the startup error backfill (customer feedback: an unannounced wall of pre-agent Error events with a single identical timestamp read like a live failure). Agent: the backfill scan now buffers the capped record set, emits an Info summary event first (`modern_deployment_log`, `backfillSummary: true` + `replayedCount`/`droppedOverCap`/`lookbackMinutes`), then replays oldest-first so the timeline sequence follows event-log chronology. Web: `EventTimeline.tsx` badges `backfilled: true` events („⟲ Backfilled", tooltip) and renders the original `timeCreated` as the row time with a "(reported …)" suffix plus a `Recorded` metadata line — works retroactively for already-stored events. Severity is deliberately not downgraded.
-
-* **Creation**: Added `agent/gather-rule-debug-log.md` — the new per-tenant setting `EnableGatherRuleDebugLog` (ConfigVersion 35 → 36, portal toggle under Settings → Agent, `EnableImeMatchLog`-style bool→path projection in `RemoteConfigMerger`). When enabled, the agent writes `%ProgramData%\AutopilotMonitor\Logs\gather_rules_debug.log`: one pipe-delimited line per evaluation decision across ten previously silent "produced nothing" exits — disabled rules, `interval` without `intervalSeconds` (never runs), the first-tick-after-one-full-interval window, phase-scope skips incl. `currentPhase=Unknown`, per-(rule, phase) dedup, empty collector results (`emitOnlyIfExists`), `on_change` hash suppression (hash prefix + streak), guard blocks, logparser per-file outcomes (position skips, parse failures with a `format=text` hint when every line fails CMTrace parsing, `maxLines`/wildcard caps), and full exception stacks that the agent log drops. 10 MB cap + one `.old` generation; no hot-reload (per-enrollment lifecycle); flag survives the offline config cache; `--run-gather-rules` always traces and echoes under `--console`; zero-rules delivery leaves a one-line file instead of nothing. Side fix: `GatherRuleExecutorHost` now passes the logger into `InformationalEventPost`, so gather-event emissions appear in the agent DEBUG log.
-
-* **Correction + Update**: `web/portal-navigation-prefetch.md`. The HTTP/1.1 claim in the 2026-07-27 entry below is **wrong** and has been struck from the document: `portal.autopilotmonitor.com` negotiates **h2**, verified by `openssl s_client -alpn h2,http/1.1` and a .NET `HttpClient` returning `HTTP/2.0`. The false reading came from the Windows/Schannel curl build in this environment, which has no HTTP/2 support and therefore always reports `1.1` — do not use it to determine HTTP versions. There is no six-connection cap in play; the queue is server-side in the SWA SSR runtime, which does not change the fix or the evidence, only the mechanism. Added an `Outcome` section with 20 h of post-change telemetry: the Free → Standard plan change (16:02:44 UTC) produced **no measurable latency gain** once stratified by the gap to the previous request (p50 Free → Standard: `<10s` 85 → 95 ms, `5-30min` 429 → 441 ms; tail rates 1.64 %/0.374 % over 2 s/10 s vs 6 and 1 events at n = 258 against 4.2 and 1.0 expected; `browserTimings` Mann-Whitney z = −0.24, p = 0.81). The freezes were removed by `prefetch={false}` (16:34:13 UTC): worst `browserTimings.totalDuration` 225,277 → 4,856 ms. The prefetch storm was also an **accidental keep-alive** — requests under 10 s apart fell from 85 % to 46 %, and on the identical never-cacheable `/sessions/{id}` route the median rose 87 → 211 ms and p90 465 → 1,480 ms, with one 11,441 ms abandoned request (`resultCode 0`) after 517 minutes idle. Synthetic bursts warm the runtime and must not be used to benchmark this (round 1 p50 288 ms vs rounds 4–25 p50 113 ms).
-
-## 2026-07-27
-
-* **Creation**: Added `web/portal-navigation-prefetch.md` (and a `Web Portal` section to the index) — root cause of the minute-long portal freezes. `GlobalSidebar` and `Navbar` render the whole navigation on every page, so the App Router's default viewport prefetch issued one `?_rsc=` request per visible link against `portal.autopilotmonitor.com` (~10,400 in 14 days). *(The original entry attributed the freeze to HTTP/1.1 and a six-connection-per-origin cap — see the 2026-07-28 correction; the queue is server-side.)* When the Static Web Apps managed runtime queued the prefetches (p50 91 ms, p95 896 ms, but max 234 s / 21 samples over 30 s), the navigation the user wanted was stuck behind that queue. Measured on the 2026-07-27 17:25 CEST incident: `/admin/presence?_rsc=` 151 s, three siblings finishing within 340 ms of each other at ~37.5 s, all `200`, while the backend API answered in 1.6–2.2 s and `browserTimings` showed `networkDuration` 16 ms against `processingDuration` 225 s. Every navigation Link now sets `prefetch={false}` — these routes are client components behind `ProtectedRoute` that fetch their own data, so the prefetched RSC payload carried no benefit. The doc also records that browser telemetry lives in a **separate** App Insights resource (`AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`) that the MCP `query_backend_logs` tool cannot reach, which is why the freezes left no trace in the backend logs.
-
-* **Creation**: Added `backend/rule-regression-radar.md` — F3 regression radar (analyze rules only; gather rules wait for their per-batch stats dedup fix): per (tenant, rule) daily hit rate from `RuleStats`, firing only when the trailing 7-day window has ≥5 hit sessions and ≥20 evaluated sessions, the rate is ≥2× the prior 28-day baseline AND the Wilson 95 % intervals are disjoint (deterministic `MetricsMath` primitive with hand-computed test vectors). Suppressed for deleted rules, rules younger than baseline+window (`CreatedAt` grace), rules edited inside the window (`UpdatedAt`), empty baselines, and the `RuleRegressionRadarDisabled` app-setting kill switch. Alert episodes live as `ruleregression|{ruleId}` tracker rows (one bell + one `RuleFrequencyRegression` ops event per episode; numbers refreshed while active; re-armed under 1.5× baseline, on fire-stop, or by the 30-day tracker retention). On-fire dimension correlation over osBuild/model/agentVersion/imeVersion with the "correlated, not necessarily causal" wording contract. Surfaces: `regressions[]` in the rule-stats response (MCP inherits), the analyze-rules page's 30-day sparkline and regression badge.
-
-* **Creation**: Added `backend/device-journeys.md` — F2 device history / First-Time-Right: the device key (trim + case-fold serial, junk/placeholder exclusion incl. the agent's `Unknown` WMI sentinel), journey grouping over the terminal set Succeeded/Failed/Incomplete (first success ends a journey, a >30-day gap from the previous attempt's CompletedAt starts one, WhiteGlove's single session row is ONE attempt, open sessions are never attempts), the `DeviceHistories` chain (cap 20, written inline at the terminal seam, healed by the sweep, deleted-session refs pruned tombstone-driven, deliberately not in the per-session deletion manifest) and the additive `DeviceJourneyAggregates` daily rows (window rate = ratio of sums — no rolling row needed, 180-day retention). Surfaces: the session-detail "Attempt N" banner with server-computed attempt numbers (virtual-attempt rule for live sessions), the Fleet Health First-time-right section (≥20-journey gate, attempt histogram, repeat-devices violator list), and the MCP `get_device_history` tool (serial mode / fleet FTR mode).
-
-## 2026-07-25
-
-* **Update**: `agent/secureboot-ca2023-detection.md` — review follow-up on 90012d9 hardened the privilege scope, the repo's only privilege-adjustment code and therefore the precedent for any future one. The process token moved from a raw `IntPtr` to a `SafeHandle` assigned by the P/Invoke marshaler, so the CLR owns it from the moment `OpenProcessToken` returns and the critical finalizer releases it even when `Dispose` never runs — previously an async exception between the successful open and the caller's `using` leaked the handle *with the privilege enabled and no owner left to restore it*. `Dispose` became idempotent and now releases the handle in a `finally`, so a throwing restore cannot strand it; the restore obligation is recorded immediately after the successful `AdjustTokenPrivileges` with nothing throwable in between. The whole enable → read → restore sequence runs under a static gate because the privilege is adjusted on the *process* token: a concurrent reader would see "already enabled", correctly skip its own restore, and then lose the privilege mid-read when the first reader disposed, reporting `privilege_denied` on a machine that holds it.
-
-## 2026-07-24
-
-* **Creation**: Added `backend/server-actions-on-demand-diagnostics.md` — the ServerAction channel (queue on `Sessions.PendingActionsJson`, deliver piggy-backed on the next ingest response, at-least-once with `Type|RuleId|QueuedAt` dedup and sequential dispatch) and the on-demand log collection built on it: the portal's always-visible **Collect Logs** button, the new `EndpointPolicy.TenantAdminOrOperator` tier with the mandatory in-function per-type re-gate (Operators queue only `request_diagnostics`), the member-readable `diagnosticsUploadConfigured` feature flag, the admin quick-config path that must queue `rotate_config` before `request_diagnostics` (works against the deployed fleet — a one-time override would not, the mode gate is agent-side), sequence-based progress matching immune to agent clock skew, and the offboarding cascade's hosted-prefix sweep closing the latest-wins orphan-blob gap.
-
-* **Update**: `agent/esp-policy-provider-stall.md` — the customer's follow-up on issue #106 corrected the field-case mechanics: `TrackingPoliciesCreated=1` WAS set under the foreign `ConfigMgr` provider, so the ESP ignores a foreign provider's completion values and waits on the Intune-registered `Sidecar` provider by name (the rename to `Sidecar` creates no tracking entries yet unblocks instantly). The completeness-keyed detector would have missed exactly this — the incident it was built for. The tripwire is now two-armed under one event type discriminated by `reason`: `provider_incomplete` (unchanged dwell on continuously-incomplete providers) and `sidecar_provider_missing` (≥ 1 Setup/Apps provider registered without `Sidecar`, completeness deliberately ignored, clock reset when Sidecar registers later). Sidecar-missing wins the `reason` when both arms cross in one round; the cross-restart fingerprint gains a `sidecarMissing` sentinel; payload adds `reason` and `sidecarMissingForMinutes`. Evidence for the name-keyed wait: Niehaus' documented Intune WAP payload always registers `Sidecar` (ConfigMgr only via a co-management settings policy) and Microsoft's ESP troubleshooting models app tracking exclusively through the Sidecar subkey.
-
-* **Creation**: Added `agent/esp-policy-provider-stall.md` — a customer diagnosed that pre-provisioned devices with the ConfigMgr client as a blocking app occasionally park the user ESP at "Apps (Identifying)" for days: only a `ConfigMgr` provider is registered under `EnrollmentStatusTracking\Device\Setup\Apps\PolicyProviders` (no `Sidecar` = IME) and `TrackingPoliciesCreated` never becomes 1 — a wait the CSP defines without any timeout; renaming the key to `Sidecar` unblocks immediately. The agent now ships the always-on `esp_policy_provider_stalled` tripwire (60-s tick, 15-min continuous-incompleteness dwell, one-shot per provider, `StartupEventGate` fingerprint across restarts, purely observational via the InformationalEvent rail — no toggle, no ConfigVersion bump), generalized to any provider in both `Setup/Apps` and `DevicePreparation` kinds rather than hardcoding the ConfigMgr case. Companion change: `SOFTWARE\Microsoft\Windows\Autopilot` joins the gather-rule registry allowlist so tenants can target the subtree with custom rules (e.g. `not_exists` on the Sidecar key).
-
-* **Creation**: Added `agent/secureboot-ca2023-detection.md` — ANALYZE-SEC-001 warned on devices whose firmware already carried the 2023 certificate, because the agent only read the `SecureBoot\Servicing\UEFICA2023Status` registry value, which mirrors the Windows Update rollout rather than the firmware (customer report). The agent now reads the UEFI `db`/`KEK` variables natively (`GetFirmwareEnvironmentVariableExW` with `SeSystemEnvironmentPrivilege` enabled on the process token — first privilege-adjustment code in the repo) and emits per-certificate booleans on `secureboot_status`. Suppression rides on a one-sided marker, `uefiCa2023FirmwareConfirmed`, emitted only on positive confirmation: the engine's `not_exists` precondition fails on any present value, so a two-sided boolean could not distinguish "confirmed" from "checked and missing", while the marker's absence keeps old agents and firmware-missing devices on the v2 path. Rule v3.0.0 is therefore safe to seed before the agent release.
-
-* **Update**: `url-registry.md` — the first release after the alias migration surfaced Front Door caching as a correctness hazard: the alias served the previous `version.json` (`X-Cache: TCP_REMOTE_HIT`) after the origin had rotated, and since manifest and ZIP are independent cache entries, a stale manifest with a fresh ZIP fails the bootstrap SHA-256 check. Route caching on `/agent/*` is now disabled and every blob upload stamps `Cache-Control: no-cache` (CI `Send-Blob`, local `build.ps1`, `versions/*.json` manifests) — all agent-container blobs rotate in place, so nothing there is safely cacheable.
-
-* **Update**: `agent/decision-engine.md` — the RealmJoin completion gate has a third terminal, `FirstDeploymentIncomplete`. Session 224b2087 showed why: an interactive logon 17 s after DeploymentPhase 101 makes RealmJoin reclassify the run as a secondary-user deployment, whose branch writes 200/210 and never 110 — the gate stayed closed until the 60-min hard timeout although Hello and desktop were long resolved. `realmjoin_phase_changed` is now a typed `RealmJoinPhaseChanged` signal, so `RealmJoinFacts.LastDeploymentPhase` is persisted across agent restarts (this also fixes every `realmjoin_timeout` event claiming "last phase: 0"); a transition out of 100/101 into 200/210 releases the gate with the `realmjoin_first_deployment_incomplete` Warning, and the `RealmJoinDetected` replay path evaluates the same rule for restarts that swallow the transition. A first observation of 210 deliberately does not release — session 6f1959c0 started at 210 and only deployed afterwards.
-
-* **Creation**: Added `url-registry.md` — all well-known hosts (own subdomains, both blob accounts, API origin, Graph, Entra login) are now defined once per component (`Constants.cs`, web `utils/config.ts`, MCP `src/config.ts`) and referenced everywhere else; three guard tests fail the build on any literal outside the registries. Written because the EU cutover missed two hardcoded copies of the legacy blob host — `LatestVersionsService` (feeds the portal's version badge) and `ValidateBootstrapCodeFunction` — which kept working only through the fail-soft legacy mirror in `build-agent.yml`; those two plus the agent `SelfUpdater` now use the `download.autopilotmonitor.com` alias (verified serving all four artifacts first). The portal's bootstrap allow-list accepts alias AND legacy host during the transition, which imposes a deploy order: web before (or with) backend. The sweep also surfaced a fourth copy of the www/portal host pair in `middleware.ts` (now derived from the registry via `hostRouting.ts`) and a backend short-link built on the bare apex domain, which only worked through a registrar-level 301.
-
-## 2026-07-22
-
-* **Creation**: Added `versioning.md` — agent, backend and MCP now share one version shape (`<major>.<minor>.<build>` + 7-char commit + build timestamp) and one implementation of the build-number reservation (`.github/scripts/Request-BuildNumber.ps1`, previously copy-pasted between `build-agent.yml` and `build.ps1`). The backend had been pinned at a hand-written `1.0.0` since inception and now starts at `1.5.1000`; the MCP server's `package.json` version was bumped by hand and now starts at `1.5.300`, and it reports its own commit on `/health` instead of only the documentation bundle's. Both deploy workflows poll their health endpoint until it reports the build just deployed and publish `versions/<component>.json` only then, so a manifest that disagrees with the live endpoint means the instance drifted rather than the pipeline failing halfway. `agent/build-counter-blob.md` keeps the agent-specific parts and now points at the shared protocol; its counter URL was still the pre-cutover storage account.
-
-* **Creation**: Added `rules/gather-rule-guardrails.md` — the gather-rule allowlists are enforced only on the agent (the backend validates no `collectorType`, `target`, or `parameters`), so a collector that forgets to call its guard *is* the vulnerability. Written because two had: `LogParserCollector` read any path in `rule.Target`, bypassing even the `C:\Users` hard block that every other file collector honours, and `EventLogCollector` read any channel including `Security` — while the customer-facing documentation already promised both were allowlisted. Both now guard, with `logparser` checking the directory for wildcard targets (`Path.GetFullPath` throws on `*`) and re-checking each resolved path. Added an event-log channel allowlist (`eventLogChannels`) plus hard-blocked channels held in C# rather than JSON, so a parse error cannot lift them. Also fixed the command timeout, which was inert: `ReadToEnd()` blocks until the pipe closes, so `WaitForExit(30000)` was only reached after the process had already exited and a hung command pinned its worker forever — now read asynchronously and killed at the timeout.
-
-* **Update**: Added `.github/workflows/ci.yml` — the full suite (backend, agent V2 Core, DecisionCore, SummaryDialog, web, MCP) now runs on every pull request and every push to main, plus a job that fails if the generated guardrail files drift from `rules/guardrails.json`. Previously **no** workflow ran tests on a PR: the deploy workflows build without testing, and `build-agent.yml` tested only `DecisionCore.Tests` on manual dispatch — while `trust/security-faq.md` already told customers that automated tests run in CI. Added CodeQL (C# and TypeScript) and Dependabot (nuget, npm ×2, actions). Marked `OfficeBinaryWatcherTests` `[Collection("SerialThreading")]`: its bounded re-probe races the shared ThreadPool and failed once under full-suite load.
-
-## 2026-07-21
-
-* **Update**: `search_docs` and `search_knowledge` now state in their tool descriptions that queries must be in English. Both corpora and `all-MiniLM-L6-v2` are English-only, and the failure is total rather than gradual — a German question returns zero results, not weak ones. The caller is a language model, so translating the question before the call and answering in the user's language costs nothing; a multilingual embedding model would be the alternative but is much larger and would have to be measured against the eval harness first, since it changes English retrieval too.
-
-* **Update**: Added `scripts/eval-docs-search.ts`, an offline retrieval evaluation harness (2465 queries in three classes: chunk headings as a regression detector, rare identifiers, and hand-written questions as the reality anchor), and used it to close a third `search_docs` gap found during the live test. The keyword fallback only fired when semantic search returned *fewer* than `topK`; a pasted identifier like `WOW6432Node` instead returned three chunks at ~0.29 that did not contain the word while the one chunk that did was never considered. It now also fires on a weak semantic head (<0.35), letting exact matches take the front while keeping one semantic result. The threshold is measured, not guessed: 0.35 fixes 335 queries and breaks 0 (identifier recall 66.2% → 81.1%), while 0.40 fixes more but starts demoting hand-written questions. The measurement also resized the problem — identifier queries were only succeeding 66.2% of the time, so the reported case was one of roughly 750.
-
-* **Update**: Closed the two measured recall gaps in `search_docs` (`mcp/docs-corpus.md`). (1) **Token windows** — 87 of 324 chunks exceeded the model's 256-token context and 13% of all tokens never reached the ranking; a character budget cannot fix this (the corpus ranges 2.43–5.81 chars/token), so long text is now embedded as 250-token windows with 40 overlap and scored by its BEST window (`embeddings: number[][]`, max not mean). Token coverage 87% → 100%; "proxy configuration blocking app downloads" went from absent to 0.559 at rank 1; the ten reference queries kept byte-identical scores. Costs +31% vectors, index 2.63 → 3.12 MB. The rules corpus gained the same treatment (128 rules → 172 vectors). (2) **Keyword fallback** — when the semantic pass returns fewer than `topK`, results are topped up via literal `lexicalMatch` on distinctive query terms, requiring two matching terms for corroboration (one incidental substring match returned a page about LLM providers for a sourdough query). Fuzzy matching was measured and rejected: at a threshold low enough to surface "RealmJoin" it invents 5 hits for "SCEPman", which the corpus never mentions. Also sharpened the tool description with the measured context argument for preferring it over fetching the docs site.
-
-* **Creation**: Added `mcp/docs-corpus.md` (new `mcp/` section) — the MCP server gains `search_docs`, a third semantic corpus built from the published customer documentation repository (`autopilotmonitor-docs`, checked out into the Docker build context by the deploy workflow). Documents the h2/h3 + `<details>` chunking with breadcrumb prefixes, the two deliberate size exceptions (tables never split, unbroken changelog lists split at line level), the CRLF precondition (`.` does not match `\r` in JS — headings silently stop matching, which produced 286 wrong-but-plausible chunks before it was found), the optional `docs` section in `search-index.json` and its validation asymmetry, embedding rounding to 6 decimals, and the cross-repo coupling: a docs edit reaches clients only after an MCP redeploy, made checkable via `DOCS_COMMIT` on `/health`. Container resources raised to 0.5 vCPU / 1.0 GiB for the cold-start query-embedder load.
-
-## 2026-07-20
-
-* **Update**: `rules/gather-rule-phase-scoping.md` — the gather-rule form now shows the phase-scope and emit-mode controls only where they can change behavior (`supportsPhaseScope` / `supportsEmitMode`), nulls hidden-control state out of the payload, and rejects a scope mode selected but left unfilled. Offering all three "when" controls unconditionally allowed combinations that could only suppress a one-shot rule, plus a silent no-op state.
-* **Update**: Extended `rules/gather-rule-phase-scoping.md` with the `phase_exit` trigger — the closing bookend to `phase_change`, for one-shot collection when a phase is LEFT (e.g. "state at the end of Account Setup"). Documents the evaluation-before-phase-advance rule (triggerPhase match and scope gate see the phase being left), firing into `Failed`, the disjoint `exit:` dedup key space, and why no ConfigVersion bump is needed (no new field — old agents simply never fire the rule).
-* **Update**: Reworked `agent/mdm-reboot-coalescing.md` after the first real enrollment (session b2e890c1): 2800 records are now **aggregated per burst** into ONE neutral Info event (`rebootUris[]`/`uriCount`/`firstRebootUri`; watermark persisted at flush so a pre-emit reboot kill loses nothing); the raw event no longer claims a reboot — ANALYZE-ESP-005 is gated on an actually-observed `system_reboot_detected`. **Removed** the Shell-Core `esp_reboot_coalescing` event entirely: the "RebootCoalescing" token appears in the routine `SubcategoryProcessing_Started` bootstrap marker on every enrollment (false positive by construction). Verified 2800 description shape recorded.
-* **Creation**: Added `agent/mdm-reboot-coalescing.md` — the agent now attributes the "unexpected mid-ESP reboot + second sign-in" pattern (PMPC research) to the device-assigned policy URIs that forced it: new `MdmRebootPolicyTracker` (DM-Enterprise EventID 2800, per-URI `mdm_policy_reboot_required` events, cross-restart RecordId watermark), a `RebootCoalescing` branch in `ShellCoreTracker` (`esp_reboot_coalescing`, backfill-emitting by design), and the `ANALYZE-ESP-005` advisory (reassign device → user groups). ConfigVersion 35; event types deliberately distinct from `system_reboot_detected` so RebootCount stays uninflated.
-
-* **Creation**: Added `backend/business-timestamps.md` (new `backend/` section) — the 2026-07-18 migration reset every row's system Timestamp, exposing that AuditLogs/OpsEvents/Events had (unknowingly) displayed and filtered on it all along; documents the `OccurredUtc` column, the RowKey decoders and RowKey-range date/retention clauses in `BusinessTimestamp`, the GUID-guard trap, the audit/ops backfill endpoint, and the "system Timestamp is never authoritative" migration rule.
-* **Creation**: Added `rules/gather-rule-phase-scoping.md` (new `rules/` section) — gather rules gain `activePhases` (run only during listed phases), `activeFromPhase` (sticky latch from a phase onwards, never via Failed) and `emitMode: "on_change"` (canonical-hash result dedup with `suppressedPolls` observability), ConfigVersion 34. Includes the prerequisite backend fix: the custom-rule toggle PUT no longer wipes the stored rule definition (partial-merge in `GatherRuleService.UpdateRuleAsync`).
-
-## 2026-07-18
-
-* **Creation**: Added `agent/endpoint-migration.md` — config-channel agent re-home (`MigrateToApiBaseUrl` on `GET agent/config`, ConfigVersion 33): backend or per-tenant API-URL moves without DNS indirection (impossible due to mTLS/Flex-TLS). Live-fetch-only with cache strip, `AgentEndpointMigrationRules` allowlist validated on both sides, one hop, kill-switch wins. Built as the lesson from the 2026-07-18 WEU→GWC cutover, which hard-cut all in-flight agents.
-
-## 2026-07-26
-
-* **Creation**: Added `backend/time-attribution.md` — the F1 enrollment time attribution: exact-partition invariant against the session's authoritative DurationSeconds, two-window WhiteGlove model, segment mapping from phase-declaration events, positive-evidence ESP-blocking join with "up to" what-if bounds, reboot spans from event gaps around `lastBootUtc`, and the SessionTimeBreakdowns / TimeAttributionAggregates tables with their terminal-seam + maintenance-sweep compute paths and read surfaces (web lane, fleet panel, MCP `get_time_attribution`).
-
-## 2026-07-17
-
-* **Creation**: Added `agent/build-counter-blob.md` — agent build numbers now come from a shared public counter blob (`buildcounter-v{N}.txt`, reserve-before-build with ETag-CAS) so local `build.ps1` and CI `build-agent.yml` builds can never mint the same number. Documents the CI parity fixes (SummaryDialog.exe.config in the ZIP, EXE-vs-manifest version check, hash-oracle update gated on stable cutover) and the Sigstore provenance attestation on CI-built ZIPs.
-
-## 2026-07-16
-
-* **Creation**: Added `agent/autopilot-ztd-diagnostics.md` — reference for Windows' own ZTD diagnostic surfaces (ModernDeployment Autopilot event IDs incl. 807/809/815/908, the `Diagnostics\Autopilot` registry key, deployment-service endpoints, known-issue error-code map with KB fixes). Backs the agent's `ZtdEvidence` collector (`ztdVerdict` on `autopilot_profile_missing`) and the backend known-issue rules; sources carry a re-check RSS feed.
-
-## 2026-07-13
-
-* **Removal**: Moved `customer-graph-add-on-permissions.md` out of this contributor bundle into the customer documentation repository (`reference/optional-graph-permissions.md`). It was customer-facing product content and did not belong in the tech-docs bundle; removed the entry from `index.md`.
-
-* **Creation**: Added `agent/hello-wizard-unskip.md` — session 772fe502 fix: the `HelloWizardStarted` decision signal (prevention veto + un-skip cure for the policy-disabled Hello shortcut) and the HelloTracker confirmation second read against flip-flopping WHfB CSP values.
-
-## 2026-07-11
-
-* **Creation**: Added the `agent/` section — three concept documents on the V2 agent: `agent/overview.md` (runtime, collectors, telemetry pipeline), `agent/decision-engine.md` (DecisionCore reducer, signals, A/B/C completion arms, invariants), `agent/logs-and-persistence.md` (persisted artifacts, signal log vs spool, recovery/replay flow) plus `agent/index.md`.
-
-* **Creation**: Converted `docs/` into an OKF v0.1 knowledge bundle — added YAML frontmatter to `architecture.md`, `mcp-oauth-flow.md`, and `customer-graph-add-on-permissions.md`; created `index.md` and this log.
@@ -1,126 +0,0 @@
---
-type: Reference
-title: MCP OAuth Flow — Who Authenticates Where
-description: How the two unrelated identities (AI-product account vs. Entra ID work account) and three parties interact when connecting an AI client to the Autopilot Monitor MCP server.
-resource: /src/McpServer/autopilot-monitor-mcp/src/oauth.ts
-tags:
-  - mcp
-  - oauth
-  - entra-id
-  - security
-timestamp: 2026-07-11T10:59:31+02:00
---
-
-# MCP OAuth Flow — Who Authenticates Where
-
-**Status:** Reference · **Owner:** MCP Server · **Code:** [`src/McpServer/autopilot-monitor-mcp/src/oauth.ts`](../../src/McpServer/autopilot-monitor-mcp/src/oauth.ts)
-
-## Why this document exists
-
-Connecting an AI client (Claude Desktop, claude.ai, VS Code, ChatGPT) to the
-Autopilot Monitor MCP server involves **two unrelated identities** and **three
-parties plus Entra ID**. This regularly confuses users during setup, because
-the account signed in to the AI product and the account used for Autopilot
-Monitor are usually different people-in-one: e.g. **Luke** uses his normal
-account `luke` for his Claude subscription, but his admin account `adm.luke`
-for Autopilot Monitor.
-
-The two identities never mix:
-
-* **`luke` (AI-product account)** — only authenticates Luke against Claude
-  itself. Anthropic needs it to associate the OAuth callback with the right
-  Claude user and connector. The MCP server never sees this identity.
-* **`adm.luke` (Entra ID work account)** — the identity *inside* the token.
-  Every MCP tool call is authorized as `adm.luke`; roles and tenant scope
-  derive from it. Anthropic never sees this password, only the issued tokens.
-
-## The parties
-
-1. **AI client + its backend** (e.g. Claude Desktop + claude.ai) — the OAuth
-   *client*. For hosted surfaces the token exchange and token storage happen
-   in the vendor's backend, not on the user's machine.
-2. **MCP server** (Container App) — acts as a stateless **OAuth proxy /
-   authorization-server façade** in front of Entra ID. It is *not* an IdP:
-   it registers clients dynamically (RFC 7591, HMAC-signed stateless
-   `client_id`), enforces the redirect-URI allowlist and PKCE, and exchanges
-   codes at Entra using its confidential client secret.
-3. **Entra ID** — the real identity provider. This is where `adm.luke` lives.
-
-## Full sequence
-
-```
-Claude Desktop        Browser (user's           MCP server              Entra ID
-+ claude.ai backend   DEFAULT browser!)         (OAuth proxy)
-     │                      │                        │                      │
- 1.  │─ POST /mcp ──────────┼───────────────────────▶│ 401 + WWW-Auth       │
- 2.  │─ Discovery ──────────┼───────────────────────▶│ RFC 9728/8414 docs   │
- 3.  │─ POST /oauth/register┼───────────────────────▶│ client_id (HMAC-     │
-     │                      │                        │ signed, embeds the   │
-     │                      │                        │ registered callback) │
-     │                      │                        │                      │
- 4.  │─ opens browser ─────▶│─ GET /oauth/authorize ▶│─ 302 to Entra ──────▶│
-     │                      │  (PKCE challenge)      │  app-reg client_id,  │
-     │                      │                        │  prompt=select_acct  │
-     │                      │                        │                      │
- 5.  │                      │◀── Microsoft sign-in: account picker ────────│
-     │                      │    ➜ user picks adm.luke HERE                │
-     │                      │                        │                      │
- 6.  │                      │◀─ 302 /oauth/callback?code=... ──────────────│
-     │                      │─ code ────────────────▶│ verifies HMAC state, │
-     │                      │                        │ re-checks allowlist  │
-     │                      │◀─ 302 claude.ai/api/mcp/auth_callback?code=..│
-     │                      │                        │                      │
-     │◀═ browser hits claude.ai ═════╗               │                      │
-     │   ➜ the browser MUST have an  │               │                      │
-     │     active claude.ai session  │               │                      │
-     │     as luke — otherwise       │               │                      │
-     │     Anthropic cannot map the  │               │                      │
-     │     code to a user/connector  │               │                      │
-     │     and the connect fails ════╝               │                      │
-     │                      │                        │                      │
- 7.  │─ Anthropic backend: POST /oauth/token ───────▶│─ + client_secret ───▶│
-     │   (code + PKCE verifier)                      │◀─ access + refresh ──│
-     │◀─ tokens (stored server-side at Anthropic, per connector)            │
-     │                      │                        │                      │
- 8.  │─ POST /mcp + Bearer ─┼───────────────────────▶│ validates Entra JWT  │
-     │                      │                        │ ➜ acts as adm.luke   │
-```
-
-## Key properties
-
-* **Step 5 vs. step 6 is the double sign-in.** The whole browser leg runs in
-  the user's *default* browser. That one browser profile needs **both** an
-  active session at the AI product (`luke` at claude.ai — same account as in
-  the desktop app) *and* the Entra sign-in as `adm.luke`. `prompt=
-  select_account` forces the Entra account picker so an existing SSO session
-  for the wrong account cannot be silently reused.
-* **Step 6 is authenticated at the vendor.** `claude.ai/api/mcp/auth_callback`
-  is an authenticated Anthropic endpoint; the authorization code is bound to
-  the Claude user via the browser's claude.ai session cookies. No claude.ai
-  session (or a different browser profile) → the code lands on a login page
-  and the connect stalls, even though the Entra half succeeded. This is the
-  single most common setup failure.
-* **The MCP server is a pure intermediary.** Its client secret never leaves
-  the server; the AI client never talks to Entra directly. The redirect
-  target is checked twice (authorize + callback) against a strict allowlist
-  of exact vendor callback URIs, and the proxy state that transits the
-  user-agent is HMAC-signed with a 10-minute lifetime.
-* **PKCE is end-to-end.** The AI client generates the verifier; the proxy
-  forwards the challenge (step 4) and the verifier (step 7) untouched, and
-  Entra validates the pair. The proxy additionally *requires* S256 PKCE and
-  rejects downgrades.
-* **Tokens are Entra tokens for `adm.luke`** with audience
-  `api://<client_id>/access_as_user`. For hosted surfaces they are stored in
-  the vendor's backend per connector (which is why the connector then works
-  across desktop, web and mobile). Renewal is a silent `refresh_token` grant
-  through the same `/oauth/token` proxy — no account picker again.
-* **Native CLIs skip step 6's hosted callback.** Claude Code, Gemini CLI and
-  VS Code's loopback flow use RFC 8252 `http://localhost:<port>` /
-  `http://127.0.0.1:<port>` redirects instead; there the token exchange runs
-  on the user's machine and no vendor-side session is involved.
-
-## One-line summary
-
-`luke` authenticates the *return path* of the authorization code to the AI
-vendor (step 6); `adm.luke` is the identity *inside* the token that the MCP
-server authorizes on every tool call (step 8).
@@ -1,305 +0,0 @@
---
-type: Concept
-title: MCP Docs Corpus — search_docs and the Cross-Repo Build Coupling
-description: How the published customer documentation becomes a third semantic search corpus in the MCP server — CRLF-safe heading chunking, build-time embedding, the corpus hash guard, and why editing the docs does not update a running server.
-resource: /src/McpServer/autopilot-monitor-mcp/src/docs-corpus.ts
-tags:
-  - mcp
-  - search
-  - embeddings
-  - documentation
-  - build
-timestamp: 2026-07-21T19:30:00+02:00
---
-
-# Purpose
-
-The MCP server answers two different kinds of question, and they need two
-different corpora.
-
-* *"Why did this enrollment fail?"* → analysis rules, gather rules, IME log
-  patterns. That is `search_knowledge`, backed by `knowledge-base.ts`.
-* *"How do I deploy the agent?" / "Where is my data stored?"* → the published
-  customer documentation. That is `search_docs`, backed by `docs-corpus.ts`.
-
-They are deliberately **separate indexes**. Merged into one, they would compete
-for the same `topK` and dilute each other: a rules query would surface prose
-pages, and a product question would surface rule definitions.
-
-# Schema
-
-## Corpus source
-
-The corpus is the `autopilotmonitor-docs` repository — a public OKF bundle
-published at `docs.autopilotmonitor.com`. It is **not** vendored into this repo.
-The deploy workflow checks it out into `mcp-docs/` of the Docker build context;
-the Dockerfile copies it to `/app/docs` in both the build and the final stage
-(byte-identical, or the boot-time corpus hash rejects the precomputed index).
-
-`SUMMARY.md` and `log.md` are skipped as navigation scaffolding. `index.md` is
-kept — it is the documentation map and answers "what documentation exists" — but
-gets no `url`, because the bundle deliberately keeps it out of `SUMMARY.md` and
-GitBook therefore never renders it.
-
-## Chunking
-
-A whole page cannot be one document: `trust/security-faq.md` is 36 KB, while
-MiniLM-L6-v2 truncates at ~256 tokens. An un-chunked page would silently embed
-only its first paragraph.
-
-Chunks are cut at **h2/h3 headings**, which in this bundle are also the semantic
-boundaries — `security-faq.md` carries 37 h3s, one per question.
-`<details><summary>Q</summary>` blocks (used by `troubleshooting/faq.md`) are
-treated the same way, with the summary as the section title. Each chunk is
-prefixed with a `Page Title › Section › Subsection` breadcrumb so a hit lifted
-out of the middle of a page is self-describing to both the embedder and the
-reader.
-
-Two deliberate exceptions to the ~1500-character budget:
-
-* **Markdown tables are never split.** A table broken across chunks leaves
-  `| --- |` rows with no header — unreadable in a result and meaningless to
-  embed. Tables carry real answers here (the role matrix, the settings
-  reference), so an over-long table is allowed to exceed the budget.
-* **Unbroken lists split at line level.** The changelog pages are one bullet
-  list per release with no blank lines, so paragraph splitting cannot touch
-  them; left whole, everything past the model's window would be truncated away
-  and become unsearchable.
-
-Short sections are **kept**, not filtered. A one-line answer ("Is it free?" →
-"Yes, the Community plan is free") is often the most valuable hit, and the
-breadcrumb supplies the context the short body lacks. Only structural residue
-(under 25 alphanumeric characters) is dropped.
-
-## CRLF is a correctness precondition
-
-The docs repo is authored on Windows and ships CRLF. In JavaScript `.` does not
-match `\r`, so a pattern like `/^(#{2,3})\s+(.*)$/` matches **nothing** on a CRLF
-file: `(.*)` stops before the `\r` and `$` never reaches end-of-string.
-
-This was observed during development, and the failure mode is what makes it
-dangerous: no crash, no error — headings and frontmatter simply stop being
-recognized and every page silently degrades to unlabelled paragraph splits. The
-first working build produced 286 plausible-looking chunks that were almost all
-wrong; after normalizing, `security-faq.md` went from 29 blind splits to 46 real
-question sections.
-
-`normalizeNewlines()` runs before any parsing. Do not remove it, and do not
-"fix" a future parsing bug here by adding `\r?` to one pattern.
-
-## Token windows: why a chunk can hold several vectors
-
-Chunking at heading boundaries keeps sections coherent, but it does not bound the
-result by *tokens* — and it cannot. Measured on this corpus the ratio ranges from
-**2.43 to 5.81 characters per token**, a factor of 2.4, so no character budget maps
-reliably onto the model's 256-token window. A budget safe for the worst case
-(~620 characters) would shred prose and tables alike.
-
-Left alone, 87 of 324 chunks exceeded the window and **13% of all tokens never
-reached the ranking** — silently, since the tokenizer truncates without complaint.
-The effect was concrete: in `built-in-rules.md :: Apps` (734 tokens), the strings
-`ANALYZE-APP-013`, `ANALYZE-OFFICE-001`, `ANALYZE-CORR-003` and `Click-to-Run` all
-sit past the cutoff, so *"proxy configuration blocking app downloads"* did not
-retrieve that section at all.
-
-So the *chunk* stays whole and the *embedding* is split instead:
-`VectorSearchProvider.index()` cuts long text into 250-token windows with 40 tokens
-of overlap and embeds each. A document therefore carries `embeddings: number[][]`,
-and `search()` scores it by its **best** window.
-
- **Max, not mean.** Averaging window vectors would blur a long section's several
-  topics into one mediocre direction — the same dilution that makes large context
-  windows worse than chunking. Max keeps a document findable by any one thing it
-  discusses.
- **The tokenizer is a build-time dependency only.** `index()` runs during the
-  Docker build; production boots from precomputed vectors and never loads it. It is
-  also only the vocabulary, not the ONNX weights (~93 ms).
- Cost: 324 chunks → 424 vectors (+31%), index 2.63 → 3.12 MB, and 424 instead of
-  324 dot products per query — still microseconds.
- The rules corpus benefits too, unplanned: 128 rules now carry 172 vectors.
-
-Measured effect: token coverage 87% → **100%**, *"Office Click-to-Run install never
-finished"* 0.318 → **0.442**, *"proxy configuration blocking app downloads"* absent
-→ **0.559 at rank 1**. The ten reference queries kept byte-identical scores — their
-chunks are short, hence one window, hence the same vector as before.
-
-## Keyword fallback
-
-Semantic ranking alone leaves a gap: proper nouns embed poorly. `RealmJoin` occurs
-in 3 chunks yet scores under the threshold.
-
-Fuzzy matching is the wrong remedy, and the corpus says so. At a threshold low
-enough to surface `RealmJoin` (0.28), Fuse also returns 5 hits for `SCEPman` — a
-word this corpus contains **zero** times. Literal containment has neither problem.
-
-So when the semantic pass returns fewer than `topK`, `search_docs` tops the list up
-via `lexicalMatch`, the substring scan every provider already exposes:
-
- Query terms are filtered to distinctive ones (≥4 characters, non-stopword, max 6).
- A hit needs **corroboration**: at least two matching terms, unless the query has
-  only one. Without this rule, "how do I bake sourdough bread" matched a page about
-  LLM providers, because "bake" is a substring of "baked into the image".
- Hits are **appended, never merged**: they carry no cosine similarity, so semantic
-  results keep the head of the list and keyword hits fill the tail, flagged
-  `matchType: "keyword"` with `keywordFallback` in the response.
-
-### Language
-
-The corpus and `all-MiniLM-L6-v2` are both English-only, and the failure is total
-rather than gradual: "wo werden meine Daten gespeichert" returns **zero** results,
-not weak ones, because the query vector lands nowhere near any English chunk.
-
-The fix is a sentence in the tool description telling the caller to query in English
-and answer in the user's language — the caller is a language model, so translating
-the question before the call costs nothing. A multilingual embedding model would
-handle it natively but is substantially larger and would need to be measured against
-`scripts/eval-docs-search.ts` first, since it changes English retrieval too.
-`search_knowledge` carries the same note for the same reason.
-
-### When it fires
-
-Two triggers, and the second one exists because the first was not enough:
-
-1. **Fewer than `topK` semantic hits** — the obvious case.
-2. **A weak semantic head** (best score below `WEAK_SEMANTIC_SCORE`, 0.35). Topping
-   up only a short list misses the more common failure: a pasted identifier like
-   `WOW6432Node` returns three chunks at ~0.29 that do not contain the word, while
-   the single chunk that does never gets considered. When nothing semantic is
-   convincing, exact matches take the front — keeping at least one semantic result,
-   so a weak-but-correct hit is never pushed out entirely.
-
-The threshold was chosen by measurement, not intuition. `scripts/eval-docs-search.ts`
-scores strategies over 2465 queries in three classes — every chunk heading
-(known-item, a regression detector), rare identifiers (the class this fallback
-serves), and hand-written questions (the reality anchor, not derived from the
-corpus):
-
-| strategy | known-item | literal | handwritten MRR | fixed | broken |
-| --- | --- | --- | --- | --- | --- |
-| append-only (previous) | 71.9% | 66.2% | 1.000 | — | — |
-| weak < 0.30 | 71.9% | 72.6% | 1.000 | 142 | 0 |
-| **weak < 0.35** | **73.7%** | **81.1%** | **1.000** | **335** | **0** |
-| weak < 0.40 | 76.3% | 88.2% | 0.944 | 502 | 3 |
-| weak < 0.45 | 77.2% | 93.0% | 0.889 | 613 | 5 |
-
-0.35 is strictly dominant: better in every class, worse in none. Higher thresholds
-keep repairing more identifier queries but start demoting hand-written questions —
-the class that most resembles real use — so the gain is not free past that point.
-
-The measurement also corrected the size of the problem: identifier queries were
-succeeding only 66.2% of the time, so `WOW6432Node` was not an outlier but one of
-roughly 750 such failures.
-
-## Build-time embedding
-
-Like the rules corpus, docs are embedded once at Docker build time by
-`precompute-embeddings.js <rulesDir> <outFile> [docsDir]`, into a third
-`PrecomputedSection` (`docs`) of `search-index.json`. The container never embeds
-a corpus at boot — only the incoming query.
-
-The `docs` section is **optional** in the file format, which is what makes a
-local checkout without the docs repo work: `validatePrecomputedIndex` skips it
-when the booting server loaded zero doc chunks. The asymmetry is intentional —
-if the server *has* a docs corpus and the file does *not*, that is staleness and
-is rejected like any other mismatch.
-
-Embeddings are rounded to 6 decimals on serialize. A float64 component
-serializes to ~20 characters of JSON, so 384 dims cost ~7.8 KB per vector;
-rounding roughly halves the index file, which is `JSON.parse`d on every
-scale-to-zero cold start. The induced L2 norm error (~1e-5 over 384 dims) sits
-two orders of magnitude inside `UNIT_NORM_EPSILON`.
-
-## Registration
-
-`search_docs` is registered for **every role**, unlike the platform tools: this
-is public documentation carrying no tenant data, and a tenant user asking "how do
-I deploy the agent" has as much business here as a Global Admin. It is skipped
-entirely when the corpus is empty, so a doc-less build advertises no broken tool.
-
-# Cold start
-
-`minReplicas: 0` means every idle period ends in a cold start someone waits through.
-Measured from outside: **24.5 s** to first byte after `ScaledToZero`, against **60 ms**
-warm.
-
-Where those seconds go could not be answered from outside the process. Log Analytics
-stamps every console line of one ingestion batch with the same time, so the boot
-sequence collapses to a single instant however it is queried. The server therefore
-times itself — `[boot +Nms]` marks from `process.uptime()`, which includes Node's own
-startup and module loading.
-
-Measured in production on a real cold start (31.5 s to first byte that time):
-
-```
-+244ms  node started (startup + module loading)
-+431ms  corpora read from disk         (+187ms)
-+491ms  index read, validated, hydrated (+60ms  <- for 3.12 MB)
-+504ms  listening
-+677ms  query embedder warm            (background)
-```
-
-**The application accounts for half a second of it.** The other ~31 s — 98% — is
-Container Apps activation: KEDA reacting to the request, scheduling a pod, mounting
-the 236 MB image, starting the container. The container also boots *faster* than a
-development laptop (504 ms against 1273 ms), so nothing here is CPU-starved.
-
-Three conclusions, and two of them overturn assumptions this file previously stated:
-
- **Index size is irrelevant to startup.** 3.12 MB hydrates in 60 ms. Growing the
-  corpus is effectively free, and the embedding rounding earns its keep on file size
-  alone, not on boot time.
- **Raising the container to 0.5 vCPU was not justified by cold start.** The stated
-  reason was the embedding model load; prebaked, that is 173 ms and runs in the
-  background, where only the first *search* could ever wait on it. The extra vCPU may
-  still help concurrent requests, but the cold-start argument does not survive
-  measurement.
- **The only real lever is `minReplicas: 1`**, which removes activation entirely at
-  roughly 7× the monthly free consumption grant. Shrinking the image would shave the
-  mount, but that is a fraction of platform time, not the bulk of it.
-
-# Cross-repo coupling
-
-**Editing the documentation does not update a running MCP server.** The corpus is
-baked into the image, so only re-running the *Deploy MCP Server* workflow picks
-up doc changes.
-
-That coupling is made checkable rather than memorable: the build passes the docs
-checkout SHA as `--build-arg DOCS_COMMIT`, and `/health` reports
-`docs: { commit, chunks, sections }`. Comparing that commit against
-`git rev-parse HEAD` in `autopilotmonitor-docs` answers "is the deployed
-documentation stale?" directly.
-
-Automatic redeploy on a docs push was considered and rejected: it would need a
-PAT secret in the docs repo and would turn every typo fix into a container
-deployment.
-
-# Examples
-
-Retrieval measured against the real bundle (323 chunks, all-MiniLM-L6-v2):
-
-```
-"where is my data stored"            → 0.566  troubleshooting/faq.md :: General › Where is my data stored?
-"how do I deploy the agent with Intune" → 0.819  troubleshooting/faq.md :: Setup & Agent › How do I deploy the agent?
-"which roles exist and what can they do" → 0.500  trust/security-faq.md :: Identity and Access › What roles exist?
-"how do I set up Teams notifications"    → 0.592  reference/settings.md  :: Tenant › Notifications
-"what firewall URLs do I need to allow"  → 0.374  reference/network-endpoints.md :: (intro)
-```
-
-The 0.25 `minScore` default is tuned to that observed band — short keyword
-queries on all-MiniLM score low, and a relevant-but-marginal hit lands around
-0.34.
-
-# Citations
-
-* `/src/McpServer/autopilot-monitor-mcp/src/docs-corpus.ts` — loader, frontmatter
-  parser, chunker
-* `/src/McpServer/autopilot-monitor-mcp/src/tools/search.ts` — `search_docs`
-  registration
-* `/src/McpServer/autopilot-monitor-mcp/src/precomputed-index.ts` — `docs`
-  section and its validation asymmetry
-* `/src/McpServer/autopilot-monitor-mcp/Dockerfile` — `mcp-docs/` copy,
-  `DOCS_COMMIT`
-* `/.github/workflows/deploy-mcp.yml` — docs checkout and SHA capture
-* `/src/McpServer/autopilot-monitor-mcp/scripts/eval-docs-search.ts` — retrieval
-  evaluation harness; run it before changing anything about ranking
-* [MCP OAuth Flow](../mcp-oauth-flow.md) — the other MCP concept document
@@ -1,84 +0,0 @@
---
-type: concept
-title: MCP Tool Telemetry
-description: The three telemetry layers for judging MCP tool quality — backend App Insights via X-MCP-Tool-Name, the per-user usage table, and the MCP_TOOL_LOGGING stderr lines that carry the signals the backend cannot see (soft errors, result size vs. cap, zero-hit searches, Zod rejections).
-resource: src/McpServer/autopilot-monitor-mcp/src/telemetry.ts
-tags: [mcp, telemetry, observability, tool-quality]
-timestamp: 2026-08-05
---
-
-# Schema
-
-Three layers answer "are the MCP tools doing their job, and are tools missing?":
-
-1. **Backend App Insights** — every tool handler runs inside `withToolTelemetry`
-   (`src/telemetry.ts`), which propagates the tool name via AsyncLocalStorage so
-   `apiFetch` stamps `X-MCP-Tool-Name` on each backend request.
-   `RequestTelemetryMiddleware` copies it into the request telemetry as
-   `McpToolName`: per-tool call volume, latency percentiles and HTTP failure
-   rates by KQL. Blind spot: tools that never call the backend, and handler-level
-   soft errors (see layer 3).
-2. **Usage table** — `McpQuotaEnforcementMiddleware.TrackUsage` counts per
-   user/day under the key `toolname:endpoint`; surfaced by the `get_api_usage`
-   tool. Counts only, every call counts as success.
-3. **stderr JSON lines** (`MCP_TOOL_LOGGING=true`, queryable via Container App
-   Logs) — the layer that carries what the other two structurally cannot:
-   - `tool_call`: duration, `isError` **including soft errors** (handlers never
-     throw — `toolError` *returns* `isError: true`, so backend-only telemetry
-     records those calls as successes), `errorMessage` (capped; the thrown
-     message or the first lines of the `toolError` text, which name the error
-     class — HTTP status / timeout / auth / not found; absent on success),
-     `resultChars` + `overCap` (result
-     exceeds the tool's `anthropic/maxResultSizeChars` hint → the host truncates
-     it; a frequently-overCap tool needs tighter defaults or projections), a
-     size-bounded args summary, and the caller scope (ga/delegated/tenant).
-     This is the ONLY telemetry for backend-free tools: `search_docs`,
-     `validate_rule`, `get_resource`, the local ranking of `search_knowledge`.
-   - `search_zero_hit`: query text (capped) whenever `search_events` /
-     `search_knowledge` / `search_docs` return zero results — the most direct
-     "missing docs / missing knowledge / missing tool?" demand signal.
-   - `tool_call_rejected`: rejections the SDK answers *before* any handler runs
-     (Zod argument validation, unknown/disabled tool). Two non-obvious facts,
-     both found by live verification: SDK 1.30 wraps these McpErrors as a
-     *successful* JSON-RPC response whose result is `{ isError: true, text:
-     "MCP error <code>: …" }` — a JSON-RPC error envelope never exists for
-     them — and the Hono bridge (`getRequestListener`) may stream the body as
-     `res.write` chunks with a bare `res.end()`. The sniffer in the `/mcp`
-     route therefore wraps both `write` and `end`, reassembles up to 10 KB and
-     matches both shapes (`attachToolCallRejectionSniffer` in `telemetry.ts`).
-     Handler soft errors never carry the `MCP error` prefix, so they are not
-     double-logged. This is the strongest "the schema or description confuses
-     the model" signal and was previously invisible everywhere.
-
-The env flag defaults to `true` in `infra/mcp-server.bicep` (documented desired
-state — the template is not routinely deployed; the live flag is set with
-`az containerapp update --set-env-vars MCP_TOOL_LOGGING=true`).
-
-# Examples
-
-Count zero-hit queries to find unmet demand (Log Analytics):
-
-```kusto
-ContainerAppConsoleLogs_CL
-| where Log_s has '"type":"search_zero_hit"'
-| extend d = parse_json(Log_s)
-| summarize count() by tostring(d.tool), tostring(d.query)
-```
-
-Per-tool soft-error and truncation rates:
-
-```kusto
-ContainerAppConsoleLogs_CL
-| where Log_s has '"type":"tool_call"'
-| extend d = parse_json(Log_s)
-| summarize calls = count(), errors = countif(d.isError == true),
-            overCap = countif(d.overCap == true), p95ms = percentile(tolong(d.durationMs), 95)
-  by tool = tostring(d.tool)
-```
-
-# Citations
-
- `src/McpServer/autopilot-monitor-mcp/src/telemetry.ts` — wrapper + log emitters
- `src/McpServer/autopilot-monitor-mcp/src/index.ts` — `/mcp` rejection sniffer
- `src/Backend/AutopilotMonitor.Functions/Middleware/RequestTelemetryMiddleware.cs` — `McpToolName` stamping
- `src/Backend/AutopilotMonitor.Functions/Middleware/McpQuotaEnforcementMiddleware.cs` — usage-table counting
@@ -1,122 +0,0 @@
---
-type: Concept
-title: Analyze Rule Evaluation Triggers (evaluateOn)
-description: "Opt-in interim evaluation of analyze rules before a session is terminal — enrollment_end stays the default, whiteglove_sealed and on_event:<type> triggers close the WhiteGlove notification gap and the never-terminal stuck-session gap with one mechanism, backed by update-semantics on RuleResults instead of the permanent dedupe freeze."
-resource: backend/rule-engine
-tags: [rules, analyze, triggers, notifications, whiteglove]
-timestamp: 2026-08-14
---
-
-# Status
-
-**IMPLEMENTED 2026-08-14** (same day the spec was approved). The open product decisions below were confirmed as "no" for v1. Key implementation anchors: `AnalyzeRuleTriggers` (Shared — grammar + matching helpers, shared by engine, ingest registry and CRUD validation), `AnalyzeRunContext` / `AnalysisOutcome.ResolvedResults` (RuleEngine), `InterimTriggerRegistry` (5-min-TTL per-tenant cache for the ingest hot path, fail-soft), `AnalyzeOnEnrollmentEndHandler` interim branch, `EvaluateOnJson` + five RuleResult lifecycle columns in `TableStorageService.Rules`. ANALYZE-ID-004 ships as the first interim-enabled rule (`on_event:hybrid_login_pending`, repetition-gated at threshold 75).
-
-# Problem
-
-Analyze rules run at exactly three points today, all of them terminal or near-terminal:
-
-1. `enrollment_complete` / `enrollment_failed` observed at ingest (`EventIngestProcessor.cs`, classification → analyze envelope).
-2. The maintenance sweep terminalizing a silent session (Failed / Incomplete + synthetic `session_timeout`, `MaintenanceService.cs`).
-3. The vulnerability-correlation rerun (`vulnerability_correlated` reason — incremental, no stats).
-
-Two incident classes fall through this model:
-
- **WhiteGlove gap (sits-d, 2026-08-11):** `whiteglove_complete` seals a session to Pending but enqueues no analyze run. A rule that should alert at the end of pre-provisioning (technician still at the bench) never fires, and when Part 2 eventually terminalizes days later, the permanent per-(session, rule) dedupe means a finding that sneaked in earlier (e.g. via the vuln-rerun backdoor) is frozen and never notifies.
- **Never-terminal stuck sessions (esa-logistics, 2026-08-13/14):** a session looping in Account Setup (user signs in daily, hybrid affinity never establishes) resets the 5h inactivity clock on every logon. It is never terminalized, therefore never analyzed — the exact sessions where a diagnosis would help most (ANALYZE-ID-004, ANALYZE-APP-015) produce no finding while the customer watches the device loop.
-
-Both gaps share one root cause: *evaluation time is hard-wired to session end*. Gather rules already solved the analogous problem on-device with declarative triggers (`startup` / `phase_change` / `phase_exit` / `interval` / `on_event`); analyze rules need the server-side equivalent.
-
-# Design Overview
-
-Add an optional `evaluateOn` array to the analyze-rule schema. Absent field ⇒ `["enrollment_end"]` ⇒ **today's behavior, bit-for-bit, for every existing rule**.
-
-```
-"evaluateOn": ["enrollment_end", "on_event:hybrid_login_pending"]
-```
-
-Trigger grammar (v1):
-
-| Trigger | Fires when | Notes |
-|---|---|---|
-| `enrollment_end` | terminal analyze run (complete / failed / sweep-terminalized) | default; also the **finalization pass** for interim results (below) |
-| `whiteglove_sealed` | ingest classifies the first genuine `whiteglove_complete` (session → Pending, `isPreProvisioned`) | duplicate seals do not re-trigger |
-| `on_event:<eventType>` | an ingest batch contains ≥1 event of `<eventType>` | `<eventType>` validated against the event-types catalog; phase boundaries are covered by `on_event:phase_transition` / `on_event:esp_phase_changed` — no separate phase grammar needed, since every run evaluates the full stream anyway |
-
-Explicitly **not** in v1: interval/timer triggers (no cheap host for them; the sweep remains the only clock), and `on_event` filters on data fields (the rule's own conditions do that — the trigger only decides *when* to look).
-
-# Pipeline Changes
-
-## Ingest (producer side)
-
- `EventIngestProcessor` already classifies each stored batch. After classification, intersect the batch's event types with the tenant's **trigger registry** (the set of `on_event` types across the tenant's active rules — derivable from `AnalyzeRuleService`'s merged rule load, cached alongside it). Non-empty intersection ⇒ enqueue one envelope `Reason=interim_trigger`, carrying the matched trigger event types. Reuse the existing 30s visibility delay (terminal-flush ordering argument in `AzureQueueAnalyzeOnEnrollmentEndProducer` applies to interim batches too).
- The `whiteglove_complete` seal path (`EventIngestProcessor.Classification.cs`) enqueues `Reason=whiteglove_sealed` — only on the first seal, only for `isPreProvisioned`.
- Terminal enqueue (`CompletionEvent` / `FailureEvent`) is unchanged.
-
-## Handler / engine (consumer side)
-
-`AnalyzeOnEnrollmentEndHandler` branches by reason today (primary vs. `vulnerability_correlated`); interim reasons become a third branch. The engine call gets a run context instead of the bare `reanalyze` flag:
-
-| Aspect | Terminal run (`enrollment_end`) | Interim run (`whiteglove_sealed`, `interim_trigger`) |
-|---|---|---|
-| Rule set | ALL active rules (interim-triggered ones get their finalization pass here) | only rules whose `evaluateOn` matches the reason / one of the batch's trigger types |
-| KO (`MarkSessionAsFailed`) | applies (unchanged) | **suppressed** — a Pending/InProgress session must never be flipped Failed by an interim pass (`TryMarkSessionFailedFromRuleAsync` is skipped; the terminal run re-fires the rule and applies KO then) |
-| Platform stat `IssuesDetected` | counted | skipped (like vuln rerun) |
-| Per-rule fire stats | counted | skipped (like vuln rerun) — keeps the terminal-only stats convention and the Rule Regression Radar baselines clean |
-| Channel notifications | new findings notify (unchanged) | new findings notify — **this is the point** of both gaps |
-| SignalR results-available | yes | yes (live update of an open session page) |
-
-## Result lifecycle: update semantics replace the dedupe freeze
-
-Today the engine skips any rule that already has a stored `RuleResult` row for the session (`RuleEngine.AnalyzeSessionAsync`, existing-results lookup) — findings are frozen at first write, which is precisely the WG-gap failure mode ("dedupe permanent").
-
-New model — `RuleResult` gains four fields (`FirstDetectedAt`, `LastEvaluatedAt`, `IsInterim`, `ResolvedAt`, plus `NotifiedAt` for the notification marker):
-
- **Interim run:** rules in scope are (re-)evaluated even when a row exists. Fired ⇒ upsert (evidence/confidence refreshed, `FirstDetectedAt` preserved, `IsInterim=true`). Not fired + existing interim row ⇒ `ResolvedAt` set (kept for audit; excluded from issue counts and default UI).
- **Terminal run:** every rule that has an interim row is re-evaluated regardless of dedupe (finalization). Fired ⇒ row finalized (`IsInterim=false`, evidence refreshed — fixes the stale-template-field freeze, e.g. the ESP-004 `{{appName}}` case). Not fired (typically a `not_exists` precondition on `enrollment_complete` now failing because the session healed) ⇒ `ResolvedAt` set. Rules without interim rows keep today's skip-if-exists dedupe.
- **Notification dedupe** moves off "row exists" onto `NotifiedAt` on the row: notify once per (session, rule) at first fire — interim or terminal, whichever comes first; refreshes and finalization do not re-notify. The manual `reanalyze=true` path must **preserve** `NotifiedAt` across its rebuild (today it deletes rows; delete-and-recreate would silently re-arm notifications) and keeps its designed never-notify behavior.
- Legacy rows (null new fields) read as final/terminal — no migration.
-
-# Authoring Guardrails (validate_rule lints)
-
-Interim evaluation changes what a rule's conditions mean mid-flight. Three new lints in the MCP `validate_rule` pre-flight (and the baked authoring guide):
-
-1. **Terminal-precondition trap (warning):** `evaluateOn` contains an interim trigger AND a precondition is `not_exists` on `enrollment_complete` / `enrollment_failed` / `session_timeout`. Mid-run these pass trivially — the rule needs conditions that are *monotonic* (once true on the growing event stream, stays true) or repetition-gated. Worked example: ANALYZE-APP-015 must NOT get an interim trigger as-is — even successful sessions transiently show its "completion signal deferred" + `pending>=1` pattern (the terminal precondition is its only gate). ANALYZE-ID-004 is interim-safe by construction (threshold 65 requires repeated `hybrid_login_pending`).
-2. **Unknown trigger event type (error):** `on_event:<type>` not in the event-types catalog.
-3. **KO-on-interim (warning):** `markSessionAsFailedDefault: true` on a rule whose only triggers are interim — the KO would never apply until terminal; say so.
-
-# Cost & Safety
-
- Interim runs are bounded by trigger frequency, and the chosen v1 triggers are rare by construction (`hybrid_login_pending` ≤1 per boot, `whiteglove_sealed` once per session). High-frequency telemetry event types (performance_snapshot, agent_metrics_snapshot, download_progress, network churn, log_entry, agent_trace, stall_probe_check) are **hard-blocked** as `on_event` triggers, not merely advised against: the CRUD write is rejected (`AnalyzeRuleTriggers.BlockedOnEventTypes`, code-only enforcement), the runtime matcher drops them from any row that slipped in (defense in depth — the trigger registry and the engine both go through `OnEventTypes`), and the MCP lint reports them as an error. The JSON mirror lives in `rules/guardrails.json` (`blockedInterimTriggerEventTypes`) with a parity test pinning it to the C# set — the same pattern the gather hard blocks use. If a legitimate rare-but-bursty type ever hurts, a per-(session, reason) throttle marker is the v2 lever.
- Each run loads the full event stream once (existing engine behavior, no change); rule filtering makes interim passes strictly cheaper than terminal ones.
- Queue semantics (retry via visibility timeout, poison after MaxDequeueCount, idempotent partial-success re-runs) are inherited unchanged; upserts keep idempotency.
-
-# Surfaces
-
- **Web session page:** interim findings render live (existing SignalR results-available notification) with a "preliminary" badge on `IsInterim`; `ResolvedAt` rows hidden by default behind a toggle.
- **MCP:** `get_session(includeAnalysis)` / `get_session_summary` expose `isInterim` / `resolvedAt`; `list_session_annotations`' fired-rule snapshot semantics unchanged (labels bind to whatever was fired at annotation time).
- **Success-rate / platform stats:** terminal-only convention untouched (interim runs record no stats).
-
-# Application to the Motivating Cases
-
- WG battery rule (sits-d): `evaluateOn: ["enrollment_end", "whiteglove_sealed"]` — technician gets the channel alert at the bench; Part-2 terminal pass finalizes or resolves the finding.
- Hybrid-affinity stuck (esa): ANALYZE-ID-004 gets `evaluateOn: ["enrollment_end", "on_event:hybrid_login_pending"]` — the second overdue-login event (threshold 65) produces a live finding on the still-InProgress session. ANALYZE-APP-015 stays `enrollment_end`-only until its conditions are hardened (lint 1).
-
- Stuck after a forced mid-ESP reboot (sits-d Cloud PCs, 2026-08-19): `on_event:session_stalled` is the established trigger for the never-terminal stuck session. The agent emits `session_stalled` exactly once per session (60-minute stall probe), so the trigger is rare by construction and needs no throttle. Five Cloud PCs sat at `InProgress` with **zero findings** for hours — a mid-ESP reboot had killed the agent in `Stage=EspAccountSetup` — before the max-lifetime watchdog eventually terminalised them as `Incomplete`. ANALYZE-ESP-005 carries the trigger and fires on that stream at confidence 95 (verified against session `8110e262`): both its conditions (`mdm_policy_reboot_required.firstRebootUri` exists, `system_reboot_detected` count ≥ 1) are **monotonic** and it has no terminal preconditions, so lint 1 does not apply. ANALYZE-APP-016 is interim-safe for the same reason (`app_install_starved` count ≥ 1 only ever grows).
-
-  Two rules were considered and deliberately **not** given the trigger: ANALYZE-APP-015 is the worked example of lint 1 above and stays `enrollment_end`-only; ANALYZE-ESP-001 gates on `phase_duration` of a phase that is still open mid-run, and that evaluation is not pinned by a test — an unverified trigger is not worth a possible false positive on every slow DeviceSetup.
-
-# Product Decisions (settled 2026-08-14)
-
-1. Notify-on-resolve (a "finding healed" message)? **No** (v1) — resolution is visible in UI/MCP.
-2. Re-notify on severity/confidence escalation of an existing finding? **No** (v1) — one notification per finding.
-3. `whiteglove_sealed` runs allowing KO rules to flip Pending → Failed? **No** — the Pending state is the WhiteGlove contract; suppression is unconditional for interim.
-
-# Citations
-
- `src/Backend/AutopilotMonitor.Functions/Services/EventIngestProcessor.cs` — terminal-only enqueue (classification → analyze envelope).
- `src/Backend/AutopilotMonitor.Functions/Services/Analyze/AnalyzeOnEnrollmentEndHandler.cs` — reason branching, notify path, stats side-effects.
- `src/Backend/AutopilotMonitor.Functions/Services/Analyze/AzureQueueAnalyzeOnEnrollmentEndProducer.cs` — 30s visibility delay rationale.
- `src/Backend/AutopilotMonitor.Functions/Services/RuleEngine.cs` — existing-results dedupe, `TryMarkSessionFailedFromRuleAsync` KO path.
- `src/Backend/AutopilotMonitor.Functions/Services/MaintenanceService.cs` — sweep terminalization + analyze enqueue; inactivity-clock reset explains the never-terminal gap.
- `rules/gather-rule-phase-scoping.md` (this bundle) — the on-device trigger precedent this design mirrors.
- `rules/rule-authoring-surface.md` (this bundle) — where the new lints land (validate_rule + baked guide).
@@ -1,95 +0,0 @@
---
-type: Concept
-title: Gather Rule Guardrails
-description: >-
-  How gather-rule collectors are fenced in — the allowlists in rules/guardrails.json,
-  the hard blocks that survive unrestricted mode, and why every collector must call a
-  guard rather than trusting rule.Target.
-resource: src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather
-tags: [gather-rules, security, guardrails, agent]
-timestamp: 2026-08-11
---
-
-# Concept
-
-A gather rule is authored by a **tenant administrator** through `POST /api/rules/gather` and executed by the agent as **SYSTEM** on an enrolling device. The backend does not validate `collectorType`, `target`, or `parameters` at all — it only enforces scope/emit-mode fields, a 1 MB body cap, that the rule lands in the caller's own tenant partition, and that `Author` is stamped from the caller's JWT (create and PUT-upsert; true updates preserve the original author). Everything that decides *what a rule may reach* is therefore enforced **on the agent**, in `GatherRuleGuards`.
-
-This is the security boundary. The portal's `ValidationIndicator` is a convenience — the API stays reachable directly and the backend stays validation-free — but since 2026-08 the portal additionally **gates enabling** on the same client-side validation: a custom rule whose target fails validation cannot be toggled on, is created `enabled=false`, and an edit that makes the target invalid force-disables the rule (`targetBlocked` in `app/gather-rules/types.ts`). An enabled rule with an invalid target shows a "Blocked on devices" badge. All of this is UX, not security — the agent guard remains the enforcement point.
-
-# Schema
-
-Allowlists come from `rules/guardrails.json`, embedded into the agent assembly as
-`AutopilotMonitor.Agent.V2.Core.Resources.guardrails.json` (see the `EmbeddedResource`
-item in `AutopilotMonitor.Agent.V2.Core.csproj`) and regenerated into the portal's
-`utils/guardrails.generated.ts` by `node rules/scripts/combine.js`.
-
-| Guard | Source list | Match rule |
-| --- | --- | --- |
-| `IsRegistryPathAllowed` | `registryPrefixes` | prefix, boundary `\` or end |
-| `IsFilePathAllowed` | `filePrefixes` | `Path.GetFullPath` first, then prefix + boundary |
-| `IsWmiQueryAllowed` | `wmiQueryPrefixes` | `SELECT <* \| property-list> FROM <class>`; class = case-insensitive equality against classes derived from the `SELECT * FROM <class>` entries, boundary whitespace or end (trailing `WHERE` allowed). Non-canonical entries (none today) fall back to literal prefix + boundary |
-| `IsCommandAllowed` | `allowedCommands` | **exact** match, trimmed — never prefix |
-| `IsEventLogChannelAllowed` | `eventLogChannels` | prefix, boundary `/` or end |
-
-**Hard blocks live in code, not in the JSON**, so a parse error cannot lift them — on a
-parse failure the allowlists fall back to empty and everything is blocked (fail-closed),
-but the hard blocks must hold regardless of configuration:
-
-* `BlockedUsersPrefix` (`C:\Users`) and `AdditionalHardBlockedPathPrefixes`
-  (`C:\Windows\System32\config`) — exception only for `%LOGGED_ON_USER_PROFILE%`
-  under `AppData\Local` / `AppData\Roaming`.
-* `HardBlockedCommandPatterns` — download, user/group creation, boot config,
-  persistence, destructive operations; plus `MaxCommandLength`.
-* `HardBlockedEventLogChannels` — `Security` (audit trail of user behaviour) and the
-  PowerShell channels (script-block logging routinely contains secrets in clear text).
-
-`rules/guardrails.json` mirrors the blocked lists (`blockedFilePrefixes`,
-`blockedEventLogChannels`, `blockedCommandPatterns`, `maxCommandLength`) **for display
-and pre-flight only**. Enforcement is the C# constant; `GuardrailsParityTests` (agent
-test project) pins the JSON mirror to the constants so neither side can drift. The
-portal (`utils/guardValidation.ts`) and the MCP validator (`rule-validation.ts`) apply
-the mirrored hard blocks in the same order as the agent — before the unrestricted-mode
-early-return — so a rule the agent would refuse is never shown as "Allowed".
-
-# Examples
-
-Every collector must call its guard and return `context.EmitSecurityWarning(...)` on
-refusal — that emits the `security_warning` event that makes a block visible in the
-timeline instead of failing silently.
-
-```csharp
-// FileCollector / JsonCollector / XmlCollector
-if (!GatherRuleGuards.IsFilePathAllowed(filePath, context.UnrestrictedMode, userProfilePath))
-    return context.EmitSecurityWarning(rule, "file", filePath);
-```
-
-Two collectors were added to this contract on 2026-07-22 after shipping without it:
-
-* **`LogParserCollector`** read any path in `rule.Target`, bypassing even the `C:\Users`
-  hard block. It cannot guard `rule.Target` directly — a wildcard filename makes
-  `Path.GetFullPath` throw — so it guards **the directory** when the filename contains
-  `*`/`?`, and re-guards **each resolved path** after wildcard expansion (a junction can
-  surface a file the directory check did not cover).
-* **`EventLogCollector`** read any channel, including `Security`.
-
-`ImeLogPathOverride` comes only from the local `--ime-log-path` CLI flag, never from
-remote config. The operator using it is already a local admin, so it relaxes the
-allowlist exactly the way unrestricted mode does — hard blocks still apply.
-
-**WMI property projections (2026-08):** `SELECT BatteryStatus FROM Win32_Battery` is
-allowed because `SELECT * FROM Win32_Battery` is — a projection exposes a strict subset
-of the allowed class. The matcher parses the query shape instead of literal-prefix
-matching; the allowed-class set is derived at load time from the existing
-`wmiQueryPrefixes` entries, so `rules/guardrails.json` needs no new key. The same
-algorithm is mirrored in the portal (`utils/guardValidation.ts`) and the MCP server
-(`rule-validation.ts`); agents older than the change still block projections with a
-`security_warning` until they self-update.
-
-# Citations
-
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleGuards.cs`
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleContext.cs` — `EmitSecurityWarning`
-* `src/Agent/AutopilotMonitor.Agent.V2.Core.Tests/Monitoring/Gather/GatherRuleCollectorGuardTests.cs`
-* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/GatherRulesFunction.cs` — what the backend does *not* validate
-* `rules/guardrails.json`, `rules/scripts/combine.js`
-* Customer-facing counterpart: `autopilotmonitor-docs/rules/gather-rules.md` (§ Security guardrails)
@@ -1,167 +0,0 @@
---
-type: Concept
-title: Gather Rule Phase Scoping, One-Shot Triggers & Emit-on-Change
-description: How gather rules are restricted to enrollment phases (activePhases / activeFromPhase), collect once at a phase boundary (phase_change / phase_exit), and how emitMode "on_change" suppresses repeated identical results.
-resource: /src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs
-tags:
-  - agent
-  - backend
-  - gather-rules
-  - config
-timestamp: 2026-08-04T00:00:00+02:00
---
-
-# Problem
-
-Interval gather rules (e.g. a registry poll every 60 s) ran during **all** enrollment phases
-and emitted an event on **every** tick — including `exists=false` events while the target key
-did not exist yet. A rule needed only from Account Setup onwards produced hundreds of
-identical noise events per session and wasted collector runs.
-
-# Schema
-
-Three opt-in fields on `GatherRule` (Shared model, `rules/schema/gather-rule.schema.json`,
-delivered to the agent via `GET agent/config`; ConfigVersion 34). Absent fields = legacy
-behavior — full back-compat.
-
-| Field | Type | Semantics |
-|---|---|---|
-| `activePhases` | `string[]` \| null | Rule runs only while the current phase is in the list. Null/empty = unrestricted. |
-| `activeFromPhase` | `string` \| null | Sticky latch: activates when the phase first reaches the threshold, then stays active for the rest of the session — including through `Failed`. Null = unrestricted. |
-| `emitMode` | `"always"` \| `"on_change"` \| null | `on_change`: poll on the trigger cadence, emit only when the collected result changes. Null/`always` = emit every collection (legacy). |
-
-Canonical phase tokens are the `EnrollmentPhase` enum **names** `Start`(0) …`Complete`(7).
-Backend validation (`GatherRulesFunction.ValidateScopeAndEmitMode`) rejects `Unknown`/`Failed`,
-numeric tokens, unknown emit modes, and both scope fields set at once (400). The agent
-defensively prefers `activePhases` if both arrive anyway.
-
-# One-shot collection at phase boundaries
-
-Scoping answers "while *may* this rule run". The trigger answers "when does it fire". For
-one-shot collection the two phase triggers are the bookends of a phase:
-
-| Trigger | Fires |
-|---|---|
-| `phase_change` | Once when `triggerPhase` is **entered** (dedup key `{ruleId}\|{phase}`). |
-| `phase_exit` | Once when `triggerPhase` is **left** (dedup key `exit:{ruleId}\|{phase}`). |
-
-Empty `triggerPhase` means every transition. Both keys live in the same
-`_phaseRulesExecuted` set; the `exit:` prefix keeps the two key spaces disjoint, so an
-enter-rule and an exit-rule on the same phase never cannibalise each other's slot.
-
-`phase_exit` semantics that are easy to get wrong:
-
-* It is evaluated **before** `_currentPhase` advances, so both the `triggerPhase` match and
-  the phase-scope gate see the phase being **left**. A rule scoped to `DeviceSetup` therefore
-  still fires on its own exit, even though the phase being entered is outside that scope.
-* A transition into `Failed` **does** fire the exit rules of the failing phase — capturing
-  state at the failure boundary is the point.
-* Exit of `Unknown` never fires (nothing was entered yet), and a repeated identical phase
-  signal is not a transition.
-* An exit rule on `Complete` only fires if something transitions *away* from Complete. For
-  "at the end of enrollment", use `phase_change` on `Complete` or `on_event` with
-  `enrollment_complete`.
-* Old agents do not know the trigger value and simply never fire the rule (silent no-op) —
-  which is why `phase_exit` needs no ConfigVersion bump: no new field is transported.
-
-# Which "phase" feeds the triggers — the emitted timeline, not raw signals
-
-The phase the executor sees is fed by `GatherRuleExecutorHost` from the **post-reduce
-`TimelineEventStream`**: `EventTimelineEmitter` publishes every emitted event's
-`(eventType, phase)` after the decision engine reduced the originating signal. Phase triggers
-therefore fire exactly when the UI timeline shows the phase — by construction.
-
-This replaced the original V2 wiring (`SignalIngress.SignalPosted`), which fires at enqueue
-time with the **raw** collector payload. The raw phase can run minutes ahead of the
-engine-declared one: in session `32312a32` (RealmJoin tenant) the Shell-Core ESP-exit
-synthesized `EspPhaseChanged(FinalizingSetup)` at 12:18, while the engine — holding the
-transition behind the RealmJoin completion gate until the first deployment resolved — declared
-`phase_transition(FinalizingSetup)` at 12:25. A `phase_change` rule on `FinalizingSetup`
-reading `HKLM\SOFTWARE\RealmJoin\Custom\BIOS` fired 7 minutes early and read the key before
-the RealmJoin package wrote it (`exists=false`).
-
-Consequences of the emitted-event feed:
-
-* `phase_change` / `phase_exit` / phase **scope** gates all follow the engine-reduced phase
-  (single feed, consistent with the portal's "collects once when the enrollment reaches …").
-* `on_event` now sees **every emitted event type**, including engine-emitted ones
-  (`enrollment_complete`, `phase_transition`, `realmjoin_resolved`, …) that never existed on
-  the raw signal stream — the documented "On Event with `enrollment_complete`" end-of-enrollment
-  pattern only works because of this. This restores V1 semantics (V1 fired triggers from every
-  emitted `EnrollmentEvent`).
-* Other hosts (`DeviceInfoHost`, `UserEspKeepAwakeHost`, `ProvisioningPackageHost`) still key
-  off the raw signal stream deliberately — their collections are about OS state at the raw
-  boundary (ESP exit, keep-awake), not about timeline agreement.
-
-# Scope semantics (agent, `GatherRuleExecutor`)
-
-* Scope applies to **all trigger types**:
-  * `interval` — timers keep running; an out-of-scope tick is a free early-return (no
-    start/stop lifecycle races on phase transitions).
-  * `startup` — a scoped startup rule not yet in scope at `UpdateRules` is **deferred**: it
-    runs exactly once from `OnPhaseChanged` when its scope activates (same
-    `_startupRulesExecuted` dedup; it is not part of the `WaitForStartupRules` latch).
-  * `phase_change` — evaluated against the **new** phase; the scope gate runs before the
-    per-(rule, phase) dedup so an out-of-scope pass does not consume the execution slot.
-  * `on_event` — gated by the current phase.
-* **Before the first phase signal** of a session (`_currentPhase == Unknown`) scoped rules are
-  inactive. Sessions that never produce phase signals never run them (documented behavior).
-* **From-phase latch**: activates when `phase != Unknown && phase != Failed && (int)phase >=
-  (int)fromPhase`. `Failed=99` would ordinal-satisfy every threshold, hence the explicit
-  exclusion — but once latched, a rule stays active through `Failed`. A config refresh that
-  delivers a from-phase rule after its threshold passed latches it immediately.
-* `--run-gather-rules` (diagnostic CLI) sets `IgnorePhaseScope = true` — no phase context
-  exists there, scoped rules execute unconditionally (log line marks the bypass).
-
-# Emit-on-change semantics
-
-* The collector result dict is canonically hashed (keys ordinal-sorted at every nesting
-  level, invariant value formatting, SHA-256) **before** `ruleId`/`ruleTitle` injection.
-* First in-scope non-empty result always emits — on an absent registry key that first
-  `exists=false` event *is* the visible "we're polling now" indicator.
-* Unchanged results increment a per-rule suppression counter; the next emitted event carries
-  `suppressedPolls` + `suppressedSinceUtc` in its `Data` so the gap is observable.
-* Composition with `emitOnlyIfExists=true` (collector-level): a miss returns an empty dict —
-  no emit AND no hash update. Result: zero noise while absent, one event on appearance, then
-  only on change.
-* State is in-memory and survives `UpdateRules` config refreshes; an agent restart causes at
-  most one re-emit per rule (acceptable under the per-enrollment lifecycle).
-* Volatile collectors (eventlog timestamps, logparser positions) degrade `on_change` to
-  `always` — every poll hashes differently. The option stays visible for them since some
-  outputs are stable; this is documented, not hidden.
-
-# Portal & delivery
-
-* Create form defaults new rules to `emitMode: "on_change"`; existing rules load as
-  `always`. The scope UI is a three-way mode (always / during phases / from phase) backed by
-  a canonical `GATHER_PHASES` list — the same list replaced the free-text `triggerPhase`
-  input, whose placeholder used to suggest invalid tokens.
-* **Controls are shown only where they change behavior** (`supportsPhaseScope` /
-  `supportsEmitMode` in `types.ts`). Offering all three "when" controls unconditionally
-  produced meaningless combinations — a scope on a `phase_change` rule naming a concrete
-  phase can only ever suppress the single firing, and `on_change` has no second result to
-  compare against. Hidden controls are nulled by `buildScopeFields` so state from an earlier
-  trigger choice cannot leak into the payload, and `validateScopeSelection` rejects a scope
-  mode that was selected but left unfilled (which previously serialised to null and silently
-  ran the rule everywhere while the form still read "From a phase onwards").
-  Startup is the deliberate exception: a scope there defers the one-shot rather than
-  suppressing it, so the scope control stays while emit mode is hidden.
-* The custom-rule toggle PUT (`{enabled, isBuiltIn, isCommunity}`) previously full-replaced
-  the stored rule and wiped Title/Target/Trigger — `GatherRuleService.UpdateRuleAsync` now
-  merges toggle-style partials (empty Title/CollectorType/Target) into the existing row and
-  preserves `CreatedAt` on full edits. This fix is a prerequisite: without it every toggle
-  would silently clear the new fields.
-* Old agents (Newtonsoft) ignore unknown config properties: scoped rules run everywhere,
-  `emitMode` is ignored — graceful degradation until the fleet rolls forward.
-* `ContentEquivalent` treats null and empty `activePhases` as equal, so pre-existing DB rows
-  (absent columns → null) never diff against seeds — no reseed churn.
-
-# Citations
-
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Monitoring/Telemetry/Gather/GatherRuleExecutor.cs` — scope gates, latch, canonical hash
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/Hosts/GatherRuleExecutorHost.cs` — timeline-event trigger feed
-* `src/Agent/AutopilotMonitor.Agent.V2.Core/Orchestration/TimelineEventStream.cs` — post-reduce observer surface
-* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/GatherRulesFunction.cs` — `ValidateScopeAndEmitMode`
-* `src/Backend/AutopilotMonitor.Functions/Services/GatherRuleService.cs` — partial-PUT merge, `ContentEquivalent`
-* `src/Shared/AutopilotMonitor.Shared/Models/Rules/GatherRule.cs` — field contracts
-* Tests: `GatherRuleExecutorPhaseScopeTests`, `GatherRuleExecutorEmitModeTests`, `GatherRuleExecutorHostTimelineFeedTests` (agent); `GatherRuleUpdatePartialMergeTests`, `GatherRuleScopeFieldsTests` (backend)
@@ -1,152 +0,0 @@
---
-type: Concept
-title: Rule Authoring Surface — MCP Resources, validate_rule, and the Analyze Dry-Run
-description: >-
-  How customer AIs author gather/analyze rules against the real contract: the baked
-  authoring resources (guide, schemas, guardrails) generated by combine.js, the
-  MCP-local validate_rule pre-flight, and the side-effect-free backend dry-run that
-  traces a draft analyze rule against one session's events.
-resource: src/McpServer/autopilot-monitor-mcp/src/tools/rules.ts
-tags: [rules, mcp, analyze-rules, gather-rules, dry-run, authoring]
-timestamp: 2026-08-05
---
-
-# Concept
-
-Customers author rules with an AI connected to the MCP server. Retrieval
-(`search_docs`) is deliberately NOT the knowledge source for authoring: chunked
-top-K retrieval can silently omit an operator, a guardrail prefix, or an enum,
-and the AI then produces a plausible-but-dead rule. The authoring surface is
-therefore **deterministic**: three `get_resource` entries carry the complete
-contract, a local validator rejects what production would reject or silently
-ignore, and a backend dry-run evaluates a draft against real session events with
-a full trace.
-
-The intended loop: draft → `validate_rule` → `test_analyze_rule` against a real
-session (one that should fire, one that should not) → iterate → create in the
-portal. The `author-rule` MCP prompt walks a client through exactly this order.
-
-# Schema
-
-## Resources (deterministic authoring context)
-
-| Resource | Content | Source |
-| --- | --- | --- |
-| `rule_authoring_guide` | Hand-written complete authoring knowledge: collector types, triggers, condition sources, operators, confidence model incl. the exact factor DSL, `{{token}}` interpolation order, guardrail matching semantics, pitfalls | `src/rule-authoring-guide.ts` |
-| `rule_schemas` | Both JSON Schemas (2020-12) verbatim | generated |
-| `rule_guardrails` | `rules/guardrails.json` verbatim | generated |
-
-Generation: `node rules/scripts/combine.js` bakes schemas + guardrails into
-`src/McpServer/autopilot-monitor-mcp/src/rule-authoring.generated.ts` (same
-pattern as the web's `utils/guardrails.generated.ts`; the tsconfig `rootDir` and
-the Docker build's exclusion of `rules/schema` rule out importing the JSON
-directly). Drift is closed twice: CI's `guardrails-in-sync` job re-runs
-combine.js and fails on any diff, and `rule-authoring-drift.test.ts` pins
-generated == repo source plus guide enums == schema enums.
-
-## validate_rule (MCP-local)
-
-`src/rule-validation.ts`, no backend call. Three layers:
-
-1. **Schema** — ajv (draft 2020-12) against the baked schemas, validating the
-   single-rule `$defs` entry directly (the top-level oneOf wrapper would double
-   every error).
-2. **Guardrails** — mirrors the AGENT's matching semantics from
-   `GatherRuleGuards.cs` (see [gather-rule-guardrails.md](gather-rule-guardrails.md)):
-   hive-stripped segment-bounded registry/file prefixes, whitespace-bounded WMI
-   prefixes, EXACT command matching, `/`-bounded event-log channels, and the
-   code-enforced hard blocks (`Security` etc. channels, `C:\Users`,
-   `C:\Windows\System32\config`).
-3. **Semantic lint** — schema-valid-but-dead rules: unreachable
-   confidenceThreshold, factor conditions outside the three parseable shapes
-   (`exists`, `count >= N`, `phase_duration > N`), unknown event types (warning;
-   `gather_*` softened to info), unanchored `not_regex` allow-lists,
-   unresolvable `{{token}}`s, trigger cross-fields, outputEventType
-   convention/collision checks.
-
-The validator is advisory pre-flight only — the agent re-enforces guardrails
-on-device and the backend re-validates structure. It must never be stricter
-than production.
-
-## POST /api/rules/analyze/dryrun (backend)
-
-`DryRunAnalyzeRuleFunction` → `RuleEngine.DryRunRuleAsync`. Body
-`{ sessionId, rule }` (draft `AnalyzeRule`, 1 MB cap). Policy tier
-`TenantAdminOrGlobalReader` — a POST by shape but a pure read in effect, so the
-read-only Global Reader is admitted; platform-scope callers reach any tenant's
-session via `FindSessionTenantIdAsync` (same pattern as `GetRuleResultsFunction`).
-
-`RuleEngine.DryRun.cs` is a partial-class trace twin of `EvaluateRule`: it
-shares the exact evaluators (`EvaluatePrecondition` / `EvaluateCondition` /
-`EvaluateConfidenceFactor`) but evaluates **all** conditions instead of breaking
-on the first failed required one — the full picture is the point of a dry run.
-Verdicts: `fired`, `skipped_by_precondition`, `required_condition_not_met`,
-`no_conditions_matched`, `below_confidence_threshold`, `no_events`. Each
-condition entry carries `matched`, the production evidence dictionary (or the
-evaluator's reason string) and `matchingEventCount` — how many session events
-even have that eventType, the first thing to check on an unexpected miss.
-
-Invariants, pinned by `RuleEngineDryRunTests`:
-
-* **Parity**: verdict `fired` ⇔ `EvaluateRule` produces a result, with identical
-  confidence and evidence keys. Factor evaluation stays sequential against the
-  accumulating `matchedConditions` (a factor can observe earlier `factor_*`
-  entries) — reordering would change results.
-* **Side-effect freedom**: exactly one strict event read; never a RuleResult
-  write, never `TryMarkSessionFailedFromRuleAsync`, never a notification.
-  `wouldMarkSessionAsFailed` is reported, not acted on.
-
-`test_analyze_rule` (MCP) wraps the endpoint and adds the interpolated
-explanation/remediation preview via the existing `interpolate-rule-template.ts`
-against the returned `matchedConditions`.
-
-## POST /api/rules/gather/test-pattern (backend)
-
-The logparser counterpart to the analyze dry-run, added after a field incident:
-a customer verified a logparser regex with a PHP tester and the agent's .NET
-engine matched differently. `TestLogPatternFunction` evaluates a pattern against
-pasted sample lines with the AGENT's exact matching semantics:
-
-* Regex construction identical to `LogParserCollector`: `Compiled`, 1 s timeout,
-  **no IgnoreCase** — logparser matching is case-sensitive (unlike analyze-rule
-  regex conditions, which run IgnoreCase).
-* `format` behaves exactly like the rule parameter: `cmtrace` (default) parses
-  each line via the shared `CmTraceLogParser` and matches against the parsed
-  MESSAGE only; `text` matches the raw line. First match per line
-  (`Regex.Match`), group `"0"` excluded, unsuccessful groups omitted — the
-  returned `groups` are exactly the event-data fields the device would emit.
-* Mirrors the agent's diagnostics: per-line outcomes
-  (`matched | no_match | parse_failed | regex_timeout`), the all-lines-parse-fail
-  hint ("set parameter format=text") verbatim, and a case-sensitivity note on
-  zero matches.
-* Pure compute on the request body — no tenant data touched. Same policy tier
-  as the dry-run (`TenantAdminOrGlobalReader`); caps: 200 lines, 8 KB/line,
-  1 MB body.
-
-Parity is structural, not duplicated: `CmTraceLogParser` moved from the agent
-(`Monitoring/Enrollment/Ime`) to **Shared** (`AutopilotMonitor.Shared.Logging`)
-so agent and backend run the SAME parsing implementation. Timestamp caveat:
-bias-less CMTrace lines parse with `AssumeLocal`, which on the backend is the
-server's timezone — the endpoint therefore reports match/parse results, never
-timestamps. `test_log_pattern` (MCP) wraps the endpoint; `validate_rule`
-additionally lints logparser parameters (missing/non-compiling pattern, unknown
-format value) and its `nextStep` routes logparser drafts to `test_log_pattern`.
-
-## What is deliberately absent
-
-* **No gather-rule remote execution** — gather rules run as SYSTEM on devices;
-  session dry-run is analyze-only. Logparser authors get the pattern tester
-  above; all gather authors get guardrail pre-flight plus the on-device debug
-  log ([gather-rule-debug-log](../agent/gather-rule-debug-log.md)).
-* **No rule write/deploy via MCP** — creating rules stays in the portal.
-
-# Citations
-
-* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/TestLogPatternFunction.cs` — logparser pattern tester
-* `src/Shared/AutopilotMonitor.Shared/Logging/CmTraceLogParser.cs` — shared CMTrace parser (agent + backend)
-* `src/Backend/AutopilotMonitor.Functions/Services/RuleEngine.DryRun.cs` — trace twin + DTOs
-* `src/Backend/AutopilotMonitor.Functions/Functions/Rules/DryRunAnalyzeRuleFunction.cs` — endpoint + draft validation
-* `src/McpServer/autopilot-monitor-mcp/src/rule-validation.ts` — validator
-* `src/McpServer/autopilot-monitor-mcp/src/tools/rules.ts` — validate_rule / test_analyze_rule
-* `src/McpServer/autopilot-monitor-mcp/src/rule-authoring-guide.ts` — guide resource
-* `rules/scripts/combine.js` — MCP module generation
@@ -1,137 +0,0 @@
---
-type: Concept
-title: Customer Script Publishing — download.autopilotmonitor.com/agent/
-description: How the customer-facing PowerShell scripts reach the download alias, why publishing is decoupled from agent releases, and the guards that keep the published copy, the version badge and the portal's version oracle in agreement.
-resource: /.github/scripts/Publish-BootstrapScripts.ps1
-tags:
-  - build
-  - ci
-  - release
-  - bootstrap
-  - download-alias
-timestamp: 2026-08-19T00:00:00+02:00
---
-
-# Overview
-
-Four PowerShell scripts are served to customers from `https://download.autopilotmonitor.com/agent/`:
-
-| Blob | Source | Consumed by |
-| --- | --- | --- |
-| `Install-AutopilotMonitor.ps1` | `scripts/Bootstrap/Install-AutopilotMonitor.ps1` | Intune platform script (customer uploads a copy); downloaded live on every device by the WDP bootstrap MSI |
-| `Install-AutopilotMonitor-Dev.ps1` | rendered from the same source | dev fleet |
-| `Test-ShouldBootstrapAgent.ps1` | `scripts/Bootstrap/Test-ShouldBootstrapAgent.ps1` | customer dry run via `irm ... \| iex` |
-| `Grant-AutopilotMonitorAddOn.ps1` | `scripts/CustomerSetup/Grant-AutopilotMonitorAddOn.ps1` | optional Graph permission grant |
-
-`Uninstall-AutopilotMonitor.ps1` is deliberately not published — nothing links it, and an
-unauthenticated uninstall script on the public download host is not a feature.
-
-The alias is a Front Door route in front of the `agent` container; see
-[url-registry.md](url-registry.md) for the host registry and the migration to the alias.
-
-# Publishing chain
-
-`.github/scripts/Publish-BootstrapScripts.ps1` is the single owner. Two workflows call it
-with identical arguments:
-
-* **`publish-scripts.yml`** — on every push to `main` touching `scripts/Bootstrap/**`,
-  `scripts/CustomerSetup/**` or the publisher itself, plus `workflow_dispatch` with a
-  `dry_run` input.
-* **`build-agent.yml`** — inside the `publish_as_stable` branch, after `version.json` is
-  uploaded, so a release lands a set consistent with what is already live.
-
-Before this split, the script blobs rotated **only** on a stable agent release. A bootstrap
-fix therefore sat unpublished until the next agent cutover — while the WDP MSI downloads the
-published copy on every enrolling device. Script publishing is now decoupled from the agent
-release cadence; the release path still publishes, so it can never fall behind either.
-
-Both workflows share the concurrency group `agent-blob-publish` (`cancel-in-progress: false`).
-Both write `version.json`, and the publisher's `bootstrapVersion` read-modify-write must not
-interleave with a release writing the agent fields.
-
-# Publisher steps
-
-1. **Parse** `$ScriptVersion` from the bootstrap source.
-2. **Dev render** — literal substitution of the two `$AgentDownloadUrl` / `$VersionJsonName`
-   defaults. A missing anchor literal is a hard failure: a silently un-substituted dev script
-   would point the dev fleet at the stable agent.
-3. **Version-bump guard** — if the published bootstrap changed *behaviour* under an unchanged
-   `$ScriptVersion`, the run aborts. Comment and formatting changes publish with a warning.
-   See [Version oracles](#version-oracles).
-4. **Upload** every blob with `Cache-Control: no-cache` (they all rotate in place), mirrored
-   fail-soft to the legacy storage account.
-5. **Reconcile the version oracles.**
-6. **Verify through the alias** — re-download each blob and compare SHA-256, six attempts
-   20 s apart. A persistent mismatch means blobs were written but Front Door serves stale
-   content, and the error names the `az afd endpoint purge` command.
-
-## Deterministic publish form
-
-Every blob is published as **CRLF, UTF-8 without BOM**, normalized by the publisher rather
-than taken from the working copy. Git normalizes line endings on checkout — a Windows runner
-yields CRLF, a `core.autocrlf=false` clone yields LF — so publishing raw working-copy bytes
-would emit different blobs for identical source and make every byte comparison, guard and
-verification alike, depend on where the workflow ran. CRLF is also what PS 5.1 expects on the
-device and what has always been published.
-
-The ASCII-only rule for `scripts/Bootstrap/*.ps1` (enforced by the gates below) is unrelated
-but adjacent: PS 5.1 reads BOM-less files as ANSI and corrupts multi-byte characters.
-
-## Version oracles
-
-Three places state the bootstrap script version, and all three are derived from
-`$ScriptVersion` in the source:
-
-* `version.json.bootstrapVersion` — read by the docs badge. Written by the publisher as a
-  read-modify-write under `If-Match`, so a concurrent agent release keeps its own fields.
-  `build-agent.yml` seeds the field when it builds the manifest so the published manifest is
-  never briefly missing it; the publisher owns and re-asserts it afterwards.
-* `AdminConfiguration.LatestBootstrapV2ScriptVersion` — read by the portal to tell a customer
-  their uploaded copy is outdated. **Only** the publisher writes it; `build-agent.yml` writes
-  the `LatestAgentV2*` fields and nothing else. One writer per field.
-* The `Bootstrap script version: v<x>` marker the script logs, parsed out of captured platform
-  script stdout by `utils/bootstrapVersion.ts`.
-
-The version-bump guard exists because those three would otherwise keep asserting a version
-that no longer matches what customers download: a behaviour change under an unchanged version
-is invisible to every consumer, and customers decide from that version whether to re-upload
-their Intune copy.
-
-"Changed" means changed **behaviour**, matching what the source file's own comment on
-`$ScriptVersion` already asks for ("bump on meaningful changes"). The guard compares a code
-fingerprint — the PowerShell token stream with comments, newlines and line continuations
-removed — so comment fixes, typo corrections in comments and reflow publish with a
-`::warning::` instead of failing. Tokenising rather than regex-stripping keeps a `#` inside a
-string literal from being mistaken for a comment.
-
-# Gates
-
-`.github/workflows/bootstrap-script-gates.yml` is a `workflow_call` workflow holding the
-checks once:
-
-* Pester suite under **Windows PowerShell 5.1** — the runtime IME uses for platform scripts.
-* ASCII-only scan over `scripts/Bootstrap/*.ps1`.
-* `Publish-BootstrapScripts.ps1 -DryRun` — exercises the dev-render anchors and the
-  version-bump guard, and reports per blob whether the alias is current, stale or missing.
-
-Two callers: `pester.yml` on pull requests (reports, does not block the merge button), and
-`publish-scripts.yml` on pushes to `main`, where the gates job is a `needs:` dependency of the
-publish job and therefore **blocks** the upload. `pester.yml` deliberately has no push trigger
-— it would duplicate the gate run with no consequence.
-
-# Operating it
-
-* Dry run and drift check, no credentials needed for the read paths:
-  `pwsh .github/scripts/Publish-BootstrapScripts.ps1 -DryRun`
-* Republish without a code change: `workflow_dispatch` on **Publish customer scripts** with
-  `dry_run=false`.
-* Front Door serving stale content after a successful upload:
-  `az afd endpoint purge --resource-group rg-autopilotmonitor-prd-gwc --profile-name autopilotmonitor-fd --endpoint-name apm-download --content-paths '/agent/*'`
-
-# Citations
-
-* `.github/scripts/Publish-BootstrapScripts.ps1`
-* `.github/workflows/publish-scripts.yml`, `.github/workflows/bootstrap-script-gates.yml`, `.github/workflows/pester.yml`
-* `.github/workflows/build-agent.yml` (the `publish_as_stable` branch of the upload step)
-* `src/Agent/AutopilotMonitor.BootstrapMsi/Invoke-BootstrapDownload.ps1`
-* `src/Web/autopilot-monitor-web/utils/bootstrapVersion.ts`
@@ -1,121 +0,0 @@
---
-type: Concept
-title: URL Registry — One Place per Component, Guard-Enforced
-description: Every well-known own or Microsoft host lives in exactly one registry file per component (Constants.cs, utils/config.ts, src/config.ts); guard tests fail the build on any literal outside them. Includes the agent-download host migration to the download alias.
-resource: /src/Shared/AutopilotMonitor.Shared/Constants.cs
-tags:
-  - architecture
-  - urls
-  - ci
-  - convention
-timestamp: 2026-07-23T00:00:00+02:00
---
-
-# URL Registry
-
-Every well-known base URL — own hosts (portal, www, docs, download alias, MCP,
-API, both blob accounts) and Microsoft hosts (Graph, Entra login) — is defined
-in exactly one registry file per component. Code references the constant; the
-literal appears nowhere else.
-
-| Component | Registry | Guard test |
-|---|---|---|
-| C# (Shared/Backend/Agent) | `AutopilotMonitor.Shared.Constants` (`*BaseUrl`) | `HardcodedUrlGuardTests` |
-| Web | `utils/config.ts` (`DOCS_URL`, `SITE_URL`, `PORTAL_URL`, `BOOTSTRAP_GO_URL`, `ENTRA_LOGIN_URL`, `API_URL_PROD`, `BLOB_URL_PROD`, `AGENT_DOWNLOAD_HOSTNAMES`) | `utils/__tests__/hardcodedUrls.guard.test.ts` |
-| MCP | `src/config.ts` (`API_BASE_URL`, `ENTRA_LOGIN_BASE_URL`, `DOCS_BASE_URL`) | `src/__tests__/hardcoded-urls.guard.test.ts` |
-
-Derived registries build on these instead of repeating hosts:
-`lib/hostRouting.ts` computes `PUBLIC_HOST`/`PORTAL_HOST`/`APEX_HOST` from the
-URL constants, and `middleware.ts` imports from it.
-
-# Schema
-
-The guards scan non-test source for the enforced host list and fail with
-file:line on any occurrence outside the registry. Comment lines are ignored
-(docs may cite URLs). Test files are excluded on purpose: a literal in a test
-is an independent oracle — `ValidateBootstrapCodeResponseShapeTests` spells the
-full agent download URL out so a registry change must be acknowledged in two
-places, backend and portal allow-list, consciously.
-
-Why enforced rather than agreed: the registry existed before (both
-`Constants.AgentBlobBaseUrl` and the MCP `config.ts` header document earlier
-drift), yet the EU cutover still missed two literal copies of the blob host —
-`LatestVersionsService` and `ValidateBootstrapCodeFunction` kept reading the
-legacy account, silently kept alive only by the fail-soft legacy mirror in
-`build-agent.yml`. A convention that is not checked decays; these guards make
-the next stray literal a red build instead of a production surprise.
-
-# Agent-download host migration (2026-07-23)
-
-The two legacy readers above plus the agent's `SelfUpdater` now use
-`Constants.AgentDownloadBaseUrl` (`download.autopilotmonitor.com/agent`, Front
-Door in front of the current blob origin — verified serving `version.json`,
-`version-v2.json` and both ZIPs before the switch). The portal's
-`bootstrapValidation.ts` allow-lists BOTH the alias and the legacy blob host
-(`AGENT_DOWNLOAD_HOSTNAMES`) because bootstrap scripts already deployed in
-customer Intune tenants still carry legacy URLs.
-
-Deploy-order constraint: the web allow-list must be live BEFORE (or with) the
-backend that serves alias URLs — an old portal build rejects the alias host and
-the bootstrap flow dies client-side. Remove the legacy hostname from the
-allow-list only after the legacy account is torn down.
-
-**Front Door caching is a correctness hazard here, not a staleness nuisance.**
-The first release after the migration exposed it: the alias kept serving the
-previous `version.json` (`X-Cache: TCP_REMOTE_HIT`) while the origin was already
-updated — and because manifest and ZIP are independent cache entries, a stale
-manifest paired with a fresh ZIP fails the bootstrap's SHA-256 check. Two
-defenses, both in place since 2026-07-23: route caching on `/agent/*` is
-DISABLED, and every blob upload (CI `Send-Blob`, local `build.ps1`, the
-`versions/*.json` manifests) stamps `Cache-Control: no-cache` — all these blobs
-rotate in place, even the per-line ZIP. If caching is ever re-enabled, the
-headers keep the mismatch class impossible.
-
-Deliberately still on the legacy account: the `HealthCheckService` /
-`MaintenanceService` legacy-keepalive probes and the fail-soft mirror in
-`build-agent.yml` — they exist precisely to keep already-deployed customer
-bootstrap scripts working until the customer migration completes.
-
-# Bootstrap go-URL (2026-07-28)
-
-The OOBE bootstrap short-URL moved from `www.autopilotmonitor.com/go/{code}`
-(Next.js route, SSR) to **`go.autopilotmonitor.com/{code}`** — a Front Door
-custom domain whose `/*` route rewrites onto `/api/bootstrap/go/{code}` on the
-Function App (`GetBootstrapScriptFunction`). Registry entries:
-`Constants.BootstrapGoBaseUrl` (C#, the single producer via
-`CreateBootstrapSessionFunction`) and `BOOTSTRAP_GO_URL` (web, display-only in
-the sessions list); `go.autopilotmonitor.com` is on both guards' enforced-host
-lists. `CreateBootstrapSessionUrlShapeTests` pins the produced URL as an
-independent oracle — before this, no test guarded the bootstrap URL shape at
-all.
-
-Front Door route caching for `bootstrap-go` is DISABLED — same hazard class as
-the `/agent/*` route above, sharpened: the script body inlines the bearer
-token, so a cache hit would replay one requester's token to another.
-`NoStoreCacheMiddleware` additionally stamps `no-store` via the
-`/api/bootstrap/go/` prefix.
-
-Transition COMPLETED with the static-export PR (2026-07-29): the legacy
-Next.js `/go/[code]` route, `utils/bootstrapValidation.ts`, and
-`middleware.ts` are deleted — verified safe because the BootstrapSessions
-table held zero active sessions predating the URL cutover (all expired
-2026-03). The backend is now the only script producer;
-`OobeBootstrapScriptGeneratorTests`' golden file remains as the pin of the
-shipped template.
-
-Portal detail routes are query-string based since the same PR
-(`/sessions?id=…` etc., builders in `lib/routes.ts`, notification producer
-`Constants.PortalSessionUrl`). Legacy PATH-shaped links in sent
-Teams/Slack/webhook notifications are rewritten forever by SWA wildcard
-rewrites + `components/LegacyPathRedirect.tsx`; `staticwebapp.config.json`
-carries the production redirects/headers and is guarded by
-`utils/__tests__/swaConfig.guard.test.ts` (registry-backed hosts, no
-unsafe-eval, route order).
-
-# Citations
-
- `src/Shared/AutopilotMonitor.Shared/Constants.cs` — C# registry
- `src/Web/autopilot-monitor-web/utils/config.ts` — web registry
- `src/McpServer/autopilot-monitor-mcp/src/config.ts` — MCP registry
- `src/Backend/AutopilotMonitor.Functions.Tests/HardcodedUrlGuardTests.cs`
- [Version Contract](versioning.md) — the release pipeline this migration protects
@@ -1,118 +0,0 @@
---
-type: Concept
-title: Version Contract — Agent, Backend, MCP, Web
-description: One version shape for all shipping components, the ETag-CAS counter blob that mints build numbers, and the published manifests that make "what is deployed" checkable from outside.
-resource: /.github/scripts/Request-BuildNumber.ps1
-tags:
-  - build
-  - ci
-  - release
-  - versioning
-timestamp: 2026-07-22T00:00:00+02:00
---
-
-# Version Contract
-
-Four components ship from this repository — the agent, the Functions backend, the
-MCP server and the web portal. They share one version shape, one way of minting build
-numbers, and one manifest format, so that a version string means the same thing
-whoever emits it. The web portal is the commit-only exception: a static export has no
-runtime that could report a `major.minor.build`, so it carries `commit` + `buildUtc`
-alone (no counter blob).
-
-```
-version   = <major>.<minor>.<build>    major.minor curated by hand, build minted per build
-commit    = 7-char short SHA of this repo
-buildUtc  = ISO-8601 build moment
-```
-
-| Component | major.minor from | Counter blob | Reported by |
-|---|---|---|---|
-| Agent V2 | `VersionPrefix` in `AutopilotMonitor.Agent.V2.csproj` | `agent/buildcounter-v2.txt` | `agent/version.json` |
-| Backend | `VersionPrefix` in `AutopilotMonitor.Functions.csproj` | `versions/backend.txt` | `GET /api/health` |
-| MCP | `version` in `package.json` | `versions/mcp.txt` | `GET /health`, MCP handshake |
-| Web portal | — (commit-only) | — | `GET /version.json` on the portal host |
-
-# Schema
-
-## Build numbers — reserve before build, ETag-CAS
-
-`.github/scripts/Request-BuildNumber.ps1` is the only implementation; the CI
-workflows and the local `build.ps1` all call it.
-
-1. Anonymous `GET` on the counter blob → value `N` and `ETag`. The blob holds the
-   **last used** number as plain text and is public-read; only the write needs the
-   container SAS.
-2. `PUT N+1` with `If-Match: <etag>`. The quoted ETag form is required — PowerShell
-   strips the quotes on read, and an unquoted `If-Match` is rejected client-side.
-3. `412 Precondition Failed` → a concurrent build reserved first → re-read and retry
-   (5 attempts, linear backoff).
-4. Build with the reserved number.
-
-Reserving *before* the build is what makes concurrent minting impossible. **A failed
-build burns a number** — deliberate: uniqueness matters, density does not.
-
-Why a counter and not the published manifest: manifests are written on publish, not on
-build. The agent writes `version.json` only for stable releases, so deriving the next
-number from it would hand two consecutive dev builds the same number and let the second
-overwrite the first's artifact. A state-free scheme such as `git rev-list --count HEAD`
-fails for the same reason — two builds of one commit collide.
-
-**Seeding** (once per component): `PUT <last used number>` with `If-None-Match: *`, so
-an existing counter can never be clobbered. Agent V2 was seeded with `1356` on
-2026-07-17; `versions/backend.txt` with `999` and `versions/mcp.txt` with `299` on
-2026-07-22.
-
-## Local builds
-
-No counter is reached, the build number stays `0`, and the commit is empty or
-`unknown`. A `1.5.0` with no commit hash on `/api/health` is therefore a developer
-machine, not a release — the fallback is the signal, not a defect. The agent is the
-exception: `build.ps1` produces uploadable artifacts and reserves a real number unless
-`-SkipUpload` is passed.
-
-## Manifests
-
-`versions/backend.json` and `versions/mcp.json` (public-read) record what is deployed:
-
-```json
-{ "component": "backend", "version": "1.5.1000", "commit": "abc1234",
-  "buildUtc": "…", "deployedUtc": "…", "runId": "…" }
-```
-
-The MCP manifest adds `docsCommit`, because for that component "which build" and "which
-documentation" are separate questions. `versions/web.json` carries `component`, `commit`,
-`deployedUtc` and `runId` (no `version`/`buildUtc` — the served `/version.json` holds the
-build moment). The portal's own stamp is generated into `public/version.json` by
-`scripts/generate-version.js` (prebuild) from `GITHUB_SHA`, served with
-`Cache-Control: no-store`, and `deploy-web.yml` polls it until the deployed commit
-matches the pushed SHA before publishing the manifest.
-
-Each is written **last and only after the deploy workflow has polled the component's
-health endpoint until it reports that exact version and commit**. A green deploy step
-alone means the package was accepted, not that it is being served. Consequently a
-manifest that disagrees with the live endpoint means the running instance drifted after
-the fact (rollback, stale revision) rather than a half-finished pipeline.
-
-The agent keeps its own manifest at `agent/version.json` — the bootstrap derives that
-URL from the download URL and verifies the ZIP against its `sha256`, so it cannot move.
-It carries the same `commit` and `buildUtc` fields; `sha256` and `bootstrapVersion`
-remain, being the customer-facing integrity contract.
-
-# Consequences
-
- Bumping `major.minor` is a human decision, made in the component's own file
-  (`VersionPrefix`, or `version` in `package.json`). Nothing bumps it automatically.
- A new component joins by seeding a counter blob and calling the same script; no new
-  mechanism.
- The counter blobs and manifests live in the `versions` container on
-  `autopilotmonitoreu` (writes via `AZURE_BLOB_VERSIONS_SAS_TOKEN`). The agent's
-  counter stays in the `agent` container next to the artifacts it numbers.
-
-# Citations
-
- `.github/scripts/Request-BuildNumber.ps1` — the CAS protocol
- `.github/workflows/deploy-backend.yml`, `deploy-mcp.yml` — reserve, verify, publish
- `.github/workflows/deploy-web.yml`, `src/Web/autopilot-monitor-web/scripts/generate-version.js` — web stamp, verify, publish
- `.github/workflows/build-agent.yml`, `scripts/Deployment/build.ps1` — agent line
- [Build Counter Blob](agent/build-counter-blob.md) — agent-specific consequences
@@ -1,126 +0,0 @@
---
-type: Concept
-title: Portal Navigation Prefetch & the SWA Runtime Bottleneck
-description: Why every navigation Link in the portal sets prefetch={false} — the App Router's viewport prefetch fires one RSC request per visible link, and the Static Web Apps SSR runtime queues them server-side into a multi-minute latency tail. Also records what the follow-up measurement showed about the Standard SKU and the keep-alive side effect.
-resource: src/Web/autopilot-monitor-web/components/GlobalSidebar.tsx
-tags:
-  - web
-  - performance
-  - nextjs
-  - static-web-apps
-  - observability
-timestamp: 2026-07-27T18:00:00+02:00
---
-
-# Context
-
-The portal is a Next.js 15 App Router application hosted on Azure Static Web Apps. Every page under
-the authenticated shell is a client component behind `ProtectedRoute` that fetches its own data from
-the Function App (`autopilotmonitor-api-eu`) after mount. The RSC payload a route returns on
-navigation therefore carries no page data — only the shell.
-
-`GlobalSidebar` and `Navbar` render the full navigation on every page. With the App Router's default
-prefetch behaviour, each visible `<Link>` triggers a background `GET /<route>?_rsc=<hash>` as soon as
-it enters the viewport.
-
-# Mechanism
-
-Two properties combine into a portal-wide freeze:
-
-1. **Fan-out.** The navigation is fully rendered on each page load, so a single navigation issues one
-   RSC request per visible link — measured at ~10,400 requests over 14 days.
-2. **A heavy latency tail on the SSR runtime.** RSC responses are prerendered and edge-cached
-   (`x-nextjs-cache: HIT`, `s-maxage=31536000`), so the median is fast. On a cache miss or cold start
-   the Static Web Apps managed runtime queues them **server-side**, and the queue drains all at once.
-
-The navigation the user wants is then stuck behind that queue and the tab shows a loading spinner or a
-blank page until it drains. Nothing fails — the requests eventually return `200`, which is why the
-failure leaves no error trace anywhere.
-
-> **Correction (2026-07-28).** The original version of this document named a third property: that
-> `portal.autopilotmonitor.com` negotiates HTTP/1.1 and the prefetches exhaust the six-connection
-> browser cap. **That is wrong.** It came from `curl -w '%{http_version}'` on a Windows build of curl
-> whose Schannel backend has no HTTP/2 support, so it can only ever report `1.1`. ALPN says otherwise:
-> `openssl s_client -alpn h2,http/1.1` negotiates **h2** on the portal host, confirmed by a .NET
-> `HttpClient` request returning `HTTP/2.0`. There is no six-connection cap and connection starvation
-> was never the mechanism — the queue is server-side. Verify HTTP versions with `openssl s_client
-> -alpn` or `HttpClient`, never with this curl build.
-
-# Evidence
-
-Incident of 2026-07-27, 17:25–17:29 CEST. Browser-side dependencies during the freeze:
-
-| Request | Duration | Status |
-| --- | --- | --- |
-| `/admin/presence?_rsc=…` | 151,461 ms | 200 |
-| `/gather-rules?_rsc=…` | 52,283 ms | 200 |
-| `/progress?_rsc=…` | 37,878 ms | 200 |
-| `/analyze-rules?_rsc=…` | 37,559 ms | 200 |
-| `/audit?_rsc=…` | 37,539 ms | 200 |
-| Backend API, same window | 1,600–2,200 ms | 200 |
-
-The three ~37.5 s responses complete within 340 ms of each other — a queue draining, not independent
-slow requests. The corresponding `browserTimings` row for `/geographic-performance` reports
-`networkDuration` = 16 ms against `processingDuration` = 225,095 ms: the network delivered the
-document immediately and the browser then waited nearly four minutes for the `load` event.
-
-Fourteen-day distribution of RSC prefetches: n = 10,428, p50 = 91 ms, p95 = 896 ms, max = 234,230 ms,
-38 over 10 s, 21 over 30 s.
-
-# Outcome, measured 2026-07-28
-
-Two changes landed within half an hour of each other on 2026-07-27: the SWA plan went Free → Standard
-at 16:02:44 UTC, and `prefetch={false}` went live at 16:34:13 UTC. Twenty hours of production
-telemetry separate their effects.
-
-**The Standard plan produced no measurable latency gain.** Latency is governed almost entirely by the
-gap to the previous request — the SSR runtime cools down — so raw percentiles only measure the traffic
-mix. Stratified by that gap, the two eras are indistinguishable (p50, Free → Standard): `<10s`
-85 → 95 ms · `10-60s` 100 → 117 ms · `1-5min` 295 → 310 ms · `5-30min` 429 → 441 ms. Tail rates match
-too: Free ran 1.64 % over 2 s and 0.374 % over 10 s (n = 10,163); Standard produced 6 and 1 events at
-n = 258 against 4.2 and 1.0 expected. `browserTimings.totalDuration` by Mann-Whitney: n = 436 vs 48,
-z = −0.24, **p = 0.81**.
-
-**The prefetch fix is what removed the freezes** — worst `browserTimings.totalDuration` fell from
-225,277 ms to 4,856 ms, and the 30-second events stopped.
-
-**It also removed an accidental keep-alive.** The prefetch storm kept the SSR runtime warm: 85 % of
-requests used to arrive less than 10 s apart, now 46 % do. On an identical never-cacheable route
-(`/sessions/{id}`) the median rose from 87 ms to 211 ms and p90 from 465 ms to 1,480 ms. After 517
-minutes idle, one request took 11,441 ms and was abandoned (`resultCode 0`). The trade — minute-long
-freezes gone, ~150 ms added to a cold navigation — is worth it, but it is a trade.
-
-Do not benchmark this with a synthetic burst. Firing requests in quick succession warms the runtime
-and measures the best case: in a 25-round `curl --parallel-max 6` run, round 1 came in at p50 288 ms
-and rounds 4–25 at p50 113 ms.
-
-> **Endgame (2026-07-29).** The cold-start class was eliminated at the root: the portal became a
-> full static export (`output: 'export'`) — the SWA-managed SSR runtime no longer exists, so there
-> is nothing left to cool down. One escalation drove this: on 2026-07-28 a cold start exceeded the
-> SWA's 45-second function limit and the landing page served a hard "Backend call failure" 500.
-> The availability test that bridged the gap as a keep-alive stays as plain uptime monitoring.
-
-# Diagnosing this class of problem
-
-The backend Application Insights resource is the wrong place to look — a freeze appears there as an
-*absence* of requests, never as an error. Browser telemetry lives in a **separate** Application
-Insights resource addressed by `AUTOPILOT_MONITOR_WEB_APPINSIGHTS_ID`, which the MCP
-`query_backend_logs` tool does not reach. Query it through
-`.claude/commands/scripts/query-appinsights.sh` with that ID exported, and read `dependencies`
-(client-side fetches, including RSC prefetches) and `browserTimings` (the network/processing split of
-a document load).
-
-# Contract
-
-Navigation `<Link>` elements in `GlobalSidebar` and `Navbar` set `prefetch={false}`. The prefetched
-RSC payload buys nothing for these routes, so the only remaining cost of a click is the route's JS
-chunk, which the browser caches after first use.
-
-Do not remove the prop to "speed up navigation" without first re-measuring the tail in the web
-Application Insights resource — the prefetch is cheap only while the runtime is warm.
-
-# Citations
-
-* `src/Web/autopilot-monitor-web/components/GlobalSidebar.tsx` — nav link rendering, rationale comment
-* `src/Web/autopilot-monitor-web/components/Navbar.tsx` — top-bar and notification links
-* [SWA and Oryx node pinning](../architecture.md) — hosting model for the web app
@@ -1,268 +0,0 @@
-// Autopilot-Monitor MCP Server — Azure Container App Infrastructure
-//
-// Reconciled against the live deployment on 2026-07-21 (rg-autopilotmonitor-prd-gwc,
-// Germany West Central). The template had drifted behind two changes made directly
-// in Azure: the EU cutover (registry/API renamed) and the ACR hardening (admin user
-// disabled, image pull moved to the app's system-assigned identity).
-//
-// !! BEFORE RE-DEPLOYING THIS TEMPLATE, READ THIS !!
-// The live app carries an ingress custom-domain binding for mcp.autopilotmonitor.com
-// (SNI-enabled, with a managed certificate). Custom domains are NOT modelled below,
-// because the certificate is bound out-of-band. A full template deployment would
-// therefore REMOVE that binding and take the public MCP endpoint offline.
-// For routine changes (CPU/memory, env vars, image) prefer the surgical CLI form:
-//   az containerapp update -n autopilotmonitor-mcp -g rg-autopilotmonitor-prd-gwc --cpu 0.5 --memory 1.0Gi
-// Treat this file as the documented desired state and as a rebuild-from-scratch
-// recipe — not as a routinely-applied deployment.
-//
-// On a FROM-SCRATCH deploy the AcrPull assignment below is created only after the
-// Container App exists (it needs the app's principalId), so the very first revision
-// can fail to pull its image. Re-run the deployment, or restart the revision, once
-// the role assignment has propagated. This does not affect updates to a live app.
-//
-// Deploy (two-stage; required to set the OAuth public URL safely):
-//   1. First deploy without mcpPublicUrl:
-//      az deployment group create \
-//        --resource-group <rg-name> \
-//        --template-file infra/mcp-server.bicep \
-//        --parameters apiUrl=https://autopilotmonitor-api-eu.azurewebsites.net \
-//                     entraClientSecret=<secret-value>
-//      This emits `containerAppUrl` as an output (e.g. https://autopilotmonitor-mcp.<env-suffix>.<region>.azurecontainerapps.io).
-//
-//   2. Re-deploy with that URL pinned, so the OAuth proxy never trusts caller-
-//      supplied X-Forwarded-Host / Host headers when building issuer / WWW-
-//      Authenticate / redirect_uri metadata:
-//        --parameters mcpPublicUrl=<containerAppUrl from step 1>
-//
-//   When mcpPublicUrl is set, the MCP server uses it verbatim and ignores any
-//   forwarded-headers from the request. Without it, the server logs a startup
-//   warning and falls back to header-derived URLs (acceptable for local dev,
-//   not for production).
-
-@description('Azure region for all resources')
-param location string = resourceGroup().location
-
-@description('Name of the Container App')
-param containerAppName string = 'autopilotmonitor-mcp'
-
-@description('Name of the Container App Environment')
-param environmentName string = 'autopilotmonitor-env'
-
-@description('Name of the Log Analytics Workspace (dedicated for Container Apps)')
-param logAnalyticsName string = 'autopilotmonitor-container-logs'
-
-@description('Name of the Azure Container Registry')
-param acrName string = 'autopilotmonitoreuacr'
-
-@description('Backend API URL')
-param apiUrl string = 'https://autopilotmonitor-api-eu.azurewebsites.net'
-
-@description('Container image tag')
-param imageTag string = 'latest'
-
-@description('Entra ID app registration client_id used for the OAuth proxy. Public value (appears in JWT aud claim); not a secret. Since the C4A8 app-reg move this is the NEW app (the old 1a400946-… app remains valid at the backend for legacy-homed tenants).')
-param entraClientId string = '886ab5e2-6144-442c-80cc-9b28e0667731'
-
-@secure()
-@description('Entra ID client secret for OAuth token exchange')
-param entraClientSecret string = ''
-
-@description('Comma-separated allowlist of redirect_uri hosts for the OAuth proxy. Loopback is always allowed. Empty = built-in default (Anthropic, OpenAI, Google).')
-param mcpAllowedRedirectHosts string = ''
-
-@description('Public URL of the MCP server, used verbatim for OAuth issuer / WWW-Authenticate / redirect metadata. REQUIRED in production: the container refuses to boot without it (host-spoofing defense — see config.ts). Set on the second deploy with the value of the containerAppUrl output from the first deploy. The stage-1 deploy is safe because minReplicas=0 means no container runs until this is pinned. Empty falls back to X-Forwarded-Host headers only outside production (NODE_ENV != production).')
-param mcpPublicUrl string = ''
-
-@secure()
-// NOTE: avoid characters outside cp1252 here (this one used to say a Unicode
-// >=). `az bicep build --stdout` writes through the Windows console codec and
-// dies with a UnicodeEncodeError on anything it cannot map. Em dashes are fine.
-@description('Base64-encoded HMAC key (>=32 bytes after decode) for signing the OAuth proxy state. Naming and format match the backend\'s PaginationTokenSigningKey for consistency. Empty = generate per-instance random key on startup (acceptable for single-replica deployments since state has 10 min lifetime). Generate with PowerShell: [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))')
-param oAuthStateSigningKey string = ''
-
-@description('Enable structured tool-call logging to stderr (queryable via Container App Logs). Volume is one small JSON line per tool call - negligible at current usage.')
-param toolLoggingEnabled bool = true
-
-// --- Azure Container Registry ---
-
-// Admin user is DISABLED: a registry-wide username/password pair is a static,
-// non-rotating credential that would also have to live in a Container App secret.
-// The app pulls with its system-assigned identity + AcrPull instead (see below).
-resource acr 'Microsoft.ContainerRegistry/registries@2023-07-01' = {
-  name: acrName
-  location: location
-  sku: {
-    name: 'Basic'
-  }
-  properties: {
-    adminUserEnabled: false
-  }
-}
-
-// AcrPull for the Container App's system-assigned identity — this is what replaces
-// the admin credentials. Without it the app cannot pull its own image.
-//
-// NOTE: this assignment exists on the live registry but could not be enumerated
-// during reconciliation (the CLI session lacks Microsoft.Authorization read), so it
-// is reproduced here from the documented pattern rather than read back from Azure.
-// Verify with:
-//   az role assignment list --scope <acr-id> --assignee <containerApp principalId>
-var acrPullRoleId = '7f951dda-4ed3-4680-a7ca-43fe172d538d'
-
-resource acrPull 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
-  scope: acr
-  name: guid(acr.id, containerAppName, acrPullRoleId)
-  properties: {
-    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', acrPullRoleId)
-    principalId: containerApp.identity.principalId
-    principalType: 'ServicePrincipal'
-  }
-}
-
-// --- Log Analytics Workspace (required by Container App Environment) ---
-
-resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
-  name: logAnalyticsName
-  location: location
-  properties: {
-    sku: {
-      name: 'PerGB2018'
-    }
-    retentionInDays: 30
-  }
-}
-
-// --- Container App Environment ---
-
-resource environment 'Microsoft.App/managedEnvironments@2024-03-01' = {
-  name: environmentName
-  location: location
-  properties: {
-    appLogsConfiguration: {
-      destination: 'log-analytics'
-      logAnalyticsConfiguration: {
-        customerId: logAnalytics.properties.customerId
-        sharedKey: logAnalytics.listKeys().primarySharedKey
-      }
-    }
-  }
-}
-
-// --- Container App ---
-
-resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
-  name: containerAppName
-  location: location
-  // System-assigned identity: the credential the app uses to pull from the ACR
-  // (see the AcrPull assignment above). Replaces the former admin-user secret.
-  identity: {
-    type: 'SystemAssigned'
-  }
-  properties: {
-    managedEnvironmentId: environment.id
-    configuration: {
-      ingress: {
-        external: true
-        targetPort: 8080
-        transport: 'auto'
-        allowInsecure: false
-      }
-      // 'system' = pull with the app's system-assigned identity. No username, no
-      // password secret — nothing to rotate and nothing to leak from the app config.
-      registries: [
-        {
-          server: acr.properties.loginServer
-          identity: 'system'
-        }
-      ]
-      secrets: [
-        {
-          name: 'entra-client-secret'
-          value: entraClientSecret
-        }
-        {
-          name: 'oauth-state-signing-key'
-          value: oAuthStateSigningKey
-        }
-      ]
-      activeRevisionsMode: 'Single'
-    }
-    template: {
-      containers: [
-        {
-          name: 'mcp-server'
-          image: '${acr.properties.loginServer}/${containerAppName}:${imageTag}'
-          // 0.5 vCPU, but NOT for the reason originally given. It was raised from
-          // 0.25 to shorten the scale-to-zero cold start, on the assumption that
-          // loading the ONNX embedding model dominated it. Measurement disproved
-          // that: the app boots in 504 ms in production (see the [boot] marks in
-          // the container log and docs/mcp/docs-corpus.md), of which the prebaked
-          // embedder is 173 ms in the background. Of a 31 s cold start, ~98% is
-          // Container Apps activation — pod scheduling, image mount, container
-          // start — which no CPU setting touches.
-          //
-          // It stays at 0.5 because it plausibly helps CONCURRENT requests
-          // (maxReplicas is 1, so one replica serves up to 10 in-flight calls) and
-          // because at scale-to-zero the container bills only while active, making
-          // the difference negligible. If cold start ever needs to actually go
-          // away, the only lever is minReplicas: 1. Container Apps accepts fixed
-          // CPU/memory pairs, so memory moves with the CPU.
-          resources: {
-            cpu: json('0.5')
-            memory: '1.0Gi'
-          }
-          env: [
-            { name: 'AUTOPILOT_API_URL', value: apiUrl }
-            { name: 'PORT', value: '8080' }
-            { name: 'AUTOPILOT_ENTRA_CLIENT_ID', value: entraClientId }
-            { name: 'AUTOPILOT_ENTRA_CLIENT_SECRET', secretRef: 'entra-client-secret' }
-            { name: 'MCP_ALLOWED_REDIRECT_HOSTS', value: mcpAllowedRedirectHosts }
-            { name: 'MCP_PUBLIC_URL', value: mcpPublicUrl }
-            { name: 'OAuthStateSigningKey', secretRef: 'oauth-state-signing-key' }
-            { name: 'MCP_TOOL_LOGGING', value: toolLoggingEnabled ? 'true' : 'false' }
-          ]
-          probes: [
-            {
-              type: 'Liveness'
-              httpGet: {
-                path: '/health'
-                port: 8080
-              }
-              periodSeconds: 30
-              initialDelaySeconds: 10
-            }
-            {
-              type: 'Readiness'
-              httpGet: {
-                path: '/health'
-                port: 8080
-              }
-              periodSeconds: 10
-              initialDelaySeconds: 5
-            }
-          ]
-        }
-      ]
-      scale: {
-        minReplicas: 0
-        maxReplicas: 1
-        rules: [
-          {
-            name: 'http-scaler'
-            http: {
-              metadata: {
-                concurrentRequests: '10'
-              }
-            }
-          }
-        ]
-      }
-    }
-  }
-}
-
-// --- Outputs ---
-
-output containerAppUrl string = 'https://${containerApp.properties.configuration.ingress.fqdn}'
-output mcpEndpoint string = 'https://${containerApp.properties.configuration.ingress.fqdn}/mcp'
-output acrLoginServer string = acr.properties.loginServer
@@ -5,7 +5,7 @@
  "description": "Detects when the Enrollment Status Page failed on the Apps subcategory and the agent's AppX deployment log scan identified a suspected MSIX/Store package. Store/MSIX apps install outside the Win32 pipeline, so the regular per-app tracking sees nothing — this correlation names the likely culprit.",
  "severity": "warning",
  "category": "apps",
-  "version": "1.2.0",
+  "version": "1.2.1",
  "enabled": true,
  "evaluateOn": [
    "enrollment_end",
@@ -93,7 +93,7 @@
      "steps": [
        "Open Event Viewer → Applications and Services Logs → Microsoft → Windows → AppXDeploymentServer → Operational on the device (or in the diagnostics archive if uploaded)",
        "Filter for Error-level events around the ESP failure time and confirm the package name and HRESULT match this finding",
-        "Look up the HRESULT: 0x80073cf9 = generic install failure, 0x80073cf0 = invalid/corrupt package, 0x80073cff = sideloading/licensing policy block, 0x80073d02 = blocked because app is in use"
+        "Look up the HRESULT: 0x80073cf9 = generic install failure, 0x80073cf0 = package could not be opened (unsigned, publisher mismatch, or not found), 0x80073cff = sideloading/licensing policy block, 0x80073d02 = blocked because app is in use"
      ]
    },
    {
@@ -0,0 +1,92 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-APP-017",
+  "title": "App Install Blocked by Another Installer (0x80070652)",
+  "description": "Detects Win32 app installs that failed because the Windows Installer was busy with another installation (HRESULT 0x80070652 / MSI exit code 1618, ERROR_INSTALL_ALREADY_RUNNING). The IME retries on a fixed budget (~15-17 minutes across several attempts) and then reports the app as failed; when the app is ESP-blocking, the Device Setup Apps subcategory terminates with it.",
+  "severity": "high",
+  "category": "apps",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "baseConfidence": 70,
+  "conditions": [
+    {
+      "signal": "mutex_blocked_install",
+      "source": "event_type",
+      "eventType": "app_install_failed",
+      "dataField": "hresultFromWin32",
+      "operator": "equals",
+      "value": "-2147023278",
+      "required": true
+    },
+    {
+      "signal": "installer_exit_1618",
+      "source": "event_data",
+      "eventType": "app_install_failed",
+      "dataField": "exitCode",
+      "operator": "equals",
+      "value": "1618",
+      "required": false
+    },
+    {
+      "signal": "esp_failed_with_mutex_code",
+      "source": "event_data",
+      "eventType": "esp_failure_settle_started",
+      "dataField": "errorCode",
+      "operator": "equals",
+      "value": "0x80070652",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    {
+      "signal": "installer_exit_1618",
+      "condition": "exists",
+      "weight": 10
+    },
+    {
+      "signal": "esp_failed_with_mutex_code",
+      "condition": "exists",
+      "weight": 20
+    }
+  ],
+  "confidenceThreshold": 65,
+  "explanation": "App **{{appName}}** failed to install because the Windows Installer service was already busy with another installation — HRESULT **0x80070652** / MSI exit code **1618** (`ERROR_INSTALL_ALREADY_RUNNING`). Only one Windows Installer transaction can run at a time; the Intune Management Extension retried on its fixed budget (typically ~15-17 minutes across several attempts) and then reported the app as failed. If this app is required in the Enrollment Status Page, the Device Setup Apps subcategory fails with it and the enrollment terminates.\n\nThis failure is **deterministic per attempt**: as long as the competing installer keeps winning the race, a plain re-enrollment fails again at roughly the same minute mark — retrying without fixing the collision only churns devices.\n\nCommon sources of the competing installation:\n\n- The **preceding Win32 app in the install order**: its installer exits 0 (so IME moves on) but leaves a child `msiexec` transaction or post-install MSI work running. Security agents and proxy clients that chain multiple MSIs are frequent offenders.\n- **OEM factory software** installing on first boot (factory-image provisioning packages, vendor updaters) — typical on brand-new hardware batches.\n- **Microsoft 365 Apps (C2R), driver updaters or Windows servicing** running installations in parallel outside IME's control.",
+  "remediation": [
+    {
+      "title": "Identify the competing installer",
+      "steps": [
+        "In this session's timeline, note which app finished installing immediately before {{appName}} started — its installer is the prime suspect for holding the Windows Installer mutex",
+        "On a reproduction device, when the failure window is active, check for running installers: Get-Process msiexec | Select-Object Id,StartTime and the in-progress marker key HKLM\\SOFTWARE\\Microsoft\\Windows\\Installer\\InProgress",
+        "Check the Application event log for MsiInstaller events around the failure timestamp to see which product held the transaction",
+        "On factory-fresh hardware, also look for OEM first-boot installers (vendor updater services, factory provisioning packages) that run outside Intune"
+      ]
+    },
+    {
+      "title": "Serialize the install chain",
+      "steps": [
+        "Add an Intune Win32 dependency so {{appName}} depends on the app whose installer causes the collision — IME then orders them explicitly instead of racing",
+        "Alternatively, wrap the offending predecessor so its install script waits until msiexec has fully finished (poll the InProgress registry key or the _MSIExecute mutex with a bounded timeout) before exiting",
+        "If the app does not have to gate the ESP, remove it from the blocking-app list so a transient 1618 no longer terminates the enrollment; Intune retries it after the desktop"
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: MsiExec.exe error messages (1618 = another installation is in progress)",
+      "url": "https://learn.microsoft.com/en-us/windows/win32/msi/error-codes"
+    },
+    {
+      "title": "Microsoft Learn: Troubleshoot Win32 app installations in Intune",
+      "url": "https://learn.microsoft.com/en-us/troubleshoot/mem/intune/app-management/troubleshoot-win32-app-install"
+    }
+  ],
+  "tags": [
+    "apps",
+    "msiexec",
+    "mutex",
+    "0x80070652",
+    "1618",
+    "esp"
+  ]
+}
@@ -0,0 +1,98 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-APP-018",
+  "title": "App Return Code Requested a Reboot During Enrollment",
+  "description": "Detects Win32 apps whose installer exit code maps to Soft reboot or Hard reboot in the app's Intune return-code table (the '[Win32App] lpExitCode is defined as ...' line). Hard reboot stops app processing and restarts the device in Device Setup - the mid-enrollment restart and second sign-in; Soft reboot leaves the app pending until the next restart while the ESP moves on. Confidence rises for Hard reboot and when a reboot was actually observed in the session.",
+  "severity": "warning",
+  "category": "apps",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
+  "trigger": "single",
+  "baseConfidence": 60,
+  "conditions": [
+    {
+      "signal": "reboot_return_code",
+      "source": "event_data",
+      "eventType": "app_install_completed",
+      "dataField": "exitCodeClass",
+      "operator": "in",
+      "value": "SoftReboot,HardReboot",
+      "required": true
+    },
+    {
+      "signal": "hard_reboot_return_code",
+      "source": "event_data",
+      "eventType": "app_install_completed",
+      "dataField": "exitCodeClass",
+      "operator": "equals",
+      "value": "HardReboot",
+      "required": false
+    },
+    {
+      "signal": "reboot_observed",
+      "source": "event_count",
+      "eventType": "system_reboot_detected",
+      "operator": "count_gte",
+      "value": "1",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    {
+      "signal": "hard_reboot_return_code",
+      "condition": "exists",
+      "weight": 25
+    },
+    {
+      "signal": "reboot_observed",
+      "condition": "exists",
+      "weight": 15
+    }
+  ],
+  "confidenceThreshold": 60,
+  "explanation": "App **{{appName}}** returned exit code **{{exitCode}}**, which its Intune return-code table maps to **{{exitCodeClass}}** - the installer asked for a restart before its work is complete.\n\n- **SoftReboot**: the Intune Management Extension reports the app as *pending reboot*. The Enrollment Status Page treats it as completed and moves on, and Intune only marks the app installed after the next restart re-evaluates the detection rule. Until then the app may be unusable or half-configured, and the user sees a restart notification.\n- **HardReboot**: the Intune Management Extension stops processing further apps and, in Device Setup, restarts the device right away (the restart grace period does not apply during the ESP) - the same mid-enrollment restart and second sign-in that ANALYZE-ESP-005 attributes to reboot-required policies. In Account Setup the extension does not restart the device itself and the app stays pending.\n\nA restart requested by an installer is normal for many MSI packages (exit codes 3010 and 1641), but during Autopilot it lengthens the ESP, can surprise the user with a restart, and hides the app's real state until after the reboot. The return-code class is the app's own configuration in Intune, not a device fault.",
+  "remediation": [
+    {
+      "title": "Check the app's return-code mapping",
+      "steps": [
+        "Open the app in the Intune admin center > Properties > Program and review the return codes table: exit code {{exitCode}} is currently mapped to {{exitCodeClass}}",
+        "If the installer only recommends a restart (MSI 3010 ERROR_SUCCESS_REBOOT_REQUIRED, 1641 ERROR_SUCCESS_REBOOT_INITIATED), map the code to Soft reboot instead of Hard reboot so the next app can install before the restart",
+        "If the app works without an immediate restart, suppress the installer's own reboot (for MSI: REBOOT=ReallySuppress on the install command) so it returns 0 and the restart happens on your schedule",
+        "Keep Hard reboot only when the following apps genuinely cannot install before the restart - and then expect the mid-ESP restart in every enrollment"
+      ]
+    },
+    {
+      "title": "Take the app out of the ESP critical path",
+      "steps": [
+        "If the app is not needed for first use, remove it from the ESP blocking-app list so the restart happens after the user reaches the desktop",
+        "If it must stay blocking, order it last in Device Setup (dependencies or install order) so a hard reboot does not interrupt the remaining apps",
+        "For Soft reboot apps, plan a restart at the end of enrollment or accept that the app finishes on the user's first restart"
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: Add a Win32 app - Program step (device restart behavior and return codes)",
+      "url": "https://learn.microsoft.com/en-us/intune/app-management/deployment/add-win32#step-2-program"
+    },
+    {
+      "title": "Microsoft Learn: Enrollment Status Page tracking",
+      "url": "https://learn.microsoft.com/en-us/autopilot/enrollment-status"
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": [
+    "apps",
+    "reboot",
+    "return-code",
+    "soft-reboot",
+    "hard-reboot",
+    "esp",
+    "second-sign-in"
+  ]
+}
@@ -2,7 +2,7 @@
  "$schema": "../schema/analyze-rule.schema.json",
  "ruleId": "ANALYZE-DEV-007",
  "title": "System Clock Skew — TPM Attestation and ESP Timeout Risk",
-  "description": "The device's real-time clock deviates from NTP by more than two minutes. Microsoft documents that a clock off by several minutes causes TPM attestation errors (self-deploying/pre-provisioning) and ESP timeouts. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md.",
+  "description": "The device's real-time clock deviates from NTP by more than two minutes. Microsoft documents that a clock off by several minutes causes TPM attestation errors (self-deploying/pre-provisioning) and ESP timeouts.",
  "severity": "warning",
  "category": "device",
  "version": "1.1.0",
@@ -0,0 +1,69 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-DEV-008",
+  "title": "Device Clock Wrong During Enrollment — Jump or Sustained Offset",
+  "description": "The device's clock changed by five or more minutes mid-session (clock jump) or ran five or more minutes off server time for the whole session (sustained offset), measured against the server receive frame of every uploaded event. Complements ANALYZE-DEV-007, which is a one-shot NTP check at agent startup and misses devices where NTP was unreachable or the clock changed later. IME-log-derived events are excluded from the measurement.",
+  "severity": "warning",
+  "category": "device",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed"
+  ],
+  "trigger": "single",
+  "baseConfidence": 60,
+  "confidenceThreshold": 50,
+  "conditions": [
+    {
+      "signal": "clock_jump",
+      "source": "clock_skew",
+      "skewMetric": "clock_jump",
+      "operator": "gte",
+      "value": "300",
+      "required": false
+    },
+    {
+      "signal": "sustained_offset",
+      "source": "clock_skew",
+      "skewMetric": "sustained_offset",
+      "operator": "gte",
+      "value": "300",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [],
+  "explanation": "This device's {{skewSummary}} (five-minute threshold). A clock that is off by five or more minutes breaks time-sensitive enrollment mechanisms: Kerberos tolerates at most 5 minutes of skew (Hybrid Join), Entra ID token validation allows about 5 minutes on token lifetimes, and freshly issued SCEP/PKCS certificates can be rejected as \"not yet valid\" when the clock is more than ~10 minutes behind the CA.\n\nUnlike ANALYZE-DEV-007 (a one-shot NTP comparison at agent startup), this finding is measured across the whole session against the server's receive time — it also catches devices where the NTP check could not run (UDP 123 blocked) or where the clock changed after startup (time sync correcting a wrong RTC, Windows auto-timezone, manual change).",
+  "remediation": [
+    {
+      "title": "Fix the device clock and time source",
+      "steps": [
+        "Check the BIOS/RTC clock and the CMOS battery if the wrong time recurs on the same hardware.",
+        "At OOBE, run 'w32tm /resync /force' (Shift+F10 command prompt) to sync with time.windows.com.",
+        "Ensure UDP port 123 to time.windows.com is open in the deployment network.",
+        "Review 'Set time automatically' and 'Set time zone automatically' behavior on the deployment image — automatic timezone changes mid-enrollment show up as clock jumps."
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: Windows Autopilot known issues — device provisioning can fail (clock skew)",
+      "url": "https://learn.microsoft.com/en-us/autopilot/known-issues"
+    },
+    {
+      "title": "Microsoft Learn: Windows Autopilot requirements — Networking (NTP)",
+      "url": "https://learn.microsoft.com/en-us/autopilot/requirements?tabs=networking"
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": [
+    "device",
+    "clock-skew",
+    "clock-jump",
+    "time-sync",
+    "kerberos",
+    "certificates",
+    "known-issue"
+  ]
+}
@@ -0,0 +1,48 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-DEV-009",
+  "title": "Battery Critically Low During Enrollment",
+  "description": "Detects that the device's battery dropped to 15% or less while enrolling on battery power (power_state_change threshold event from the agent's live power watcher). A device dying mid-enrollment leaves a half-provisioned state that typically needs a full reset; this rule surfaces the risk while there is still time to plug the device in. Uses a single required condition on the agent-stamped thresholdPercent field (the data field 'transition' on the event is unrelated to this rule's 'trigger' property).",
+  "severity": "high",
+  "category": "device",
+  "version": "1.0.0",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:power_state_change"
+  ],
+  "trigger": "single",
+  "baseConfidence": 90,
+  "confidenceThreshold": 60,
+  "conditions": [
+    {
+      "signal": "battery_threshold_15",
+      "source": "event_data",
+      "eventType": "power_state_change",
+      "dataField": "thresholdPercent",
+      "operator": "equals",
+      "value": "15",
+      "required": true
+    }
+  ],
+  "explanation": "The device's battery fell below **{{thresholdPercent}}%** while the enrollment was running on battery power. If the battery drains completely mid-enrollment, the device is left in a half-provisioned state — apps, policies, or the user profile may be incomplete, and in most cases the device has to be reset and re-enrolled. The agent detected the threshold crossing live via a Windows power-status notification; the exact percentage at that moment is recorded on the matched power_state_change event in the session timeline.",
+  "remediation": [
+    {
+      "title": "Secure power for the running enrollment",
+      "steps": [
+        "Connect the device to AC power immediately — the enrollment continues normally once power is stable.",
+        "If the device shut down before completing, check whether the session reached the desktop; if not, reset the device (Autopilot reset or reimage) and re-enroll it plugged in.",
+        "For technician/White Glove flows, make AC power part of the bench checklist — pre-provisioning on battery is the most common source of this alert.",
+        "If this fires across many devices of one model, review that model's battery health (the hardware_spec event carries design vs. full-charge capacity)."
+      ]
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": [
+    "device",
+    "power",
+    "battery",
+    "environment"
+  ]
+}
@@ -0,0 +1,48 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-DEV-010",
+  "title": "Enrollment Switched From AC to Battery Power",
+  "description": "Detects that the device lost AC power and switched to battery while the enrollment was running (power_state_change event with transition ac_to_battery from the agent's live power watcher). Uses a single required condition so the match is pinned to one event instance; the event payload carries the battery percentage at the moment of the switch. The agent debounces power flapping (5s) so a brief unplug/replug does not produce this event.",
+  "severity": "warning",
+  "category": "device",
+  "version": "1.0.0",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:power_state_change"
+  ],
+  "trigger": "single",
+  "baseConfidence": 85,
+  "confidenceThreshold": 60,
+  "conditions": [
+    {
+      "signal": "switched_to_battery",
+      "source": "event_data",
+      "eventType": "power_state_change",
+      "dataField": "transition",
+      "operator": "equals",
+      "value": "ac_to_battery",
+      "required": true
+    }
+  ],
+  "explanation": "The device switched from AC to battery power mid-enrollment. Enrollments are power-hungry — app downloads, Windows Update and disk encryption drain a battery quickly, and Windows may also throttle CPU and network on battery, slowing the enrollment down. The battery percentage at the moment of the switch is recorded on the matched power_state_change event in the session timeline; if the device stayed on battery, look there for subsequent threshold events (50/30/15%) — a later battery_to_ac event means power was restored.",
+  "remediation": [
+    {
+      "title": "Restore AC power",
+      "steps": [
+        "Reconnect the device to AC power; the enrollment continues normally.",
+        "Check the session timeline for a subsequent battery_to_ac event (power restored) or threshold_crossed events (battery draining) to judge urgency.",
+        "If this alert is frequent in a deployment area, check docking stations/USB-C hubs for loose power delivery — a flapping dock is a common cause.",
+        "Make 'plugged in during setup' part of the end-user/technician enrollment instructions."
+      ]
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": [
+    "device",
+    "power",
+    "battery",
+    "environment"
+  ]
+}
@@ -0,0 +1,52 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-DEV-012",
+  "title": "Device Entered Standby During Enrollment",
+  "description": "Detects that the device completed a sleep, hibernate or Modern Standby episode of at least 5 minutes while the enrollment was running (system_sleep_episode event from the agent's system timeline watcher, recorded retroactively at wake from the Windows event log). The watcher also backfills pre-agent episodes from the last 24 h for timeline context (backfilled=true); those ended before the enrollment started and are excluded via the same-event filter backfilled equals false — a separate condition could not do that, because each condition scans all events on its own and a pre-session hibernate would still satisfy the duration test. A single required condition keeps the match pinned to one event instance so the interpolated duration is the matched value. Short Modern Standby screen-off scenarios (under 60 s of real sleep) never emit the event, and this rule adds a 5-minute floor so brief lid-close moments do not fire it.",
+  "severity": "info",
+  "category": "device",
+  "version": "1.1.0",
+  "enabled": true,
+  "evaluateOn": [
+    "enrollment_end",
+    "whiteglove_sealed",
+    "on_event:system_sleep_episode"
+  ],
+  "trigger": "single",
+  "baseConfidence": 90,
+  "confidenceThreshold": 60,
+  "conditions": [
+    {
+      "signal": "slept_during_enrollment",
+      "source": "event_data",
+      "eventType": "system_sleep_episode",
+      "dataField": "durationSeconds",
+      "operator": "gte",
+      "value": "300",
+      "filterField": "backfilled",
+      "filterOperator": "equals",
+      "filterValue": "false",
+      "required": true
+    }
+  ],
+  "explanation": "The device was asleep for {{durationSeconds}} seconds during the enrollment window. Nothing progresses while the device sleeps — downloads pause, the IME stops processing and the ESP simply waits — so the wall-clock enrollment duration includes this pause and can look much slower than the enrollment actually was. The matched system_sleep_episode event in the session timeline carries the exact enter/exit times, the episode kind (sleep, hibernate or Modern Standby) and, for Modern Standby, whether the device was on AC power. A long unexplained gap in the timeline right before that event is this pause, not missing telemetry.",
+  "remediation": [
+    {
+      "title": "Keep the device awake during enrollment",
+      "steps": [
+        "Check the matched system_sleep_episode event in the timeline for the episode bounds and kind — the enrollment duration minus the episode duration is the real active time.",
+        "If the device slept on battery, connect AC power during setup; Windows sleeps far more aggressively on battery.",
+        "Instruct users/technicians to keep the lid open and the device powered until the enrollment finishes.",
+        "For recurring cases, review the power plan applied during OOBE/ESP (e.g. via provisioning or Intune policy) — consider disabling sleep on AC for the enrollment window."
+      ]
+    }
+  ],
+  "markSessionAsFailedDefault": false,
+  "tags": [
+    "device",
+    "power",
+    "standby",
+    "sleep",
+    "environment"
+  ]
+}
@@ -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'. 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).",
+  "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.",
  "severity": "high",
  "category": "enrollment",
  "version": "1.1.0",
@@ -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. 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).",
+  "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.",
  "severity": "high",
  "category": "enrollment",
  "version": "1.1.0",
@@ -2,7 +2,7 @@
  "$schema": "../schema/analyze-rule.schema.json",
  "ruleId": "ANALYZE-ENRL-005",
  "title": "Hybrid Join Timeout 0x80004005 — Fixed by Windows Update",
-  "description": "A Microsoft Entra hybrid join Autopilot deployment hit error 0x80004005 — a documented build-dependent known issue, resolved by KB5065789 (25H2, build >= 26200.6725), KB5065426 (24H2, build >= 26100.6584), and KB5070312 (23H2, build >= 22631.6276). Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+  "description": "A Microsoft Entra hybrid join Autopilot deployment hit error 0x80004005 — a documented build-dependent known issue, resolved by KB5065789 (25H2, build >= 26200.6725), KB5065426 (24H2, build >= 26100.6584), and KB5070312 (23H2, build >= 22631.6276).",
  "severity": "high",
  "category": "enrollment",
  "version": "1.1.0",
@@ -5,7 +5,7 @@
  "description": "Detects when the LocalAdminAnalyzer flags unexpected local user accounts or profile directories on the device. This is a known Autopilot bypass technique where admin accounts are created before or during enrollment to gain persistent local admin access.",
  "severity": "high",
  "category": "identity",
-  "version": "1.1.0",
+  "version": "1.3.0",
  "author": "Autopilot Monitor",
  "enabled": true,
  "evaluateOn": [
@@ -56,7 +56,7 @@
    }
  ],
  "confidenceThreshold": 50,
-  "explanation": "The agent detected unexpected local user accounts or profile directories on this device that are not in the built-in or tenant-configured allowed list.\n\nThis is a security-relevant finding. Creating local admin accounts before or during Autopilot enrollment is a known bypass technique (e.g. via BypassNRO or Shift+F10 during OOBE) that grants persistent local administrator access.\n\nClick the event link below to jump to the local_admin_analysis event and check: unexpected_accounts (local user accounts not on the allowed list), unexpected_profiles (C:\\Users profile directories not on the allowed list), bypass_nro (whether the BypassNRO registry flag was set), and confidence_score (the agent's confidence in the finding, 0-100).\n\nIf these accounts are expected for your environment (e.g. a service account or helpdesk account), add them to the allowed list in Tenant Settings.",
+  "explanation": "The agent detected unexpected local user accounts or profile directories on this device that are not in the built-in or tenant-configured allowed list.\n\nThis is a security-relevant finding. Creating local admin accounts before or during Autopilot enrollment is a known bypass technique (e.g. via BypassNRO or Shift+F10 during OOBE) that grants persistent local administrator access.\n\nClick the event link below to jump to the local_admin_analysis event and check: unexpected_accounts (local user accounts not on the allowed list — disabled accounts included, a dormant account can be re-enabled later), unexpected_admin_members (unexpected accounts that are members of the local Administrators group — the actual backdoor), account_details (per account: disabled state and Administrators membership), unexpected_profiles (C:\\Users profile directories not on the allowed list), logged_in_local_accounts (local accounts that were signed in when the shutdown scan ran — a signed-in local account is never exempted, only Entra/domain users are), bypass_nro (whether the BypassNRO registry flag was set), and confidence_score (the agent's confidence in the finding, 0-100).\n\nIf these accounts are expected for your environment (e.g. a service account or helpdesk account), add them to the allowed list in Tenant Settings.",
  "remediation": [
    {
      "title": "Review the unexpected accounts",
@@ -79,7 +79,7 @@
      "steps": [
        "Check if the BypassNRO registry flag was set (indicates OOBE was bypassed)",
        "Review the enrollment timeline for Shift+F10 or other OOBE escape indicators",
-        "Check whether the unexpected account has admin group membership",
+        "Check 'unexpected_admin_members' and 'account_details' — an unexpected account with Administrators membership is a backdoor even while it is disabled (it can be re-enabled by a scheduled task after enrollment)",
        "Consider re-imaging the device if unauthorized admin access is confirmed"
      ]
    }
@@ -2,14 +2,14 @@
  "$schema": "../schema/analyze-rule.schema.json",
  "ruleId": "ANALYZE-ID-004",
  "title": "Hybrid Sign-In Never Establishes Entra User Affinity",
-  "description": "On a hybrid-joined device the real user reached the desktop, but the Autopilot provisioning placeholder stayed active in JoinInfo and the agent repeatedly reported the hybrid sign-in as overdue. The user session never establishes Entra user affinity (no PRT), so the Account Setup ESP re-runs on every logon and the enrollment never completes.",
+  "description": "On a hybrid-joined device the real user reached the desktop, but the Intune Management Extension never acquired a Microsoft Entra user token for that user within the wait window — repeatedly across reboots when the warning recurs. Without a user token the signed-in user has no Entra user affinity: user-targeted apps and policies cannot apply, Windows Hello for Business cannot provision, and with a user ESP the Account Setup page re-runs on every logon.",
  "severity": "high",
  "category": "identity",
-  "version": "1.2.0",
+  "version": "2.0.0",
  "author": "Autopilot Monitor",
  "enabled": true,
  "trigger": "correlation",
-  "evaluateOn": ["enrollment_end", "on_event:hybrid_login_pending"],
+  "evaluateOn": ["enrollment_end", "on_event:entra_user_affinity_pending"],
  "baseConfidence": 60,
  "confidenceThreshold": 75,
  "preconditions": [
@@ -17,14 +17,14 @@
      "source": "event_data",
      "eventType": "enrollment_complete",
      "operator": "not_exists",
-      "description": "Suppress when the session eventually completed — a single overdue-login warning followed by a successful sign-in is normal hybrid latency, not a broken affinity."
+      "description": "Suppress when the session eventually completed — a single pending-affinity warning followed by a successful token acquisition is hybrid latency, not a broken affinity."
    }
  ],
  "conditions": [
    {
-      "signal": "hybrid_login_overdue",
+      "signal": "user_affinity_pending",
      "source": "event_type",
-      "eventType": "hybrid_login_pending",
+      "eventType": "entra_user_affinity_pending",
      "operator": "exists",
      "value": "",
      "required": true
@@ -38,28 +38,27 @@
      "required": true
    },
    {
-      "signal": "placeholder_still_active",
+      "signal": "no_user_token",
      "source": "event_type",
-      "eventType": "aad_placeholder_user_detected",
-      "operator": "exists",
+      "eventType": "ime_user_token_acquired",
+      "operator": "not_exists",
      "value": "",
-      "required": false
+      "required": true
    }
  ],
  "confidenceFactors": [
-    { "signal": "hybrid_login_pending", "condition": "count >= 2", "weight": 20 },
-    { "signal": "hybrid_login_pending", "condition": "count >= 3", "weight": 10 },
-    { "signal": "aad_placeholder_user_detected", "condition": "count >= 3", "weight": 10 }
+    { "signal": "entra_user_affinity_pending", "condition": "count >= 2", "weight": 20 },
+    { "signal": "entra_user_affinity_pending", "condition": "count >= 3", "weight": 10 }
  ],
-  "explanation": "A real user signed in and reached the desktop, but the device kept reporting the **Autopilot provisioning placeholder** as the active identity in JoinInfo and the hybrid sign-in as **overdue** — across multiple reboots. This means the signed-in user never established **Microsoft Entra user affinity** (no Primary Refresh Token), so:\n\n- the Account Setup ESP page re-appears on every logon,\n- user-targeted required apps and policies cannot settle,\n- the enrollment never reaches completion.\n\nAfter this many hours this is not normal Entra Connect sync latency — something is structurally preventing the user (or the computer object) from registering:\n\n- the computer object's `userCertificate` attribute is not syncing to Entra ID (sync scope / OU filtering),\n- the signing-in user is not synced, or their UPN does not match a verified Entra domain,\n- the device has no line of sight to a domain controller **at logon time**, so the hybrid PRT flow cannot finish,\n- time skew or a proxy blocking `login.microsoftonline.com` / `enterpriseregistration.windows.net` from the user context.\n\nA frequent variant: the user's **first sign-in happens without domain-controller reachability** — for example when a pre-logon VPN tunnel (GlobalProtect, Always On VPN, Zscaler ZPA) is not established yet at the logon screen. Windows falls back to cached credentials, the hybrid PRT flow silently never runs, and later reboots do not fix it — sessions in this state typically show repeated reboots and network flapping while the placeholder identity stays active.\n\nA visible side effect: **the Windows Hello for Business wizard never appears**, because Hello provisioning requires an Entra user token (PRT). Hello is a downstream symptom here, not the cause.",
+  "explanation": "**What was measured.** A real user signed in and reached the desktop (`desktop_arrived`), and by the end of the agent's wait window the Intune Management Extension (IME) had still not acquired a **Microsoft Entra user token** for that user (`entra_user_affinity_pending`). That event lists the IME token error codes observed after the desktop (`tokenFailureCodes`) and how often the acquisition failed (`tokenFailureCount`). Each agent run reports this at most once, so a second or third occurrence means the same outcome across reboots — that repetition is what raises the confidence of this finding. No `ime_user_token_acquired` event followed in this session.\n\n**Why this means no user affinity.** IME's user check-in acquires the user token through the Windows web account manager (WAM), which needs the signed-in user's Entra identity — the Primary Refresh Token (PRT) that a hybrid sign-in establishes at logon. When that PRT was never issued, every token request fails and the user has **no Entra user affinity** on this device. Consequences:\n\n- user-targeted required apps and policies cannot apply,\n- Windows Hello for Business cannot provision (it requires a user token),\n- with a user ESP the Account Setup page re-appears on every logon instead of completing.\n\n**What this diagnosis does not use.** The Autopilot provisioning placeholder in JoinInfo (`aad_placeholder_user_detected`) is not part of this finding — on hybrid devices it can stay present through a perfectly healthy sign-in. Likewise, `dsregcmd /status` collected by the agent runs as SYSTEM and shows only the **device** join state; the per-user PRT state is visible only when the command runs as the signed-in user.\n\n**Typical causes** — something structurally prevents the user (or the computer object) from registering:\n\n- the computer object's `userCertificate` attribute is not syncing to Entra ID (sync scope / OU filtering),\n- the signing-in user is not synced, or their UPN does not match a verified Entra domain,\n- the device has no line of sight to a domain controller **at logon time**, so the hybrid PRT flow cannot finish,\n- time skew or a proxy blocking `login.microsoftonline.com` / `enterpriseregistration.windows.net` from the user context.\n\nA frequent variant: the user's **first sign-in happens without domain-controller reachability** — for example when a pre-logon VPN tunnel (GlobalProtect, Always On VPN, Zscaler ZPA) is not established yet at the logon screen. Windows falls back to cached credentials, the hybrid PRT flow silently never runs, and later reboots do not fix it.\n\nThe `device_registration_event` entries in the timeline (User Device Registration events 304/305) carry the OS-side record of the failed registration; the error codes in `entra_user_affinity_pending` carry the token side. A missing Windows Hello for Business wizard is a downstream symptom here, not the cause.",
  "remediation": [
    {
      "title": "Verify user affinity on the device",
      "steps": [
        "Sign in as the affected user and run: dsregcmd /status — under 'SSO State' the value AzureAdPrt must be YES. NO means the user has no Entra token and this diagnosis is confirmed.",
-        "Also check 'Device State': AzureAdJoined = YES and DomainJoined = YES are expected for hybrid join.",
-        "Check Event Viewer: Applications and Services Logs > Microsoft > Windows > User Device Registration > Admin for PRT / registration errors (e.g. event 304/305/362).",
-        "Enable the gather rules 'Collect dsregcmd join status' so future sessions capture this state automatically."
+        "Also check 'Device State': AzureAdJoined = YES and DomainJoined = YES are expected for hybrid join — they prove the device join only, not the user's registration.",
+        "Check Event Viewer: Applications and Services Logs > Microsoft > Windows > User Device Registration > Admin for PRT / registration errors (e.g. event 304/305/362). The device_registration_event entries (304/305) in the session timeline carry the same OS-side failure record.",
+        "Enable the gather rule GATHER-DEVICE-006 (dsregcmd /status at the moment of the finding — device state only, the agent runs as SYSTEM). GATHER-DEVICE-007 and GATHER-DEVICE-008 (Microsoft-Windows-AAD/Operational events 1098 and 1097 at the same moment) are on by default."
      ]
    },
    {
@@ -0,0 +1,81 @@
+{
+  "$schema": "../schema/analyze-rule.schema.json",
+  "ruleId": "ANALYZE-NET-001",
+  "title": "Diagnostics Upload Blocked by Web Security Gateway",
+  "description": "Detects diagnostics package uploads that were answered by a security appliance's HTML block page instead of the Autopilot Monitor backend. A forward proxy / secure web gateway (SWG) with SSL inspection is intercepting the upload endpoint, so exactly the sessions where diagnostics matter most (OnFailure uploads) are the ones losing them.",
+  "severity": "warning",
+  "category": "network",
+  "version": "1.0.0",
+  "author": "Autopilot Monitor",
+  "enabled": true,
+  "baseConfidence": 75,
+  "conditions": [
+    {
+      "signal": "foreign_html_response",
+      "source": "event_data",
+      "eventType": "diagnostics_upload_failed",
+      "dataField": "errorCode",
+      "operator": "contains",
+      "value": "HTML platform error page",
+      "required": true
+    },
+    {
+      "signal": "security_gateway_marker",
+      "source": "event_data",
+      "eventType": "diagnostics_upload_failed",
+      "dataField": "errorCode",
+      "operator": "regex",
+      "value": "mcafee|skyhigh|zscaler|netskope|blue ?coat|proxysg|forcepoint|websense|palo ?alto|fortigate|fortiguard|sophos|watchguard|barracuda|iboss|umbrella|lightspeed|smoothwall|contentkeeper|web ?gateway|web ?filter|content ?filter|secure ?gateway",
+      "required": true
+    },
+    {
+      "signal": "http_403_block",
+      "source": "event_data",
+      "eventType": "diagnostics_upload_failed",
+      "dataField": "errorCode",
+      "operator": "contains",
+      "value": "403",
+      "required": false
+    }
+  ],
+  "confidenceFactors": [
+    {
+      "signal": "http_403_block",
+      "condition": "exists",
+      "weight": 15
+    }
+  ],
+  "confidenceThreshold": 70,
+  "explanation": "The agent collected a diagnostics package but the upload was answered with an **HTML block page from a web security gateway** instead of a response from the Autopilot Monitor backend — the event message names the product that served the page. A forward proxy / SWG with SSL inspection is intercepting HTTPS traffic from the enrollment network and blocking the upload endpoint.\n\nThe consequence is quietly painful: diagnostics upload is typically configured **OnFailure**, so the sessions that fail — the ones where the IME logs and diagnostics ZIP would explain the root cause — are exactly the sessions whose evidence never arrives. Enrollment telemetry itself may still flow (the agent often starts before the gateway's client enforcement does, or other endpoints are treated differently), which makes the gap easy to miss until a failure needs investigating.\n\nNote this rule only fires when the blocking page carries a recognizable security-product marker. A plain HTML error page without one usually means a stale or stopped endpoint instead — that is a different problem.",
+  "remediation": [
+    {
+      "title": "Exempt the upload endpoint in the web gateway",
+      "steps": [
+        "Identify the product from the block-page title quoted in this event's message (e.g. a Skyhigh/McAfee Web Gateway notification page)",
+        "In that gateway, add the Autopilot Monitor API host shown in the event message to the SSL-inspection bypass AND the URL allowlist for the enrollment network segment",
+        "Enrollment traffic often originates from a dedicated provisioning VLAN or from devices without the proxy client yet — make sure the exemption applies to that segment, not only to managed clients",
+        "If the gateway enforces per-user policy, remember ESP-phase traffic runs as SYSTEM/device before any user signs in — the exemption must cover unauthenticated device traffic"
+      ]
+    },
+    {
+      "title": "Verify the fix",
+      "steps": [
+        "Re-run an enrollment (or wait for the next failed one) and confirm a diagnostics package appears on the session in the portal",
+        "Optionally set diagnostics upload to Always temporarily to validate the path without needing a failure"
+      ]
+    }
+  ],
+  "relatedDocs": [
+    {
+      "title": "Microsoft Learn: Windows Autopilot networking requirements",
+      "url": "https://learn.microsoft.com/en-us/autopilot/networking-requirements"
+    }
+  ],
+  "tags": [
+    "network",
+    "proxy",
+    "ssl-inspection",
+    "swg",
+    "diagnostics"
+  ]
+}
@@ -615,7 +615,7 @@
      "description": "Detects when the Enrollment Status Page failed on the Apps subcategory and the agent's AppX deployment log scan identified a suspected MSIX/Store package. Store/MSIX apps install outside the Win32 pipeline, so the regular per-app tracking sees nothing — this correlation names the likely culprit.",
      "severity": "warning",
      "category": "apps",
-      "version": "1.2.0",
+      "version": "1.2.1",
      "enabled": true,
      "evaluateOn": [
        "enrollment_end",
@@ -703,7 +703,7 @@
          "steps": [
            "Open Event Viewer → Applications and Services Logs → Microsoft → Windows → AppXDeploymentServer → Operational on the device (or in the diagnostics archive if uploaded)",
            "Filter for Error-level events around the ESP failure time and confirm the package name and HRESULT match this finding",
-            "Look up the HRESULT: 0x80073cf9 = generic install failure, 0x80073cf0 = invalid/corrupt package, 0x80073cff = sideloading/licensing policy block, 0x80073d02 = blocked because app is in use"
+            "Look up the HRESULT: 0x80073cf9 = generic install failure, 0x80073cf0 = package could not be opened (unsigned, publisher mismatch, or not found), 0x80073cff = sideloading/licensing policy block, 0x80073d02 = blocked because app is in use"
          ]
        },
        {
@@ -943,6 +943,194 @@
        "delivery-gap"
      ]
    },
+    {
+      "ruleId": "ANALYZE-APP-017",
+      "title": "App Install Blocked by Another Installer (0x80070652)",
+      "description": "Detects Win32 app installs that failed because the Windows Installer was busy with another installation (HRESULT 0x80070652 / MSI exit code 1618, ERROR_INSTALL_ALREADY_RUNNING). The IME retries on a fixed budget (~15-17 minutes across several attempts) and then reports the app as failed; when the app is ESP-blocking, the Device Setup Apps subcategory terminates with it.",
+      "severity": "high",
+      "category": "apps",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "baseConfidence": 70,
+      "conditions": [
+        {
+          "signal": "mutex_blocked_install",
+          "source": "event_type",
+          "eventType": "app_install_failed",
+          "dataField": "hresultFromWin32",
+          "operator": "equals",
+          "value": "-2147023278",
+          "required": true
+        },
+        {
+          "signal": "installer_exit_1618",
+          "source": "event_data",
+          "eventType": "app_install_failed",
+          "dataField": "exitCode",
+          "operator": "equals",
+          "value": "1618",
+          "required": false
+        },
+        {
+          "signal": "esp_failed_with_mutex_code",
+          "source": "event_data",
+          "eventType": "esp_failure_settle_started",
+          "dataField": "errorCode",
+          "operator": "equals",
+          "value": "0x80070652",
+          "required": false
+        }
+      ],
+      "confidenceFactors": [
+        {
+          "signal": "installer_exit_1618",
+          "condition": "exists",
+          "weight": 10
+        },
+        {
+          "signal": "esp_failed_with_mutex_code",
+          "condition": "exists",
+          "weight": 20
+        }
+      ],
+      "confidenceThreshold": 65,
+      "explanation": "App **{{appName}}** failed to install because the Windows Installer service was already busy with another installation — HRESULT **0x80070652** / MSI exit code **1618** (`ERROR_INSTALL_ALREADY_RUNNING`). Only one Windows Installer transaction can run at a time; the Intune Management Extension retried on its fixed budget (typically ~15-17 minutes across several attempts) and then reported the app as failed. If this app is required in the Enrollment Status Page, the Device Setup Apps subcategory fails with it and the enrollment terminates.\n\nThis failure is **deterministic per attempt**: as long as the competing installer keeps winning the race, a plain re-enrollment fails again at roughly the same minute mark — retrying without fixing the collision only churns devices.\n\nCommon sources of the competing installation:\n\n- The **preceding Win32 app in the install order**: its installer exits 0 (so IME moves on) but leaves a child `msiexec` transaction or post-install MSI work running. Security agents and proxy clients that chain multiple MSIs are frequent offenders.\n- **OEM factory software** installing on first boot (factory-image provisioning packages, vendor updaters) — typical on brand-new hardware batches.\n- **Microsoft 365 Apps (C2R), driver updaters or Windows servicing** running installations in parallel outside IME's control.",
+      "remediation": [
+        {
+          "title": "Identify the competing installer",
+          "steps": [
+            "In this session's timeline, note which app finished installing immediately before {{appName}} started — its installer is the prime suspect for holding the Windows Installer mutex",
+            "On a reproduction device, when the failure window is active, check for running installers: Get-Process msiexec | Select-Object Id,StartTime and the in-progress marker key HKLM\\SOFTWARE\\Microsoft\\Windows\\Installer\\InProgress",
+            "Check the Application event log for MsiInstaller events around the failure timestamp to see which product held the transaction",
+            "On factory-fresh hardware, also look for OEM first-boot installers (vendor updater services, factory provisioning packages) that run outside Intune"
+          ]
+        },
+        {
+          "title": "Serialize the install chain",
+          "steps": [
+            "Add an Intune Win32 dependency so {{appName}} depends on the app whose installer causes the collision — IME then orders them explicitly instead of racing",
+            "Alternatively, wrap the offending predecessor so its install script waits until msiexec has fully finished (poll the InProgress registry key or the _MSIExecute mutex with a bounded timeout) before exiting",
+            "If the app does not have to gate the ESP, remove it from the blocking-app list so a transient 1618 no longer terminates the enrollment; Intune retries it after the desktop"
+          ]
+        }
+      ],
+      "relatedDocs": [
+        {
+          "title": "Microsoft Learn: MsiExec.exe error messages (1618 = another installation is in progress)",
+          "url": "https://learn.microsoft.com/en-us/windows/win32/msi/error-codes"
+        },
+        {
+          "title": "Microsoft Learn: Troubleshoot Win32 app installations in Intune",
+          "url": "https://learn.microsoft.com/en-us/troubleshoot/mem/intune/app-management/troubleshoot-win32-app-install"
+        }
+      ],
+      "tags": [
+        "apps",
+        "msiexec",
+        "mutex",
+        "0x80070652",
+        "1618",
+        "esp"
+      ]
+    },
+    {
+      "ruleId": "ANALYZE-APP-018",
+      "title": "App Return Code Requested a Reboot During Enrollment",
+      "description": "Detects Win32 apps whose installer exit code maps to Soft reboot or Hard reboot in the app's Intune return-code table (the '[Win32App] lpExitCode is defined as ...' line). Hard reboot stops app processing and restarts the device in Device Setup - the mid-enrollment restart and second sign-in; Soft reboot leaves the app pending until the next restart while the ESP moves on. Confidence rises for Hard reboot and when a reboot was actually observed in the session.",
+      "severity": "warning",
+      "category": "apps",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "evaluateOn": [
+        "enrollment_end",
+        "whiteglove_sealed"
+      ],
+      "trigger": "single",
+      "baseConfidence": 60,
+      "conditions": [
+        {
+          "signal": "reboot_return_code",
+          "source": "event_data",
+          "eventType": "app_install_completed",
+          "dataField": "exitCodeClass",
+          "operator": "in",
+          "value": "SoftReboot,HardReboot",
+          "required": true
+        },
+        {
+          "signal": "hard_reboot_return_code",
+          "source": "event_data",
+          "eventType": "app_install_completed",
+          "dataField": "exitCodeClass",
+          "operator": "equals",
+          "value": "HardReboot",
+          "required": false
+        },
+        {
+          "signal": "reboot_observed",
+          "source": "event_count",
+          "eventType": "system_reboot_detected",
+          "operator": "count_gte",
+          "value": "1",
+          "required": false
+        }
+      ],
+      "confidenceFactors": [
+        {
+          "signal": "hard_reboot_return_code",
+          "condition": "exists",
+          "weight": 25
+        },
+        {
+          "signal": "reboot_observed",
+          "condition": "exists",
+          "weight": 15
+        }
+      ],
+      "confidenceThreshold": 60,
+      "explanation": "App **{{appName}}** returned exit code **{{exitCode}}**, which its Intune return-code table maps to **{{exitCodeClass}}** - the installer asked for a restart before its work is complete.\n\n- **SoftReboot**: the Intune Management Extension reports the app as *pending reboot*. The Enrollment Status Page treats it as completed and moves on, and Intune only marks the app installed after the next restart re-evaluates the detection rule. Until then the app may be unusable or half-configured, and the user sees a restart notification.\n- **HardReboot**: the Intune Management Extension stops processing further apps and, in Device Setup, restarts the device right away (the restart grace period does not apply during the ESP) - the same mid-enrollment restart and second sign-in that ANALYZE-ESP-005 attributes to reboot-required policies. In Account Setup the extension does not restart the device itself and the app stays pending.\n\nA restart requested by an installer is normal for many MSI packages (exit codes 3010 and 1641), but during Autopilot it lengthens the ESP, can surprise the user with a restart, and hides the app's real state until after the reboot. The return-code class is the app's own configuration in Intune, not a device fault.",
+      "remediation": [
+        {
+          "title": "Check the app's return-code mapping",
+          "steps": [
+            "Open the app in the Intune admin center > Properties > Program and review the return codes table: exit code {{exitCode}} is currently mapped to {{exitCodeClass}}",
+            "If the installer only recommends a restart (MSI 3010 ERROR_SUCCESS_REBOOT_REQUIRED, 1641 ERROR_SUCCESS_REBOOT_INITIATED), map the code to Soft reboot instead of Hard reboot so the next app can install before the restart",
+            "If the app works without an immediate restart, suppress the installer's own reboot (for MSI: REBOOT=ReallySuppress on the install command) so it returns 0 and the restart happens on your schedule",
+            "Keep Hard reboot only when the following apps genuinely cannot install before the restart - and then expect the mid-ESP restart in every enrollment"
+          ]
+        },
+        {
+          "title": "Take the app out of the ESP critical path",
+          "steps": [
+            "If the app is not needed for first use, remove it from the ESP blocking-app list so the restart happens after the user reaches the desktop",
+            "If it must stay blocking, order it last in Device Setup (dependencies or install order) so a hard reboot does not interrupt the remaining apps",
+            "For Soft reboot apps, plan a restart at the end of enrollment or accept that the app finishes on the user's first restart"
+          ]
+        }
+      ],
+      "relatedDocs": [
+        {
+          "title": "Microsoft Learn: Add a Win32 app - Program step (device restart behavior and return codes)",
+          "url": "https://learn.microsoft.com/en-us/intune/app-management/deployment/add-win32#step-2-program"
+        },
+        {
+          "title": "Microsoft Learn: Enrollment Status Page tracking",
+          "url": "https://learn.microsoft.com/en-us/autopilot/enrollment-status"
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "apps",
+        "reboot",
+        "return-code",
+        "soft-reboot",
+        "hard-reboot",
+        "esp",
+        "second-sign-in"
+      ]
+    },
    {
      "ruleId": "ANALYZE-CORR-003",
      "title": "Proxy Configuration Causing Download Failure",
@@ -1450,7 +1638,7 @@
    {
      "ruleId": "ANALYZE-DEV-007",
      "title": "System Clock Skew — TPM Attestation and ESP Timeout Risk",
-      "description": "The device's real-time clock deviates from NTP by more than two minutes. Microsoft documents that a clock off by several minutes causes TPM attestation errors (self-deploying/pre-provisioning) and ESP timeouts. Knowledge source: docs/agent/autopilot-ztd-diagnostics.md.",
+      "description": "The device's real-time clock deviates from NTP by more than two minutes. Microsoft documents that a clock off by several minutes causes TPM attestation errors (self-deploying/pre-provisioning) and ESP timeouts.",
      "severity": "warning",
      "category": "device",
      "version": "1.1.0",
@@ -1516,6 +1704,219 @@
        "known-issue"
      ]
    },
+    {
+      "ruleId": "ANALYZE-DEV-008",
+      "title": "Device Clock Wrong During Enrollment — Jump or Sustained Offset",
+      "description": "The device's clock changed by five or more minutes mid-session (clock jump) or ran five or more minutes off server time for the whole session (sustained offset), measured against the server receive frame of every uploaded event. Complements ANALYZE-DEV-007, which is a one-shot NTP check at agent startup and misses devices where NTP was unreachable or the clock changed later. IME-log-derived events are excluded from the measurement.",
+      "severity": "warning",
+      "category": "device",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "evaluateOn": [
+        "enrollment_end",
+        "whiteglove_sealed"
+      ],
+      "trigger": "single",
+      "baseConfidence": 60,
+      "confidenceThreshold": 50,
+      "conditions": [
+        {
+          "signal": "clock_jump",
+          "source": "clock_skew",
+          "skewMetric": "clock_jump",
+          "operator": "gte",
+          "value": "300",
+          "required": false
+        },
+        {
+          "signal": "sustained_offset",
+          "source": "clock_skew",
+          "skewMetric": "sustained_offset",
+          "operator": "gte",
+          "value": "300",
+          "required": false
+        }
+      ],
+      "confidenceFactors": [],
+      "explanation": "This device's {{skewSummary}} (five-minute threshold). A clock that is off by five or more minutes breaks time-sensitive enrollment mechanisms: Kerberos tolerates at most 5 minutes of skew (Hybrid Join), Entra ID token validation allows about 5 minutes on token lifetimes, and freshly issued SCEP/PKCS certificates can be rejected as \"not yet valid\" when the clock is more than ~10 minutes behind the CA.\n\nUnlike ANALYZE-DEV-007 (a one-shot NTP comparison at agent startup), this finding is measured across the whole session against the server's receive time — it also catches devices where the NTP check could not run (UDP 123 blocked) or where the clock changed after startup (time sync correcting a wrong RTC, Windows auto-timezone, manual change).",
+      "remediation": [
+        {
+          "title": "Fix the device clock and time source",
+          "steps": [
+            "Check the BIOS/RTC clock and the CMOS battery if the wrong time recurs on the same hardware.",
+            "At OOBE, run 'w32tm /resync /force' (Shift+F10 command prompt) to sync with time.windows.com.",
+            "Ensure UDP port 123 to time.windows.com is open in the deployment network.",
+            "Review 'Set time automatically' and 'Set time zone automatically' behavior on the deployment image — automatic timezone changes mid-enrollment show up as clock jumps."
+          ]
+        }
+      ],
+      "relatedDocs": [
+        {
+          "title": "Microsoft Learn: Windows Autopilot known issues — device provisioning can fail (clock skew)",
+          "url": "https://learn.microsoft.com/en-us/autopilot/known-issues"
+        },
+        {
+          "title": "Microsoft Learn: Windows Autopilot requirements — Networking (NTP)",
+          "url": "https://learn.microsoft.com/en-us/autopilot/requirements?tabs=networking"
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "device",
+        "clock-skew",
+        "clock-jump",
+        "time-sync",
+        "kerberos",
+        "certificates",
+        "known-issue"
+      ]
+    },
+    {
+      "ruleId": "ANALYZE-DEV-009",
+      "title": "Battery Critically Low During Enrollment",
+      "description": "Detects that the device's battery dropped to 15% or less while enrolling on battery power (power_state_change threshold event from the agent's live power watcher). A device dying mid-enrollment leaves a half-provisioned state that typically needs a full reset; this rule surfaces the risk while there is still time to plug the device in. Uses a single required condition on the agent-stamped thresholdPercent field (the data field 'transition' on the event is unrelated to this rule's 'trigger' property).",
+      "severity": "high",
+      "category": "device",
+      "version": "1.0.0",
+      "enabled": true,
+      "evaluateOn": [
+        "enrollment_end",
+        "whiteglove_sealed",
+        "on_event:power_state_change"
+      ],
+      "trigger": "single",
+      "baseConfidence": 90,
+      "confidenceThreshold": 60,
+      "conditions": [
+        {
+          "signal": "battery_threshold_15",
+          "source": "event_data",
+          "eventType": "power_state_change",
+          "dataField": "thresholdPercent",
+          "operator": "equals",
+          "value": "15",
+          "required": true
+        }
+      ],
+      "explanation": "The device's battery fell below **{{thresholdPercent}}%** while the enrollment was running on battery power. If the battery drains completely mid-enrollment, the device is left in a half-provisioned state — apps, policies, or the user profile may be incomplete, and in most cases the device has to be reset and re-enrolled. The agent detected the threshold crossing live via a Windows power-status notification; the exact percentage at that moment is recorded on the matched power_state_change event in the session timeline.",
+      "remediation": [
+        {
+          "title": "Secure power for the running enrollment",
+          "steps": [
+            "Connect the device to AC power immediately — the enrollment continues normally once power is stable.",
+            "If the device shut down before completing, check whether the session reached the desktop; if not, reset the device (Autopilot reset or reimage) and re-enroll it plugged in.",
+            "For technician/White Glove flows, make AC power part of the bench checklist — pre-provisioning on battery is the most common source of this alert.",
+            "If this fires across many devices of one model, review that model's battery health (the hardware_spec event carries design vs. full-charge capacity)."
+          ]
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "device",
+        "power",
+        "battery",
+        "environment"
+      ]
+    },
+    {
+      "ruleId": "ANALYZE-DEV-010",
+      "title": "Enrollment Switched From AC to Battery Power",
+      "description": "Detects that the device lost AC power and switched to battery while the enrollment was running (power_state_change event with transition ac_to_battery from the agent's live power watcher). Uses a single required condition so the match is pinned to one event instance; the event payload carries the battery percentage at the moment of the switch. The agent debounces power flapping (5s) so a brief unplug/replug does not produce this event.",
+      "severity": "warning",
+      "category": "device",
+      "version": "1.0.0",
+      "enabled": true,
+      "evaluateOn": [
+        "enrollment_end",
+        "whiteglove_sealed",
+        "on_event:power_state_change"
+      ],
+      "trigger": "single",
+      "baseConfidence": 85,
+      "confidenceThreshold": 60,
+      "conditions": [
+        {
+          "signal": "switched_to_battery",
+          "source": "event_data",
+          "eventType": "power_state_change",
+          "dataField": "transition",
+          "operator": "equals",
+          "value": "ac_to_battery",
+          "required": true
+        }
+      ],
+      "explanation": "The device switched from AC to battery power mid-enrollment. Enrollments are power-hungry — app downloads, Windows Update and disk encryption drain a battery quickly, and Windows may also throttle CPU and network on battery, slowing the enrollment down. The battery percentage at the moment of the switch is recorded on the matched power_state_change event in the session timeline; if the device stayed on battery, look there for subsequent threshold events (50/30/15%) — a later battery_to_ac event means power was restored.",
+      "remediation": [
+        {
+          "title": "Restore AC power",
+          "steps": [
+            "Reconnect the device to AC power; the enrollment continues normally.",
+            "Check the session timeline for a subsequent battery_to_ac event (power restored) or threshold_crossed events (battery draining) to judge urgency.",
+            "If this alert is frequent in a deployment area, check docking stations/USB-C hubs for loose power delivery — a flapping dock is a common cause.",
+            "Make 'plugged in during setup' part of the end-user/technician enrollment instructions."
+          ]
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "device",
+        "power",
+        "battery",
+        "environment"
+      ]
+    },
+    {
+      "ruleId": "ANALYZE-DEV-012",
+      "title": "Device Entered Standby During Enrollment",
+      "description": "Detects that the device completed a sleep, hibernate or Modern Standby episode of at least 5 minutes while the enrollment was running (system_sleep_episode event from the agent's system timeline watcher, recorded retroactively at wake from the Windows event log). The watcher also backfills pre-agent episodes from the last 24 h for timeline context (backfilled=true); those ended before the enrollment started and are excluded via the same-event filter backfilled equals false — a separate condition could not do that, because each condition scans all events on its own and a pre-session hibernate would still satisfy the duration test. A single required condition keeps the match pinned to one event instance so the interpolated duration is the matched value. Short Modern Standby screen-off scenarios (under 60 s of real sleep) never emit the event, and this rule adds a 5-minute floor so brief lid-close moments do not fire it.",
+      "severity": "info",
+      "category": "device",
+      "version": "1.1.0",
+      "enabled": true,
+      "evaluateOn": [
+        "enrollment_end",
+        "whiteglove_sealed",
+        "on_event:system_sleep_episode"
+      ],
+      "trigger": "single",
+      "baseConfidence": 90,
+      "confidenceThreshold": 60,
+      "conditions": [
+        {
+          "signal": "slept_during_enrollment",
+          "source": "event_data",
+          "eventType": "system_sleep_episode",
+          "dataField": "durationSeconds",
+          "operator": "gte",
+          "value": "300",
+          "filterField": "backfilled",
+          "filterOperator": "equals",
+          "filterValue": "false",
+          "required": true
+        }
+      ],
+      "explanation": "The device was asleep for {{durationSeconds}} seconds during the enrollment window. Nothing progresses while the device sleeps — downloads pause, the IME stops processing and the ESP simply waits — so the wall-clock enrollment duration includes this pause and can look much slower than the enrollment actually was. The matched system_sleep_episode event in the session timeline carries the exact enter/exit times, the episode kind (sleep, hibernate or Modern Standby) and, for Modern Standby, whether the device was on AC power. A long unexplained gap in the timeline right before that event is this pause, not missing telemetry.",
+      "remediation": [
+        {
+          "title": "Keep the device awake during enrollment",
+          "steps": [
+            "Check the matched system_sleep_episode event in the timeline for the episode bounds and kind — the enrollment duration minus the episode duration is the real active time.",
+            "If the device slept on battery, connect AC power during setup; Windows sleeps far more aggressively on battery.",
+            "Instruct users/technicians to keep the lid open and the device powered until the enrollment finishes.",
+            "For recurring cases, review the power plan applied during OOBE/ESP (e.g. via provisioning or Intune policy) — consider disabling sleep on AC for the enrollment window."
+          ]
+        }
+      ],
+      "markSessionAsFailedDefault": false,
+      "tags": [
+        "device",
+        "power",
+        "standby",
+        "sleep",
+        "environment"
+      ]
+    },
    {
      "ruleId": "ANALYZE-ENRL-001",
      "title": "Enrollment Failed",
@@ -1686,7 +2087,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'. 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).",
+      "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.",
      "severity": "high",
      "category": "enrollment",
      "version": "1.1.0",
@@ -1776,7 +2177,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. 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).",
+      "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.",
      "severity": "high",
      "category": "enrollment",
      "version": "1.1.0",
@@ -1863,7 +2264,7 @@
    {
      "ruleId": "ANALYZE-ENRL-005",
      "title": "Hybrid Join Timeout 0x80004005 — Fixed by Windows Update",
-      "description": "A Microsoft Entra hybrid join Autopilot deployment hit error 0x80004005 — a documented build-dependent known issue, resolved by KB5065789 (25H2, build >= 26200.6725), KB5065426 (24H2, build >= 26100.6584), and KB5070312 (23H2, build >= 22631.6276). Knowledge source: docs/agent/autopilot-ztd-diagnostics.md (error-code map).",
+      "description": "A Microsoft Entra hybrid join Autopilot deployment hit error 0x80004005 — a documented build-dependent known issue, resolved by KB5065789 (25H2, build >= 26200.6725), KB5065426 (24H2, build >= 26100.6584), and KB5070312 (23H2, build >= 22631.6276).",
      "severity": "high",
      "category": "enrollment",
      "version": "1.1.0",
@@ -2465,7 +2866,7 @@
      "description": "Detects when the LocalAdminAnalyzer flags unexpected local user accounts or profile directories on the device. This is a known Autopilot bypass technique where admin accounts are created before or during enrollment to gain persistent local admin access.",
      "severity": "high",
      "category": "identity",
-      "version": "1.1.0",
+      "version": "1.3.0",
      "author": "Autopilot Monitor",
      "enabled": true,
      "evaluateOn": [
@@ -2516,7 +2917,7 @@
        }
      ],
      "confidenceThreshold": 50,
-      "explanation": "The agent detected unexpected local user accounts or profile directories on this device that are not in the built-in or tenant-configured allowed list.\n\nThis is a security-relevant finding. Creating local admin accounts before or during Autopilot enrollment is a known bypass technique (e.g. via BypassNRO or Shift+F10 during OOBE) that grants persistent local administrator access.\n\nClick the event link below to jump to the local_admin_analysis event and check: unexpected_accounts (local user accounts not on the allowed list), unexpected_profiles (C:\\Users profile directories not on the allowed list), bypass_nro (whether the BypassNRO registry flag was set), and confidence_score (the agent's confidence in the finding, 0-100).\n\nIf these accounts are expected for your environment (e.g. a service account or helpdesk account), add them to the allowed list in Tenant Settings.",
+      "explanation": "The agent detected unexpected local user accounts or profile directories on this device that are not in the built-in or tenant-configured allowed list.\n\nThis is a security-relevant finding. Creating local admin accounts before or during Autopilot enrollment is a known bypass technique (e.g. via BypassNRO or Shift+F10 during OOBE) that grants persistent local administrator access.\n\nClick the event link below to jump to the local_admin_analysis event and check: unexpected_accounts (local user accounts not on the allowed list — disabled accounts included, a dormant account can be re-enabled later), unexpected_admin_members (unexpected accounts that are members of the local Administrators group — the actual backdoor), account_details (per account: disabled state and Administrators membership), unexpected_profiles (C:\\Users profile directories not on the allowed list), logged_in_local_accounts (local accounts that were signed in when the shutdown scan ran — a signed-in local account is never exempted, only Entra/domain users are), bypass_nro (whether the BypassNRO registry flag was set), and confidence_score (the agent's confidence in the finding, 0-100).\n\nIf these accounts are expected for your environment (e.g. a service account or helpdesk account), add them to the allowed list in Tenant Settings.",
      "remediation": [
        {
          "title": "Review the unexpected accounts",
@@ -2539,7 +2940,7 @@
          "steps": [
            "Check if the BypassNRO registry flag was set (indicates OOBE was bypassed)",
            "Review the enrollment timeline for Shift+F10 or other OOBE escape indicators",
-            "Check whether the unexpected account has admin group membership",
+            "Check 'unexpected_admin_members' and 'account_details' — an unexpected account with Administrators membership is a backdoor even while it is disabled (it can be re-enabled by a scheduled task after enrollment)",
            "Consider re-imaging the device if unauthorized admin access is confirmed"
          ]
        }
@@ -2636,16 +3037,16 @@
    {
      "ruleId": "ANALYZE-ID-004",
      "title": "Hybrid Sign-In Never Establishes Entra User Affinity",
-      "description": "On a hybrid-joined device the real user reached the desktop, but the Autopilot provisioning placeholder stayed active in JoinInfo and the agent repeatedly reported the hybrid sign-in as overdue. The user session never establishes Entra user affinity (no PRT), so the Account Setup ESP re-runs on every logon and the enrollment never completes.",
+      "description": "On a hybrid-joined device the real user reached the desktop, but the Intune Management Extension never acquired a Microsoft Entra user token for that user within the wait window — repeatedly across reboots when the warning recurs. Without a user token the signed-in user has no Entra user affinity: user-targeted apps and policies cannot apply, Windows Hello for Business cannot provision, and with a user ESP the Account Setup page re-runs on every logon.",
      "severity": "high",
      "category": "identity",
-      "version": "1.2.0",
+      "version": "2.0.0",
      "author": "Autopilot Monitor",
      "enabled": true,
      "trigger": "correlation",
      "evaluateOn": [
        "enrollment_end",
-        "on_event:hybrid_login_pending"
+        "on_event:entra_user_affinity_pending"
      ],
      "baseConfidence": 60,
      "confidenceThreshold": 75,
@@ -2654,14 +3055,14 @@
          "source": "event_data",
          "eventType": "enrollment_complete",
          "operator": "not_exists",
-          "description": "Suppress when the session eventually completed — a single overdue-login warning followed by a successful sign-in is normal hybrid latency, not a broken affinity."
+          "description": "Suppress when the session eventually completed — a single pending-affinity warning followed by a successful token acquisition is hybrid latency, not a broken affinity."
        }
      ],
      "conditions": [
        {
-          "signal": "hybrid_login_overdue",
+          "signal": "user_affinity_pending",
          "source": "event_type",
-          "eventType": "hybrid_login_pending",
+          "eventType": "entra_user_affinity_pending",
          "operator": "exists",
          "value": "",
          "required": true
@@ -2675,40 +3076,35 @@
          "required": true
        },
        {
-          "signal": "placeholder_still_active",
+          "signal": "no_user_token",
          "source": "event_type",
-          "eventType": "aad_placeholder_user_detected",
-          "operator": "exists",
+          "eventType": "ime_user_token_acquired",
+          "operator": "not_exists",
          "value": "",
-          "required": false
+          "required": true
        }
      ],
      "confidenceFactors": [
        {
-          "signal": "hybrid_login_pending",
+          "signal": "entra_user_affinity_pending",
          "condition": "count >= 2",
          "weight": 20
        },
        {
-          "signal": "hybrid_login_pending",
-          "condition": "count >= 3",
-          "weight": 10
-        },
-        {
-          "signal": "aad_placeholder_user_detected",
+          "signal": "entra_user_affinity_pending",
          "condition": "count >= 3",
          "weight": 10
        }
      ],
-      "explanation": "A real user signed in and reached the desktop, but the device kept reporting the **Autopilot provisioning placeholder** as the active identity in JoinInfo and the hybrid sign-in as **overdue** — across multiple reboots. This means the signed-in user never established **Microsoft Entra user affinity** (no Primary Refresh Token), so:\n\n- the Account Setup ESP page re-appears on every logon,\n- user-targeted required apps and policies cannot settle,\n- the enrollment never reaches completion.\n\nAfter this many hours this is not normal Entra Connect sync latency — something is structurally preventing the user (or the computer object) from registering:\n\n- the computer object's `userCertificate` attribute is not syncing to Entra ID (sync scope / OU filtering),\n- the signing-in user is not synced, or their UPN does not match a verified Entra domain,\n- the device has no line of sight to a domain controller **at logon time**, so the hybrid PRT flow cannot finish,\n- time skew or a proxy blocking `login.microsoftonline.com` / `enterpriseregistration.windows.net` from the user context.\n\nA frequent variant: the user's **first sign-in happens without domain-controller reachability** — for example when a pre-logon VPN tunnel (GlobalProtect, Always On VPN, Zscaler ZPA) is not established yet at the logon screen. Windows falls back to cached credentials, the hybrid PRT flow silently never runs, and later reboots do not fix it — sessions in this state typically show repeated reboots and network flapping while the placeholder identity stays active.\n\nA visible side effect: **the Windows Hello for Business wizard never appears**, because Hello provisioning requires an Entra user token (PRT). Hello is a downstream symptom here, not the cause.",
+      "explanation": "**What was measured.** A real user signed in and reached the desktop (`desktop_arrived`), and by the end of the agent's wait window the Intune Management Extension (IME) had still not acquired a **Microsoft Entra user token** for that user (`entra_user_affinity_pending`). That event lists the IME token error codes observed after the desktop (`tokenFailureCodes`) and how often the acquisition failed (`tokenFailureCount`). Each agent run reports this at most once, so a second or third occurrence means the same outcome across reboots — that repetition is what raises the confidence of this finding. No `ime_user_token_acquired` event followed in this session.\n\n**Why this means no user affinity.** IME's user check-in acquires the user token through the Windows web account manager (WAM), which needs the signed-in user's Entra identity — the Primary Refresh Token (PRT) that a hybrid sign-in establishes at logon. When that PRT was never issued, every token request fails and the user has **no Entra user affinity** on this device. Consequences:\n\n- user-targeted required apps and policies cannot apply,\n- Windows Hello for Business cannot provision (it requires a user token),\n- with a user ESP the Account Setup page re-appears on every logon instead of completing.\n\n**What this diagnosis does not use.** The Autopilot provisioning placeholder in JoinInfo (`aad_placeholder_user_detected`) is not part of this finding — on hybrid devices it can stay present through a perfectly healthy sign-in. Likewise, `dsregcmd /status` collected by the agent runs as SYSTEM and shows only the **device** join state; the per-user PRT state is visible only when the command runs as the signed-in user.\n\n**Typical causes** — something structurally prevents the user (or the computer object) from registering:\n\n- the computer object's `userCertificate` attribute is not syncing to Entra ID (sync scope / OU filtering),\n- the signing-in user is not synced, or their UPN does not match a verified Entra domain,\n- the device has no line of sight to a domain controller **at logon time**, so the hybrid PRT flow cannot finish,\n- time skew or a proxy blocking `login.microsoftonline.com` / `enterpriseregistration.windows.net` from the user context.\n\nA frequent variant: the user's **first sign-in happens without domain-controller reachability** — for example when a pre-logon VPN tunnel (GlobalProtect, Always On VPN, Zscaler ZPA) is not established yet at the logon screen. Windows falls back to cached credentials, the hybrid PRT flow silently never runs, and later reboots do not fix it.\n\nThe `device_registration_event` entries in the timeline (User Device Registration events 304/305) carry the OS-side record of the failed registration; the error codes in `entra_user_affinity_pending` carry the token side. A missing Windows Hello for Business wizard is a downstream symptom here, not the cause.",
      "remediation": [
        {
          "title": "Verify user affinity on the device",
          "steps": [
            "Sign in as the affected user and run: dsregcmd /status — under 'SSO State' the value AzureAdPrt must be YES. NO means the user has no Entra token and this diagnosis is confirmed.",
-            "Also check 'Device State': AzureAdJoined = YES and DomainJoined = YES are expected for hybrid join.",
-            "Check Event Viewer: Applications and Services Logs > Microsoft > Windows > User Device Registration > Admin for PRT / registration errors (e.g. event 304/305/362).",
-            "Enable the gather rules 'Collect dsregcmd join status' so future sessions capture this state automatically."
+            "Also check 'Device State': AzureAdJoined = YES and DomainJoined = YES are expected for hybrid join — they prove the device join only, not the user's registration.",
+            "Check Event Viewer: Applications and Services Logs > Microsoft > Windows > User Device Registration > Admin for PRT / registration errors (e.g. event 304/305/362). The device_registration_event entries (304/305) in the session timeline carry the same OS-side failure record.",
+            "Enable the gather rule GATHER-DEVICE-006 (dsregcmd /status at the moment of the finding — device state only, the agent runs as SYSTEM). GATHER-DEVICE-007 and GATHER-DEVICE-008 (Microsoft-Windows-AAD/Operational events 1098 and 1097 at the same moment) are on by default."
          ]
        },
        {
@@ -2754,6 +3150,86 @@
        "esp"
      ]
    },
+    {
+      "ruleId": "ANALYZE-NET-001",
+      "title": "Diagnostics Upload Blocked by Web Security Gateway",
+      "description": "Detects diagnostics package uploads that were answered by a security appliance's HTML block page instead of the Autopilot Monitor backend. A forward proxy / secure web gateway (SWG) with SSL inspection is intercepting the upload endpoint, so exactly the sessions where diagnostics matter most (OnFailure uploads) are the ones losing them.",
+      "severity": "warning",
+      "category": "network",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "baseConfidence": 75,
+      "conditions": [
+        {
+          "signal": "foreign_html_response",
+          "source": "event_data",
+          "eventType": "diagnostics_upload_failed",
+          "dataField": "errorCode",
+          "operator": "contains",
+          "value": "HTML platform error page",
+          "required": true
+        },
+        {
+          "signal": "security_gateway_marker",
+          "source": "event_data",
+          "eventType": "diagnostics_upload_failed",
+          "dataField": "errorCode",
+          "operator": "regex",
+          "value": "mcafee|skyhigh|zscaler|netskope|blue ?coat|proxysg|forcepoint|websense|palo ?alto|fortigate|fortiguard|sophos|watchguard|barracuda|iboss|umbrella|lightspeed|smoothwall|contentkeeper|web ?gateway|web ?filter|content ?filter|secure ?gateway",
+          "required": true
+        },
+        {
+          "signal": "http_403_block",
+          "source": "event_data",
+          "eventType": "diagnostics_upload_failed",
+          "dataField": "errorCode",
+          "operator": "contains",
+          "value": "403",
+          "required": false
+        }
+      ],
+      "confidenceFactors": [
+        {
+          "signal": "http_403_block",
+          "condition": "exists",
+          "weight": 15
+        }
+      ],
+      "confidenceThreshold": 70,
+      "explanation": "The agent collected a diagnostics package but the upload was answered with an **HTML block page from a web security gateway** instead of a response from the Autopilot Monitor backend — the event message names the product that served the page. A forward proxy / SWG with SSL inspection is intercepting HTTPS traffic from the enrollment network and blocking the upload endpoint.\n\nThe consequence is quietly painful: diagnostics upload is typically configured **OnFailure**, so the sessions that fail — the ones where the IME logs and diagnostics ZIP would explain the root cause — are exactly the sessions whose evidence never arrives. Enrollment telemetry itself may still flow (the agent often starts before the gateway's client enforcement does, or other endpoints are treated differently), which makes the gap easy to miss until a failure needs investigating.\n\nNote this rule only fires when the blocking page carries a recognizable security-product marker. A plain HTML error page without one usually means a stale or stopped endpoint instead — that is a different problem.",
+      "remediation": [
+        {
+          "title": "Exempt the upload endpoint in the web gateway",
+          "steps": [
+            "Identify the product from the block-page title quoted in this event's message (e.g. a Skyhigh/McAfee Web Gateway notification page)",
+            "In that gateway, add the Autopilot Monitor API host shown in the event message to the SSL-inspection bypass AND the URL allowlist for the enrollment network segment",
+            "Enrollment traffic often originates from a dedicated provisioning VLAN or from devices without the proxy client yet — make sure the exemption applies to that segment, not only to managed clients",
+            "If the gateway enforces per-user policy, remember ESP-phase traffic runs as SYSTEM/device before any user signs in — the exemption must cover unauthenticated device traffic"
+          ]
+        },
+        {
+          "title": "Verify the fix",
+          "steps": [
+            "Re-run an enrollment (or wait for the next failed one) and confirm a diagnostics package appears on the session in the portal",
+            "Optionally set diagnostics upload to Always temporarily to validate the path without needing a failure"
+          ]
+        }
+      ],
+      "relatedDocs": [
+        {
+          "title": "Microsoft Learn: Windows Autopilot networking requirements",
+          "url": "https://learn.microsoft.com/en-us/autopilot/networking-requirements"
+        }
+      ],
+      "tags": [
+        "network",
+        "proxy",
+        "ssl-inspection",
+        "swg",
+        "diagnostics"
+      ]
+    },
    {
      "ruleId": "ANALYZE-OFFICE-001",
      "title": "Microsoft 365 Apps Install Failed",
@@ -130,16 +130,16 @@
    },
    {
      "ruleId": "GATHER-DEVICE-006",
-      "title": "Collect dsregcmd join status on overdue hybrid sign-in",
-      "description": "Runs dsregcmd /status the moment the agent reports a hybrid sign-in as overdue (hybrid_login_pending), capturing the Entra join and registration state at exactly the point where the problem is detected. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
+      "title": "Collect dsregcmd join status on pending user affinity",
+      "description": "Runs dsregcmd /status the moment the agent reports that the signed-in user still has no Entra user token (entra_user_affinity_pending), capturing the device join and registration state at exactly the point where ANALYZE-ID-004 draws its evidence. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
      "category": "device",
-      "version": "1.0.0",
+      "version": "1.1.0",
      "author": "Autopilot Monitor",
      "enabled": false,
      "collectorType": "command_allowlisted",
      "target": "dsregcmd /status",
      "trigger": "on_event",
-      "triggerEventType": "hybrid_login_pending",
+      "triggerEventType": "entra_user_affinity_pending",
      "outputEventType": "gather_dsregcmd_status",
      "outputSeverity": "Info",
      "tags": [
@@ -149,6 +149,54 @@
        "hybrid"
      ]
    },
+    {
+      "ruleId": "GATHER-DEVICE-007",
+      "title": "Collect Entra operational log on pending user affinity (event 1098)",
+      "description": "Collects the most recent Entra token-broker operational events with ID 1098 from Microsoft-Windows-AAD/Operational the moment the agent reports that the signed-in user still has no Entra user token (entra_user_affinity_pending). Captures the OS-side token-broker record at exactly the point where ANALYZE-ID-004 draws its evidence. The event log collector filters on one event ID per rule; GATHER-DEVICE-008 collects event 1097 from the same channel.",
+      "category": "device",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "collectorType": "eventlog",
+      "target": "Microsoft-Windows-AAD/Operational",
+      "parameters": {
+        "eventId": "1098",
+        "maxEntries": "20"
+      },
+      "trigger": "on_event",
+      "triggerEventType": "entra_user_affinity_pending",
+      "outputEventType": "gather_aad_operational_events",
+      "outputSeverity": "Warning",
+      "tags": [
+        "device",
+        "entra",
+        "hybrid"
+      ]
+    },
+    {
+      "ruleId": "GATHER-DEVICE-008",
+      "title": "Collect Entra operational log on pending user affinity (event 1097)",
+      "description": "Collects the most recent Entra token-broker operational events with ID 1097 from Microsoft-Windows-AAD/Operational the moment the agent reports that the signed-in user still has no Entra user token (entra_user_affinity_pending). Captures the OS-side token-broker record at exactly the point where ANALYZE-ID-004 draws its evidence. The event log collector filters on one event ID per rule; GATHER-DEVICE-007 collects event 1098 from the same channel.",
+      "category": "device",
+      "version": "1.0.0",
+      "author": "Autopilot Monitor",
+      "enabled": true,
+      "collectorType": "eventlog",
+      "target": "Microsoft-Windows-AAD/Operational",
+      "parameters": {
+        "eventId": "1097",
+        "maxEntries": "20"
+      },
+      "trigger": "on_event",
+      "triggerEventType": "entra_user_affinity_pending",
+      "outputEventType": "gather_aad_operational_events",
+      "outputSeverity": "Warning",
+      "tags": [
+        "device",
+        "entra",
+        "hybrid"
+      ]
+    },
    {
      "ruleId": "GATHER-ENROLL-001",
      "title": "MDM enrollment diagnostic events",
@@ -4,7 +4,7 @@
    {
      "patternId": "HS-COMPLIANCE",
      "category": "always",
-      "pattern": "\\[HS\\] the (?<part>pre|post)-rem(?:e)?diation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+      "pattern": "^\\[HS\\] the (?<part>pre|post)-rem(?:e)?diation detection script compliance result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
      "action": "healthScriptDetectionResult",
      "parameters": {
        "scriptType": "remediation"
@@ -15,7 +15,7 @@
    {
      "patternId": "HS-COMPLIANCE-POST",
      "category": "always",
-      "pattern": "\\[HS\\] the (?<part>post) detection script result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
+      "pattern": "^\\[HS\\] the (?<part>post) detection script result for (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) is (?<compliance>True|False)",
      "action": "healthScriptDetectionResult",
      "parameters": {
        "scriptType": "remediation"
@@ -26,7 +26,7 @@
    {
      "patternId": "HS-EXITCODE",
      "category": "always",
-      "pattern": "\\[HS\\] exit code of the script is (?<exitCode>-?\\d+)",
+      "pattern": "^\\[HS\\] exit code of the script is (?<exitCode>-?\\d+)",
      "action": "scriptExitCode",
      "parameters": {
        "scriptType": "remediation"
@@ -37,7 +37,7 @@
    {
      "patternId": "HS-NEW-RESULT",
      "category": "always",
-      "pattern": "\\[HS\\] new result = (?<json>\\{[\\s\\S]*\\})\\s*$",
+      "pattern": "^\\[HS\\] new result = (?<json>\\{[\\s\\S]*\\})\\s*$",
      "action": "healthScriptResult",
      "parameters": {
        "scriptType": "remediation"
@@ -48,7 +48,7 @@
    {
      "patternId": "HS-RUN-CONTEXT",
      "category": "always",
-      "pattern": "\\[HS\\] The policy needs be run as (?<context>System|User)",
+      "pattern": "^\\[HS\\] The policy needs be run as (?<context>System|User)",
      "action": "scriptContext",
      "parameters": {
        "scriptType": "remediation"
@@ -59,7 +59,7 @@
    {
      "patternId": "HS-SCRIPT-START",
      "category": "always",
-      "pattern": "\\[HS\\] ProcessScript PolicyId: (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) PolicyType: (?<policyType>\\d+)",
+      "pattern": "^\\[HS\\] ProcessScript PolicyId: (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}) PolicyType: (?<policyType>\\d+)",
      "action": "scriptStarted",
      "parameters": {
        "scriptType": "remediation"
@@ -70,7 +70,7 @@
    {
      "patternId": "HS-STDERR",
      "category": "always",
-      "pattern": "\\[HS\\] err output = (?<output>.*)",
+      "pattern": "^\\[HS\\] err output = (?<output>.*)",
      "action": "scriptOutput",
      "parameters": {
        "scriptType": "remediation",
@@ -82,7 +82,7 @@
    {
      "patternId": "HS-STDOUT",
      "category": "always",
-      "pattern": "\\[HS\\] std output = (?<output>.*)",
+      "pattern": "^\\[HS\\] std output = (?<output>.*)",
      "action": "scriptOutput",
      "parameters": {
        "scriptType": "remediation",
@@ -94,7 +94,7 @@
    {
      "patternId": "IME-AGENT-VERSION",
      "category": "always",
-      "pattern": "Agent version is: (?<agentVersion>[\\d.]+)",
+      "pattern": "^Agent version is: (?<agentVersion>[\\d.]+)",
      "action": "imeAgentVersion",
      "description": "Captures the Intune Management Extension agent version number.",
      "enabled": true
@@ -102,7 +102,7 @@
    {
      "patternId": "IME-ALREADY-DETECTED-1",
      "category": "otherPhases",
-      "pattern": "\\[Win32App\\] Completed detectionManager SideCar\\w+?DetectionManager, applicationDetectedByCurrentRule: True",
+      "pattern": "^\\[Win32App\\] Completed detectionManager SideCar\\w+?DetectionManager, applicationDetectedByCurrentRule: True",
      "action": "ignoreCompletedApp",
      "description": "Detects when an app from a previous ESP phase is detected as already installed, so it should be ignored in the current phase.",
      "enabled": true
@@ -110,7 +110,7 @@
    {
      "patternId": "IME-ALREADY-DETECTED-2",
      "category": "otherPhases",
-      "pattern": "\\[Win32App\\] Setting enforcementState as\\W+Success\\b",
+      "pattern": "^\\[Win32App\\] Setting enforcementState as\\W+Success\\b",
      "action": "ignoreCompletedApp",
      "description": "Detects enforcement success in a non-current phase, indicating an app completed in a previous phase should be ignored.",
      "enabled": true
@@ -118,7 +118,7 @@
    {
      "patternId": "IME-APP-TYPE-MSI",
      "category": "always",
-      "pattern": "\\[Win32App\\].*?\\bMSI App (?<id>{GUID})",
+      "pattern": "^\\[Win32App\\].*?\\bMSI App (?<id>{GUID})",
      "action": "captureAppTypeMsi",
      "description": "Detects an MSI-based Win32 app via the 'MSI App <guid>' phrase in the ESP retry configuration line. Marks AppType as 'MSI' for that app id.",
      "enabled": true
@@ -126,7 +126,7 @@
    {
      "patternId": "IME-APP-TYPE-WINGET",
      "category": "always",
-      "pattern": "\\[Win32App\\]\\[WinGetApp\\].*?app with id: (?<id>{GUID})",
+      "pattern": "^\\[Win32App\\]\\[WinGetApp\\].*?app with id: (?<id>{GUID})",
      "action": "captureAppTypeWinGet",
      "description": "Detects a WinGet-backed Store app by any [Win32App][WinGetApp] handler log line (Detection/Applicability/Operation). Marks AppType as 'WinGet' for that app id.",
      "enabled": true
@@ -134,7 +134,7 @@
    {
      "patternId": "IME-APP-VERSION",
      "category": "always",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: (?<id>{GUID}).*?\"DetectedIdentityVersion\":\\{[^}]*?\"NewValue\":\"(?<appVersion>[^\"]+)\"",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: (?<id>{GUID}).*?\"DetectedIdentityVersion\":\\{(?:\"OldValue\":[^,}]{0,64},)?\"NewValue\":\"(?<appVersion>[^\"]+)\"",
      "action": "captureAppVersion",
      "description": "Captures the product version IME detected after an app install (e.g. \"11.2.1787.0\"). Source: [ReportingManager] Detection state update with DetectedIdentityVersion.NewValue. Used by App Dashboard to show version-level failure breakdowns.",
      "enabled": true
@@ -142,7 +142,7 @@
    {
      "patternId": "IME-ATTEMPT-NUMBER",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] ===Step=== Execute retry (?<attempt>\\d+)$",
+      "pattern": "^\\[Win32App\\] ===Step=== Execute retry (?<attempt>\\d+)$",
      "action": "captureAttemptNumber",
      "parameters": {
        "useCurrentApp": "true"
@@ -153,7 +153,7 @@
    {
      "patternId": "IME-CACHE-MISS",
      "category": "always",
-      "pattern": "\\[Win32App\\] Content cache miss for app \\(id = {GUID}, name = (?<name>.*?)\\), start downloading",
+      "pattern": "^\\[Win32App\\] Content cache miss for app \\(id = {GUID}, name = (?<name>.*?)\\), start downloading",
      "action": "updateName",
      "description": "Captures 'Content cache miss for app (id = <guid>, name = <name>), start downloading...' (ContentManager.cs) as a secondary app-name source. Fires right before a real download begins, so it resolves names for exactly the apps that will produce download/install activity — a redundancy for IME-POLICIES-based naming after IME retired the old name-bearing processing lines.",
      "enabled": true
@@ -161,7 +161,7 @@
    {
      "patternId": "IME-DECRYPT-FAILED",
      "category": "currentPhase",
-      "pattern": "Decryption is failed for appId {GUID}",
+      "pattern": "^Decryption is failed for appId {GUID}",
      "action": "updateStateError",
      "description": "Detects when app content decryption fails, indicating a corrupted or tampered download.",
      "enabled": true
@@ -169,7 +169,7 @@
    {
      "patternId": "IME-DETECTED-INSTALLED-1",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DetectionState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}Installed\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Detection state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DetectionState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}Installed\"{1,2}",
      "action": "updateStateInstalled",
      "description": "Detects when an app's detection state transitions to Installed (new ReportingManager format). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -177,23 +177,15 @@
    {
      "patternId": "IME-DETECTED-INSTALLED-2",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: {GUID} resulted in action status: Success and detection state: Detected",
+      "pattern": "^\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: {GUID} resulted in action status: Success and detection state: Detected",
      "action": "updateStateInstalled",
      "description": "Detects when an app's detection action handler reports successful detection (app is installed).",
      "enabled": true
    },
-    {
-      "patternId": "IME-DETECTED-OLD",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Detected app {GUID} ",
-      "action": "updateStateInstalled",
-      "description": "Detects when an app is detected as installed (old log format). DISABLED 2026-08-17: the standalone 'Detected app <guid> ' line no longer exists in IME 1.97.107; this regex instead matched the 'Detected app ... and intent is to install, skip applicability check' line, colliding with IME-SKIP-INSTALL-DETECTED and firing updateStateInstalled and updateStateSkipped on the same physical line (see tasks/ime-v1-code-audit-2026-08-17.md).",
-      "enabled": false
-    },
    {
      "patternId": "IME-DETECTION-RESULT",
      "category": "always",
-      "pattern": "\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>DetectedDifferentVersion|NotDetected|Detected)",
+      "pattern": "^\\[Win32App\\]\\[DetectionActionHandler\\] Detection for policy with id: (?<id>{GUID}) resulted in action status: Success and detection state: (?<detection>DetectedDifferentVersion|NotDetected|Detected)",
      "action": "captureDetectionResult",
      "description": "Captures the detection rule result after IME runs detection for an app. 'Detected' means the detection rule matched (app is installed), 'NotDetected' means it did not, 'DetectedDifferentVersion' means a different version was found (supersedence / WinGet version mismatch). DetectedDifferentVersion must come first in the alternation so the unanchored regex does not mis-capture its 'Detected' prefix. Excludes [SimulatedDetectionActionHandler] which fires during applicability pre-checks.",
      "enabled": true
@@ -201,23 +193,23 @@
    {
      "patternId": "IME-DO-TEL",
      "category": "currentPhase",
-      "pattern": "\\[DO TEL\\] = (?<doTelJson>\\{.*\\})",
+      "pattern": "^\\[DO TEL\\] = (?<doTelJson>\\{.*\\})",
      "action": "updateDoTelemetry",
-      "description": "Captures Delivery Optimization telemetry JSON after a DO download completes. Contains file size, peer caching stats, download mode, and duration.",
+      "description": "Captures Delivery Optimization telemetry JSON after a DO download completes. Contains file size, peer caching stats, download mode, and duration. IME removed the [DO TEL] emitter in 1.104 (absent in 1.104.102.0 and 1.105.103.0 decompiles, present in 1.97.107.0); kept while 1.101/1.103 devices are in the fleet — retire once those versions are gone.",
      "enabled": true
    },
    {
      "patternId": "IME-DO-TIMEOUT-1",
      "category": "currentPhase",
-      "pattern": "\\[Win32App DO\\] DO download(?=.*?\\bnot finished\\b)(?=.*?\\btimeout\\b).*?intunewin-bin_{GUID}",
+      "pattern": "^\\[Win32App DO\\] DO downloading is not finished within timeout, jobId = [^,]{0,64}, fileId =.*?intunewin-bin_{GUID}",
      "action": "updateStatePostponed",
-      "description": "Detects when a Delivery Optimization download times out for a specific app (identified by GUID in filename).",
+      "description": "Detects when a Delivery Optimization download times out for a specific app (identified by GUID in the DO fileId). Source literal (ContentDownloaderDeliveryOptimization, identical IME 1.97-1.105): \"[Win32App DO] DO downloading is not finished within timeout, jobId = {0}, fileId = {1}\".",
      "enabled": true
    },
    {
      "patternId": "IME-DO-TIMEOUT-2",
      "category": "currentPhase",
-      "pattern": "\\[Win32App DO\\] DO download(?=.*?\\bnot finished\\b)(?=.*?\\btimeout\\b)",
+      "pattern": "^\\[Win32App DO\\] DO downloading is not finished within timeout",
      "action": "updateStatePostponed",
      "parameters": {
        "useCurrentApp": "true"
@@ -228,7 +220,7 @@
    {
      "patternId": "IME-DOWNLOADING",
      "category": "currentPhase",
-      "pattern": "\\[StatusService\\] Downloading app \\(id = {GUID}.*?\\) via (?<tech>\\w+), bytes (?<bytes>\\w+)/(?<ofbytes>\\w+) for user",
+      "pattern": "^\\[StatusService\\] Downloading app \\(id = {GUID}.*?\\) via (?<tech>\\w+), bytes (?<bytes>\\w+)/(?<ofbytes>\\w+) for user",
      "action": "updateStateDownloading",
      "description": "Captures app download progress including technology (DO/CDN), bytes downloaded, and total bytes.",
      "enabled": true
@@ -236,7 +228,7 @@
    {
      "patternId": "IME-ENFORCEMENT-SUCCESS",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}\\w+\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}Success\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}\\w+\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}Success\"{1,2}",
      "action": "updateStateInstalled",
      "description": "Detects when an app's enforcement state transitions to Success in an Execution state report delta. OldValue is deliberately unpinned: besides InProgressDownloadCompleted it can be Error (retry succeeding in a later check-in), InProgressPendingReboot (post-reboot completion) or null (first write) — the previously pinned InProgressDownloadCompleted missed those legitimate success paths (IME 1.97 audit 2026-08-17). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -244,7 +236,7 @@
    {
      "patternId": "IME-ENFORCEMENT-SUCCESS-OLD",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Setting enforcementState as\\W+Success\\b",
+      "pattern": "^\\[Win32App\\] Setting enforcementState as\\W+Success\\b",
      "action": "updateStateInstalled",
      "parameters": {
        "useCurrentApp": "true"
@@ -255,7 +247,7 @@
    {
      "patternId": "IME-ERROR-DOWNLOAD",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:\"{1,2}InProgress\"{1,2},\"{1,2}NewValue\"{1,2}:\"{1,2}ErrorDownloadingContent\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Download state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:\"{1,2}InProgress\"{1,2},\"{1,2}NewValue\"{1,2}:\"{1,2}ErrorDownloadingContent\"{1,2}",
      "action": "updateStateError",
      "description": "Detects when an app's enforcement state transitions to ErrorDownloadingContent. Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -263,7 +255,7 @@
    {
      "patternId": "IME-ERROR-ENFORCEMENT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Setting enforcementState as\\W+Error\\b",
+      "pattern": "^\\[Win32App\\] Setting enforcementState as\\W+Error\\b",
      "action": "updateStateError",
      "parameters": {
        "useCurrentApp": "true"
@@ -274,7 +266,7 @@
    {
      "patternId": "IME-ERROR-NO-CONTENT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Didn't get content info from service",
+      "pattern": "^\\[Win32App\\] Didn't get content info from service",
      "action": "updateStateError",
      "parameters": {
        "useCurrentApp": "true"
@@ -285,7 +277,7 @@
    {
      "patternId": "IME-ERROR-REPORT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}(?<from>\\w+)\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}(?<to>\\w+)\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Execution state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}EnforcementState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:(?:\"{1,2}(?<from>\\w+)\"{1,2}|null),\"{1,2}NewValue\"{1,2}:\"{1,2}(?<to>\\w+)\"{1,2}",
      "action": "updateStateError",
      "parameters": {
        "checkTo": "true"
@@ -296,7 +288,7 @@
    {
      "patternId": "IME-ERROR-TIMEOUT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Installation is timeout",
+      "pattern": "^\\[Win32App\\] Installation is timeout",
      "action": "updateStateError",
      "parameters": {
        "useCurrentApp": "true"
@@ -307,7 +299,7 @@
    {
      "patternId": "IME-ERROR-UNMAPPED-EXIT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Admin did NOT set mapping for lpExitCode\\W+(?<exitCode>\\d+) of app\\W+{GUID}",
+      "pattern": "^\\[Win32App\\] Admin did NOT set mapping for lpExitCode\\W+(?<exitCode>\\d+) of app\\W+{GUID}",
      "action": "updateStateError",
      "description": "Detects when an app installer returned an exit code that has no mapping configured in Intune.",
      "enabled": true
@@ -315,7 +307,7 @@
    {
      "patternId": "IME-ESP-APP-REGISTERED",
      "category": "always",
-      "pattern": "\\[Win32App\\]\\[EspManager\\] In EspPhase: \\w+\\. App {GUID} has been registered.*?App name: (?<name>.*?)$",
+      "pattern": "^\\[Win32App\\]\\[EspManager\\] In EspPhase: \\w+\\. App {GUID} has been registered.*?App name: (?<name>.*?)$",
      "action": "updateName",
      "description": "Captures the ESP tracked-app registration line ('App <guid> has been registered[ for user <id>]. App name: <name>', EspManager.cs) as an app-name source. Primary replacement for the retired IME-UPDATE-NAME-1/2/3 whose emitters were removed with IME's old V1/V2 processing pipeline; also documents exactly which apps IME registered for ESP tracking. Category 'always' so names resolve even before the first ApplicationPoller EspPhase line is seen.",
      "enabled": true
@@ -323,7 +315,7 @@
    {
      "patternId": "IME-ESP-PHASE",
      "category": "always",
-      "pattern": "\\[Win32App\\] (?:In|The) EspPhase: (?<espPhase>\\w+)",
+      "pattern": "^\\[Win32App\\] (?:In|The) EspPhase: (?<espPhase>\\w+)",
      "action": "espPhaseDetected",
      "description": "Detects ESP phase transitions reported by IME Win32App processing (e.g., DeviceSetup, AccountSetup).",
      "enabled": true
@@ -331,7 +323,7 @@
    {
      "patternId": "IME-ESP-TRACK-STATUS",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}",
+      "pattern": "^\\[Win32App\\]\\[EspManager\\] Updating ESP tracked install status from (?<from>\\w+) to (?<to>\\w+) for application {GUID}",
      "action": "espTrackStatus",
      "description": "Captures ESP tracked install status transitions (e.g., InProgress to Installed) for a specific app. No trailing anchor: IME 1.97 (Dec 2025) appends ' with name: <appName>.' after the GUID (EspManager.cs), which broke the previous '\\.' suffix. 'from' can be the literal string 'null' on first tracking.",
      "enabled": true
@@ -339,7 +331,7 @@
    {
      "patternId": "IME-EXITCODE",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] lpExitCode (?<exitCode>-?\\d+)$",
+      "pattern": "^\\[Win32App\\] lpExitCode (?<exitCode>-?\\d+)$",
      "action": "captureExitCode",
      "parameters": {
        "useCurrentApp": "true"
@@ -347,10 +339,21 @@
      "description": "Captures the installer exit code (lpExitCode) for the current app.",
      "enabled": true
    },
+    {
+      "patternId": "IME-EXITCODE-CLASS",
+      "category": "currentPhase",
+      "pattern": "^\\[Win32App\\] lpExitCode is defined as (?<exitCodeClass>Success|SoftReboot|HardReboot|Retry|Failed)$",
+      "action": "captureExitCodeClass",
+      "parameters": {
+        "useCurrentApp": "true"
+      },
+      "description": "Captures the admin-defined return-code class of the installer exit code for the current app ('[Win32App] lpExitCode is defined as <Failed|Success|SoftReboot|HardReboot|Retry>', Win32AppInstaller.cs, enum AppReturnCodeType - literal identical from IME 1.50 through 1.105). Stored as exitCodeClass on the app and emitted on its terminal events; the last value wins, so a Retry loop that ends in Success reports Success. Anchored on both ends on purpose: the no-mapping warning ('... defined as <n>, fall into default now.') and an unparsable numeric type print a raw number and must not match. Companion of IME-EXITCODE (the number, logged just before) and IME-EXITCODE-MAPPED-FAILED (the Failed state transition), which still owns the error path.",
+      "enabled": true
+    },
    {
      "patternId": "IME-EXITCODE-MAPPED-FAILED",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] lpExitCode is defined as Failed$",
+      "pattern": "^\\[Win32App\\] lpExitCode is defined as Failed$",
      "action": "updateStateError",
      "parameters": {
        "useCurrentApp": "true"
@@ -361,7 +364,7 @@
    {
      "patternId": "IME-GRS-CLEARED",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ExecutionActionHandler\\] Encountered early subgraph termination\\. Clearing GRS for app with id: {GUID} so it can be retried during the next check-in\\.",
+      "pattern": "^\\[Win32App\\]\\[ExecutionActionHandler\\] Encountered early subgraph termination\\. Clearing GRS for app with id: {GUID} so it can be retried during the next check-in\\.",
      "action": "updateStatePostponed",
      "description": "IME aborted the app's subgraph before enforcement finished and cleared its GRS entry so the app retries on the next check-in (ExecutionActionHandler, AppWorkload.log). Maps to Postponed: the install did not complete this pass but is scheduled to run again - previously this looked like an unexplained gap. Wording verified in IME 1.97 and 1.104.",
      "enabled": true
@@ -369,7 +372,7 @@
    {
      "patternId": "IME-GRS-SKIP",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID} to (?:install|uninstall) is in GRS\\. The app will not be enforced\\.",
+      "pattern": "^\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID} to (?:install|uninstall) is in GRS\\. The app will not be enforced\\.",
      "action": "updateStatePostponed",
      "description": "GRS (Global Retry Schedule) skip: the app failed recently and IME will not re-enforce it this check-in ('App with id: <guid> to install is in GRS. The app will not be enforced.', EnforcementActionProcessor / MixedEnforcementActionProcessor). THE canonical reason an app silently does nothing for up to 24h - previously invisible. Lives in AppActionProcessor.log, which the agent tails since the 2026-08-18 release; wording verified in IME 1.97 and 1.104.",
      "enabled": true
@@ -377,7 +380,7 @@
    {
      "patternId": "IME-HRESULT",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] hResultFromWin32 (?<hresult>-?\\d+)$",
+      "pattern": "^\\[Win32App\\] hResultFromWin32 (?<hresult>-?\\d+)$",
      "action": "captureHResult",
      "parameters": {
        "useCurrentApp": "true"
@@ -388,7 +391,7 @@
    {
      "patternId": "IME-IMPERSONATION",
      "category": "always",
-      "pattern": "After impersonation: (?<user>.*?)$",
+      "pattern": "^After impersonation: (?<user>.*?)$",
      "action": "imeImpersonation",
      "description": "Detects when IME impersonates a user context for app installation.",
      "enabled": true
@@ -396,7 +399,7 @@
    {
      "patternId": "IME-INSTALL-HANDLER",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ExecutionActionHandler\\] Handler invoked with execution type: Install for policy with id: {GUID}",
+      "pattern": "^\\[Win32App\\]\\[ExecutionActionHandler\\] Handler invoked with execution type: Install for policy with id: {GUID}",
      "action": "updateStateInstalling",
      "description": "Detects when the IME execution handler starts installing an app.",
      "enabled": true
@@ -404,7 +407,7 @@
    {
      "patternId": "IME-LAUNCH-INSTALLER",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Launch Win32AppInstaller in \\w+? session",
+      "pattern": "^\\[Win32App\\] Launch Win32AppInstaller in \\w+? session",
      "action": "updateStateInstalling",
      "parameters": {
        "useCurrentApp": "true"
@@ -415,7 +418,7 @@
    {
      "patternId": "IME-NO-ACTION",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ActionProcessor\\] No action required for app with id: {GUID}",
+      "pattern": "^\\[Win32App\\]\\[ActionProcessor\\] No action required for app with id: {GUID}",
      "action": "updateStateSkipped",
      "description": "Detects when IME determines no action is required for an app (already in desired state).",
      "enabled": true
@@ -423,7 +426,7 @@
    {
      "patternId": "IME-NOT-APPLICABLE-1",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ApplicabilityActionHandler\\] Applicability check for policy with id: {GUID} resulted in action status: Success and applicability state: NotApplicable",
+      "pattern": "^\\[Win32App\\]\\[ApplicabilityActionHandler\\] Applicability check for policy with id: {GUID} resulted in action status: Success and applicability state: NotApplicable",
      "action": "updateStateSkipped",
      "description": "Detects when an app's applicability check returns NotApplicable (requirements not met).",
      "enabled": true
@@ -431,7 +434,7 @@
    {
      "patternId": "IME-NOT-APPLICABLE-2",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Applicability state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}ApplicabilityState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}ScriptRequirementRuleNotMet\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Applicability state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}ApplicabilityState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}ScriptRequirementRuleNotMet\"{1,2}",
      "action": "updateStateSkipped",
      "description": "Detects when an app's applicability state is set to ScriptRequirementRuleNotMet (PowerShell requirement script returned false). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -439,7 +442,7 @@
    {
      "patternId": "IME-NOT-APPLICABLE-3",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}None\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}None\"{1,2}",
      "action": "updateStateSkipped",
      "description": "Detects when an app's desired state is set to None (not targeted or not applicable). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -447,7 +450,7 @@
    {
      "patternId": "IME-NOT-APPLICABLE-4",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}NotPresent\"{1,2}",
+      "pattern": "^\\[Win32App\\]\\[ReportingManager\\] Desired state for app with id: {GUID} has been updated\\. Report delta: \\{\"{1,2}DesiredState\"{1,2}:\\{\"{1,2}OldValue\"{1,2}:null,\"{1,2}NewValue\"{1,2}:\"{1,2}NotPresent\"{1,2}",
      "action": "updateStateSkipped",
      "description": "Detects when an app's desired state is set to NotPresent (targeted for uninstall or not required). Quote-flexible since 2026-08-17: IME 1.104 serializes the report-delta JSON with single quotes ({\"Key\":...) where older versions logged doubled quotes ({\"\"Key\"\":...) - every literal quote in the delta is matched as \"{1,2} to cover both.",
      "enabled": true
@@ -455,7 +458,7 @@
    {
      "patternId": "IME-NOT-TARGETED-1",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID}, targeted intent: RequiredInstall, and enforceability: Enforceable has projected enforcement classification: NotApplicableOrNotTargeted with desired state: None\\.",
+      "pattern": "^\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID}, targeted intent: RequiredInstall, and enforceability: Enforceable has projected enforcement classification: NotApplicableOrNotTargeted with desired state: None\\.",
      "action": "updateStateSkipped",
      "description": "Detects when an app with RequiredInstall intent is classified as NotApplicableOrNotTargeted (new log format).",
      "enabled": true
@@ -463,7 +466,7 @@
    {
      "patternId": "IME-NOT-TARGETED-2",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID}, effective intent: RequiredInstall, and enforceability: Enforceable has projected enforcement classification: NotApplicableOrNotTargeted with desired state: None\\.",
+      "pattern": "^\\[Win32App\\]\\[ActionProcessor\\] App with id: {GUID}, effective intent: RequiredInstall, and enforceability: Enforceable has projected enforcement classification: NotApplicableOrNotTargeted with desired state: None\\.",
      "action": "updateStateSkipped",
      "description": "Detects when an app with effective RequiredInstall intent is classified as NotApplicableOrNotTargeted.",
      "enabled": true
@@ -471,7 +474,7 @@
    {
      "patternId": "IME-POLICIES",
      "category": "currentPhase",
-      "pattern": "Get policies =\\s*(?<policies>.*)",
+      "pattern": "^Get policies =\\s*(?<policies>.*)",
      "action": "policiesDiscovered",
      "description": "Captures the JSON policies list discovered by IME, used to build the app inventory.",
      "enabled": true
@@ -479,7 +482,7 @@
    {
      "patternId": "IME-RESTART-STOP-PROCESSING",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[V3Processor\\] A restart is required to continue processing apps\\. Stop processing\\.",
+      "pattern": "^\\[Win32App\\]\\[V3Processor\\] A restart is required to continue processing apps\\. Stop processing\\.",
      "action": "updateStatePostponed",
      "parameters": {
        "useCurrentApp": "true"
@@ -490,39 +493,15 @@
    {
      "patternId": "IME-SESSION-CHANGE",
      "category": "always",
-      "pattern": "OnSessionChange:? (?<change>.*?)$",
+      "pattern": "^OnSessionChange:? (?<change>.*?)$",
      "action": "imeSessionChange",
      "description": "Detects Windows session change events (logon, logoff, lock, unlock) reported by IME.",
      "enabled": true
    },
-    {
-      "patternId": "IME-SET-CURRENT-1",
-      "category": "always",
-      "pattern": "\\[Win32App\\] ProcessAppWithDependencies starts for {GUID} with name",
-      "action": "setCurrentApp",
-      "description": "Detects when IME begins processing an app with its dependency chain, setting it as the current app. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-SET-CURRENT-2",
-      "category": "always",
-      "pattern": "\\[Win32App\\] ExecManager: processing targeted app.*?\\bid\\W+{GUID}",
-      "action": "setCurrentApp",
-      "description": "Detects when the IME ExecManager starts processing a targeted app, setting it as current. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-SET-CURRENT-3",
-      "category": "always",
-      "pattern": "\\[Win32App\\] ===Step=== Start to Present app {GUID}",
-      "action": "setCurrentApp",
-      "description": "Detects the start of app presentation step in IME, setting the app as current. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
    {
      "patternId": "IME-SET-CURRENT-4",
      "category": "always",
-      "pattern": "\\[Win32App\\] SetCurrentDirectory:.*?\\\\{GUID}_\\d+",
+      "pattern": "^\\[Win32App\\] SetCurrentDirectory:.*?\\\\{GUID}_\\d+",
      "action": "setCurrentApp",
      "description": "Detects when IME sets the working directory for an app's staging folder, setting it as current.",
      "enabled": true
@@ -530,7 +509,7 @@
    {
      "patternId": "IME-SHUTDOWN",
      "category": "currentPhase",
-      "pattern": "EMS Agent received shutdown signal",
+      "pattern": "^EMS Agent received shutdown signal",
      "action": "updateStatePostponed",
      "parameters": {
        "useCurrentApp": "true"
@@ -538,34 +517,10 @@
      "description": "Detects when the IME agent receives a shutdown signal, postponing the current app installation.",
      "enabled": true
    },
-    {
-      "patternId": "IME-SKIP-APPLICABILITY-NOTMET",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] (?=.*?\\bapplicability\\b)(?=.*?NotMet\\b).*?\\bapp\\W+{GUID}\\b",
-      "action": "updateStateSkipped",
-      "description": "Detects when an app's applicability check returns NotMet (old log format with lookaheads). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-SKIP-DEPENDENCY-DETECT",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] app\\W+{GUID}\\b.*?\\bis a dependency\\b.*?\\bDetect Only mode\\b.*?\\bfinished processing",
-      "action": "updateStateSkipped",
-      "description": "Detects when a dependency app in Detect Only mode finishes processing (no install needed). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-SKIP-DETECTED",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Detected app {GUID}.*?skip next step",
-      "action": "updateStateSkipped",
-      "description": "Detects when an already-detected app is skipped for further processing steps (old log format). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
    {
      "patternId": "IME-SKIP-FILTERS",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[V3Processor\\] All apps in the subgraph are not applicable due to assignment filters\\. Skipping processing\\.",
+      "pattern": "^\\[Win32App\\]\\[V3Processor\\] All apps in the subgraph are not applicable due to assignment filters\\. Skipping processing\\.",
      "action": "updateStateSkipped",
      "parameters": {
        "useCurrentApp": "true"
@@ -576,7 +531,7 @@
    {
      "patternId": "IME-SKIP-INSTALL-DETECTED",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Detected app {GUID} and intent is to install, skip applicability check",
+      "pattern": "^\\[Win32App\\] Detected app {GUID} and intent is to install, skip applicability check",
      "action": "updateStateSkipped",
      "description": "Detects when an app targeted for install is already detected/installed, so the install is skipped (old log format).",
      "enabled": true
@@ -584,23 +539,15 @@
    {
      "patternId": "IME-SKIP-UNINSTALL-NOTDETECTED",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Not detected app {GUID} and intent is to un-install, skip applicability check",
+      "pattern": "^\\[Win32App\\] Not detected app {GUID} and intent is to un-install, skip applicability check",
      "action": "updateStateSkipped",
      "description": "Detects when an app targeted for uninstall is not detected, so the uninstall is skipped (old log format).",
      "enabled": true
    },
-    {
-      "patternId": "IME-SKIP-UNINSTALL-NOTDETECTED-2",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] NOT detected app {GUID}.*?skip un-installation",
-      "action": "updateStateSkipped",
-      "description": "Detects when an app is not detected and uninstall is skipped (alternate old log format). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
    {
      "patternId": "IME-STARTED",
      "category": "always",
-      "pattern": "EMS Agent Started",
+      "pattern": "^EMS Agent Started",
      "action": "imeStarted",
      "description": "Detects when the Intune Management Extension (IME) agent starts up.",
      "enabled": true
@@ -608,7 +555,7 @@
    {
      "patternId": "IME-STOP-SIGNAL",
      "category": "currentPhase",
-      "pattern": "EMS Agent received stop signal",
+      "pattern": "^EMS Agent received stop signal",
      "action": "updateStatePostponed",
      "parameters": {
        "useCurrentApp": "true"
@@ -619,7 +566,7 @@
    {
      "patternId": "IME-SUBGRAPH",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\]\\[V3Processor\\] Processing subgraph with app ids: {GUID}",
+      "pattern": "^\\[Win32App\\]\\[V3Processor\\] Processing subgraph with app ids: {GUID}",
      "action": "cancelStuckAndSetCurrent",
      "description": "Detects when V3Processor starts a new subgraph, cancelling any stuck app and setting the new app as current.",
      "enabled": true
@@ -627,7 +574,7 @@
    {
      "patternId": "IME-TOKEN-FAILURE",
      "category": "always",
-      "pattern": "Failed to get AAD token\\..*?errorCode = (?<errorCode>.*?)$",
+      "pattern": "^Failed to get AAD token\\..*?errorCode = (?<errorCode>.*?)$",
      "action": "imeTokenFailure",
      "description": "IME token acquisition failure ('Failed to get AAD token. len = N using client id ... and resource id ..., errorCode = N', IntuneTokenManager, IntuneManagementExtension.log). This line appears ROUTINELY during the device phase (no user token exists yet), so the agent holds the failure pending: any IME-TOKEN-SUCCESS match clears it, and the ime_token_failure Warning fires only when no success follows for the whole 30-min grace window (then deduped to one Warning per distinct errorCode). A genuine auth outage (WAM broken, conditional access, network) runs long enough to hit the window. Verified against IME 1.97 and 1.104 decompiled sources.",
      "enabled": true
@@ -635,7 +582,7 @@
    {
      "patternId": "IME-TOKEN-SUCCESS",
      "category": "always",
-      "pattern": "Successfully get the token",
+      "pattern": "^Successfully get the token",
      "action": "espPhaseDetected",
      "parameters": {
        "phase": "AccountSetup"
@@ -643,42 +590,26 @@
      "description": "Detects successful token acquisition, indicating the AccountSetup ESP phase has started.",
      "enabled": true
    },
-    {
-      "patternId": "IME-UPDATE-NAME-1",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] ExecManager: processing targeted app.*?name\\W+(?<name>.*?)\\W+id\\W+{GUID}",
-      "action": "updateName",
-      "description": "Captures the app name from ExecManager processing log (old format: name before id). DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-UPDATE-NAME-2",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] ProcessAppWithDependencies starts for {GUID} with name (?<name>.*?)$",
-      "action": "updateName",
-      "description": "Captures the app name from ProcessAppWithDependencies log entry. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
-    {
-      "patternId": "IME-UPDATE-NAME-3",
-      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Processing app \\(id={GUID}, name = (?<name>.*?)\\)",
-      "action": "updateName",
-      "description": "Captures the app name from the Processing app log entry. DISABLED 2026-08-17: emitter no longer exists in current IME (1.97.107, Dec 2025) - the old V1/V2 app processing pipeline was removed and this line is not logged anymore (verified against decompiled source, see tasks/ime-v1-code-audit-2026-08-17.md). Kept for history.",
-      "enabled": false
-    },
    {
      "patternId": "IME-USER-SESSION-COMPLETED",
      "category": "always",
-      "pattern": "\\[Win32App\\] \\.+ Completed user session \\d+, userId: (?<userId>[a-f0-9\\-]+), userSID: (?<userSid>S-[\\d\\-]+) \\.+",
+      "pattern": "^\\[Win32App\\] \\.+ Completed user session \\d+, userId: (?<userId>[a-f0-9\\-]+), userSID: (?<userSid>S-[\\d\\-]+) \\.+",
      "action": "enrollmentCompleted",
      "description": "Detects when IME completes a user session, indicating enrollment has finished for that user.",
      "enabled": true
    },
+    {
+      "patternId": "IME-USER-SESSION-ZERO-APPS",
+      "category": "always",
+      "pattern": "^\\[Win32App\\] Get 0 apps for user session (?<sessionId>\\d+), user id = (?<userId>[a-f0-9\\-]+)",
+      "action": "userSessionZeroApps",
+      "description": "Detects when IME enumerated a user session and found zero targeted Win32 apps. IME then skips its 'Completed user session' line entirely (the zero-app branch in ApplicationPoller continues before that log statement), so this line is the only evidence that user-phase enforcement finished on a device with no user-targeted apps. Treated as equivalent to a completed user session.",
+      "enabled": true
+    },
    {
      "patternId": "IME-WIN32-STATE-1",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] Got InstanceID: Win32App_{GUID}_\\d+, installationStateString: (?<state>\\d)",
+      "pattern": "^\\[Win32App\\] Got InstanceID: Win32App_{GUID}_\\d+, installationStateString: (?<state>\\d)",
      "action": "updateWin32AppState",
      "description": "Captures the Win32 app installation state string from instance ID tracking (old log format).",
      "enabled": true
@@ -686,7 +617,7 @@
    {
      "patternId": "IME-WIN32-STATE-2",
      "category": "currentPhase",
-      "pattern": "\\[Win32App\\] (?:Got|Set) (?:ESP )?win32App state (?<state>\\w+) for {GUID}",
+      "pattern": "^\\[Win32App\\] (?:Got|Set) (?:ESP )?win32App state (?<state>\\w+) for {GUID}",
      "action": "updateWin32AppState",
      "description": "Captures the Win32 app ESP state (e.g., Installed, InProgress) for a specific app.",
      "enabled": true
@@ -694,7 +625,7 @@
    {
      "patternId": "IME-WINGET-ERROR",
      "category": "currentPhase",
-      "pattern": "\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID}.*?- Operation Phase = Error",
+      "pattern": "^\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID}.*?- Operation Phase = Error",
      "action": "updateStateError",
      "description": "Marks a WinGet (new Store) app as failed when its operation progress reports phase Error (WinGetOperationInstallPhase: Downloading/Installing/Queued/Finished/Error). Before this pattern only the Installing phase was matched, so WinGet failures never surfaced as app errors (IME 1.97 audit 2026-08-17).",
      "enabled": true
@@ -702,7 +633,7 @@
    {
      "patternId": "IME-WINGET-INSTALLING-1",
      "category": "currentPhase",
-      "pattern": "\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID} and user = .*?- Operation Phase = Installing",
+      "pattern": "^\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID} and user = .*?- Operation Phase = Installing",
      "action": "updateStateInstalling",
      "description": "Detects WinGet app installation progress with Operation Phase = Installing (format variant 1).",
      "enabled": true
@@ -710,7 +641,7 @@
    {
      "patternId": "IME-WINGET-INSTALLING-2",
      "category": "currentPhase",
-      "pattern": "\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID}.*?- Operation Phase = Installing",
+      "pattern": "^\\[WinGetMessageProcessor\\] Processing Progress for app = {GUID}.*?- Operation Phase = Installing",
      "action": "updateStateInstalling",
      "description": "Detects WinGet app installation progress with Operation Phase = Installing (format variant 2).",
      "enabled": true
@@ -718,7 +649,7 @@
    {
      "patternId": "PS-AGENT-ERROR",
      "category": "always",
-      "pattern": "error from script =(?<output>[\\s\\S]*)",
+      "pattern": "^error from script =(?<output>[\\s\\S]*)",
      "action": "scriptOutput",
      "parameters": {
        "scriptType": "platform",
@@ -730,7 +661,7 @@
    {
      "patternId": "PS-AGENT-EXITCODE",
      "category": "always",
-      "pattern": "Powershell exit code is (?<exitCode>-?\\d+)",
+      "pattern": "^Powershell exit code is (?<exitCode>-?\\d+)",
      "action": "scriptExitCode",
      "parameters": {
        "scriptType": "platform"
@@ -741,7 +672,7 @@
    {
      "patternId": "PS-AGENT-INVOCATION",
      "category": "always",
-      "pattern": "ExecutorLog AgentExecutor gets invoked",
+      "pattern": "^ExecutorLog AgentExecutor gets invoked",
      "action": "resetPlatformScriptContext",
      "description": "Marks the start of a new AgentExecutor.exe invocation. AgentExecutor hosts BOTH platform scripts (Policies\\Scripts\\<id>.ps1) and proactive-remediation scripts (IMECache\\HealthScripts\\<id>\\detect.ps1) and writes their lines interleaved into the shared AgentExecutor.log. The policyId-less 'Powershell exit code is N' / 'write output done' lines are otherwise routed to the last-started platform script via a sticky pointer, so a remediation invocation (whose start line does not match PS-AGENT-SCRIPT-START) leaks its exit/output into that platform script's result. This pattern resets the platform-script line-capture context at each invocation boundary so only the matching platform invocation captures its own exit/output.",
      "enabled": true
@@ -749,7 +680,7 @@
    {
      "patternId": "PS-AGENT-OUTPUT",
      "category": "always",
-      "pattern": "write output done\\. output = (?<output>[\\s\\S]*?), error = (?<error>[\\s\\S]*)",
+      "pattern": "^write output done\\. output = (?<output>[\\s\\S]*?), error = (?<error>[\\s\\S]*)",
      "action": "scriptOutput",
      "parameters": {
        "scriptType": "platform"
@@ -760,7 +691,7 @@
    {
      "patternId": "PS-AGENT-SCRIPT-START",
      "category": "always",
-      "pattern": "Adding argument powershell with value C:\\\\.*\\\\Policies\\\\Scripts\\\\[a-z0-9\\-]+_(?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})\\.ps1",
+      "pattern": "^Adding argument powershell with value C:\\\\.*\\\\Policies\\\\Scripts\\\\[a-z0-9\\-]+_(?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})\\.ps1",
      "action": "scriptStarted",
      "parameters": {
        "scriptType": "platform",
@@ -772,7 +703,7 @@
    {
      "patternId": "PS-SCRIPT-CONTEXT",
      "category": "always",
-      "pattern": "Launch powershell executor in (?<context>machine|user) session",
+      "pattern": "^Launch powershell executor in (?<context>machine|user) session",
      "action": "scriptContext",
      "description": "Captures whether a PowerShell script runs in machine (System) or user session context.",
      "enabled": true
@@ -780,7 +711,7 @@
    {
      "patternId": "PS-SCRIPT-EXITCODE",
      "category": "always",
-      "pattern": "Powershell execution is done, exitCode = (?<exitCode>-?\\d+)",
+      "pattern": "^Powershell execution is done, exitCode = (?<exitCode>-?\\d+)",
      "action": "scriptExitCode",
      "description": "Captures the PowerShell exit code when script execution completes in the IME log.",
      "enabled": true
@@ -788,7 +719,7 @@
    {
      "patternId": "PS-SCRIPT-GENERATED",
      "category": "always",
-      "pattern": "Script file C:\\\\.*\\\\Policies\\\\Scripts\\\\[a-z0-9\\-]+_(?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})\\.ps1 is generated",
+      "pattern": "^Script file C:\\\\.*\\\\Policies\\\\Scripts\\\\[a-z0-9\\-]+_(?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12})\\.ps1 is generated",
      "action": "scriptStarted",
      "parameters": {
        "scriptType": "platform"
@@ -799,7 +730,7 @@
    {
      "patternId": "PS-SCRIPT-RESULT",
      "category": "always",
-      "pattern": "\\[PowerShell\\] User Id = [a-z0-9\\-]+, Policy id = (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}), policy result = (?<result>\\w+)",
+      "pattern": "^\\[PowerShell\\] User Id = [a-z0-9\\-]+, Policy id = (?<id>[a-z0-9]{8}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{12}), policy result = (?<result>\\w+)",
      "action": "scriptCompleted",
      "parameters": {
        "scriptType": "platform"
@@ -1,16 +1,16 @@
 {
  "$schema": "../schema/gather-rule.schema.json",
  "ruleId": "GATHER-DEVICE-006",
-  "title": "Collect dsregcmd join status on overdue hybrid sign-in",
-  "description": "Runs dsregcmd /status the moment the agent reports a hybrid sign-in as overdue (hybrid_login_pending), capturing the Entra join and registration state at exactly the point where the problem is detected. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
+  "title": "Collect dsregcmd join status on pending user affinity",
+  "description": "Runs dsregcmd /status the moment the agent reports that the signed-in user still has no Entra user token (entra_user_affinity_pending), capturing the device join and registration state at exactly the point where ANALYZE-ID-004 draws its evidence. Complements GATHER-DEVICE-001 (snapshot on entering Account Setup). Note: the agent runs as SYSTEM, so the output shows device join state — the per-user SSO/PRT state still requires running dsregcmd as the signed-in user.",
  "category": "device",
-  "version": "1.0.0",
+  "version": "1.1.0",
  "author": "Autopilot Monitor",
  "enabled": false,
  "collectorType": "command_allowlisted",
  "target": "dsregcmd /status",
  "trigger": "on_event",
-  "triggerEventType": "hybrid_login_pending",
+  "triggerEventType": "entra_user_affinity_pending",
  "outputEventType": "gather_dsregcmd_status",
  "outputSeverity": "Info",
  "tags": ["device", "entra", "join", "hybrid"]
--- a/Show More
+++ b/Show More