@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk-deployment/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: mdk-deployment
+description: >
+  Deploy and run a working MDK stack from mdk.yaml. Use when the task mentions
+  "deploy", "run the stack", "start the Kernel + Workers + Gateway",
+  "register a plugin", "register an app", "mdk.yaml", or MDK environment configuration.
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.5.0"
+license: Apache-2.0
+---
+
+# Deploy and run an MDK stack
+
+In CLI-managed projects (this folder), the stack is declared in `mdk.yaml` and
+started with `mdk run`. Boot order matters: **Kernel → Workers → apps → Gateway/UI**.
+
+## Project shape
+
+```
+<project>/
+├── mdk.yaml                 # Stack spec (source of truth)
+├── package.json             # private root manifest; links workers/<name> and apps/<name> by file: deps
+├── workers/<name>/          # Worker Plugin packages (mdk create worker)
+├── apps/<name>/             # apps: mdk-app.yaml + plugin/ route table (mdk create app)
+├── apps/dashboard/          # UI shell (mdk create dashboard)
+└── .mdk/                    # runtime state written by `mdk run` — gitignored, disposable
+```
+
+Workers and apps are linked from the root manifest by relative `file:`
+dependencies: one root `npm install` links every component into the project's
+`node_modules`, which is how `mdk run` resolves them. The dashboard is
+deliberately **not** linked — it links the MDK UI packages by `file:` path and
+installs on its own, so its React is never hoisted alongside those links.
+
+## `mdk.yaml` essentials
+
+```yaml
+apiVersion: mdk/v1
+kind: Stack
+metadata:
+  name: <stack-name>
+spec:
+  kernel:
+    port: 3848
+  gateway:
+    port: 3847
+  apps:
+    - name: <app-name>                 # ^[a-z][a-z0-9-]*$; routes served under /apps/<app-name>
+      package: <app-package-name>      # e.g. fleet-summary, or @org/name
+      config: {}                       # overrides the mdk-app.yaml config defaults
+      # mount: /                       # serve at the Gateway root (required for @tetherto/mdk-app-agent)
+  mcp:
+    port: 3947   # optional — defaults to gateway.port + 100
+  workers:
+    - name: <worker-name>
+      package: ./workers/<worker-name>   # local path, or an installed npm name
+      config:
+        mock: true
+        devices:
+          - id: dev-0
+            opts: { host: 127.0.0.1, port: 18080, serial: DEV-0 }
+```
+
+Both `mdk create worker <name>` and `mdk create app <name>` scaffold the
+package **and** register it here automatically (Workers under
+`spec.workers`, apps under `spec.apps`) — no manual
+`package.json` linking step. `create worker` also seeds a stack-unique mock port/device id
+per Worker, so scaffolding several in one project never collides. A published
+package goes through `mdk add app <npm-or-github-source>` / `mdk add worker <source>`,
+which installs it, validates it, and only then adds the entry. If you add a
+package by hand instead, mirror that: `npm install` at the project root, append the
+entry yourself, then check it with `mdk validate app <name>` / `mdk validate worker <name>`.
+
+`spec.gateway.plugins` is rejected by the CLI; move each entry to `spec.apps` with a `name`.
+
+## Run commands
+
+```bash
+mdk run                     # whole stack from mdk.yaml: kernel + workers + one process per app + gateway
+mdk run kernel
+mdk run gateway
+mdk run worker <name>       # e.g. mdk run worker demo-miner
+mdk run app <name>          # one app runtime, in the foreground
+mdk run dashboard           # the scaffolded UI shell's dev server
+mdk run mcp                 # standalone MCP server for AI agents (needs Kernel running first)
+```
+
+`mdk run` with no target boots everything together; that's not a spec setting,
+just which command you type. Use the per-component targets and separate
+terminals when debugging one tier. Gateway port is `spec.gateway.port`
+(example: `3847`); curl an app at `http://127.0.0.1:<gateway-port>/apps/<app-name>/api/...`
+(or at `/api/...` when its entry sets `mount: /`). Each app runs in its own runtime process
+and accepts calls only from the Gateway's key; the Gateway forwards each request to it.
+
+Like the dashboard, `mcp` is never part of the default `all` target — always
+start it explicitly, in its own terminal, after `mdk run kernel` (a standalone
+`run mcp` has no in-process Kernel handle to reuse). It reads `spec.apps` and exposes each
+declared app's routes as agent-callable tools, over `spec.mcp.port` if set,
+else `spec.gateway.port + 100`. Routes not marked `"safety": "read-only"` are withheld
+unless it is started with `--allow-write`.
+
+Every caller publishes its Kernel key to `.mdk/trusted-keys/` (`gateway.pub`, `mcp.pub`,
+`cli.pub`, `app-<name>.pub`, …) and the fail-closed Kernel admits it with full access: an app's
+`permissions` in `mdk-app.yaml` are not enforced yet.
+
+Ctrl+C / SIGTERM stops components in reverse boot order (Gateway → apps → Workers →
+Kernel) and always exits, even if a component's own shutdown hangs.
+
+### Verify
+
+```bash
+mdk status                              # environment + Kernel/Gateway/worker health, exit code encodes it
+mdk status -o json | jq .health
+curl -s http://127.0.0.1:3847/apps/<app-name>/api/<route> | jq .
+```
+
+`mdk status` never starts, stops or repairs anything — it probes the Kernel
+over HRPC and the Gateway over HTTP, reports declared-vs-registered Workers, and
+counts an app as running while a live process holds its run lock.
+Exit codes: `0` healthy, `4` precondition not met (bad Node, invalid
+`mdk.yaml`, packages not installed), `5` stack not fully up.
+
+UI: `mdk run dashboard` (or `cd apps/dashboard && npm run dev` directly) and
+open the page route added by `mdk-ui-component`.
+
+## Scaffolding helpers
+
+| Need               | Command                                                |
+| ------------------ | ------------------------------------------------------ |
+| Guided `mdk.yaml`  | `mdk onboard`                                          |
+| New Worker package | `mdk create worker <name>` → then `mdk-worker-plugin`  |
+| New app            | `mdk create app <name>` (`mdk-create-app`) → then `mdk-gateway-plugin` for its routes |
+| Published app      | `mdk add app <npm-or-github-source>`                   |
+| New dashboard app  | `mdk create dashboard`                                 |
+
+The `create` commands run `npm install` by default (`--no-install` to skip) and, for
+Workers/apps, install at the project root so the new package links into the
+project rather than getting its own nested `node_modules`.
+
+## Boot-order invariant
+
+1. Kernel listening.
+2. Workers announce on the DHT topic, or attach directly when run in the same process.
+3. One runtime process per app (each builds its own Kernel client).
+4. Gateway reads each app's route table and forwards requests to its runtime; an app not up yet answers `503`.
+5. UI last — it only talks to the Gateway.
+
+Starting the UI or an app before the Worker is online yields empty arrays,
+not necessarily HTTP errors — treat an empty `devices: []` in an app
+response as a deployment signal, not a bug.
+
+## Hand-off
+
+| Next need                          | Skill                |
+| ---------------------------------- | -------------------- |
+| How many Workers / which host tier | `mdk-site-sizing`    |
+| New device Worker                  | `mdk-worker-plugin`  |
+| New app package                    | `mdk-create-app`     |
+| New aggregation API                | `mdk-gateway-plugin` |
+| New dashboard page                 | `mdk-ui-component`   |

package/dist/skills/mdk-gateway-plugin/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: mdk-gateway-plugin
+description: >
+  Build the HTTP routes of an MDK app (route table + controllers, served
+  through the Gateway) over one or more MDK Workers. Use when the task
+  mentions "aggregate", "combine Workers",
+  "site summary / rollup", "plugin", "mdk-plugin.json", "Gateway endpoint",
+  "cross-worker endpoint", or when a UI needs live Worker data and no matching
+  `/api/...` route exists yet.
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.5.0"
+license: Apache-2.0
+---
+
+# Build the routes of an MDK app
+
+The Gateway serves HTTP routes from **apps**. An app is a small Node package with an `mdk-app.yaml` manifest
+and a route table (`mdk-plugin.json`, in `plugin/` or the package root); `mdk run` runs each app in its own
+process and the Gateway forwards each request to it. Each route is a controller that queries Workers through
+the app's own `@tetherto/mdk-client`, built once from `require('@tetherto/mdk-gateway/plugin')`.
+
+Apps are the **server half** of any "show me X from my devices" request.
+If the UI needs data that no existing route returns, build the app's route
+first, then hand off to `mdk-ui-component`. Creating the package itself (manifest,
+permissions, layout) is the [`mdk-create-app`](../mdk-create-app/SKILL.md) skill; this
+skill owns the route table and controllers.
+
+## When to use this skill
+
+| Situation                                             | Action                     |
+| ----------------------------------------------------- | -------------------------- |
+| UI / chart needs a metric and no Gateway route exists | Add a route here first     |
+| Aggregate / rollup / site summary" across devices     | Add a route                |
+| Endpoint already exists (check `mdk.yaml` → `spec.apps`, or `mdk status`) | Skip — go straight to `mdk-ui-component` |
+| Need a new device protocol                            | Wrong skill — use `mdk-worker-plugin` |
+
+## Workflow
+
+### 1. site capability discovery (mandatory)
+
+Do **not** invent channel names, units, or device brands. Ground every field
+in an installed Worker contract.
+
+**Resolve each Worker's contract from `mdk.yaml` → `spec.workers[].package`:**
+
+| `package` value                               | Contract path                                                                       |
+| --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Local path (`./workers/<name>`, `../…`)       | `<package>/mdk-contract.json` (or legacy `<package>/plugin/mdk-contract.json`)      |
+| npm name (`@tetherto/mdk-worker-avalon`, …)   | `node_modules/<package>/mdk-contract.json` (or legacy `…/plugin/mdk-contract.json`) |
+
+Also scan `workers/*/mdk-contract.json` and `workers/*/plugin/mdk-contract.json` for any local scaffolds not yet
+listed in `mdk.yaml`. If an npm package is listed but missing under
+`node_modules/`, run `npm install` first — do not invent the contract.
+
+Then:
+
+1. Open each resolved `mdk-contract.json`.
+2. Read `capabilities.telemetry[]` / `commands[]` — note `name`, `type`, `unit`.
+3. Read `metadata.brand` / `deviceFamily` / `provider` for how to recognize
+   the device family at runtime.
+4. Confirm the Kernel actually has the Worker online (`mdk run worker <name>`
+   or `mdk status`) before assuming data flows.
+
+`getCapabilities` returns the capability list only — not full contract
+metadata (no `brand`/`provider`) — so the fingerprint you match against at
+runtime is the telemetry/command **name set**, derived from the contract you
+just read, not a hard-coded device list.
+
+### 2. Scaffold the app
+
+```bash
+mdk create app <app-name>
+```
+
+Scaffolds and registers in one step (manifest rules: [`mdk-create-app`](../mdk-create-app/SKILL.md)):
+
+```
+apps/<app-name>/
+├── package.json          # name: <app-name> (or @org/<app-name> with --org)
+├── mdk-app.yaml          # id, version (= package.json), displayName, permissions, config defaults
+└── plugin/
+    ├── mdk-plugin.json   # routes + OpenAPI-ish response schema
+    ├── lib/client.js     # the app's MDK client
+    └── controllers/
+        └── summary.js    # async (req) => payload
+```
+
+It also links the package into the project's root `package.json` (root `npm install`,
+skip with `--no-install`) and appends it under `mdk.yaml` →
+`spec.apps` (skip with `--no-stack-entry`) — no manual
+`package.json` linking step. Check it with `mdk validate app <app-name>`.
+
+### 3. Author `mdk-plugin.json`
+
+Every route needs:
+
+- `id` — stable dotted id (`<domain>.<metric>`, e.g. `fleet.summary`)
+- `handler` — relative path to the controller
+- `http.method` + `http.path` — the UI will `fetch` this path
+- `http.responses.200.content.application/json.schema` — real response shape
+- `description`, `constraints`, `examples`, `errors`, `safety`
+
+Path convention: `/api/<domain>/<resource>` (e.g. `/api/fleet/summary`). The Gateway serves it under
+`/apps/<app-name>` (so `/apps/<app-name>/api/fleet/summary`) unless the app's `spec.apps` entry sets
+`mount`; never write the `/apps/<app-name>` prefix into the route table yourself.
+
+Full field notes: [`references/plugin-authoring.md`](./references/plugin-authoring.md).
+
+### 4. Implement the controller
+
+Build the client once per app, in a `lib/client.js` every controller requires — the
+scaffold's `plugin/lib/client.js` is this exact pattern
+(`createMdkClient(config)` over `require('@tetherto/mdk-gateway/plugin')`).
+
+```js
+'use strict'
+
+const mdkClient = require('../lib/client')
+
+module.exports = async function myRoute (req) {
+  // mdkClient methods return the bare payload — never read `.payload`
+  const workersResp = await mdkClient.listWorkers()
+  const workers = (workersResp && workersResp.workers) || []
+  // … filter devices, pullTelemetry, shape response …
+  return { /* matches mdk-plugin.json schema */ }
+}
+```
+
+Typical [fan-out pattern](./references/controller-patterns.md):
+
+1. `listWorkers()` → collect `deviceIds`.
+2. `getCapabilities(deviceId)` → keep devices matching the contract fingerprint.
+3. `pullTelemetry(deviceId, 'metrics')` → read `metrics.<channel>`.
+4. Return a UI-friendly object (`unit`, totals, per-device rows).
+
+### 5. Register in `mdk.yaml`
+
+Already done if you scaffolded with `mdk create app` (step 2). Otherwise
+add it by hand (`name` matches `^[a-z][a-z0-9-]*$`):
+
+```yaml
+spec:
+  apps:
+    - name: <app-name>
+      package: <app-name>
+      config: {}
+      # mount: /   # only when a client calls the routes at the Gateway root
+```
+
+`spec.gateway.plugins` is rejected by the CLI; move any such entry to `spec.apps`.
+Then restart (`mdk run`, or `mdk run app <app-name>` beside `mdk run gateway`).
+Wiring and boot order details live in `mdk-deployment`.
+
+### 6. Smoke-check the route
+
+With the stack up:
+
+```bash
+curl -s http://127.0.0.1:<gateway-port>/apps/<app-name>/api/<domain>/<resource> | jq .
+```
+
+Confirm the JSON matches the schema and examples in `mdk-plugin.json`.
+Only then build UI against it.
+
+## Non-negotiable invariants
+
+- **Never reference a Worker, channel, or field** that is not in an installed
+  contract. Aggregation must be site-grounded.
+- **`mdkClient` returns bare payloads** — do not unwrap `.payload`.
+- **Recognize device families from capability signatures** when
+  `getCapabilities` omits brand/metadata (common). Prefer telemetry name sets
+  over hard-coded `deviceId` lists.
+- Controllers are **read-only by default**; set `"safety": "read-only"` unless
+  the route intentionally mutates (commands).
+- Throw `ERR_SCREAMING_SNAKE` strings; declare them under `errors` in the route.
+
+## Hand-off
+
+| Next need                             | Skill                     |
+| ------------------------------------- | ------------------------- |
+| App manifest, permissions, packaging  | `mdk-create-app`          |
+| Render this route in the dashboard    | `mdk-ui-component`        |
+| Register / restart / verify the stack | `mdk-deployment`          |
+| Device does not exist yet             | `mdk-worker-plugin` first |
+
+## References
+
+- [`references/plugin-authoring.md`](./references/plugin-authoring.md): `mdk-plugin.json` fields + a fully populated route example
+- [`references/controller-patterns.md`](./references/controller-patterns.md): list / filter / `pullTelemetry` patterns
+- [`../mdk/references/protocol.md`](../mdk/references/protocol.md): envelope / action set
+- Shipped monorepo examples (when present): `backend/apps/demo/` (read-only fan-out), `backend/apps/agent/` (auth + stream routes)

package/dist/skills/mdk-gateway-plugin/references/controller-patterns.md

@@ -0,0 +1,99 @@
+# Controller patterns
+
+Build the client once per app, in a `lib/client.js` every controller requires. The
+`plugin/lib/client.js` that `mdk create app` scaffolds is this exact pattern:
+
+```js
+const { config } = require('@tetherto/mdk-gateway/plugin')
+const { createMdkClient } = require('@tetherto/mdk-client')
+module.exports = createMdkClient(config)
+```
+
+`config` carries the app's own Kernel identity (`kernelKey`, `kernelKeyPair`), so the client connects with the app
+runtime's key.
+
+Controllers are plain async functions that require it:
+
+```js
+const mdkClient = require('../lib/client')
+
+module.exports = async function routeName (req) {
+  // ...
+  return payload
+}
+```
+
+`mdkClient` is `@tetherto/mdk-client`. Methods return **bare payloads** — never `.payload`. It connects on first use and
+memoizes the connection; a failure maps to `ERR_MDK_CLIENT_UNAVAILABLE` and resets so the next call retries — no `null`
+check needed, just a `try`/`catch` around the call if you want to remap the error.
+
+## Pattern: fan-out telemetry for a device family
+
+```js
+const isTargetFamily = (capsPayload) => {
+  const telemetry =
+    (capsPayload && capsPayload.capabilities && capsPayload.capabilities.telemetry) ||
+    (capsPayload && capsPayload.telemetry) ||
+    []
+  const names = new Set(telemetry.map((t) => t && t.name).filter(Boolean))
+  // Fingerprint derived from the installed contract — adjust per family
+  return names.has('<channel-1>') && names.has('<channel-2>')
+}
+
+module.exports = async function example (req) {
+  const workersResp = await mdkClient.listWorkers()
+  const workers = (workersResp && workersResp.workers) || []
+  const deviceIds = workers.flatMap((w) => w.deviceIds || [])
+
+  const rows = []
+  let total = 0
+
+  for (const deviceId of deviceIds) {
+    const caps = await mdkClient.getCapabilities(deviceId).catch(() => null)
+    if (!isTargetFamily(caps)) continue
+
+    const tel = await mdkClient.pullTelemetry(deviceId, 'metrics').catch(() => null)
+    const metrics = (tel && tel.metrics) || {}
+    const value = Number(metrics['<channel-1>']) // channel name from contract
+    if (!Number.isFinite(value)) continue
+
+    rows.push({ deviceId, value })
+    total += value
+  }
+
+  return { unit: '<unit-from-contract>', total, devices: rows }
+}
+```
+
+### Why capability fingerprints?
+
+Kernel `getCapabilities` returns the capability list, not full
+`mdk-contract.json` metadata (`brand`, `provider`, …). Matching on the
+telemetry name set (and optionally command names) is the reliable filter.
+Derive the set from the installed contract — do not guess.
+
+### Channel → metrics key
+
+`pullTelemetry(deviceId, 'metrics')` returns `{ metrics: { <channel>: value, ... } }`.
+Keys match contract telemetry `name` fields exactly.
+
+### Resilience
+
+- `.catch(() => null)` per device so one offline device does not fail the route.
+- Skip non-finite numbers instead of throwing.
+- Empty `rows` is a valid 200 — the UI shows an empty state.
+
+## Pattern: single-device read
+
+When the route takes `deviceId` (query/body):
+
+1. Validate `deviceId` is present.
+2. Optionally `getCapabilities` to confirm the channel exists.
+3. `pullTelemetry` once and return the shaped value.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `ERR_MDK_CLIENT_UNAVAILABLE` | `mdkClient` failed to connect (Kernel unreachable) |
+| `ERR_<DOMAIN>_*` | Domain-specific; declare in `mdk-plugin.json` `errors` |

package/dist/skills/mdk-gateway-plugin/references/plugin-authoring.md

@@ -0,0 +1,121 @@
+# mdk-plugin.json authoring
+
+## Package layout
+
+```
+apps/<name>/
+├── package.json
+├── mdk-app.yaml
+└── plugin/
+    ├── mdk-plugin.json
+    ├── lib/client.js
+    └── controllers/<route>.js
+```
+
+### package.json
+
+```json
+{
+  "name": "<name>",
+  "version": "0.1.0",
+  "private": true,
+  "description": "<one-line: what telemetry/commands this aggregates>"
+}
+```
+
+`mdk create app <name>` sets this for you (bare `<name>`, or `@org/<name>`
+with `--org`) — `mdk.yaml` references whatever name lands here, the same way
+it would a published package. `mdk-app.yaml`'s `version` must equal this
+`version`; the [`mdk-create-app`](../../mdk-create-app/SKILL.md) skill owns the rest of that manifest.
+
+### mdk-plugin.json — required route fields
+
+| Field | Purpose |
+| --- | --- |
+| `name` / `version` / `description` | Package identity (often mirrors package.json) |
+| `routes[].id` | Stable id (`<domain>.<resource>`) |
+| `routes[].handler` | Relative path, e.g. `./controllers/power.js` |
+| `routes[].auth` | `true` makes the Gateway answer `401` unless its `authVerifier` returns an identity, which reaches the controller as `req._info`. The Gateway hands `permissions` to that verifier as `route.permissions` and does not interpret them itself |
+| `routes[].http.method` | `GET` / `POST` / … |
+| `routes[].http.path` | Path the UI fetches (`/api/...`), served under `/apps/<app-name>` unless the app is mounted elsewhere |
+| `routes[].http.responses` | Document `200` schema + error statuses |
+| `routes[].description` | What the route does (operator + LLM context) |
+| `routes[].constraints` | Runtime preconditions (Kernel connected, channels present) |
+| `routes[].examples` | At least one request/response example with realistic values |
+| `routes[].errors` | `ERR_*` strings the controller may throw |
+| `routes[].safety` | `"read-only"` unless the route mutates devices. `mdk run mcp` withholds every other route unless started with `--allow-write` |
+
+## Response schema rules
+
+- Schema properties must match what the controller **actually returns**.
+- Prefer flat, UI-ready shapes:
+
+```json
+{
+  "unit": "W",
+  "total": 3400,
+  "devices": [
+    { "deviceId": "dev-0", "value": 3400 }
+  ]
+}
+```
+
+- Include the contract `unit` as a field so the UI never hard-codes it.
+- Name numeric fields with the unit suffix when helpful (`powerW`, not `power`
+  next to a separate `unit`), so cards can round without guessing.
+
+## Fully populated route example
+
+Every field from the table above, together, on one route:
+
+```json
+{
+  "id": "example.metric",
+  "handler": "./controllers/metric.js",
+  "auth": false,
+  "http": {
+    "method": "GET",
+    "path": "/api/example/metric",
+    "responses": {
+      "200": {
+        "description": "Aggregated metric across matching devices.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "unit": { "type": "string" },
+                "total": { "type": "number" },
+                "devices": { "type": "array" }
+              }
+            }
+          }
+        }
+      },
+      "400": { "description": "MDK client unavailable." }
+    }
+  },
+  "description": "Fans out telemetry.pull to matching devices and returns shaped rows.",
+  "constraints": [
+    "Requires the MDK client to be connected to a Kernel instance.",
+    "Devices must expose the contract channel(s) this route reads."
+  ],
+  "examples": [
+    {
+      "description": "Example success payload",
+      "request": "GET /api/example/metric",
+      "response": { "unit": "W", "total": 0, "devices": [] }
+    }
+  ],
+  "errors": ["ERR_MDK_CLIENT_UNAVAILABLE"],
+  "safety": "read-only"
+}
+```
+
+## Registering
+
+`mdk create app <name>` does all of this: links the package into the project's
+root `package.json` (root `npm install`) and appends it under `mdk.yaml` →
+`spec.apps[]` → `{ name: <name>, package: <name>, config: {} }`. Scaffolding by
+hand instead, do the same two steps yourself, run `mdk validate app <name>`,
+then restart with `mdk run`.