@tetherto/mdk-skill 0.0.0 → 0.12.1

package/dist/skills/mdk/references/mdk-contract.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "This schema describes a static Worker Plugin contract. Runtime device IDs and connection configuration belong to the host process and are reported dynamically by WorkerRuntime identity responses; they are intentionally not embedded here.",
+  "title": "MDK Device-Lib Contract Schema",
+  "description": "Formal JSON Schema defining the unified programmatic and semantic capabilities contract for MDK device integration workers.",
+  "type": "object",
+  "required": [
+    "metadata",
+    "capabilities"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "metadata": {
+      "type": "object",
+      "description": "Identity and family metadata defining what the worker represents.",
+      "required": ["provider", "deviceFamily", "brand", "modelsSupported", "overview"],
+      "properties": {
+        "provider": { "type": "string", "description": "The corporate or individual provider behind the worker (e.g., 'microbt')." },
+        "deviceFamily": { "type": "string", "description": "The broad category of devices (e.g., 'miner', 'sensor', 'switchgear')." },
+        "brand": { "type": "string", "description": "The human-readable brand name of the device." },
+        "modelsSupported": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of specific models this specific contract supports."
+        },
+        "overview": { 
+          "type": "string", 
+          "description": "Mandatory semantic overview. Used to instruct AI agents on the broad purpose and critical environmental constraints for this device group." 
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "description": "The unified machine and semantic capabilities mapping for the device.",
+      "required": ["telemetry", "commands", "health", "errors"],
+      "properties": {
+        "telemetry": {
+          "type": "array",
+          "description": "Metrics continuously updated and read from the device. Natural semantic rules should be appended to the 'description' field.",
+          "items": {
+            "type": "object",
+            "required": ["name", "type", "handler", "description"],
+            "properties": {
+              "name": { "type": "string" },
+              "unit": { "type": "string" },
+              "type": { "type": "string", "enum": ["number", "string", "boolean", "object", "array"] },
+              "handler": { "type": "string", "description": "CommonJS handler path relative to the Worker Plugin directory. Removed from the contract published to Kernel." },
+              "description": { "type": "string", "description": "Human and AI readable metric description. Should include semantic boundaries (e.g., 'If 0, device is booting')." }
+            }
+          }
+        },
+        "commands": {
+          "type": "array",
+          "description": "Callable operations the device accepts.",
+          "items": {
+            "type": "object",
+            "required": ["name", "handler"],
+            "properties": {
+              "name": { "type": "string" },
+              "handler": { "type": "string", "description": "CommonJS handler path relative to the Worker Plugin directory. Removed from the contract published to Kernel." },
+              "description": { "type": "string", "description": "What the command does physically." },
+              "constraints": { "type": "string", "description": "Strict semantic limits (e.g., 'Do not call more than once every 15 minutes')." },
+              "examples": {
+                "type": "array",
+                "description": "Concrete AI instruction workflows for how to utilize this command optimally.",
+                "items": {
+                  "type": "object",
+                  "required": ["intent", "steps"],
+                  "properties": {
+                    "intent": { "type": "string", "description": "The goal or overarching reason for executing the workflow." },
+                    "steps": { "type": "array", "items": { "type": "string" }, "description": "Step-by-step numbered execution plan for the AI." }
+                  }
+                }
+              },
+              "params": {
+                "type": "array",
+                "description": "Input arguments required by the command.",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "type": { "type": "string", "enum": ["number", "string", "boolean", "object"] },
+                    "required": { "type": "boolean", "description": "Whether the command handler requires this parameter." },
+                    "enum": {
+                      "type": "array",
+                      "description": "Allowed values. WorkerRuntime rejects a command whose value is not listed (ERR_PARAM_ENUM) before the handler runs.",
+                      "items": {}
+                    },
+                    "min": { "type": "number", "description": "Allowed minimum value (for numbers)." },
+                    "max": { "type": "number", "description": "Allowed maximum value (for numbers)." }
+                  }
+                }
+              },
+              "verify": {
+                "type": "object",
+                "description": "Device-state readback after the command settles. Kernel pulls the `telemetry` metric until it equals the request's `param` value (verification VERIFIED) or `withinMs` passes (UNVERIFIED).",
+                "required": ["telemetry", "param"],
+                "properties": {
+                  "telemetry": { "type": "string", "description": "Name of a telemetry entry that reports the state this command sets." },
+                  "param": { "type": "string", "description": "Name of the command param holding the requested value." },
+                  "withinMs": { "type": "number", "minimum": 1, "description": "How long to keep reading back before UNVERIFIED. Default 60000." }
+                }
+              }
+            }
+          }
+        },
+        "config": {
+          "type": "object",
+          "description": "Device configuration models.",
+          "properties": {
+            "schema": { "type": "string", "description": "Reference identifier for config payload shape." }
+          }
+        },
+        "health": {
+          "type": "object",
+          "description": "Standardized diagnostic mappings.",
+          "required": ["supportedStates"],
+          "properties": {
+            "supportedStates": { "type": "array", "items": { "type": "string" } },
+            "alerts": { "type": "array", "items": { "type": "string" } },
+            "troubleshooting": { 
+              "type": "array", 
+              "items": { "type": "string" },
+              "description": "Semantic AI reasoning array. Provides if-then remediation workflows for specific failures."
+            }
+          }
+        },
+        "errors": {
+          "type": "object",
+          "description": "Lookup table mapping specific device error codes to human/AI-readable text.",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/dist/skills/mdk/references/package-index.md

@@ -0,0 +1,53 @@
+# Package ↔ folder index
+
+Load this before referencing any `@tetherto/mdk-*` package or repo path.
+Use only names that appear here — inventing package names is the #1 drift
+failure. Paths are relative to the monorepo root.
+
+## Core ([`backend/core/`](../../../../../../backend/core/README.md))
+
+| Package                 | Folder                                                             | What it is                                                |
+| ----------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
+| `@tetherto/mdk-core`    | [`backend/core/mdk`](../../../../../../backend/core/mdk/README.md) | Umbrella boot glue (`getKernel`, `startGateway`, `waitForDiscovery`, default topic file helpers, `libStats` aggregation ops); no generic `startWorker`, each Worker package ships its own boot function |
+| `@tetherto/mdk-kernel`  | [`backend/core/kernel`](../../../../../../backend/core/kernel/README.md) | The Kernel: protocol layer + 8 orchestration modules |
+| `@tetherto/mdk-worker`  | [`backend/core/mdk-worker`](../../../../../../backend/core/mdk-worker/index.js) | Worker Runtime: `WorkerRuntime`, `loadPlugin`, contract schema |
+| `@tetherto/mdk-gateway` | [`backend/core/gateway`](../../../../../../backend/core/gateway/README.md) | HTTP Gateway in front of the Kernel                |
+| `@tetherto/mdk-client`  | [`backend/core/client`](../../../../../../backend/core/client/README.md) | Consumer client library                              |
+| `@tetherto/mdk-mcp`     | [`backend/core/mcp`](../../../../../../backend/core/mcp/README.md) | MCP server: exposes MDK data/actions to AI agents as tools |
+
+Also under [`backend/core/`](../../../../../../backend/core/README.md): `plugins/` (Gateway plugin surface, no published package yet).
+
+## Workers ([`backend/workers/`](../../../../../../backend/workers/README.md))
+
+| Package                         | Folder                                                                                           | Device protocol          |
+| ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `@tetherto/mdk-worker-avalon`   | [`backend/workers/miners/avalon`](../../../../../../backend/workers/miners/avalon/README.md) | CGMiner ASCII over TCP       |
+| `@tetherto/mdk-worker-abb`      | [`backend/workers/power-meter/abb`](../../../../../../backend/workers/power-meter/abb/README.md) | Modbus TCP               |
+| `@tetherto/mdk-worker-satec`    | [`backend/workers/power-meter/satec`](../../../../../../backend/workers/power-meter/satec/README.md) | Modbus TCP           |
+| `@tetherto/mdk-worker-schneider` | [`backend/workers/power-meter/schneider`](../../../../../../backend/workers/power-meter/schneider/README.md) | Modbus TCP  |
+| `@tetherto/mdk-worker-seneca`   | [`backend/workers/temperature/seneca`](../../../../../../backend/workers/temperature/seneca/README.md) | Modbus TCP         |
+| `@tetherto/mdk-worker-antspace` | [`backend/workers/containers/antspace`](../../../../../../backend/workers/containers/antspace/README.md) | HTTP JSON        |
+| `@tetherto/mdk-worker-bitdeer`  | [`backend/workers/containers/bitdeer`](../../../../../../backend/workers/containers/bitdeer/README.md) | MQTT               |
+| `@tetherto/mdk-worker-f2pool`   | [`backend/workers/minerpools/f2pool`](../../../../../../backend/workers/minerpools/f2pool/README.md) | Pool HTTP API        |
+| `@tetherto/mdk-worker-ocean`    | [`backend/workers/minerpools/ocean`](../../../../../../backend/workers/minerpools/ocean/README.md) | Pool HTTP API          |
+| `@tetherto/mdk-worker-mock` | [`backend/workers/mock`](../../../../../../backend/workers/mock/README.md) | Shared device-mock framework (BaseMock, category mocks, transports) |
+
+Whatsminer support is the external [`whatsminer-mdk-worker`](https://github.com/whatsminer/whatsminer-mdk-worker) contract plugin (CGMiner JSON over TCP, AES-encrypted), hosted directly on `WorkerRuntimeV2` via a thin per-deployment adapter (see `examples/mvp-site/backend/whatsminer-adapter.js`). Antminer support is likewise the external [`antminer-mdk-worker`](https://github.com/bitmain-official/antminer-mdk-worker) contract plugin (HTTP CGI, Digest auth), hosted the same way (see `examples/mvp-site/backend/antminer-adapter.js`).
+
+Generated Worker docs: [`backend/workers/docs/supported-hardware.md`](../../../../../../backend/workers/docs/supported-hardware.md) and
+[`backend/workers/docs/catalogue.json`](../../../../../../backend/workers/docs/catalogue.json) (from
+[`backend/workers/scripts/generate-catalogue.js`](../../../../../../backend/workers/scripts/generate-catalogue.js)).
+
+## UI ([`ui/packages/`](../../../../../../ui/packages/))
+
+| Package                       | Folder                                                                               | What it is                    |
+| ----------------------------- | ------------------------------------------------------------------------------------ | ----------------------------- |
+| `@tetherto/mdk-react-devkit`  | [`ui/packages/react-devkit`](../../../../../../ui/packages/react-devkit/README.md)   | React component toolkit; components under [`src/primitives/components/`](../../../../../../ui/packages/react-devkit/src/primitives/components/) and [`src/domain/components/`](../../../../../../ui/packages/react-devkit/src/domain/components/index.ts) |
+| `@tetherto/mdk-react-adapter` | [`ui/packages/react-adapter`](../../../../../../ui/packages/react-adapter/README.md) | Hooks binding components to Worker/plugin data |
+| `@tetherto/mdk-ui-foundation` | [`ui/packages/ui-foundation`](../../../../../../ui/packages/ui-foundation/README.md) | Styling base                  |
+
+## Examples
+
+| Folder                                                                  | What it runs |
+| ----------------------------------------------------------------------- | ----------------------- |
+| [`examples/mvp-site/`](../../../../../../examples/mvp-site/README.md) | Whole stack under PM2: mocks + Kernel + multiple Workers + Gateway + MCP + UI ([`start.js`](../../../../../../examples/mvp-site/start.js)) |

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

@@ -0,0 +1,95 @@
+# MDK protocol
+
+Load this before writing anything that builds, sends, or answers an envelope.
+Source of truth: [`backend/core/kernel/lib/protocol/`](../../../../../../backend/core/kernel/lib/protocol/) ([`actions.js`](../../../../../../backend/core/kernel/lib/protocol/actions.js),
+[`envelope.js`](../../../../../../backend/core/kernel/lib/protocol/envelope.js), [`schemas.js`](../../../../../../backend/core/kernel/lib/protocol/schemas.js)). Protocol version: `0.2.0`.
+
+## The envelope
+
+Every message between Kernel and Workers is exactly this object — nine fields,
+no more:
+
+```js
+{
+  id: 'uuid',              // per-message id (crypto.randomUUID())
+  version: '0.2.0',        // PROTOCOL_VERSION
+  type: 'request',         // 'request' | 'response' | 'event'
+  action: 'telemetry.pull',// one of ACTIONS below
+  sender: 'kernel:shard-1',// sender identity string
+  target: null,            // receiver identity, or null
+  deviceId: 'miner-42',    // addressed device, or null for Worker-scoped
+  timestamp: 1750000000000,// Date.now()
+  payload: {}              // ALL action-specific data goes here
+}
+```
+
+**Never add transport-level fields — extend `payload`.** Envelopes are
+validated structurally (`ERR_ENVELOPE_*`) and, per action, by payload
+validators in [`schemas.js`](../../../../../../backend/core/kernel/lib/protocol/schemas.js) (`ERR_PAYLOAD_*`); unknown actions are rejected
+with `ERR_ENVELOPE_ACTION_UNKNOWN`. On the wire an envelope is
+JSON-serialized to a Buffer and sent over the `'mdk'` HRPC method.
+
+Build responses with `buildResponse(requestEnvelope, action, payload, sender)`
+— it flips `target` to the request's `sender` and carries `deviceId` over.
+
+## Action set ([`actions.js`](../../../../../../backend/core/kernel/lib/protocol/actions.js))
+
+| Direction | Request → Response | Purpose |
+| --- | --- | --- |
+| Kernel → Worker | `identity.request` → `identity.response` | Worker id + device list |
+| Kernel → Worker | `capability.request` → `capability.response` | Published `mdk-contract.json` (handler paths stripped) |
+| Kernel → Worker (scheduled) | `telemetry.pull` → `telemetry.response` | Read metrics/channels |
+| Kernel → Worker (scheduled) | `state.pull` → `state.response` | Device online/offline snapshot |
+| Client → Kernel → Worker | `command.request` → `command.result` | Execute a device command |
+| Client → Kernel | `command.status` → `command.status.response` | Query command lifecycle |
+| Client → Kernel | `command.cancel` → `command.cancel.response` | Cancel a pending command |
+| Kernel → Worker (scheduled) | `health.ping` → `health.pong` | Liveness |
+| Gateway → Kernel only | `worker.list`, `device.capabilities`, `worker.terminate` | Kernel queries (never forwarded to Workers) |
+| Gateway → Kernel | `action.push`, `action.push-batch`, `action.get`, `action.get-batch`, `action.query`, `action.vote`, `action.cancel-batch` | Write-action approval lifecycle |
+| Kernel → Worker | `write.calls.request` → `write.calls.response` | Write-call resolution (only when worker-infra services are injected) |
+
+Also defined there: `COMMAND_SCOPES` (`device` | `worker` | `rack`),
+`MESSAGE_TYPES`, and `VALID_COMMAND_RESULT_STATUSES`
+(the command state machine's states plus `REJECTED`).
+
+## Reads: `telemetry.pull`
+
+Payload shape: `{ query: { type, ...params } }`, `deviceId` in the envelope.
+`type` selects what a Worker returns (dispatch in
+[`backend/core/mdk-worker/lib/worker-runtime.js`](../../../../../../backend/core/mdk-worker/lib/worker-runtime.js) `_handleTelemetry`):
+
+- `type: 'metrics'` (default) — runs **every** declared telemetry handler for
+  the addressed device: `{ deviceId, metrics: { <name>: value, … }, timestamp }`.
+  With no `deviceId`, returns `{ devices: [{ deviceId, metrics|error }…] }`.
+- `type: 'list'` — `{ devices: [{ deviceId, status }] }` (no device needed).
+- `type: '<channel>'` — any single declared telemetry name, with the rest of
+  `query` passed to the handler as params:
+  `{ query: { type: 'history', limit: 3 } }` → `{ name, value }`.
+- Worker-infra built-in types (`logs`, `settings`, `stats`, `config`, …) are
+  served from injected services before plugin channels are consulted.
+
+Per-field handler errors come back inside the payload
+(`metrics.<name> = { error }`); an offline device yields
+`ERR_DEVICE_UNAVAILABLE`, an unknown channel `ERR_UNKNOWN_QUERY_TYPE`.
+
+## Writes: `command.request`
+
+Payload: `{ commandId, command, params }`, `deviceId` in the envelope.
+The **Kernel's dispatcher validates before dispatch**
+([`backend/core/kernel/lib/modules/command-dispatcher/index.js`](../../../../../../backend/core/kernel/lib/modules/command-dispatcher/index.js)):
+the command must appear in the Worker's declared capabilities
+(`ERR_COMMAND_NOT_IN_CAPABILITIES`), params must match declared types
+(`ERR_PARAM_TYPE`), and numeric params must be within declared `min`/`max`
+(`ERR_PARAM_RANGE`). Bounds you do not declare are NOT enforced anywhere.
+
+The Worker answers `command.result` with
+`{ commandId, status: 'SUCCESS', result }` or
+`{ commandId, status: 'FAILED', error }`. Handler exceptions become `FAILED`
+with the error message — so throw `ERR_*`-prefixed errors from handlers.
+
+## Error string convention
+
+Errors travel as `SCREAMING_SNAKE_CASE` strings prefixed `ERR_`, optionally
+suffixed with context after a colon (`ERR_DEVICE_NOT_FOUND: miner-42`). Device
+error codes a Worker can emit belong in the contract's `capabilities.errors`
+map.

package/dist/skills/mdk-create-app/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: mdk-create-app
+description: >
+  Scaffold a new MDK App package ready to publish. Use whenever a task mentions
+  "create app", "scaffold app", "mdk create app", or generating an MDK App's
+  mdk-app.yaml, package.json, plugin/, and ui/ modules.
+argument-hint: "<name> [--org <scope>] [--id <reverse-dns>] [--display <name>] [--devices <pattern>] [--verbs <read|read,write>]"
+metadata:
+  suite: mdk-developer-skill
+  mdk_version: "0.12.1"
+license: Apache-2.0
+---
+
+# Create an MDK App (`mdk-create-app`)
+
+An MDK App is a self-contained, publishable npm package that bundles a backend plugin, a UI shell module, and an `mdk-app.yaml` manifest.
+
+This skill governs the **creation and scaffolding phase** of an MDK App before it is added to a site or published.
+
+---
+
+## 1. The Package Layout
+
+Every scaffolded app follows the canonical structure:
+
+```text
+@tetherto/mdk-app-<name>@<version>
+├── package.json        # name, version, files, dependencies, peerDependencies
+├── mdk-app.yaml        # app manifest
+├── plugin/             # backend plugin template
+│   ├── mdk-plugin.json # route table (the Gateway serves it under /apps/<name> unless mounted)
+│   ├── controllers/    # route handlers
+│   └── lib/            # client helper used by the handlers
+└── ui/                 # built UI module with index entry point
+    └── index.js
+```
+
+---
+
+## 2. The Strict `mdk-app.yaml` Specification
+
+`mdk-app.yaml` defines the app's identity, permissions, and configuration. It contains these 5 keys, plus an optional
+one-line `description`:
+
+```yaml
+id: io.tether.sentinel              # 1. Immutable identity, reverse-DNS
+version: 0.1.0                     # 2. Semver; must equal package.json version
+displayName: Sentinel              # 3. Shown in shell's sidebar and CLI
+permissions:                       # 4. What the app asks the operator to approve (not enforced by the Kernel yet)
+  - resources: [devices]
+    verbs: [read]                  # Default: read (least privilege; [read, write] for controls/tuning)
+    resourceNames: ["*"]           # Default: allow all devices ("*"), or scoped: family/brand/worker/device
+config:                            # 5. Operational defaults (overridable in mdk.yaml)
+  driftThresholdPct: 10
+```
+
+### Critical Negative Constraints: What NOT to Add
+* **DO NOT add extraneous top-level keys**: Never add `icon`, `routes`, `auth`, `mcp`, `devices`, `metadata`, or `entry`. The specification limits the manifest to these 5 keys plus `description`; `mdk validate app` reports any other key.
+* **`config` must always be an object**: If the app has no default configuration parameters, write `config: {}`. Never leave it null, undefined, or an array.
+
+---
+
+## 3. Edge Cases & Validation Rules
+
+### Edge Case 1: Directory & Location Context
+* **Standalone Repo Mode (Outside an MDK project)**: If the current directory is an empty folder or standalone repo (no `mdk.yaml` in current or parent directories), scaffold files **directly at the root of the current directory**:
+  `./package.json`, `./mdk-app.yaml`, `./plugin/`, `./ui/`.
+* **Site Project Mode (Inside an MDK project)**: If an `mdk.yaml` exists in the current or parent directory, scaffold under `apps/<name>/`.
+* **Distinction from Dashboard Shells**: An MDK App package (`@tetherto/mdk-app-<name>`) is a backend plugin + dynamic UI shell module. It is distinct from a standalone Vite dashboard shell created via `mdk create dashboard <name>` (which defaults to `apps/dashboard`). If developing an app inside a site repo alongside an existing dashboard, ensure distinct directory names (e.g. `apps/<name>-app` or keep the dashboard at `apps/dashboard`).
+
+### Edge Case 2: RBAC Permissions & Device Hierarchy
+* **Not enforced yet**: The Kernel does not enforce `permissions` today. They are declared for operator review, and the app
+  runtime's Kernel key is admitted with full access. Declare least privilege anyway, so review is meaningful.
+* **Target Resources**: Declare apps **only on `resources: [devices]`**. Never set `resources: [workers]`, `[plugins]`, `[*]`, or `[kernel]`.
+* **Verbs**:
+  * Default: `verbs: [read]` (least privilege; for monitoring, telemetry, and metrics dashboards).
+  * Control / Tuning apps (reboots, parameter tuning, commands): `verbs: [read, write]`.
+* **Device Scoping (`resourceNames`)**: Defaults to `["*"]` to allow all devices. When scoped, it must follow the 4-part MDK device hierarchy:
+  `family / brand / worker / device`
+  * `*` — All devices across all families (Default: allow all).
+  * `miner/*` — All miners across all brands.
+  * `miner/antminer/*` — All Antminers across all workers.
+  * `miner/antminer/antminer-a/*` — Devices under worker `antminer-a`.
+  * `powermeter/*` — All power meters (note: backend family identifier is `powermeter`, not `power-meter`).
+  * `sensor/*`, `container/*` — Sensors and containers.
+* **Multiple Device Families**: If an app needs access to multiple hardware types, declare separate scoped rule blocks:
+  ```yaml
+  permissions:
+    - resources: [devices]
+      verbs: [read, write]
+      resourceNames: ["miner/*"]
+    - resources: [devices]
+      verbs: [read]
+      resourceNames: ["powermeter/*"]
+  ```
+
+### Edge Case 3: Naming, Scoping & Version Parity
+* **`<name>`**: Lowercase kebab-case slug (`^[a-z0-9][a-z0-9._-]*$`). No uppercase letters, spaces, or slashes.
+* **`id`**: Immutable reverse-DNS format (`^[a-z][a-z0-9]*(\.[a-z0-9][a-z0-9-]*)+$`, e.g. `io.tether.<name>`).
+* **`package.json` Name**: Defaults to `@tetherto/mdk-app-<name>` (or `@<scope>/mdk-app-<name>` if custom org specified).
+* **Version Parity**: `package.json#version` and `mdk-app.yaml#version` **must match byte-for-byte** (defaults to `0.1.0`).
+
+### Edge Case 4: Route Namespacing in `plugin/mdk-plugin.json`
+* **The Gateway adds the prefix**: The Gateway serves every route of an app under `/apps/<name>`, where `<name>` is the app's
+  `spec.apps[].name` in `mdk.yaml`. Declare paths **without** that prefix:
+  * Example: `/status` in `mdk-plugin.json` is served at `/apps/sentinel/status`.
+  * Never write `/apps/<name>/...` in the route table; it would be served at `/apps/<name>/apps/<name>/...`.
+* **Root mount**: An app whose client calls fixed root paths (the agent app's `/agent/sessions`, an identity app's `/oauth/...`)
+  sets `mount: /` on its `spec.apps` entry instead, and its paths are served as written. Prefixed is the default because it
+  keeps installed apps from colliding.
+
+### Edge Case 5: Dynamic UI Shell Module Contract
+* The UI entry point (`ui/index.js`) is read dynamically by the UI shell.
+* It must export a default object with:
+  ```javascript
+  export default {
+    id: 'io.tether.<name>',
+    displayName: '<DisplayName>',
+    routes: [],
+    panels: []
+  };
+  ```
+
+---
+
+## 4. Execution Workflow
+
+### Step 1: Collect App Definition (The Interview)
+Collect or confirm the definition parameters with sensible fallbacks:
+
+| Parameter | Prompt / Meaning | Default / Fallback |
+| :--- | :--- | :--- |
+| **`name`** | App slug (kebab-case) | Required (e.g. `sentinel`) |
+| **`id`** | Reverse-DNS identity | `io.tether.<name>` |
+| **`displayName`** | Human name for shell sidebar and CLI | TitleCase `<name>` |
+| **`devices`** | Target hardware hierarchy (`resourceNames`) | `*` (allow all devices) |
+| **`verbs`** | Access level needed | `read` (least privilege; `read, write` for controls) |
+| **`config`** | Initial default settings | `{}` |
+
+---
+
+### Step 2: Scaffold Files
+
+Inside an MDK project, `mdk create app <name>` (`--org <scope>` for a scoped package name) is the canonical method: it
+scaffolds `apps/<name>` with `mdk-app.yaml`, `plugin/mdk-plugin.json`, a client and one read-only route, links the package,
+and adds it under `spec.apps` in `mdk.yaml`. Then adjust `id`, `permissions` and the routes as below, and check the result
+with `mdk validate app <name>`.
+
+Without the CLI (standalone repo mode, or a layout the template does not cover), create the files directly according to
+the location context:
+
+1. **`package.json`**:
+```json
+{
+  "name": "@tetherto/mdk-app-<name>",
+  "version": "0.1.0",
+  "files": [
+    "mdk-app.yaml",
+    "plugin/",
+    "ui/"
+  ],
+  "dependencies": {},
+  "peerDependencies": {}
+}
+```
+
+2. **`mdk-app.yaml`**:
+```yaml
+id: io.tether.<name>
+version: 0.1.0
+displayName: <DisplayName>
+permissions:
+  - resources: [devices]
+    verbs: [<verbs, default: read>]
+    resourceNames: ["<device-pattern, default: *>"]
+config: {}
+```
+
+3. **`plugin/mdk-plugin.json`**:
+```json
+{
+  "id": "io.tether.<name>",
+  "name": "<name>",
+  "routes": [
+    {
+      "id": "<name>.status",
+      "handler": "controllers/status.js",
+      "http": {
+        "method": "GET",
+        "path": "/status"
+      }
+    }
+  ]
+}
+```
+
+4. **`plugin/controllers/status.js`**:
+```javascript
+'use strict'
+
+module.exports = async function status (req) {
+  return { status: 'OK', app: '<name>' }
+}
+```
+
+5. **`ui/index.js`**:
+```javascript
+export default {
+  id: 'io.tether.<name>',
+  displayName: '<DisplayName>',
+  routes: [],
+  panels: []
+};
+```
+
+*(`mdk create app` takes only `<name>`, `--org`, `--dir`, `--force`, `--no-install` and `--no-stack-entry` today; set `id`,
+`displayName` and `permissions` in the generated `mdk-app.yaml` by hand.)*
+
+---
+
+### Step 3: Self-Audit Checklist
+
+Before completing the task, the agent must verify:
+* [ ] **Manifest Keys**: `mdk-app.yaml` contains ONLY `id`, `version`, `displayName`, `permissions`, `config`, and optionally `description`.
+* [ ] **Version Parity**: `package.json` version equals `mdk-app.yaml` version.
+* [ ] **RBAC Resources**: `permissions[].resources` contains strictly `[devices]`.
+* [ ] **RBAC Verbs**: `permissions[].verbs` defaults to `[read]` (or `[read, write]`), containing only valid actions.
+* [ ] **Device Hierarchy / Scope**: `permissions[].resourceNames` defaults to `["*"]` (allow all) or follows `family/brand/worker/device` (using `powermeter` for power meters).
+* [ ] **Route Namespacing**: No route in `plugin/mdk-plugin.json` starts with `/apps/<name>/`; the Gateway adds that prefix.
+* [ ] **Validation**: `mdk validate app <name>` passes (the app's name in `mdk.yaml`).
+* [ ] **UI Contract**: `ui/index.js` exports an object with `id`, `displayName`, `routes`, and `panels`.