docs: VitePress documentation site

.gitignore

@@ -318,3 +318,8 @@ $RECYCLE.BIN/
 
 # Windows shortcuts
 *.lnk
+
+# VitePress docs site (P0 bootstrap of plan 19)
+node_modules/
+docs/.vitepress/cache/
+docs/.vitepress/dist/

docs/.vitepress/config.ts

@@ -0,0 +1,159 @@
+import { defineConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-plugin-mermaid';
+
+// VitePress config for MTConnect.NET documentation.
+//
+// Site root: `docs/` (the existing top-level docs directory).
+// Mermaid: enabled via `vitepress-plugin-mermaid` so every architecture /
+// sequence / class-relationship / state-machine / wire-flow diagram in the
+// docs is authored in Mermaid (no ASCII art, no external image renders for
+// schematic content; see `extra-files.user/plans/19-vitepress-docs/00-overview.md`).
+
+export default withMermaid(
+  defineConfig({
+    title: 'MTConnect.NET',
+    description:
+      'The .NET implementation of the MTConnect Standard — 100% public-surface API coverage, 100% MTConnect Standard compliance.',
+    lang: 'en-GB',
+
+    // Output directory for `docs:build`. Default is `docs/.vitepress/dist`;
+    // overriding here is unnecessary unless we deploy from elsewhere.
+    // outDir: '.vitepress/dist',
+
+    // Base path. Defaults to '/'. If GitHub Pages publishes under a project
+    // path (e.g. `/MTConnect.NET/`), this will need to be set at deploy
+    // time. Left as the default for now.
+    // base: '/',
+
+    cleanUrls: true,
+
+    // P0 bootstrap: stub pages reference future siblings (per-version-matrix,
+    // wire-format, spec-cross-references, …) that land in P1+. Allow dead
+    // links during the bootstrap; tighten this to `false` (or a regex
+    // allow-list) once the stubs are filled in.
+    ignoreDeadLinks: true,
+
+    head: [
+      ['meta', { name: 'theme-color', content: '#1f6feb' }],
+    ],
+
+    themeConfig: {
+      // Top nav. Mirrors the section structure committed in plan 19:
+      // Compliance / Configure & Use / API / Concepts / Wire formats /
+      // Cookbook / Troubleshooting.
+      nav: [
+        { text: 'Getting started', link: '/getting-started' },
+        { text: 'Compliance', link: '/compliance/' },
+        { text: 'Configure & Use', link: '/configure/' },
+        { text: 'Concepts', link: '/concepts/' },
+        { text: 'API', link: '/api/' },
+        { text: 'Wire formats', link: '/wire-formats/' },
+        { text: 'Cookbook', link: '/cookbook/' },
+        { text: 'Troubleshooting', link: '/troubleshooting/' },
+      ],
+
+      // Sidebar starts as a placeholder skeleton; sections fill in as the
+      // narrative pages land in P3 of the plan.
+      sidebar: {
+        '/compliance/': [
+          {
+            text: 'MTConnect Standard compliance',
+            items: [
+              { text: 'Overview', link: '/compliance/' },
+              { text: 'Per-version compliance matrix', link: '/compliance/per-version-matrix' },
+              { text: 'Wire-format compliance', link: '/compliance/wire-format' },
+              { text: 'Spec-source-vs-implementation cross-references', link: '/compliance/spec-cross-references' },
+              { text: 'Known divergences from the Standard', link: '/compliance/known-divergences' },
+              { text: 'Compliance test harness', link: '/compliance/test-harness' },
+            ],
+          },
+        ],
+        '/configure/': [
+          {
+            text: 'Configure & Use',
+            items: [
+              { text: 'Overview', link: '/configure/' },
+              { text: 'Install', link: '/configure/install' },
+              { text: 'Configure an agent', link: '/configure/agent' },
+              { text: 'Configure an adapter', link: '/configure/adapter' },
+              { text: 'Run', link: '/configure/run' },
+              { text: 'Connect a consumer', link: '/configure/consumer' },
+              { text: 'Operate', link: '/configure/operate' },
+            ],
+          },
+          {
+            text: 'Integrations',
+            items: [
+              { text: 'InfluxDB', link: '/configure/integrations/influxdb' },
+              { text: 'MQTT — Protocol overview', link: '/configure/integrations/mqtt-protocol' },
+              { text: 'MQTT — AWS Greengrass (Moquette)', link: '/configure/integrations/mqtt-aws-greengrass-moquette' },
+              { text: 'MQTT — AWS Greengrass (Mqtt-Bridge)', link: '/configure/integrations/mqtt-aws-greengrass-mqtt-bridge' },
+              { text: 'MQTT — AWS IoT', link: '/configure/integrations/mqtt-aws-iot' },
+              { text: 'MQTT — HiveMQ', link: '/configure/integrations/mqtt-hivemq' },
+              { text: 'OpenSSL setup', link: '/configure/integrations/openssl' },
+            ],
+          },
+        ],
+        '/concepts/': [
+          {
+            text: 'Concepts',
+            items: [{ text: 'Overview', link: '/concepts/' }],
+          },
+        ],
+        '/api/': [
+          {
+            text: 'API reference',
+            items: [{ text: 'Overview', link: '/api/' }],
+          },
+        ],
+        '/wire-formats/': [
+          {
+            text: 'Wire formats',
+            items: [
+              { text: 'Overview', link: '/wire-formats/' },
+              { text: 'XML', link: '/wire-formats/xml' },
+              { text: 'JSON v1', link: '/wire-formats/json-v1' },
+              { text: 'JSON-CPPAGENT (v2)', link: '/wire-formats/json-cppagent' },
+              { text: 'JSON-CPPAGENT-MQTT', link: '/wire-formats/json-cppagent-mqtt' },
+              { text: 'SHDR', link: '/wire-formats/shdr' },
+            ],
+          },
+        ],
+        '/cookbook/': [
+          {
+            text: 'Cookbook',
+            items: [{ text: 'Overview', link: '/cookbook/' }],
+          },
+        ],
+        '/troubleshooting/': [
+          {
+            text: 'Troubleshooting',
+            items: [{ text: 'Overview', link: '/troubleshooting/' }],
+          },
+        ],
+      },
+
+      socialLinks: [
+        { icon: 'github', link: 'https://github.com/TrakHound/MTConnect.NET' },
+      ],
+
+      footer: {
+        message: 'Released under the MIT License.',
+        copyright: 'Copyright © TrakHound Inc.',
+      },
+
+      search: {
+        provider: 'local',
+      },
+    },
+
+    // Mermaid plugin options — leave at sensible defaults so diagrams pick
+    // up the site's light/dark theme automatically.
+    mermaid: {
+      // example: securityLevel: 'loose',
+    },
+    mermaidPlugin: {
+      class: 'mermaid my-mermaid',
+    },
+  })
+);

docs/README.md

@@ -0,0 +1,39 @@
+# MTConnect.NET documentation site
+
+VitePress-based documentation site for `MTConnect.NET`, rooted at this `docs/` directory.
+
+## Local development
+
+```bash
+# from the repository root:
+npm install
+npm run docs:dev    # serves at http://localhost:5173
+```
+
+## Build a static bundle
+
+```bash
+npm run docs:build
+npm run docs:preview    # serves the built bundle locally for verification
+```
+
+The build output lands in `docs/.vitepress/dist/` (gitignored).
+
+## Mermaid diagrams
+
+Every architecture / sequence / class-relationship / state-machine / wire-flow diagram in this site is authored in [Mermaid](https://mermaid.js.org/) — no ASCII art, no external image renders for schematic content. Mermaid is enabled via `vitepress-plugin-mermaid` (configured in `docs/.vitepress/config.ts`).
+
+To author a diagram in any markdown page:
+
+````markdown
+```mermaid
+flowchart TD
+  A[Step one] --> B[Step two]
+```
+````
+
+## Plan + status
+
+The full documentation plan (gitignored, internal) is at `extra-files.user/plans/19-vitepress-docs/00-overview.md`. The plan tracks the multi-phase rollout: P0 site bootstrap (this commit), P1 auto-generated API pages, P2 spec-version badges, P3 narrative docs, P4–P10 (CLI / module / wire-format / workflows / CI deploy / cross-link sweep / README update).
+
+The site lands as a single PR (`feat/vitepress-docs`) AFTER every currently-open per-issue PR (#139 through #155) merges upstream.

docs/api/index.md

@@ -0,0 +1,12 @@
+# API reference
+
+> [!NOTE]
+> Stub. The auto-generated API pages — one per public type per shipped library — land in P1 of the documentation plan (`extra-files.user/plans/19-vitepress-docs/00-overview.md`). The XML-doc-to-markdown pipeline is the largest single P-phase of the plan.
+
+Once P1 lands, this section will hold a documentation page for **every public class, interface, record, enum, and delegate** in every shipped library. Each page covers:
+
+- Type signature, namespace, target frameworks.
+- Every public method / property / event / field with its parameter docs, return docs, exception docs.
+- At least one usage example per type.
+- A "Spec versions" badge / table generated from the `[MinimumVersion]` / `[MaximumVersion]` attributes (per the SysML model's `Profile:normative` / `Profile:deprecated` stereotypes).
+- Cross-links to the narrative pages (Concepts, Configure & Use, Cookbook) that reference the type.

docs/compliance/index.md

@@ -0,0 +1,36 @@
+# MTConnect Standard compliance
+
+`MTConnect.NET` targets **100% MTConnect Standard compliance** across every advertised spec version (v1.0 through v2.7, with v2.8 RC tracking).
+
+> [!NOTE]
+> Stub. Narrative + matrices land in P3 of the documentation plan (`extra-files.user/plans/19-vitepress-docs/00-overview.md`). The page exists at P0 so the navigation links resolve.
+
+## What this section will cover
+
+- **[Per-version compliance matrix](./per-version-matrix)** — which spec versions are supported, with a per-envelope (Streams / Devices / Assets / Error) status per version.
+- **[Wire-format compliance](./wire-format)** — which on-the-wire codecs are byte-for-byte cppagent-parity (XML, JSON-CPPAGENT v2 array-of-wrappers, JSON-CPPAGENT-MQTT) and which deviate (with the deviations documented + justified).
+- **[Spec-source-vs-implementation cross-references](./spec-cross-references)** — for every code path that implements a normative spec rule, the docs cite the SysML XMI line / XSD element / prose paragraph that grounds it.
+- **[Known divergences from the Standard](./known-divergences)** — pointers to the standard-maintainer reports the campaign has filed so consumers can see what's known-broken in the standard itself and how the library handles each.
+- **[Compliance test harness](./test-harness)** — how to run `tools/test.sh -c` (the compliance tier) against any deployment, with sample output and how to interpret the failure categories.
+
+## Why "100%" and what it means
+
+A consumer asking "if I write to the spec using `MTConnect.NET`, am I conformant?" should be able to answer it in this section without reading the source. That's the bar.
+
+When the **standard contradicts itself** (XMI vs XSD, prose vs cppagent), this site states the divergence explicitly, names which artefact `MTConnect.NET` follows, and links to the maintainer-bound writeup that asks the standard to resolve the contradiction. The library's compliance is not blocked by the standard's internal disagreements.
+
+## Diagram (placeholder)
+
+```mermaid
+flowchart TD
+  Spec[MTConnect Standard] --> XMI[SysML XMI]
+  Spec --> XSD[XSDs per envelope]
+  Spec --> Prose[Prose Parts 1-4]
+  Spec --> CPP[cppagent reference]
+  XMI -.generates.-> Generator[MTConnect.NET-SysML-Import]
+  Generator -.emits.-> GCS[.g.cs files]
+  GCS --> Lib[MTConnect.NET libraries]
+  XSD -.validates.-> Wire[Wire output]
+  CPP -.parity check.-> Wire
+  Lib -.serializes.-> Wire
+```

docs/concepts/index.md

@@ -0,0 +1,14 @@
+# Concepts
+
+> [!NOTE]
+> Stub. Narrative content + class-relationship + sequence diagrams (Mermaid) land in P3. The page exists at P0 so the navigation links resolve.
+
+This section explains the core MTConnect concepts as they map to `MTConnect.NET`'s public types:
+
+- **Devices** — the top-level addressable thing the agent emits observations for.
+- **Components** — the recursively-nested machine pieces under a Device (Axes, Path, Spindle, …).
+- **DataItems** — the primitive observable points on a Component (an angle, a temperature, a tool offset, …).
+- **Observations** — the time-stamped values flowing through a DataItem.
+- **Assets** — non-observation entities the device tracks (cutting tools, fixtures, files, raw materials, pallets).
+
+A class-relationship diagram (Mermaid) and a per-concept page lands in P3.

docs/configure/index.md

@@ -0,0 +1,27 @@
+# Configure & Use
+
+End-to-end guides for installing, configuring, running, and connecting consumers to `MTConnect.NET`.
+
+> [!NOTE]
+> Stub. Narrative content lands in P3 of the documentation plan (`extra-files.user/plans/19-vitepress-docs/00-overview.md`). The page exists at P0 so the navigation links resolve.
+
+## What this section will cover
+
+- **[Install](./install)** — NuGet package install for each shipped library + the agent + the modules.
+- **[Configure an agent](./agent)** — `agent.config.yaml`, `Devices.xml`, per-module config, logging.
+- **[Configure an adapter](./adapter)** — SHDR / HTTP adapter config, ports, data-source bring-up.
+- **[Run](./run)** — local development, Docker, Windows service / systemd unit.
+- **[Connect a consumer](./consumer)** — curl + browser examples for `/probe`, `/current`, `/sample`, `/asset`; MQTT subscriber examples; JSON v2 sample parser in dotnet + Python.
+- **[Operate](./operate)** — observability, common error modes + recovery, backup / restore.
+
+## Integrations
+
+- **[InfluxDB](./integrations/influxdb)**
+- **[MQTT — Protocol overview](./integrations/mqtt-protocol)**
+- **[MQTT — AWS Greengrass (Moquette)](./integrations/mqtt-aws-greengrass-moquette)**
+- **[MQTT — AWS Greengrass (Mqtt-Bridge)](./integrations/mqtt-aws-greengrass-mqtt-bridge)**
+- **[MQTT — AWS IoT](./integrations/mqtt-aws-iot)**
+- **[MQTT — HiveMQ](./integrations/mqtt-hivemq)**
+- **[OpenSSL setup](./integrations/openssl)**
+
+(Each integration page exists today as a hand-written `docs/*.md` file authored before VitePress was adopted — they're absorbed into this site at P0 of the plan and rewritten in P3 to align with the rest of the site's voice + the current library/spec versions. Mermaid diagrams replace ASCII art where present.)

docs/MQTT-AWS-Greengrass-Moquette.md → docs/configure/integrations/mqtt-aws-greengrass-moquette.md

@@ -42,7 +42,7 @@ modules:
 ## Screenshots
 
 ### AWS Thing
-![Screenshot](../img/mqtt-aws-thing-certificates.png)
+![Screenshot](/img/mqtt-aws-thing-certificates.png)
 
 ### AWS Core Device
-![Screenshot](../img/mqtt-aws-greengrass-moquette-01.png)
+![Screenshot](/img/mqtt-aws-greengrass-moquette-01.png)

docs/MQTT-Protocol.md → docs/configure/integrations/mqtt-protocol.md

@@ -5,11 +5,11 @@ This is a protocol for accessing MTConnect data using MQTT that mimics the funct
 The main difference between the HTTP and MQTT protocols is that the MQTT protocol deals with the individual MTConnect entities directly (ex. Device, Observation, Asset).
 
 #### All Devices
-![All_Devices](../img/mtconnect-mqtt-protocol-all-01.png)
+![All_Devices](/img/mtconnect-mqtt-protocol-all-01.png)
 
 
 #### By Device
-![All_Devices](../img/mtconnect-mqtt-protocol-by-device-01.png)
+![All_Devices](/img/mtconnect-mqtt-protocol-by-device-01.png)
 
 
 ### Multiple Configurable Observation Intervals

docs/cookbook/index.md

@@ -0,0 +1,17 @@
+# Cookbook
+
+> [!NOTE]
+> Stub. Recipes land in P3 of the documentation plan (`extra-files.user/plans/19-vitepress-docs/00-overview.md`).
+
+Recipes for common problems:
+
+- Write your first agent.
+- Write your first adapter.
+- Write a custom agent module.
+- Configure the MQTT relay module.
+- Write a JSON-MQTT consumer.
+- Migrate from JSON v1 to JSON-CPPAGENT v2.
+- Add a custom DataItem type.
+- Persist Assets to disk.
+- Bridge an MTConnect agent to InfluxDB / Grafana.
+- Run the agent under a Windows service / systemd unit.

docs/getting-started.md

@@ -0,0 +1,13 @@
+# Getting started
+
+> [!NOTE]
+> Stub. Narrative content lands in P3 of the documentation plan (`extra-files.user/plans/19-vitepress-docs/00-overview.md`). The page exists at P0 so the navigation links resolve.
+
+This page will walk you through:
+
+1. Installing the `MTConnect.NET-Applications-Agents` NuGet package.
+2. Writing your first 20-line agent host.
+3. Hitting `/probe` and `/current` from a browser.
+4. Adding your first DataItem.
+
+Until then, see the project's [README](https://github.com/TrakHound/MTConnect.NET/blob/master/README.md) for the current quickstart.