docs(mtconnect): P1 driver guide + tracking-doc update, defer write-back (Task 22)

- docs/drivers/MTConnect.md: getting-started guide for the P1 Agent MVP —
  config keys read off MTConnectDriverOptions/ConfigDto, capability surface,
  RawPath->dataItemId coercion precedence, UNAVAILABLE->BadNoCommunication +
  the rest of the quality-code table, CONDITION-as-String, browse-via-the-
  universal-browser, the fixture recipe (links the existing IntegrationTests
  Docker README instead of duplicating it), and a Known limitations section
  covering the two pre-existing fleet-wide gaps this build surfaced
  (IRediscoverable/IHostConnectivityProbe have no server consumer; no driver
  form blocks Save on validation). Records write-back (MTConnect Interfaces),
  P1.5 (native alarms, TIME_SERIES arrays, EVENT->enum), and P2 (SHDR ingest)
  as deferred per design doc SS3.6/SS9. Documents where the build diverged
  from the design: TrakHound MTConnect.NET was dropped entirely (no XML
  formatter in the pinned packages, no injectable HTTP handler) in favor of
  a hand-rolled System.Xml.Linq client, namespace-agnostic on LocalName.
- docs/drivers/README.md: adds MTConnect to the ground-truth driver table,
  the per-driver doc list, and the fixture coverage-map list.
- docs/plans/2026-07-24-driver-expansion-tracking.md: marks the MTConnect
  Wave-2 row Done (22/23 tasks; Task 21 live gate tracked separately in the
  plan file, not touched here), corrects mtconnect/cppagent -> mtconnect/agent
  in the fixture note, and links the new driver guide.

Deferred-cleanup decision (Task 1 review follow-up): removed
GenerateDocumentationFile/NoWarn CS1591 from Driver.MTConnect.Contracts's
csproj to match all eight sibling .Contracts projects, none of which carry
it. Verified both the Contracts project alone and the full solution still
build clean (0 warnings, 0 errors) with the flags gone — the existing XML
doc comments don't depend on GenerateDocumentationFile to compile.

docs/drivers/MTConnect.md

@@ -0,0 +1,344 @@
+# MTConnect Driver
+
+Getting-started guide for the MTConnect Agent driver (P1 Agent MVP). This is
+the short path — for the full design rationale read
+[`docs/plans/2026-07-15-mtconnect-driver-design.md`](../plans/2026-07-15-mtconnect-driver-design.md)
+and the build-vs-plan record in
+[`docs/plans/2026-07-24-mtconnect-driver.md`](../plans/2026-07-24-mtconnect-driver.md); for the
+fixture recipe read
+[`tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md`](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md)
+(not duplicated here).
+
+> **Live gate:** see the LIVE-GATE RESULT note in the plan's Task 21
+> (`docs/plans/2026-07-24-mtconnect-driver.md`) for the docker-dev `/run` verification outcome
+> (browse picker / typed editor / deploy / read / subscribe against the real Agent fixture).
+
+## What it talks to
+
+A **MTConnect Agent** — the vendor-neutral read-only telemetry endpoint that
+front-ends a machine tool (or fronts an adapter that itself talks to the
+machine over SHDR). The driver speaks plain HTTP + XML against the Agent's
+three standard REST paths:
+
+- `/probe` — the static device model (Device → Component → DataItem tree)
+- `/current` — a snapshot of every DataItem's latest observation
+- `/sample` — a `multipart/x-mixed-replace` long-poll stream of observation
+  deltas, keyed by a monotonic sequence number
+
+v1 is **agent-first and read-only** — Discover + Read + Subscribe, no Write —
+because the mainstream Agent surface has no "set value" operation.
+
+## Built vs. planned — read this before trusting the design doc's §2
+
+The design doc ([`2026-07-15-mtconnect-driver-design.md`](../plans/2026-07-15-mtconnect-driver-design.md))
+picked the **TrakHound `MTConnect.NET-Common` / `-HTTP`** NuGet packages (MIT,
+`netstandard2.0`) as the primary path, with a hand-rolled fallback. **The
+hand-rolled fallback is what shipped.** Task 6/7 of the implementation plan
+found by reflection + live invocation that the pinned TrakHound packages
+ship **no XML formatter** (`Document Formatter Not found for "xml"` — the
+formatter lives in a separate `MTConnect.NET-XML` package the design didn't
+pin) and that `MTConnectHttpClientStream` exposes no injectable `HttpClient`
+handler, so it cannot be unit-tested behind the driver's `IMTConnectAgentClient`
+seam. Both package references were dropped. There is **no TrakHound
+dependency anywhere in the shipped driver** — probe/current/sample parsing is
+hand-rolled `System.Xml.Linq` plus a multipart boundary reader, entirely
+behind `IMTConnectAgentClient`. See the CORRECTION block under Task 0 of the
+implementation plan for the full record.
+
+**Namespace-agnostic parsing.** Every parser matches XML elements on
+`LocalName` only, ignoring the document's XML namespace entirely, so
+MTConnect 1.3 through 2.x documents all parse without a schema-version
+branch. This is deliberate, not sloppy: a real Agent injects vendor-extension
+`Component`s in a foreign namespace whose child `DataItems` elements inherit
+the *default* namespace, and namespace-strict matching would silently drop
+the whole vendor component (and every DataItem beneath it) rather than fail
+loudly. Attributes are read **unqualified** for the same reason — so an
+`xsi:type` attribute is never mistaken for a DataItem's own `type`.
+
+## Project split
+
+| Project | Target | Role |
+|---------|--------|------|
+| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/` | net10.0 | In-process driver — `MTConnectDriver`, the hand-rolled `IMTConnectAgentClient` (probe/current/sample), the observation index, the factory |
+| `src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Contracts/` | net10.0 | `MTConnectDriverOptions`, `MTConnectTagDefinition`, and the pure `MTConnectDataTypeInference` table shared by the driver, browse-commit, and the AdminUI typed editor |
+
+No `.Browser` project — browse comes free from the Wave-0 universal
+discovery browser (see [Browse](#browse--free-via-the-universal-browser)
+below).
+
+## Capability surface
+
+`MTConnectDriver : IDriver, IReadable, ISubscribable, ITagDiscovery, IHostConnectivityProbe, IRediscoverable`
+(`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectDriver.cs`).
+
+Deliberately **not** `IWritable` — the Agent surface is read-only by design.
+Write-back exists only via optional, rarely-deployed MTConnect *Interfaces*
+(a request/response handshake, not a "set value" operation), and is out of
+scope for this build — see [Deferred](#deferred-not-in-this-build).
+
+| Capability | Path | Notes |
+|------------|------|-------|
+| `ITagDiscovery` | `DiscoverAsync` — streams `/probe`'s Device→Component→DataItem tree into the address-space builder | `SupportsOnlineDiscovery = true`, `RediscoverPolicy = Once` |
+| `IReadable` | `ReadAsync` → one `/current` per call | **Not the production data path** — see below |
+| `ISubscribable` | `SubscribeAsync`/`OnDataChange` — the shared `/sample` long-poll pump | **The production data path** |
+| `IHostConnectivityProbe` | periodic `/probe` under `Probe.*` | No consumer wires it today — see [Known limitations](#known-limitations) |
+| `IRediscoverable` | watches the Agent's `Header.instanceId` | No consumer wires it today — see [Known limitations](#known-limitations) |
+
+**`IReadable.ReadAsync` is never called by the running server.** The
+production data plane is entirely `ISubscribable` — `DriverInstanceActor`
+subscribes once and lives off `OnDataChange`. `ReadAsync` exists for the
+Client CLI (`... read -n ...`) and for the unit/integration suites; it is
+correct and tested, just not on the hot path.
+
+## Minimum deployment
+
+```jsonc
+"Drivers": {
+  "mtconnect-1": {
+    "Type": "MTConnect",
+    "Config": {
+      "AgentUri": "http://10.100.0.35:5000",
+      "DeviceName": null,
+      "RequestTimeoutMs": 5000,
+      "SampleIntervalMs": 1000,
+      "SampleCount": 1000,
+      "HeartbeatMs": 10000,
+      "Probe":     { "Enabled": true, "IntervalMs": 5000, "TimeoutMs": 2000 },
+      "Reconnect": { "MinBackoffMs": 0, "MaxBackoffMs": 30000, "BackoffMultiplier": 2.0 },
+      "Tags": []
+    }
+  }
+}
+```
+
+`RawTags[]` is not authored by hand — `DriverDeviceConfigMerger` injects it
+at deploy time from the tags authored on the `/raw` tree.
+
+### Config keys
+
+Read off `MTConnectDriverOptions` / `MTConnectDriverConfigDto`
+(`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Contracts/MTConnectDriverOptions.cs`,
+`src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect/MTConnectDriver.cs`):
+
+| Key | Default | Notes |
+|---|---|---|
+| `AgentUri` | — (required) | Agent base URI; the driver appends `/probe`, `/current`, `/sample` |
+| `DeviceName` | `null` | Scopes requests to `{AgentUri}/{DeviceName}/...`; `null` = whole Agent |
+| `RequestTimeoutMs` | `5000` | Per-call deadline for `/probe` and `/current` |
+| `SampleIntervalMs` | `1000` | The Agent's `/sample?interval=` query param |
+| `SampleCount` | `1000` | The Agent's `/sample?count=` query param |
+| `HeartbeatMs` | `10000` | The Agent's `/sample?heartbeat=` query param — also the watchdog's liveness window |
+| `Probe.Enabled` / `Probe.IntervalMs` / `Probe.TimeoutMs` | `true` / `5000` / `2000` | Background connectivity-probe knobs (mirrors `ModbusProbeOptions`) |
+| `Reconnect.MinBackoffMs` / `MaxBackoffMs` / `BackoffMultiplier` | `0` / `30000` / `2.0` | Geometric backoff after a failed request or a dropped `/sample` stream |
+| `Tags[]` | `[]` | Pre-v3 / CLI authoring surface — one `MTConnectTagDefinition` per DataItem `id` |
+| `RawTags[]` | `[]` (deploy-injected) | The v3 data-plane binding — see below |
+
+**All timing knobs are validated strictly positive** at `InitializeAsync`
+(`RequirePositive`, mirroring the arch-review 01/S-6 lesson: a `0` timeout
+does not mean "wait forever," it faults the driver). This applies to
+`RequestTimeoutMs`, `HeartbeatMs`, `SampleIntervalMs`, `SampleCount`, and
+(when the probe is enabled) `Probe.Interval` / `Probe.Timeout`.
+
+**No save-time gate on a blank `AgentUri` in the AdminUI.** The driver form
+renders an inline validation notice (`_form.Validate()`), but
+`DriverConfigModal.SaveAsync` has no per-form validation seam to block the
+Save button on it — no sibling driver form has one either. A blank
+`AgentUri` saves cleanly and fails at deploy with the driver's own error
+message, not at authoring time.
+
+## Data plane
+
+### FullName == DataItem `id`
+
+`FullName` (both `MTConnectTagDefinition.FullName` and every `RawTags[]`
+blob's identifier) is the MTConnect `DataItem@id` attribute — the value the
+universal browser commits and the key the driver resolves reads/subscribes
+against. `MTConnectTagConfigModel.FromJson` (the AdminUI typed editor) tries
+three spellings in order — `fullName` → `dataItemId` → `address` — and takes
+the first non-blank one, normalising onto `fullName` on save. `address` is
+accepted because that's the field name `RawBrowseCommitMapper` writes for a
+driver with no typed editor path, so a browse-committed tag stays readable
+even before the editor round-trips it.
+
+### Coercion-type precedence
+
+The driver keys its data plane by **RawPath** (the v3 raw-tag identity), not
+by DataItem id directly, resolving RawPath → dataItemId internally. Each raw
+tag's coercion type (the `DriverDataType` its Agent observation is parsed
+into) is resolved in this order, first non-null wins:
+
+1. The `RawTags[]` blob's `driverDataType` or `dataType` field (both
+   spellings accepted — the typed editor writes `dataType`, the driver's own
+   `tags[]` shape uses `driverDataType`).
+2. A matching `Tags[]` entry naming the same DataItem id.
+3. The Agent's own `/probe` declaration, via `MTConnectDataTypeInference.Infer`
+   (category/type/units/representation → `DriverDataType`).
+4. `DriverDataType.String` — the coercion that cannot fail.
+
+### Quality mapping
+
+`UNAVAILABLE` — MTConnect's one explicit "I have no value" sentinel — maps to
+**`BadNoCommunication`** (`0x80310000`). This is deliberately distinct from
+the fleet-standard `BadCommunicationError` (`0x80050000`, used elsewhere for
+the driver's *own* transport failure to the Agent): `UNAVAILABLE` means the
+Agent is reachable and answered, it just has no device-backed value for that
+item. A `CONDITION` observation's value is taken from its **element name**
+(`<Normal/>` → the string `"Normal"`, `<Fault/>` → `"Fault"`); a `<Unavailable/>`
+condition element normalises onto the same `UNAVAILABLE` sentinel as every
+other category so one comparison covers all three.
+
+Other status codes an observation can surface:
+
+| Code | Meaning |
+|---|---|
+| `BadTypeMismatch` (`0x80740000`) | The Agent's text isn't a value of the tag's coerced type at all |
+| `BadOutOfRange` (`0x803C0000`) | The Agent reported a number the coerced type can't represent |
+| `BadNotSupported` (`0x803D0000`) | A shape this build doesn't materialize — a `TIME_SERIES` vector, or a structured `DATA_SET`/`TABLE` observation (deferred to P1.5; see [Known limitations](#known-limitations)) |
+| `BadWaitingForInitialData` | Tag is authored but the Agent hasn't reported it yet |
+| `BadNodeIdUnknown` | DataItem id is neither authored nor ever observed |
+
+### Subscribe — the `/sample` pump
+
+One shared `/sample` long-poll stream per driver instance (the Agent streams
+the whole device model regardless of which subset is subscribed, so
+per-tag streams would be wasted round-trips), run under a heartbeat
+watchdog — `HttpClient.Timeout` cannot bound a long-lived stream, so a
+missing chunk **and** missing keep-alive heartbeat within
+`HeartbeatMs × N` is what detects a frozen peer.
+
+Ring-buffer overflow (the Agent's circular observation buffer wrapped past
+what the driver's cursor expects) is detected **two ways**, both triggering a
+`/current` re-baseline before the stream resumes:
+
+1. `IMTConnectAgentClient.IsSequenceGap` — the next chunk's `firstSequence`
+   is newer than the driver's expected cursor.
+2. An `MTConnectError` document reporting `OUT_OF_RANGE` — real Agents return
+   this both under HTTP 200 (a normal MTConnect error document) and as a bare
+   HTTP 400, and the client handles both.
+
+**An Agent `instanceId` change means the Agent restarted**, and is checked
+**before** the sequence-gap check (a restart also usually trips the gap, so
+the two need disambiguating, not just OR-ing together). On a changed
+`instanceId` the driver clears its cached probe model and raises
+`OnRediscoveryNeeded` — see [Known limitations](#known-limitations) for why
+that signal currently has no consumer.
+
+## Browse — free via the universal browser
+
+MTConnect ships **no bespoke browser project**. Setting
+`ITagDiscovery.SupportsOnlineDiscovery => true` is the entire integration:
+the Wave-0 `DiscoveryDriverBrowser` sees a driver whose `TryCreate` succeeds
+and whose instance reports online discovery, renders the AdminUI **Browse**
+button, constructs the driver, runs `InitializeAsync` (the `/probe` connect)
++ `DiscoverAsync` into a `CapturingAddressSpaceBuilder`, then tears the
+throwaway instance down. Each captured leaf's NodeId is the DataItem `id`,
+committed directly as `TagConfig.FullName` on pick. See
+[`docs/plans/2026-07-15-universal-discovery-browser-design.md`](../plans/2026-07-15-universal-discovery-browser-design.md).
+
+## CONDITION modelling (v1: plain String)
+
+Each `CONDITION` DataItem materializes as a `String` variable whose value is
+the current state word — `Normal` / `Warning` / `Fault` / `UNAVAILABLE`.
+There is no native OPC UA Part 9 alarm plumbing in this build;
+`DriverAttributeInfo.IsAlarm = true` is still stamped on a CONDITION leaf so
+the browse side-panel flags it and a future upgrade to native alarms doesn't
+need re-authoring. See [Deferred](#deferred-not-in-this-build).
+
+## Known limitations
+
+These are real, not placeholders — read them before relying on the driver
+for anything beyond values-and-conditions.
+
+1. **`IRediscoverable` and `IHostConnectivityProbe` have no consumer in the
+   server.** `DriverInstanceActor` wires only `ISubscribable.OnDataChange` and
+   `IAlarmSource.OnAlarmEvent`; nothing in the server subscribes to
+   `OnRediscoveryNeeded` or `OnHostStatusChanged` except `GalaxyDriver`
+   wiring its own internal `DeployWatcher` sub-component. So a restarted
+   Agent (a changed `instanceId`) leaves a stale address space behind an
+   otherwise-Healthy driver. **This is a pre-existing fleet-wide gap
+   affecting every driver that implements either interface** (eight drivers
+   besides Galaxy), not something specific to MTConnect — this build simply
+   surfaced it again.
+2. **`RawTagEntry.DeviceName` is accepted on the wire shape but ignored for
+   routing.** One driver instance owns exactly one Agent client scoped by
+   `MTConnectDriverOptions.DeviceName` (the top-level config key); the
+   per-tag `RawTagEntry.DeviceName` field the v3 raw-tag identity carries is
+   never read by the driver. Two `/raw` Devices authored under one MTConnect
+   driver instance both resolve to the same one Agent connection. Real
+   per-device routing (a client per device) would be a design change, not a
+   bug fix.
+3. **Nothing validates a raw tag's declared OPC UA `DataType` against the
+   blob's coercion type.** The `/probe`-sourced inference
+   (`MTConnectDataTypeInference`) narrows how often an author picks a wrong
+   type, but it doesn't close the gap — an authored `DataType` mismatched
+   against the actual Agent observation still surfaces as `BadTypeMismatch`
+   /`BadOutOfRange` at runtime rather than at authoring time.
+4. **`sampleCount` is not a legal `DataItem` attribute.** It belongs on a
+   `TIME_SERIES` *observation*, not the device-model declaration. A real
+   Agent that meets `sampleCount` on a `DataItem` declaration logs `The
+   following keys were present and not expected: sampleCount` and **drops
+   the entire data item** from the served model. A live TIME_SERIES tag
+   therefore always resolves to `ArrayDim = null` (variable-length array) in
+   practice — the fixture's canned `probe.xml`/`Devices.xml`, which does
+   declare a `sampleCount`, is unrealistic on this point and exists only to
+   pin the parsing rule itself.
+5. **CONDITION is a plain `String`, not a native Part 9 alarm** (see above).
+6. **`TIME_SERIES` arrays and structured `DATA_SET`/`TABLE` observations
+   surface as `BadNotSupported`**, not an approximation — see the Quality
+   mapping table.
+
+## Deferred (not in this build)
+
+- **Write-back (MTConnect Interfaces).** Design
+  [§3.6](../plans/2026-07-15-mtconnect-driver-design.md#36-iwritable--not-implemented-v1):
+  the mainstream Agent surface is read-only by design; Interfaces is a rare,
+  optional request/response handshake that would mislead if modelled as
+  `IWritable`. Revisit only on a concrete deployment need.
+- **P1.5 fast-follow** (design
+  [§9](../plans/2026-07-15-mtconnect-driver-design.md#9-phasing--effort)):
+  CONDITION → native OPC UA Part 9 alarms via `IAlarmSource` (the Galaxy
+  native-alarm pattern); `TIME_SERIES` SAMPLE arrays materialized as real
+  OPC UA arrays; EVENT controlled-vocabulary values → OPC UA enumerations.
+- **P2 (on demand): SHDR adapter ingest.** A `SourceMode: "Agent" | "Shdr"`
+  switch that opens the raw pipe-delimited SHDR TCP socket directly. Loses
+  auto-discovery (no device model without an Agent in front, so
+  `SupportsOnlineDiscovery` would have to report `false` and tags would be
+  authored by hand, like Modbus). Niche; not built.
+
+## Testing
+
+- **Unit tests** — `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Tests/`
+  (canned-XML fixtures, no network) — 491/491 at time of writing. Covers
+  discovery tree shape, `MTConnectDataTypeInference`, observation indexing,
+  `UNAVAILABLE` → `BadNoCommunication`, CONDITION state-word mapping,
+  multipart chunk framing, and ring-buffer re-baseline paging (both the
+  sequence-gap and the `OUT_OF_RANGE` legs).
+- **Integration tests** —
+  `tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/` — env-gated
+  on `MTCONNECT_AGENT_ENDPOINT` (default `http://10.100.0.35:5000`), skips
+  cleanly (12 Skipped) when the fixture is unreachable, 12/12 against a real
+  Agent. Read the fixture's own
+  [`Docker/README.md`](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md)
+  for the full recipe — summary only, here:
+  - Image is **`mtconnect/agent:2.7.0.12`** — not `mtconnect/cppagent`, which
+    does not exist on Docker Hub (the design's original assumption).
+  - The stack is **two services**: the Agent plus a stdlib-only SHDR adapter
+    (`Docker/adapter.py`, on `python:3.13-alpine`). An Agent with no adapter
+    reports every observation `UNAVAILABLE` forever, which proves nothing.
+  - Deployed at `/opt/otopcua-mtconnect/` on the shared docker host
+    (`10.100.0.35`, `project=lmxopcua` label). Endpoint
+    `http://10.100.0.35:5000`.
+  - `agent.cfg` must be **pure ASCII** — one non-ASCII byte anywhere,
+    including a comment, makes the config parser reject the whole file with
+    a bare `Failed / Stopped at line: N`.
+  - Bring-up: `lmxopcua-fix sync mtconnect` then `lmxopcua-fix up mtconnect`
+    (PowerShell helper, Windows-only) — or, directly on the docker host,
+    `rsync` the repo's `Docker/` dir to `/opt/otopcua-mtconnect/` and run
+    `docker compose up -d --wait`.
+
+## Further reading
+
+- [`docs/plans/2026-07-15-mtconnect-driver-design.md`](../plans/2026-07-15-mtconnect-driver-design.md) — full design: capability wiring, browse reconciliation, typed-editor spec, resilience/timeout rules, phasing
+- [`docs/plans/2026-07-24-mtconnect-driver.md`](../plans/2026-07-24-mtconnect-driver.md) — the executable implementation plan and the task-by-task build record, including where it diverged from the design (TrakHound → hand-rolled)
+- [`docs/plans/2026-07-24-driver-expansion-tracking.md`](../plans/2026-07-24-driver-expansion-tracking.md) — Wave-2 program tracking
+- [Docker fixture README](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md) — the authoritative fixture recipe (seeded device model, endpoint, Mac AirPlay port-5000 gotcha)

docs/drivers/README.md

@@ -30,6 +30,7 @@ Driver type metadata is registered at startup in `DriverTypeRegistry` (`src/Core
 | [FOCAS](FOCAS.md) | `Driver.FOCAS` | A | Pure-managed `FocasWireClient` — FOCAS/2 Ethernet binary protocol on TCP:8193, inlined into the driver assembly | IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IHostConnectivityProbe, IPerCallHostResolver, IAlarmSource | `IWritable` is implemented but read-only by design — `WriteAsync` returns `BadNotWritable` for every point. CNC-shaped data model (axes, spindle, PMC, macros, alarms) not a flat tag map. Previously Tier-C (Host + P/Invoke + shim DLL); retired in the 2026-04-24 migration when the managed wire client landed |
 | [OPC UA Client](OpcUaClient.md) | `Driver.OpcUaClient` | B | OPCFoundation `Opc.Ua.Client` | IDriver, ITagDiscovery, IReadable, IWritable, ISubscribable, IAlarmSource, IHistoryProvider, IHostConnectivityProbe | Gateway/aggregation driver — the only driver implementing driver-side `IHistoryProvider` (forwards HistoryRead to the upstream server). Opens a single `Session` against a remote OPC UA server and re-exposes its address space. Owns its own `ApplicationConfiguration` (distinct from `Client.Shared`) because it's always-on with keep-alive + `TransferSubscriptions` across SDK reconnect, not an interactive CLI |
 | [MQTT](Mqtt.md) | `Driver.Mqtt` (+ `.Browser`, `.Contracts`) | A | [MQTTnet 5](https://github.com/dotnet/MQTTnet) | IDriver, ITagDiscovery, IReadable, ISubscribable, IHostConnectivityProbe, IRediscoverable | **Push, not poll, and read-only** — the broker delivers PUBLISH frames the driver forwards straight to `ISubscribable.OnDataChange`; `IReadable` serves the last retained/received value from cache, and there is **no `IWritable`** (nothing publishes back). Subscriptions are indexed **by topic filter, not by topic**, so wildcard tags survive a reconnect. A rejected CONNACK throws `MqttConnectRejectedException`: unrecoverable codes → `Faulted` + supervisor stop, transient → retry. **Two modes:** `Plain` binds a tag to a concrete topic + JSON path; `SparkplugB` decodes vendored Eclipse-Tahu protobuf under one `spBv1.0/{groupId}/#` subscription and binds by the `group/edgeNode/device?/metric` tuple (birth/alias/seq-gap state machine, death→STALE, scoped rebirth NCMD). `IRediscoverable` fires on a DBIRTH but is **inert platform-side** — see [#507](https://gitea.dohertylan.com/dohertj2/lmxopcua/issues/507) |
+| [MTConnect](MTConnect.md) | `Driver.MTConnect` (+ `.Contracts`) | — | Hand-rolled `System.Xml.Linq` HTTP/XML client against a vendor-neutral MTConnect Agent (`/probe`, `/current`, `/sample`) — no TrakHound dependency (dropped; see the driver doc) | IDriver, ITagDiscovery, IReadable, ISubscribable, IHostConnectivityProbe, IRediscoverable | Read-only by design (no `IWritable`). Production data plane is entirely `ISubscribable`/`OnDataChange` — `IReadable` is CLI/test-only. Browse is free via the Wave-0 universal discovery browser, no bespoke browser project. `IRediscoverable`/`IHostConnectivityProbe` have no server-side consumer yet — a pre-existing fleet-wide gap, not MTConnect-specific |
 | [Historian.Gateway](../Historian.md) | `Driver.Historian.Gateway` | — | `ZB.MOM.WW.HistorianGateway.Client` gRPC (`historian_gateway.v1`) | IHistorianDataSource (server-side read backend) + alarm `SendEvent` writer + `WriteLiveValues` recorder + `IHistorianProvisioning` | Not a tag driver — the sole historian backend. Registers `GatewayHistorianDataSource : IHistorianDataSource` for HistoryRead and serves alarm-write + continuous historization through the gateway. No `IDriver`/`ITagDiscovery` surface. (The retired Wonderware sidecar backend it replaced is documented at [Historian.Wonderware.md](Historian.Wonderware.md).) |
 
 ## Per-driver documentation
@@ -50,6 +51,10 @@ Driver type metadata is registered at startup in `DriverTypeRegistry` (`src/Core
   - [OpcUaClient.md](OpcUaClient.md) — OPC UA Client (gateway/aggregation) driver: remote-server session, driver-side HistoryRead forwarding, reconnect behaviour
   - [Mqtt.md](Mqtt.md) — MQTT broker-subscribe driver: broker/TLS/auth config, topic + JSON-path tag binding, retained-value seeding, `#`-observation browser, CONNACK-rejection semantics, **Sparkplug B** (birth/alias/seq/rebirth state machine, birth-driven browse picker, death→STALE), and the **Known gaps** table
 
+- **MTConnect** has a short getting-started doc because the hand-rolled-vs-TrakHound divergence, the
+  data-plane precedence rules, and a non-trivial known-limitations list need explaining up front:
+  - [MTConnect.md](MTConnect.md) — Agent config, `FullName`==DataItem `id`, `UNAVAILABLE`→`BadNoCommunication`, CONDITION-as-`String`, browse-via-universal-browser, fixture recipe, deferred write-back
+
 - **Historian.Gateway** (server-side historian backend, not a tag driver) is documented in the main guide:
   - [../Historian.md](../Historian.md) — HistorianGateway backend: read-path registration, HistoryRead dispatch, alarm store-and-forward (`SendEvent`), continuous historization (`WriteLiveValues`), `EnsureTags` provisioning, config keys, deployment prerequisites. (The retired Wonderware sidecar backend it replaced: [Historian.Wonderware.md](Historian.Wonderware.md).)
 
@@ -68,6 +73,7 @@ Each driver has a dedicated fixture doc that lays out what the integration / uni
 - [OPC UA Client](OpcUaClient-Test-Fixture.md) — Dockerized `opc-plc` integration suite (task #215): real Secure Channel + Session, read + subscribe verified end-to-end; write not yet exercised in the integration suite; exhaustive capability matrix (reconnect, failover, cert-auth, history, alarms) via unit suite with mocked `Session`
 - [MQTT](Mqtt-Test-Fixture.md) — Dockerized `eclipse-mosquitto` with **TLS + real auth on both listeners (no anonymous fallback)** + a JSON-publisher sidecar; env-gated live suite (**15 tests**) — 7 plain (TLS/auth connect, CA pinning both ways, subscribe→value, retained seeding, wrong-password rejection) + 8 Sparkplug against a **project-owned C# edge-node simulator** on the `sparkplug` compose profile (birth→alias bind, DDATA, NDEATH→STALE, rebirth NCMD round-trip). Births are never retained, so `docker restart otopcua-sparkplug-sim` is how you force a fresh one
 - [Galaxy](../v1/drivers/Galaxy-Test-Fixture.md) — richest harness: gateway E2E + ZB SQL live-smoke + MXAccess opt-in (v1 archive)
+- [MTConnect](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md) — Dockerized `mtconnect/agent` + stdlib SHDR adapter (two services, the Agent alone reports everything `UNAVAILABLE`); 12/12 against the real Agent, canned XML unit fixtures cover the bulk (491/491)
 
 ## Related cross-driver docs
 

docs/plans/2026-07-24-driver-expansion-tracking.md

@@ -32,7 +32,7 @@ it reaches 📝.
 | **0** | Universal Discover-backed browser | [design](2026-07-15-universal-discovery-browser-design.md) | [plan](2026-07-15-universal-discovery-browser-implementation.md) · [tasks](2026-07-15-universal-discovery-browser-implementation.md.tasks.json) | 🟡 **Live gate open** | S–M | none (retrofits shipped drivers) |
 | **1** | Modbus RTU (extend Modbus) | [design](2026-07-15-modbus-rtu-driver-design.md) | [plan](2026-07-24-modbus-rtu-driver.md) · [tasks](2026-07-24-modbus-rtu-driver.md.tasks.json) | 🟢 **Built — live gate PASSED** (11 tasks, branch `feat/modbus-rtu-driver`, pending merge) | **S (lowest)** | `pymodbus` `rtu_over_tcp` — CI-simulatable, no new infra |
 | **1** | SQL poll | [design](2026-07-15-sql-poll-driver-design.md) | [plan](2026-07-24-sql-poll-driver.md) · [tasks](2026-07-24-sql-poll-driver.md.tasks.json) | 📝 **Plan ready** (22 tasks) | S–M | **existing central SQL Server** `10.100.0.35,14330` + SQLite unit |
-| **2** | MTConnect Agent | [design](2026-07-15-mtconnect-driver-design.md) | [plan](2026-07-24-mtconnect-driver.md) · [tasks](2026-07-24-mtconnect-driver.md.tasks.json) | 📝 **Plan ready** (23 tasks) | S–M | Dockerized `mtconnect/cppagent` — CI-simulatable |
+| **2** | MTConnect Agent | [design](2026-07-15-mtconnect-driver-design.md) | [plan](2026-07-24-mtconnect-driver.md) · [tasks](2026-07-24-mtconnect-driver.md.tasks.json) | ✅ **COMPLETE** — P1 Agent MVP, all 23 tasks + the 5-leg live gate PASSED (branch `feat/mtconnect-driver`, PR #506) | S–M | Dockerized `mtconnect/agent:2.7.0.12` (not `cppagent`) — CI-simulatable, live at `10.100.0.35:5000` |
 | **2** | MQTT / Sparkplug B | [design](2026-07-15-mqtt-sparkplug-driver-design.md) | [plan](2026-07-24-mqtt-sparkplug-driver.md) · [tasks](2026-07-24-mqtt-sparkplug-driver.md.tasks.json) | ✅ **COMPLETE** — P1 + P2 shipped, both live-gated (Tasks 0–26) | M–L | Mosquitto TLS+auth **+ C# Sparkplug edge-node simulator**, live at `10.100.0.35:8883` |
 
 > Waves 3+ (BACnet/IP, Omron) and the deferred MELSEC are tracked in the program design doc §6/§8,
@@ -134,15 +134,36 @@ SQL poll reuses the always-on central SQL Server. This is the recommended next b
 
 Both CI-simulatable on the shared docker host, no hardware.
 
-### MTConnect Agent — 📝 Plan ready
+### MTConnect Agent — ✅ Done (P1 Agent MVP)
 - **Design:** [`2026-07-15-mtconnect-driver-design.md`](2026-07-15-mtconnect-driver-design.md)
-- **Implementation plan:** [`2026-07-24-mtconnect-driver.md`](2026-07-24-mtconnect-driver.md) · [`.tasks.json`](2026-07-24-mtconnect-driver.md.tasks.json) — **23 tasks**. Task 0 is the TrakHound-vs-hand-rolled client decision; browse-picker live-verify is gated on Wave-0 #468.
+- **Implementation plan:** [`2026-07-24-mtconnect-driver.md`](2026-07-24-mtconnect-driver.md) · [`.tasks.json`](2026-07-24-mtconnect-driver.md.tasks.json) — **23 tasks; 22 built, Task 21 (live `/run` gate) tracked separately in the plan file.**
-- **Scope:** P1 Agent MVP (`IDriver`+`ITagDiscovery`+`IReadable`+`ISubscribable`+probe+rediscover),
+- **Driver guide:** [`docs/drivers/MTConnect.md`](../drivers/MTConnect.md) — config keys, capability
-  browse **free via the Wave-0 universal browser** (`SupportsOnlineDiscovery=true`, no browser code),
+  surface, data-plane precedence rules, quality-code mapping, and (most load-bearing) the **Known
-  typed editor, `UNAVAILABLE→BadNoCommunication` mapping, ring-buffer re-baseline paging.
+  limitations** section.
-- **Fixture:** canned XML unit fixtures (bulk of coverage) + a dockerized `mtconnect/cppagent`
+- **Scope shipped:** `IDriver`+`ITagDiscovery`+`IReadable`+`ISubscribable`+`IHostConnectivityProbe`+`IRediscoverable`
-  integration fixture (env-gated). Depends on Wave 0's browse seam being live-verified (#468).
+  (deliberately no `IWritable` — read-only Agent surface), browse **free via the Wave-0 universal
-- **Effort:** S–M (≈1–1.5 wk with TrakHound, ≈2.5–3 wk hand-rolled).
+  browser** (`SupportsOnlineDiscovery=true`, no browser project), typed AdminUI tag editor,
+  `UNAVAILABLE→BadNoCommunication` mapping, CONDITION-as-`String`, ring-buffer re-baseline paging
+  (both the sequence-gap and `OUT_OF_RANGE` legs).
+- **Diverged from the design:** Task 0/6/7 dropped the planned TrakHound `MTConnect.NET-Common`/`-HTTP`
+  dependency entirely — the pinned packages ship no XML formatter and the HTTP stream client has no
+  injectable handler to test behind the driver's seam. Parsing is hand-rolled `System.Xml.Linq`,
+  matching on `LocalName` only (namespace-agnostic, so 1.3–2.x all parse). See the driver guide's
+  "Built vs. planned" section.
+- **Test results:** MTConnect unit suite 491/491; integration suite 12/12 against a real Agent
+  (`mtconnect/agent:2.7.0.12`, **not** `mtconnect/cppagent` — that Docker Hub repo doesn't exist);
+  skips cleanly (12 Skipped) offline. AdminUI 749/749; full solution 0 build errors.
+- **Deferred (documented, not built):** write-back via MTConnect Interfaces (design §3.6); P1.5
+  CONDITION→native Part-9 alarms, `TIME_SERIES` array materialization, EVENT→enum vocab (design §9);
+  P2 SHDR adapter ingest (design §9). Also two pre-existing fleet-wide gaps this build surfaced
+  rather than caused: `IRediscoverable`/`IHostConnectivityProbe` have no server-side consumer (eight
+  drivers besides Galaxy), and no driver form blocks Save on a required-field validation error.
+- **Fixture:** canned XML unit fixtures (bulk of coverage) + a dockerized `mtconnect/agent` +
+  stdlib-SHDR-adapter integration fixture (env-gated), deployed at `/opt/otopcua-mtconnect/` on the
+  shared docker host. See the fixture's own
+  [`Docker/README.md`](../../tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.IntegrationTests/Docker/README.md).
+- **Effort:** S–M, hand-rolled (the TrakHound estimate in the design doc did not apply once that
+  path was ruled out).
 
 ### MQTT / Sparkplug B — ✅ **COMPLETE** (P1 + P2, both live-gated)
 - **Design:** [`2026-07-15-mqtt-sparkplug-driver-design.md`](2026-07-15-mqtt-sparkplug-driver-design.md)
@@ -219,12 +240,12 @@ Both CI-simulatable on the shared docker host, no hardware.
 
 ## Next actions
 
-1. **Close the Wave-0 live gate** (Gitea #468) — unblocks browse verification for MTConnect/BACnet.
+1. **Close the Wave-0 live gate** (Gitea #468) — unblocks browse verification for BACnet (MTConnect
+   shipped its own Task-21 live `/run` gate independently — see the plan file).
 2. **Build Wave 1** — Modbus RTU first (lowest effort, no new infra), then SQL poll. Both plans are
    📝 ready; run the command from the [Executing a plan](#executing-a-plan-git-worktree--subagent-per-task)
    table (subagent-driven-development in a git worktree).
-3. **Build Wave 2** — MTConnect's browse leg wants #468 closed first. **MQTT / Sparkplug B is
+3. **Wave 2 is done.** Both deliverables shipped and live-gated: **MQTT / Sparkplug B** (P1 + P2) and **MTConnect Agent** (P1 Agent MVP, PR #506). Remaining work on both is optional follow-on — MQTT P3 write-through (`IWritable`: NCMD/DCMD + plain publish) plus its two browse-UI
-   COMPLETE** (P1 + P2, both live-gated); its only remaining work is optional — P3 write-through
+   gaps, and MTConnect write-back (deliberately deferred; the Agent surface is read-only).
-   (`IWritable`: NCMD/DCMD + plain publish) and the two browse-UI gaps recorded above.
 
 Update this file's Summary table and per-wave status whenever a deliverable changes state.

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Contracts/ZB.MOM.WW.OtOpcUa.Driver.MTConnect.Contracts.csproj

@@ -5,8 +5,6 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-        <GenerateDocumentationFile>true</GenerateDocumentationFile>
-        <NoWarn>$(NoWarn);CS1591</NoWarn>
     </PropertyGroup>
 
     <!-- Pure records + the MTConnect data-type inference table, shared by the driver, browse-commit,