@tetherto/mdk-skill 0.0.0 → 0.12.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tether
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,133 @@
+# @tetherto/mdk-skill
+
+The **MDK Developer Skill suite**: version-controlled procedural context, in
+the universal Agent Skills format (`SKILL.md`), that makes any
+skills-compatible coding agent (Cursor, Claude Code, …) fluent in MDK
+conventions the moment the repo is cloned.
+
+The suite ships eight flat skills: the `mdk` router plus full workflows for
+device Workers, app routes served through the Gateway, MDK Apps, UI pages, stack deployment, site sizing
+from a measured envelope, and the pre-publish security audit. Composite prompts (e.g. "create a UI to show
+\<metric\> for \<device family\>") are routed as an ordered chain in
+[`mdk/SKILL.md`](./src/skills/mdk/SKILL.md).
+
+Consumers install the suite with `mdk skill add`; see the
+[agent skills guide](../../docs/guides/ui/agent-skills.md). The rest of this
+README is for working on the suite itself.
+
+## Layout
+
+```text
+src/
+├── skills/                 # Suite content (flat: one dir per skill), hand-authored except where noted
+│   ├── mdk/                # Router + suite-wide references/
+│   ├── mdk-worker-plugin/  # Worker plugin workflow + scripts/assets
+│   ├── mdk-gateway-plugin/ # App route table + controllers workflow (scaffold via `mdk create app`)
+│   ├── mdk-create-app/     # MDK App workflow (package layout, manifest, plugin, UI; `mdk create app`)
+│   ├── mdk-ui-component/   # Dashboard page workflow + ui-registry (generated)
+│   ├── mdk-deployment/     # mdk.yaml / mdk run workflow
+│   ├── mdk-site-sizing/    # Size a site from a description + measured envelope
+│   └── mdk-publish-security/ # Pre-publish security audit: tarball scan + 18-class review
+├── sources.map.json        # Source-of-truth -> bundle mapping (contract schema comes from backend/core/mdk-worker)
+├── index.mjs               # Programmatic entry point (assemble / installSkills)
+├── index.d.ts              # TypeScript types for the entry point
+├── assemble.mjs            # CLI wrapper -> dist/skills/
+└── install.mjs             # CLI wrapper: dist/skills/* -> .cursor|.claude/skills/
+dist/skills/                # Assembled suite — build output, gitignored, never hand-edited
+```
+
+[`skills/mdk-ui-component/references/ui-registry.json`](./src/skills/mdk-ui-component/references/ui-registry.json) is generated, not hand-authored. It is a verbatim copy of the devkit's
+`dist/registry.json`, written by [`docs/scripts/sync-ui-registry.mjs`](../../docs/scripts/sync-ui-registry.mjs). Regenerate it with
+`npm run generate:ui-registry` from the repo root, which rebuilds the devkit registry and rewrites this file. Hand-edits do not survive the next run,
+and a stale copy tells coding agents to use component props that no longer exist. The
+`docs-freshness` workflow watches this file and its devkit source on PRs and
+fails the check when it drifts. The job summary shows what differs; fix it by running `npm run generate:ui-registry` (or
+`npm run regenerate-docs`) and committing the result.
+
+Skills are assembled and installed **flat** — clients discover
+`<skills-dir>/<name>/SKILL.md` one level deep, and each skill's `description`
+frontmatter is its routing trigger. Copied artifacts (the Worker template, the
+contract schema) are taken from their owning packages by [`assemble.mjs`](./src/assemble.mjs), never
+hand-maintained, so the bundle cannot drift from the source of truth.
+
+## Build and install
+
+```bash
+node src/assemble.mjs        # build dist/skills/ (also runs on npm prepack)
+npm run install:skills       # assemble + copy into the enclosing repo's
+                             # .cursor/skills/ and .claude/skills/ (gitignored)
+node src/install.mjs --client cursor   # one client only
+```
+
+## Programmatic API
+
+Consume the package (e.g. from the MDK CLI) instead of shelling out to the
+scripts. Resolution goes through node/npm, so it works both as a published
+dependency and as a local workspace package.
+
+```js
+import { installSkills } from '@tetherto/mdk-skill'
+
+// Copies the assembled skills into <target>/.cursor/skills and/or
+// <target>/.claude/skills. Assembles on demand inside the monorepo.
+// Stale MDK-shipped skills (renamed or dropped since the last install) are
+// removed; each `installed` entry lists them in `removed`. Skills without the
+// `suite: mdk-developer-skill` frontmatter stamp are never touched, and a
+// same-named one is reported in `skipped`.
+const { skills, installed, skipped } = installSkills({ client: 'all', target: process.cwd() })
+```
+
+Install safety: it throws if `.cursor`, `.claude` or their `skills` dir under
+the target is a symlink, and it only replaces an existing `<skills-dir>/<name>`
+whose `SKILL.md` carries `metadata.suite: mdk-developer-skill`. Symlinked or
+foreign skill dirs with a suite skill's name are left alone, listed in
+`skipped`, and reported through `onWarn` (default `console.warn`).
+
+Also exported: `assemble()`, `isAssembled()`, `canAssemble()`, and `CLIENT_DIRS`.
+
+## Try it — routing prompts
+
+Open the repo in a skills-aware agent after installing, then check that each
+prompt activates the matching skills:
+
+| Example prompt                                              | Skills it should invoke           |
+| ----------------------------------------------------------- | ----------------------------------- |
+| "Add a new power meter Worker for our site"                 | `mdk-worker-plugin`                 |
+| "I need to integrate a new miner device into MDK"           | `mdk-worker-plugin`                 |
+| "Author an mdk-contract.json for a temperature sensor"      | `mdk-worker-plugin`                 |
+| "Build a plugin that aggregates hashrate across all miners" | `mdk-gateway-plugin`                |
+| "Add a cross-Worker endpoint that rolls up a site summary"  | `mdk-gateway-plugin`                |
+| "Create a dashboard widget that shows live telemetry from a Worker" | `mdk-ui-component` (and `mdk-gateway-plugin` if no `/api` route yet) |
+| "Create a UI to show \<metric\> for \<device family\>"      | discover → `mdk-gateway-plugin` → `mdk-deployment` → `mdk-ui-component` |
+| "How do I deploy the MDK stack?"                            | `mdk-deployment`                    |
+| "Size this site: 80 Whatsminer M56S on a 16-core NVMe box"  | `mdk-site-sizing`                   |
+| "Security check the packages before we publish to npm"      | `mdk-publish-security`              |
+| "Create an MDK app called sentinel"                         | `mdk-create-app`                    |
+| "What is MDK and how is it structured?"                     | `mdk` (router)                      |
+
+## Verify the device-Worker skill
+
+```bash
+# contract validation (exit 0/1); add --schema-only to skip the semantic checks
+node dist/skills/mdk-worker-plugin/scripts/validate-contract.mjs \
+  packages/cli/templates/worker/mdk-contract.json
+
+# in-process smoke: telemetry sweep + command bounds, no Kernel, no DHT
+node dist/skills/mdk-worker-plugin/scripts/worker-smoke.mjs <worker-dir>
+```
+
+The end-to-end proof of the skill is scaffolding a new Worker from
+[`dist/skills/mdk-worker-plugin/SKILL.md`](./src/skills/mdk-worker-plugin/SKILL.md) alone — contract validation, smoke
+pass, and brittle unit tests all green before the Worker ever meets a Kernel.
+
+## Verify the site-sizing skill
+
+```bash
+# compile eval/profiles into references/envelope.json, then the held-out bar
+npm test --workspace=@tetherto/mdk-skill
+```
+
+The bar: the Skill's recommendations match the measured envelope on a held-out
+set of site descriptions. `eval-held-out.mjs` parses each case in
+[`src/skills/mdk-site-sizing/eval/held-out.json`](./src/skills/mdk-site-sizing/eval/held-out.json)
+and exits 0 only when every recommendation matches.

package/dist/skills/mdk/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: mdk
+description: >
+  Build on the MDK (Mining Device Kit) platform. Use whenever a task mentions
+  MDK, the Kernel, a Worker, a Worker Plugin, mdk-contract.json,
+  @tetherto/mdk-* packages, a miner / power meter / sensor / container
+  integration, a cross-worker aggregation endpoint, a UI component for
+  Worker/plugin data, or deploying an MDK stack.
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.5.0"
+license: Apache-2.0
+---
+
+# Building on MDK
+
+MDK is a P2P mining device management platform layered as:
+**Consumers → Gateway (or the standalone MCP server) → Kernel → Workers → Devices**.
+
+The Kernel ([`backend/core/kernel`](../../../../../backend/core/kernel/README.md)) discovers Workers over the Hyperswarm DHT,
+pulls telemetry, dispatches commands, and monitors health. Workers
+([`backend/workers/`](../../../../../backend/workers/README.md)) are device-protocol adapters: a **Worker Plugin**, either
+a directory-loaded package (`mdk-contract.json` + `src/` handlers, hosted on
+`WorkerRuntimeV2` — the shape `mdk create worker` scaffolds) or the older
+`{ contract, dir, connect }` + handler-module shape hosted on the generic
+`WorkerRuntime` ([`backend/core/mdk-worker`](../../../../../backend/core/mdk-worker/index.js); both shapes are documented in
+[`../mdk-worker-plugin/references/worker-base-api.md`](../mdk-worker-plugin/references/worker-base-api.md)).
+All Kernel ↔ Worker communication is MDK Protocol envelopes over
+`@hyperswarm/rpc` — never direct method calls.
+
+Load [`references/architecture.md`](./references/architecture.md) when you need the module-level picture, and
+[`references/protocol.md`](./references/protocol.md) before touching anything that sends or receives
+envelopes. [`references/package-index.md`](./references/package-index.md) maps every package name to its actual
+folder. [`references/glossary.md`](./references/glossary.md) decodes the terminology.
+
+## Route to the right skill
+
+Skills are installed as flat siblings — each row names a skill directory next
+to this one. **Read this table first** on every MDK task; many user prompts
+need more than one skill in order.
+
+### Single-skill tasks
+
+| Task purpose                     | Use skill                            | Read first              |
+| -------------------------------- | ------------------------------------ | ----------------------- |
+| Integrate a new device (miner, power meter, sensor, container) | `mdk-worker-plugin` | [`references/protocol.md`](./references/protocol.md) |
+| Add / change a Gateway aggregation HTTP endpoint only | `mdk-gateway-plugin` | Worker `mdk-contract.json` |
+| Scaffold a new MDK App package ready to publish | `mdk-create-app` | [`mdk-create-app/SKILL.md`](../mdk-create-app/SKILL.md) |
+| Build a UI page/widget for an **existing** `/api/...` route | `mdk-ui-component` | [`mdk-ui-component/references/ui-registry.json`](../mdk-ui-component/references/ui-registry.json) |
+| Deploy / run / register apps in `mdk.yaml` | `mdk-deployment` | project `mdk.yaml` |
+| Size a site from a description (Workers, host tier, envelope) | `mdk-site-sizing` | [`mdk-site-sizing/references/envelope.json`](../mdk-site-sizing/references/envelope.json) |
+| Security-audit packages before an npm publish | `mdk-publish-security` | [`mdk-publish-security/references/vuln-classes.md`](../mdk-publish-security/references/vuln-classes.md) |
+
+### Composite prompts (use multiple skills, in order)
+
+Prompts like **"create a UI to show \<metric\> for a \<device\>"** are
+**not** UI-only. Follow this chain:
+
+| Step | Skill                            | What you do                           |
+| ---- | -------------------------------- | ------------------------------------- |
+| 1    | *(discovery)* | Resolve each `mdk.yaml` → `spec.workers[].package` to its `mdk-contract.json` at the package root (or legacy `plugin/mdk-contract.json`); confirm the telemetry channel, unit, and brand/fingerprint exist |
+| 2    | `mdk-gateway-plugin` | If no Gateway route returns that shaped metric, `mdk create app <name>` (scaffolds + registers under `mdk.yaml` → `spec.apps`; manifest rules in `mdk-create-app`) then write the controller + `plugin/mdk-plugin.json` |
+| 3    | `mdk-deployment`                 | Restart with `mdk run` (or `mdk run app <name>`) as needed |
+| 4    | `mdk-ui-component` | Hook (`useQuery`) → presentational panel → thin page → `routes.ts`; props from [`ui-registry.json`](../mdk-ui-component/references/ui-registry.json) only |
+| 5    | `mdk-deployment`                 | Verify with `curl` + running dashboard |
+
+Skip step 2–3 when the route already exists and returns the right JSON.
+Skip step 1's device work — if the Worker/channel is missing, insert
+`mdk-worker-plugin` **before** step 2.
+
+```
+User: "show / UI / dashboard for <metric> on <device family>"
+        │
+        ▼
+  Contract exists? ──no──► mdk-worker-plugin ──┐
+        │ yes                                  │
+        ▼                                      ▼
+  /api route exists? ──no──► mdk-gateway-plugin ──► mdk-deployment
+        │ yes                                  │
+        ▼                                      ▼
+  mdk-ui-component  ◄──────────────────────────┘
+        │
+        ▼
+  mdk-deployment (smoke: curl + UI)
+```
+
+### Quick examples
+
+| User says                                              | Skills (ordered)                         |
+| ------------------------------------------------------ | ---------------------------------------- |
+| "Create a UI to show \<metric\> for \<device family\>" | discover contract → `mdk-gateway-plugin` → `mdk-deployment` → `mdk-ui-component` |
+| "Add a fleet-wide rollup API"                          | `mdk-gateway-plugin` → `mdk-deployment`  |
+| "Chart the existing `/api/...` in the dashboard"       | `mdk-ui-component`                       |
+| "Integrate a new Modbus meter"                         | `mdk-worker-plugin`                      |
+| "Start Kernel + Worker + Gateway"                      | `mdk-deployment`                         |
+| "Size this site / how many Workers for N miners"       | `mdk-site-sizing`                        |
+| "Audit the packages before we publish"                 | `mdk-publish-security`                   |
+
+## Non-negotiable invariants
+
+- **Workers never call the Kernel.** The protocol is unidirectional: the
+  Kernel pulls (`telemetry.pull`, `state.pull`, `health.ping`) and pushes
+  commands (`command.request`). A Worker only ever answers `handleRequest`.
+- **`mdk-contract.json` is the single source of truth** for a Worker's
+  telemetry, commands, health states and error codes. Validate it against
+  `references/mdk-contract.schema.json` (the Kernel terminates Workers whose
+  capability payload is malformed, and rejects commands not declared in it).
+- **Never add transport-level envelope fields.** The envelope is exactly
+  `{ id, version, type, action, sender, target, deviceId, timestamp, payload }`
+  — extend `payload` instead.
+- **Use canonical `@tetherto/mdk-*` names only** — the full list lives in
+  [`references/package-index.md`](./references/package-index.md).
+- **Never invent UI prop names or telemetry fields** — registry + contracts
+  only (`mdk-ui-component` / `mdk-gateway-plugin`).

package/dist/skills/mdk/references/architecture.md

@@ -0,0 +1,89 @@
+# MDK architecture
+
+Load this when you need to know which module owns a behavior, or where a
+request travels between a consumer and a physical device.
+
+## Layers
+
+```
+Consumers (UI, CLI, agents)
+    │  HTTP / @tetherto/mdk-client
+Gateway (backend/core/gateway, boot glue in backend/core/mdk)
+    │  MDK envelopes over HRPC
+Kernel (backend/core/kernel)
+    │  MDK envelopes over HRPC ('mdk' method), discovery via Hyperswarm DHT
+Workers — WorkerRuntime/WorkerRuntimeV2 hosting a Worker Plugin (backend/core/mdk-worker + backend/workers/*)
+    │  vendor protocol: CGMiner TCP, HTTP JSON, Modbus TCP, MQTT…
+Devices (miners, power meters, sensors, containers)
+```
+
+## Kernel modules ([`backend/core/kernel/lib/modules/`](../../../../../../backend/core/kernel/lib/modules/))
+
+Each module has one job and modules never cross-call, they interact through the interfaces they expose:
+
+| Module                  | Job                                                                                                                    |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `worker-registry`       | `deviceId` → `workerId` → channel mapping; source of truth for routability; explicit state transition table                |
+| `command-dispatcher`    | Validates a command against the Worker's declared capabilities (name, param types, `min`/`max` bounds → `ERR_PARAM_RANGE`) and routes it |
+| `command-state-machine` | Command lifecycle with explicit transition table; every mutation is WAL'd before it takes effect; emits `command:done` |
+| `telemetry-collector`   | Pull-based: sends `telemetry.pull`, returns the raw Worker payload                                                     |
+| `health-monitor`        | Ping-based (`health.ping`); updates registry health state only                                                         |
+| `scheduler`             | Drives the periodic pull/ping cadences                                                                                 |
+| `action-manager` / `action-caller` | Write-action approval lifecycle (`action.push`, `action.vote`, …) between Gateway and Kernel                |
+
+The protocol layer ([`backend/core/kernel/lib/protocol/`](../../../../../../backend/core/kernel/lib/protocol/)) owns the envelope
+([`envelope.js`](../../../../../../backend/core/kernel/lib/protocol/envelope.js)), the action set ([`actions.js`](../../../../../../backend/core/kernel/lib/protocol/actions.js)) and per-action payload
+validators ([`schemas.js`](../../../../../../backend/core/kernel/lib/protocol/schemas.js)); [`protocol.md`](./protocol.md) documents these in full.
+
+## Worker side
+
+Two Worker Plugin shapes exist side by side, hosted on two runtime classes
+that share the same envelope dispatch, DHT discovery, and Kernel-facing
+protocol. Details for both: [`../../mdk-worker-plugin/references/worker-base-api.md`](../../mdk-worker-plugin/references/worker-base-api.md).
+
+A module-exporting Worker package ships a **Worker Plugin** — `plugin/index.js`
+exporting `{ contract, dir, connect, disconnect? }` — plus plain device-client
+code in `lib/`. It never subclasses anything and never depends on the runtime.
+`WorkerRuntime` ([`backend/core/mdk-worker/lib/worker-runtime.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime.js)) is the
+generic host: it loads the plugin (eagerly requiring every handler declared in
+the contract), opens one frozen context `{ deviceId, device, config, services }`
+per device via `connect()`, answers the `'mdk'` HRPC method by dispatching
+envelopes to handlers, and announces itself on the Kernel's DHT topic. One
+runtime hosts N same-type devices; a device whose `connect()` fails is held
+`offline` (requests return `ERR_DEVICE_UNAVAILABLE`) without affecting
+siblings. This is the shape every currently shipped device family
+(`backend/workers/miners/*`, `power-meter/*`, `containers/*`, `minerpools/*`,
+`temperature/*`) still uses.
+
+A directory-loaded Worker package ships no module of its own: just
+`mdk-contract.json` at its root plus the handler files it declares under
+`src/` — no `plugin/index.js`, no `connect()`/`disconnect()`. `WorkerRuntimeV2`
+([`backend/core/mdk-worker/lib/worker-runtime-v2.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime-v2.js))
+takes the package's directory in place of a plugin object, and handlers are
+plain `async (params) => result` functions that read their device from the
+ambient `@tetherto/mdk-worker/device` module instead of a `ctx` argument.
+There is no boot-time probe and no offline state: every device reports
+`online` immediately, and an unreachable one surfaces as an error inside the
+telemetry payload instead. This is the shape `mdk create worker` scaffolds
+today; the scaffold itself, [`packages/cli/templates/worker/`](../../../../../cli/templates/worker/README.md), is the reference
+implementation in this repo.
+
+## Discovery and request flow
+
+1. A caller boots `WorkerRuntime` or `WorkerRuntimeV2` with a `kernelTopic`;
+   the runtime joins that Hyperswarm topic in server mode and writes its HRPC
+   public key to every incoming connection.
+2. The Kernel connects to topic peers, learns the Worker's key, then sends
+   `identity.request` and `capability.request`; the registry records the
+   Worker's devices and its published contract (handler paths stripped).
+3. The scheduler then drives `telemetry.pull` / `state.pull` / `health.ping`
+   on a cadence; consumers trigger `command.request` through the Gateway (agents through the standalone MCP server).
+4. Commands flow Gateway (or MCP server) → dispatcher (capability + bounds validation) →
+   state machine (WAL) → Worker → `command.result` back up.
+
+## Where things run
+
+[`examples/mvp-site/start.js`](../../../../../../examples/mvp-site/start.js) boots the whole picture as PM2-supervised processes:
+mock devices, Kernel, real Workers, Gateway, MCP server and UI. To host a single Worker
+in-process with no Kernel, `mdk validate worker --path . --smoke` runs it against the
+simulator its `smoke.config.js` starts; [`local-testing.md`](../../mdk-worker-plugin/references/local-testing.md) shows a minimal caller.

package/dist/skills/mdk/references/glossary.md

@@ -0,0 +1,27 @@
+# Glossary
+
+| Term | Meaning |
+| --- | --- |
+| **MDK** | Mining Device Kit — the whole platform: Kernel, Workers, Gateway, client, UI toolkit. |
+| **Kernel** | The orchestration core ([`backend/core/kernel`](../../../../../../backend/core/kernel/README.md), `@tetherto/mdk-kernel`): discovery, telemetry pulls, command dispatch, health. |
+| **Worker** | A device-type adapter process: `WorkerRuntime` or `WorkerRuntimeV2` hosting a Worker Plugin, speaking MDK envelopes upward and the vendor protocol downward. |
+| **Worker Plugin** | What a Worker package ships, one of two shapes: the older `plugin/index.js` exporting `{ contract, dir, connect, disconnect? }` plus handler modules under `plugin/src/` (every currently shipped device family), or a directory-loaded package exporting no module of its own — just `mdk-contract.json` at its root plus `src/` handlers (the shape `mdk create worker` scaffolds). Neither subclasses the runtime. |
+| **WorkerRuntime** | Generic plugin host ([`backend/core/mdk-worker`](../../../../../../backend/core/mdk-worker/index.js)) for the module-exporting shape: loads the plugin, owns device contexts via `connect()`, answers envelopes over HRPC, announces on the DHT. |
+| **WorkerRuntimeV2** | Host for the directory-loaded shape ([`backend/core/mdk-worker/lib/worker-runtime-v2.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime-v2.js)): takes a package directory instead of a plugin object, has no `connect()`/boot-time probe/offline state, and builds one plugin instance per device via `createInstance`. Shares envelope dispatch and DHT discovery with `WorkerRuntime`. |
+| **Contract** (`mdk-contract.json`) | A Worker's single source of truth: metadata, telemetry channels, commands (with param types/bounds), health states, error codes. Simultaneously machine-validation input and AI context. |
+| **Published contract** | The contract as returned on `capability.response` — a copy with internal `handler` paths stripped. |
+| **Envelope** | The nine-field MDK Protocol message ([`protocol.md`](./protocol.md)). |
+| **Action** | The envelope's verb, e.g. `telemetry.pull`, `command.request` ([`backend/core/kernel/lib/protocol/actions.js`](../../../../../../backend/core/kernel/lib/protocol/actions.js)). |
+| **Channel** | One declared telemetry entry; pulled individually via `query.type = '<name>'` or all together via `type: 'metrics'`. |
+| **Handler** | A plugin module mapped from a contract entry, never seeing envelopes or transport: `async (ctx, params) => result` on `WorkerRuntime`, or plain `async (params) => result` on `WorkerRuntimeV2` (no `ctx`). |
+| **ctx** | `WorkerRuntime`'s frozen per-device handler context `{ deviceId, device, config, services }`; `device` is whatever `connect()` returned. `WorkerRuntimeV2` handlers have no `ctx` — see **Ambient device module**. |
+| **connect / disconnect** | `WorkerRuntime`-only plugin lifecycle: `connect(config, { deviceId })` builds (and probes) a device client; failing devices are held `offline`. Directory-loaded (`WorkerRuntimeV2`) plugins have neither. |
+| **Ambient device module** (`@tetherto/mdk-worker/device`) | What a `WorkerRuntimeV2` handler `require()`s to reach its own device: `{ id, opts, env, config, logger }`. Intercepted before real module resolution, scoped to one device via a private per-device module registry. |
+| **Device** | One physical unit (a miner, a meter…) addressed by `deviceId`; a Worker owns its `deviceIds` exclusively. |
+| **`kernelTopic`** | The Hyperswarm DHT topic a Kernel listens on; Workers join it (server mode) to be discovered. |
+| **HRPC** | `@hyperswarm/rpc` — the transport; Workers expose one `'mdk'` method that takes and returns serialized envelopes. |
+| **Worker-infra services** | Optional process-owned services (logs, settings, stats, comments, provisioning…) injected as `opts.services`; served as built-in telemetry types / commands ahead of plugin handlers. |
+| **Mock** | A vendor-firmware simulator (per-worker `mock/server.js`, shared framework in [`backend/workers/mock/`](../../../../../../backend/workers/mock/README.md)) so Workers run without hardware. |
+| **Gateway** | HTTP boundary in front of the Kernel ([`backend/core/gateway`](../../../../../../backend/core/gateway/README.md)) for UI/HTTP consumers; AI agents reach Kernel through the standalone MCP server instead. |
+| **WAL** | Write-ahead log in the Kernel's command state machine: every state mutation is logged before it takes effect. |
+| **Family** | A device category + vendor line (Whatsminer, Antminer, ABB…) under `backend/workers/<category>/<family>/`. |