feat(phase-2): docs reorg — promote Design to top-level section + author ADRs 0002-0010

- Move decisions/ -> docs/design/decisions/ so ADRs render in nav

- Move docs/project/customization.md -> docs/design/customization.md

- New design pages: index, scope-topology, health-model, signal-catalog, concept-mapping

- New ADRs (all Proposed; cite MS Learn / Brian Wren / Kevin Holman):

  0002 Signal source, 0003 Rollup policy, 0004 SCOM discovery, 0005 SCOM class hierarchy,

  0006 AzMon entity model, 0007 Naming convention, 0008 Customization strategy,

  0009 Alert vs health-state, 0010 Cloud prerequisites contract

- Rewrite track indexes (SCOM MP, Azure Monitor) as track-specific only

- Repurpose comparison/ as Migration section (concept table moved to design/)

- Update PLAN.md Phase 2 checklist; fix internal links

Author: kristopherjturner

PLAN.md

@@ -291,7 +291,7 @@ Both tracks use **worst-state** rollup as the default:
 - An expiring Key Vault secret rolls up to **Warning** at 30 days, **Critical** at 7 days.
 - VMs / workloads (out of scope here) that are stopped intentionally can be configured with **Suppressed** impact in workload-companion MPs.
 
-### Customization Strategy *(see [Customization](docs/project/customization.md))*
+### Customization Strategy *(see [Customization](docs/design/customization.md))*
 
 Every threshold, alert severity, and behavior is **parameterized** so customers customize without forking:
 
@@ -320,34 +320,32 @@ Every threshold, alert severity, and behavior is **parameterized** so customers
 - [x] Implement all three Mermaid diagrams in `diagrams/mermaid/`
 
 ### Phase 2 — Health Model Design
-- [ ] Author ADRs in `decisions/` (matches `AzureLocal/platform` template)
-  - [ ] ADR 0001 — Scope & topology (infra only — 3 layers, ~25 entities)
-  - [ ] ADR 0002 — Primary signal source (Azure Local PowerShell APIs + ARM/Resource Graph for Azure-side)
-  - [ ] ADR 0003 — Health rollup policy (worst-state default + impact exceptions)
-  - [ ] ADR 0004 — SCOM discovery strategy (PowerShell Discovery, not WMI)
-  - [ ] ADR 0005 — SCOM class hierarchy + hosting relationships (3-layer model)
-  - [ ] ADR 0006 — Azure Monitor entity model alignment (mirrors SCOM 1:1; uses ARM resources where available)
-  - [ ] ADR 0007 — Naming convention (cross-track parity)
-  - [ ] ADR 0008 — Customization strategy (sealed MP + override pack tiers; Bicep params + tiers)
-  - [ ] ADR 0009 — Alert vs health-state separation policy
-  - [ ] ADR 0010 — Cloud-side prerequisites contract (HCI Insights, AMA, DCMA, Service Group, RBAC, networking)
-- [ ] Build full structural inventory tables in PLAN.md / `design/`
-  - [ ] Component inventory (~25 entities across 3 layers)
-  - [ ] Signal inventory (~50–70 signals × dimensions × thresholds × source cmdlet)
-  - [ ] SCOM class hierarchy table
-  - [ ] Azure Monitor entity graph table
-  - [ ] SCOM ↔ Azure Monitor concept mapping table
-  - [ ] Threshold parameter catalog (cross-track parity table)
+- [x] Reorg docs site: add top-level Design section (cross-cutting), make track sections track-specific only
+- [x] Move ADRs into `docs/design/decisions/` so they render in MkDocs
+- [x] Move Customization into `docs/design/`
+- [x] Move SCOM ↔ AzMon concept mapping into `docs/design/concept-mapping.md`; comparison/ becomes Migration only
+- [x] Author ADRs in `docs/design/decisions/` (matches `AzureLocal/platform` template)
+  - [x] ADR 0001 — Scope & topology (infra only — 3 layers, ~25 entities) — Proposed
+  - [x] ADR 0002 — Primary signal source (Azure Local PowerShell APIs + ARM/Resource Graph) — Proposed
+  - [x] ADR 0003 — Health rollup policy (worst-state default + impact exceptions) — Proposed
+  - [x] ADR 0004 — SCOM discovery strategy (PowerShell Discovery, not WMI) — Proposed
+  - [x] ADR 0005 — SCOM class hierarchy + hosting relationships (3-layer model) — Proposed
+  - [x] ADR 0006 — Azure Monitor entity model alignment (mirrors SCOM 1:1) — Proposed
+  - [x] ADR 0007 — Naming convention (cross-track parity) — Proposed
+  - [x] ADR 0008 — Customization strategy (sealed MP + override pack tiers; Bicep params + tiers) — Proposed
+  - [x] ADR 0009 — Alert vs health-state separation policy — Proposed
+  - [x] ADR 0010 — Cloud-side prerequisites contract (HCI Insights, AMA, DCMA, Service Group, RBAC, networking) — Proposed
+- [x] Build full structural inventory tables in `docs/design/`
+  - [x] Component inventory (~25 entities across 3 layers) — `scope-topology.md`
+  - [x] Signal inventory (~60 signals × dimensions × thresholds × source) — `signal-catalog.md`
+  - [x] SCOM ↔ Azure Monitor concept mapping table — `concept-mapping.md`
+  - [x] Cloud-side prerequisites table — `azure-monitor/prerequisites.md`
 - [ ] Complete draw.io diagrams (replace Phase 1 stubs with real visuals)
   - [ ] `scom-health-model.drawio` — full 3-layer rollup tree
   - [ ] `azure-monitor-entity-graph.drawio` — entity graph w/ relationships
   - [ ] `concept-comparison.drawio` — side-by-side mapping
 - [ ] Refine Mermaid sources to match ADR 0005 / 0006 names
-- [ ] Write `docs/scom-mp/health-model.md` (embedded Mermaid + draw.io exports)
-- [ ] Write `docs/azure-monitor/concepts.md` (entities, signals, relationships)
-- [ ] Write `docs/comparison/index.md` (concept mapping table)
-- [ ] Phase 2 sign-off gate: ADRs Accepted, inventory reviewed, diagrams complete
-
+- [ ] Phase 2 sign-off gate: all 10 ADRs Accepted, inventory reviewed by maintainers, draw.io
 ### Phase 3 — Track 1: SCOM MP Authoring
 - [ ] Watch/review Brian Wren's SC 2012 R2 video series (23 modules) as primary authoring reference — see [Brian Wren Resources](#brian-wren--mpauthor-resources) below
 - [ ] Set up VSAE project + fragment library references (Kevin Holman fragments)

docs/azure-monitor/index.md

@@ -5,15 +5,42 @@ description: Azure Monitor Health Models for Azure Local (HCI) — overview.
 
 # Azure Monitor Health Models
 
-> Track 2 — Native Azure Monitor health monitoring for Azure Local clusters.
+> **Track 2** — Native Azure Monitor health monitoring for Azure Local clusters.
+
+This section covers **how the design is implemented** as an Azure Monitor Health Model.
+The *design itself* — entity model, signal catalog, rollup policy, customization — is
+track-agnostic and lives in [Design](../design/index.md). Read that first.
 
 !!! tip "Start here — Prerequisites"
     Before building or deploying the health model, work through the [Prerequisites](prerequisites.md)
     page. The model itself collects nothing — it pulls signals from data that other features (HCI
     Insights, AMA, DCMA, Resource Health) must already be flowing.
 
-!!! info "Coming soon"
-    The full health model design lands in Phase 2. See [PLAN.md](https://github.com/AzureLocal/azurelocal-scom-mp/blob/main/PLAN.md) for the roadmap.
+!!! info "Phase 4 — coming after Phase 2 sign-off"
+    Implementation lands in Phase 4 once the [Design ADRs](../design/decisions/index.md)
+    move from Proposed to Accepted. Roadmap in
+    [PLAN.md](https://github.com/AzureLocal/azurelocal-scom-mp/blob/main/PLAN.md).
+
+## What lives here
+
+| Page | Content |
+|---|---|
+| [Prerequisites](prerequisites.md) | Cloud-side setup contract (HCI Insights, AMA, DCMA, RBAC, networking) |
+| Entities (planned) | Implementation of [ADR 0006](../design/decisions/0006-azmon-entity-model.md) — Service Group + per-entity definitions |
+| Signals (planned) | DCMA metrics + KQL queries per [Signal Catalog](../design/signal-catalog.md) |
+| Health Objectives (planned) | Per-entity Availability/Performance/Configuration/Security objectives |
+| Alerts (planned) | Alert rules + action groups per [ADR 0009](../design/decisions/0009-alert-vs-health-state.md) |
+| Bicep modules (planned) | `health-model.bicep`, `service-group.bicep`, `alerts.bicep` + tier files |
+| Workbook (planned) | Azure Monitor Workbook for visualization |
+| Diagrams | Entity graph (Mermaid + draw.io), health propagation flow |
+
+## Where to start
+
+1. **[Prerequisites](prerequisites.md)** — make sure your cloud side is wired up
+2. [Design overview](../design/index.md) — the conceptual foundation
+3. [Azure Monitor entity model ADR](../design/decisions/0006-azmon-entity-model.md)
+4. [Cloud prerequisites contract ADR](../design/decisions/0010-cloud-prerequisites-contract.md)
+5. [Customization](../design/customization.md) — how operators tune the Azure Monitor track
 
 ## What will be here
 

docs/comparison/index.md

@@ -1,29 +1,43 @@
 ---
-title: SCOM ↔ Azure Monitor Comparison
-description: Side-by-side concept mapping between SCOM and Azure Monitor Health Models.
+title: Migration — SCOM → Azure Monitor
+description: SCOM-to-Azure-Monitor migration guidance for Azure Local health monitoring.
 ---
 
-# SCOM ↔ Azure Monitor Comparison
+# Migration — SCOM → Azure Monitor
 
-> Side-by-side concept crosswalk between the two health monitoring tracks.
+> **Phase 5 deliverable.** End-to-end migration guidance for operators moving from the
+> SCOM track to the Azure Monitor track (or running both side by side).
 
-!!! info "Coming soon"
-    Full comparison docs are planned for Phase 2. The concept mapping table is available in [REFERENCES.md](https://github.com/AzureLocal/azurelocal-scom-mp/blob/main/REFERENCES.md).
+!!! info "Phase 5 — coming after Phase 3 + 4"
+    Migration walkthroughs land after both tracks are authored and validated.
+    See [PLAN.md](https://github.com/AzureLocal/azurelocal-scom-mp/blob/main/PLAN.md).
 
-## Concept mapping (quick reference)
+## Looking for the concept crosswalk?
 
-| SCOM | Azure Monitor |
+The side-by-side concept mapping (SCOM ↔ Azure Monitor) lives under Design now —
+it's a track-agnostic foundation, not migration content:
+
+→ **[Design / Concept Mapping (SCOM ↔ AzMon)](../design/concept-mapping.md)**
+
+## What this section will cover
+
+| Page (planned) | Content |
+|---|---|
+| Migration walkthrough | Step-by-step move from SCOM MP to Azure Monitor Health Model |
+| Migration tool output | Auto-migrated vs manual migration items via the Microsoft `MP2AzMon` tool |
+| Side-by-side operation | How to run both tracks against the same Azure Local during transition |
+| Cutover checklist | Pre-cutover, cutover day, post-cutover validation |
+| Lessons learned | Common gotchas operators hit during migration |
+
+## Why migrate (or not)?
+
+| Reason to stay on SCOM | Reason to move to Azure Monitor |
 |---|---|
-| Management Pack | DCR + Alert Rules + Workbook (ARM/Bicep bundle) |
-| Health Model (rollup tree) | Azure Monitor Health Model (preview) |
-| Unit Monitor | Signal on an entity (metric or log query) |
-| Aggregate Monitor | Generic entity aggregating child health |
-| Dependency Monitor | Relationship with health propagation |
-| Health State (Green/Yellow/Red) | Healthy / Degraded / Unhealthy |
-| Distributed Application | Service Group + Health Model root entity |
-| SLA Reporting | Azure Monitor SLI/SLO (public preview) |
-| Discovery | Azure Resource Graph / Service Group auto-discovery |
-| Override | Signal threshold / entity impact setting |
-| Notification Subscription | Action Group |
-| Data Warehouse | Log Analytics Workspace |
-| Operations Console | Azure Portal + Workbooks + Grafana |
+| Existing SCOM investment + skill set | No SCOM infrastructure to maintain |
+| Hybrid estate that includes non-Azure-Local servers | Azure-only / Arc-only estate |
+| Custom SCOM MPs already in production | Greenfield Azure Local deployment |
+| Need on-prem alerting independent of Azure | Want Azure-native alerting + Workbooks + Grafana |
+
+The dual-track design of this project means you don't have to choose — both surfaces
+read from the same conceptual model.
+

docs/design/concept-mapping.md

@@ -0,0 +1,118 @@
+# Concept Mapping — SCOM ↔ Azure Monitor
+
+> The dual-track Rosetta Stone. Every architectural concept in this project, mapped 1:1
+> across the two delivery tracks. Locked by [ADR 0006](decisions/0006-azmon-entity-model.md)
+> (entity alignment) and [ADR 0007](decisions/0007-naming-convention.md) (naming).
+
+## Top-level concepts
+
+| Concept | SCOM | Azure Monitor Health Models |
+|---|---|---|
+| **Container for the whole model** | Distributed Application | Service Group + Health Model linked to it |
+| **Thing to be monitored** | Class instance | Entity (Azure Resource Entity / Logical Entity) |
+| **Class definition / type** | `<ClassType>` in MP XML | Entity type implied by ARM resource type or logical entity definition |
+| **How instances are found** | Discovery (PowerShell / WMI / script) | ARM resource membership in the Service Group + Resource Graph queries |
+| **Hierarchy** | Hosting relationships + reference relationships | Parent/child relationships in the entity graph |
+| **Health-bearing condition** | Monitor (Unit / Aggregate / Dependency) | Signal + threshold on an entity |
+| **Numeric data collection** | Performance Collection Rule | Metric / KQL query on a DCR-collected log |
+| **Event collection** | Event Collection Rule | KQL query on `Event` table populated by AMA |
+| **Alerting** | Alert generated by a Monitor or Rule | Alert Rule on the *signal* (separate from health state) |
+| **Customer tuning** | Override (in companion override pack) | Bicep parameter (in tier `.bicepparam` file) |
+| **Maintenance window** | Maintenance Mode | Manual `Healthy` health objective or impact override |
+| **Visualization** | SCOM Health Explorer + SquaredUp Dashboard Server | Azure portal Health Model view + Workbooks + SquaredUp Cloud |
+
+## Entity / class mapping
+
+Per [ADR 0005](decisions/0005-scom-class-hierarchy.md) and
+[ADR 0006](decisions/0006-azmon-entity-model.md), entities map 1:1 across tracks.
+
+| Logical entity | SCOM class | Azure Monitor entity type | ARM resource type (if applicable) |
+|---|---|---|---|
+| Cluster | `AzureLocal.Cluster` | Azure Resource Entity | `Microsoft.AzureStackHCI/clusters` |
+| Node | `AzureLocal.Node` | Azure Resource Entity | `Microsoft.HybridCompute/machines` |
+| Storage Pool | `AzureLocal.StoragePool` | Logical Entity (custom signals) | n/a — inferred from cluster |
+| Volume | `AzureLocal.Volume` | Logical Entity | n/a |
+| Storage Tier | `AzureLocal.StorageTier` | Logical Entity | n/a |
+| Network Intent | `AzureLocal.NetworkIntent` | Logical Entity | n/a (inferred from `MS-SDDC-Mgmt`) |
+| Storage Replica | `AzureLocal.StorageReplica` | Logical Entity | n/a |
+| Update / LCM | `AzureLocal.UpdateState` | Logical Entity | partly ARM `solutionUpdates` |
+| Arc Resource Bridge | `AzureLocal.ResourceBridge` | Azure Resource Entity | `Microsoft.ResourceConnector/appliances` |
+| AKS Arc platform | `AzureLocal.AKSArcPlatform` | Azure Resource Entity | `Microsoft.Kubernetes/connectedClusters` |
+| DCMA / Cloud Agent | `AzureLocal.DCMA` | Logical Entity | n/a |
+| HCI registration | `AzureLocal.HCIRegistration` | derived from cluster ARM | n/a |
+| Custom Location | `AzureLocal.CustomLocation` | Azure Resource Entity | `Microsoft.ExtendedLocation/customLocations` |
+| Logical Network | `AzureLocal.LogicalNetwork` | Azure Resource Entity | `Microsoft.AzureStackHCI/logicalNetworks` |
+| Managed Identity | `AzureLocal.ManagedIdentity` | Azure Resource Entity | `Microsoft.ManagedIdentity/userAssignedIdentities` (and system MI on cluster) |
+| Deployment SPN | `AzureLocal.DeploymentSPN` | Logical Entity (Graph) | n/a (Microsoft Graph) |
+| Key Vault | `AzureLocal.KeyVault` | Azure Resource Entity | `Microsoft.KeyVault/vaults` |
+| Storage Account | `AzureLocal.StorageAccount` | Azure Resource Entity | `Microsoft.Storage/storageAccounts` |
+| RBAC assignments | `AzureLocal.RBAC` | Logical Entity | n/a |
+| Update Manager linkage | `AzureLocal.UpdateMgrLinkage` | Logical Entity | `Microsoft.Maintenance/configurationAssignments` |
+| Data Collection Rule | `AzureLocal.DCR` | Azure Resource Entity | `Microsoft.Insights/dataCollectionRules` |
+| Log Analytics Workspace | `AzureLocal.Workspace` | Azure Resource Entity | `Microsoft.OperationalInsights/workspaces` |
+
+## Health state mapping
+
+| SCOM | Azure Monitor | Color | Generic state |
+|---|---|---|---|
+| `Success` | `Healthy` | Green | Healthy |
+| `Warning` | `Degraded` | Yellow | Degraded |
+| `Error` | `Unhealthy` | Red | Critical |
+| `Uninitialized` | `Unknown` | Grey | Unknown |
+
+## Signal naming parity
+
+Per [ADR 0007](decisions/0007-naming-convention.md), every threshold has a single logical
+name, with mechanical translation to each track's idiom:
+
+| Logical name | SCOM override key | Azure Monitor Bicep param |
+|---|---|---|
+| `Volume.FreeSpace.WarnPercent` | `Volume.FreeSpace.WarnPercent` | `volumeFreeSpaceWarningThresholdPct` |
+| `Volume.FreeSpace.CritPercent` | `Volume.FreeSpace.CritPercent` | `volumeFreeSpaceCriticalThresholdPct` |
+| `Node.CPU.WarnPercent` | `Node.CPU.WarnPercent` | `nodeCpuWarningThresholdPct` |
+| `Node.CPU.CritPercent` | `Node.CPU.CritPercent` | `nodeCpuCriticalThresholdPct` |
+| `KeyVault.SecretExpiry.WarnDays` | `KeyVault.SecretExpiry.WarnDays` | `keyVaultSecretExpiryWarningDays` |
+
+The translation is mechanical:
+- SCOM key uses dot-separated PascalCase verbatim from the logical name.
+- Bicep param uses camelCase, expands `Pct` → `Pct` and `Days` → `Days`, prefixed by entity.
+
+A round-trip linter validates parity at PR time (planned for Phase 3).
+
+## Rollup mapping
+
+| SCOM | Azure Monitor |
+|---|---|
+| Dependency Monitor with `Worst Of` algorithm | Child entity with `Standard` impact |
+| Dependency Monitor with `Best Of` algorithm | Child entity with custom impact rule |
+| Dependency Monitor disabled (or maintenance mode) | Child entity with `Suppressed` impact |
+| Aggregate Monitor (Availability/Performance/Configuration/Security) | Health Objective on the entity, scoped per dimension |
+
+## Alert mapping
+
+See [ADR 0009](decisions/0009-alert-vs-health-state.md). Alerts are intentionally separate
+from health state in both tracks.
+
+| SCOM | Azure Monitor |
+|---|---|
+| Monitor with `Generate alert` enabled | Alert rule on the underlying signal (metric / KQL) |
+| Alert severity (Critical / Warning / Information) | Alert severity (0–4) → action group routing |
+| Notification subscription | Action group |
+| Alert auto-resolve when monitor returns to Healthy | Alert auto-resolve via metric/log condition |
+
+## Migration implications
+
+Because the conceptual model is identical and naming is parity-locked, a customer running
+the SCOM MP today can migrate to the Azure Monitor track without re-learning *what* is
+monitored — only the surface differs. The
+[Migration Guide](../comparison/index.md) (Phase 5) walks through this end-to-end.
+
+## References
+
+- ADR 0005 — [SCOM class hierarchy](decisions/0005-scom-class-hierarchy.md)
+- ADR 0006 — [Azure Monitor entity model alignment](decisions/0006-azmon-entity-model.md)
+- ADR 0007 — [Naming convention](decisions/0007-naming-convention.md)
+- ADR 0009 — [Alert vs health-state separation](decisions/0009-alert-vs-health-state.md)
+- [Brian Wren, "Designing a Service Model" (SC 2012 R2 module 6)](https://learn.microsoft.com/en-us/shows/system-center-2012-r2-operations-manager-management-packs/)
+- [Azure Monitor Health Models — overview](https://learn.microsoft.com/en-us/azure/azure-monitor/health-models/)
+- [Azure Service Groups overview](https://learn.microsoft.com/en-us/azure/governance/service-groups/overview)

docs/project/customization.md docs/design/customization.mddocs/project/customization.md renamed to docs/design/customization.md

@@ -84,7 +84,7 @@ deployed *as part of* an Azure Local deployment, modeled across **three layers**
 - SQL MI / AVD / other workloads
 - Customer applications and their dependencies
 
-These are tracked in the [Roadmap](../docs/project/roadmap.md) as future companion MPs that
+These are tracked in the [Roadmap](../../project/roadmap.md) as future companion MPs that
 take a *dependency* on this health model.
 
 ## Consequences