docs: VitePress documentation site

[ottobolyos]

Summary

Stand up a VitePress documentation site rooted at the existing top-level docs/ directory, with Mermaid diagrams enabled for every architecture / sequence / class-relationship / state-machine / wire-flow diagram. The site documents everything in the repository — every shipped library and module, every CLI tool, every test category and dev workflow, every wire format and codec, every configuration knob, every API surface, every spec-version difference and compliance posture. Anything that lives in the source tree is on the docs site; anything that doesn't ship is not.

Site layout

The site is rooted at the existing docs/ directory — no docs/site/ subdirectory. Top-level navigation:

• Compliance — MTConnect Standard compliance posture: per-version compliance matrix, wire-format compliance, spec-source-vs-implementation cross-references, known-divergences-from-the-Standard pointers, compliance-test-harness walkthrough.
• Configure & Use — install, configure an agent, configure an adapter, run (local / Docker / Windows service / systemd unit), connect a consumer, operate.
• Concepts — Devices / Components / DataItems / Observations / Assets and their relationships.
• API — auto-generated reference for every public class, interface, record, enum, delegate, method, property, event in every shipped library, with usage examples and spec-version badges (MinimumVersion / MaximumVersion).
• Wire formats — XML, JSON v1, JSON-CPPAGENT (v2), JSON-CPPAGENT-MQTT, SHDR — sample envelopes, codec class names, wire-flow diagrams.
• Cookbook — recipes for write-an-agent / write-an-adapter / write-a-module / configure-mqtt-relay / write-a-json-mqtt-consumer / migrate-versions / etc.
• Troubleshooting — XSD validation failures, schema-version mismatches, MQTT TLS handshake failures, common error modes and recovery.
• CLI tool reference — every shipped CLI's command-line surface + a complete example invocation.
• Module catalog — setup-and-config page per shipped agent module.

A "Testing & dev workflow" section covers tools/test.sh, tools/dotnet.sh, the compliance harness layers, and the per-version compliance matrices that already live under docs/testing/.

API stability — semver guarantees, deprecation policies — is documented per type / member where the source code already carries an [Obsolete] attribute, an XML <remarks> note, or a MaximumVersion attribute. The docs surface what the source declares.

Phase map

This PR delivers P0 — site bootstrap. Subsequent phases land in follow-up commits on this branch.

P0 — site bootstrap (this commit)

• package.json at the repo root — "type": "module", scripts docs:dev / docs:build / docs:preview. Dev-deps: vitepress, mermaid, vitepress-plugin-mermaid.
• docs/.vitepress/config.ts — site config: title, description, top nav, per-section sidebars, Mermaid plugin enabled via the withMermaid(...) wrapper, local search, GitHub social link, footer. cleanUrls: true, lang: 'en-GB', ignoreDeadLinks: true while stub pages reference future-phase pages.
• docs/index.md — landing page (layout: home) with hero, six feature cards, and a Mermaid architecture-at-a-glance flowchart.
• Per-section stub index.md pages for Compliance, Configure & Use, Concepts, API, Wire formats, Cookbook, Troubleshooting.
• docs/getting-started.md stub.
• docs/README.md — local-run instructions.
• .gitignore updated for node_modules/, docs/.vitepress/cache/, docs/.vitepress/dist/.
• Existing hand-written docs/*.md pages absorbed into docs/configure/integrations/ and docs/wire-formats/.
• Existing img/ directory moved to docs/img/; image references rewritten to absolute /img/* paths from the site root.
• Obsolete docs/index.html (1-byte placeholder) removed.

P1 — auto-generated API reference

XML triple-slash → markdown pipeline that walks every shipped *.csproj under libraries/ and agent/, extracts the bin/Release/<TFM>/<Lib>.xml doc files emitted by dotnet build -c Release, and produces one markdown page per public type at docs/api/<namespace-slug>/<TypeName>.md. Each page covers type signature, every public member, parameter / return / exception docs, and at least one usage example.

P2 — spec-version badges

Each API page gets an "Introduced in" badge sourced from the type's MinimumVersion attribute and (when set) a "Deprecated in" badge from MaximumVersion. A spec-compatibility mini-matrix shows which v1.x / v2.x versions the type appears in.

P3 — narrative docs

Hand-written companion pages for Getting Started, Concepts (with Mermaid class-relationship + sequence diagrams), Compliance, Configure & Use, Wire formats, Cookbook, Migration guides, Troubleshooting. Existing absorbed integration pages (docs/configure/integrations/influxdb.md, the MQTT broker pages, docs/configure/integrations/openssl.md) are rewritten in this phase to align voice + reflect current library / spec versions, with Mermaid replacing any ASCII diagrams.

P4 — CLI tool reference

For each shipped CLI (agent, adapter, module-host, MTConnect.NET-SysML-Import): help-text reference, example invocation, configuration-file knob list with defaults + permissible values.

P5 — Module catalog

Per shipped agent module (HTTP, MQTT, MqttRelay, MqttAdapter, MqttBroker, etc.): setup, configuration knobs, wire interaction.

P6 — Wire-format reference

Per format (XML, JSON v1, JSON-CPPAGENT v2, JSON-CPPAGENT-MQTT, SHDR): sample envelope, codec class name (linked to the API reference), spec-version compatibility, wire-flow Mermaid sequence diagram.

P7 — Workflow / how-to guides

Each workflow row in docs/testing/workflows.md gets a corresponding how-to that walks the user through performing it against a real local agent.

P8 — CI build + deploy

.github/workflows/docs.yml builds the VitePress site on every push to master and deploys to GitHub Pages. A PR check builds the site without deploying so doc-breaking changes surface in review.

P9 — Cross-link sweep

Walk every page; verify every internal link resolves. Spot-check external links for liveness.

P10 — README link

The repo's top-level README.md adds a Documentation section linking to the deployed site.

Verification

npm install
npm run docs:build
npm run docs:dev    # serves at http://localhost:5173

docs/index.md renders the Mermaid architecture flowchart; the seven stub section index pages and the absorbed integration pages are reachable through the new nav.

Out of scope for this branch

• Translations (English-only).
• Per-spec-version separate doc sites (one site, version badges).