mixlar-sdk 0.1.0__tar.gz

mixlar_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to the Mixlar SDK are recorded here. Versions follow
+semver; the SDK version (`mixlar.__version__`) and the CLI version
+(`mixlar_cli.__version__`, re-exported from the same place) always match.
+
+## 0.1.0 — initial release
+
+The first complete cut of the SDK: everything needed to author, test, sign,
+and package a Mixlar Control plugin without the desktop app installed.
+
+**Core package (`mixlar`)**
+- `MixlarPlugin` — standalone base class, byte-for-byte behavioral match with
+  the app's `MixlarPlugin`, transparently replaced by the app's live class
+  when running in-process.
+- `PluginRegistry` — singleton macro/slider/widget-sender routing, same
+  transparent-replacement behavior.
+- `colors` — the exact palette the app injects into plugin modules.
+- `protocol` — the WDATA/WEVENT/WMACRO/WPAGE wire protocol as constants,
+  builders, and parsers.
+- `manifest` — `plugin.json` reading and validation (`read_manifest`,
+  `validate_package`, `build_manifest`).
+- `signing` — ed25519 package signing/verification, digest-compatible with
+  the app's `_plugin_package_digest`.
+- `widgets` — the `Widget` fluent builder for `widget.json` (mixw:1).
+- `validator` — `lint_widget` / `lint_package`, checked against the firmware's
+  accepted element types when the firmware source is reachable.
+- `settings_schema` — the `SettingsSchema` builder/validator for
+  `settings.schema.json`.
+- `events` — the system-events contract (`SystemEventsMixin`, `broadcast`,
+  `parse_deep_link`) — documented, not yet wired into the app.
+- `macros` — `MacroActions` + `@action`, ergonomic macro-action declaration.
+- `sliders` — `SliderMode`, ergonomic slider-mode declaration.
+- `icons` — plugin-icon install-path helpers.
+- `imaging` — image → RGB565 conversion for `push_widget_image`.
+- `packaging` — `.mixplugin` pack/unpack/install, with path-traversal guards.
+- `emulator` — `MockDevice` (headless device simulation) and `render`
+  (widget.json → PNG preview, needs Pillow).
+- `qt` — off-app-safe stand-ins for the Qt helpers the app injects into
+  plugin modules (`_fa`, `_EDITOR_COMBO_STYLE`, `_style_combo_view`).
+
+**CLI (`mixlar`)**
+- `create`, `validate`, `link`, `dev`, `emulate`, `pack`, `sign`, `verify`,
+  `keygen`, `publish`.
+
+**Docs, examples, tests**
+- Full `docs/` reference, cross-linked from `docs/index.md`.
+- `examples/pomodoro/` — a complete Pomodoro timer plugin: macro actions,
+  a bundled countdown-arc widget, a settings schema, live data pushes.
+- `tests/` — a pytest suite covering signing, manifest validation, widget
+  building/linting, settings schemas, packaging, the emulator, and the
+  example plugin.

mixlar_sdk-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Mixlar SDK — Proprietary License
+Copyright (c) 2026 Mixlar Labs. All rights reserved.
+
+This software (the "SDK") is provided by Mixlar Labs to enable developers to
+build plugins and device widgets for Mixlar Control and Mixlar M1X hardware.
+
+Permission is granted to install and use the SDK, and to author, build, sign,
+and distribute your own Mixlar plugins with it. You may not redistribute a
+modified copy of the SDK itself, or use the SDK to build products that
+compete with Mixlar hardware or software, without prior written permission
+from Mixlar Labs.
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL MIXLAR LABS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SDK OR THE USE OR OTHER DEALINGS IN THE SDK.
+
+For licensing questions, contact support@mixlar.net.

mixlar_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+# Ensure the source distribution (sdist) carries everything the wheel needs and
+# the docs/examples devs expect. The wheel already bundles package-data via
+# pyproject; this covers the sdist tarball.
+include README.md
+include CHANGELOG.md
+include LICENSE
+include pyproject.toml
+recursive-include src/mixlar py.typed
+recursive-include src/mixlar_cli/templates *
+recursive-include docs *.md
+recursive-include examples *
+prune **/__pycache__
+global-exclude *.pyc
+global-exclude *.mixplugin

mixlar_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mixlar-sdk
+Version: 0.1.0
+Summary: Official SDK and CLI for building Mixlar M1X plugins and device widgets.
+Author: Mixlar Labs
+License: Proprietary — Mixlar Labs
+Project-URL: Homepage, https://mixlar.net
+Project-URL: Documentation, https://github.com/MixlarLabs/mixlar-sdk/tree/main/docs
+Project-URL: Repository, https://github.com/MixlarLabs/mixlar-sdk
+Project-URL: Issues, https://github.com/MixlarLabs/mixlar-sdk/issues
+Keywords: mixlar,m1x,plugin,sdk,stream-deck,control-surface
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Requires-Dist: packaging>=21.0
+Provides-Extra: render
+Requires-Dist: Pillow>=9.0; extra == "render"
+Provides-Extra: publish
+Requires-Dist: requests>=2.25; extra == "publish"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: Pillow>=9.0; extra == "dev"
+Requires-Dist: requests>=2.25; extra == "dev"
+Provides-Extra: all
+Requires-Dist: Pillow>=9.0; extra == "all"
+Requires-Dist: requests>=2.25; extra == "all"
+Dynamic: license-file
+
+# Mixlar SDK
+
+[![PyPI](https://img.shields.io/pypi/v/mixlar-sdk.svg)](https://pypi.org/project/mixlar-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/mixlar-sdk.svg)](https://pypi.org/project/mixlar-sdk/)
+
+The official SDK and CLI for building **Mixlar Control** plugins and M1X device
+widgets. Write a plugin once, against typed, importable classes — the same
+classes the desktop app itself uses — and test it end-to-end without a device
+plugged in: lint the manifest, run it against a headless mock device, render
+its widget to a PNG, sign it, and package it, all from the command line.
+
+Off-app, `from mixlar import MixlarPlugin` gives you a faithful standalone
+implementation with autocomplete and type checking. Inside the running Mixlar
+Control app, that same import transparently becomes the app's own live class —
+so a plugin authored against this SDK loads completely unmodified. See
+[How this maps onto the app](#how-this-maps-onto-the-app) below.
+
+## Install
+
+```bash
+pip install mixlar-sdk
+```
+
+Or, to hack on the SDK itself, from a checkout of this folder:
+
+```bash
+pip install -e .
+```
+
+Optional extras, added as needed:
+
+| extra | adds | needed for |
+|---|---|---|
+| `[render]` | Pillow | `mixlar emulate --render` (widget PNG previews) |
+| `[publish]` | requests | `mixlar publish` (nicer HTTP errors; stdlib fallback works without it) |
+| `[dev]` | pytest, Pillow, requests | running this SDK's own test suite |
+| `[all]` | everything above | "just give me all of it" |
+
+```bash
+pip install -e ".[all]"
+```
+
+This installs the `mixlar` console script. You can also run it in place with
+`python -m mixlar_cli` (handy before `pip install -e .`, or in CI).
+
+## Quickstart
+
+```bash
+mixlar create "My Plugin" --template full   # scaffold into ./my_plugin/
+cd my_plugin
+mixlar validate                             # lint plugin.json + widgets/
+mixlar emulate --render preview.png         # render the widget, no hardware
+mixlar emulate --interactive                # press/toggle/slide it from a REPL
+mixlar keygen --key-id my-key               # once, if you plan to sign
+mixlar pack --sign my-key                   # build a signed .mixplugin
+mixlar link                                 # copy it into the app's plugins dir
+```
+
+`create` names the output folder after the plugin **id** (a slug derived from
+the display name, or `--id`), not the display name itself — `"My Plugin"`
+becomes `./my_plugin/`.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `create` | scaffold a new plugin package from a template (`macro`, `slider`, `widget`, `full`) |
+| `validate` | lint `plugin.json` and every bundled `widgets/<id>/widget.json` |
+| `link` | copy (or symlink) a package into the app's plugins directory |
+| `dev` | validate + link once, then watch the folder and re-sync on save |
+| `emulate` | run a package against a headless mock device — render a PNG or drive it interactively |
+| `pack` | zip a validated package into a `.mixplugin`, optionally signing it first |
+| `sign` | sign a package in place with a publisher key |
+| `verify` | check a package's signature against the pinned publisher keyset |
+| `keygen` | generate an ed25519 publisher keypair |
+| `publish` | upload a `.mixplugin` to the marketplace (stub until the endpoint ships) |
+
+Full reference with flags and example output: [`docs/cli.md`](docs/cli.md).
+
+## The SDK in a nutshell
+
+```python
+from mixlar import MixlarPlugin
+from mixlar.macros import MacroActions, action
+from mixlar.colors import ACCENT
+
+class MyPlugin(MacroActions, MixlarPlugin):
+    plugin_id = "my_plugin"
+    plugin_name = "My Plugin"
+    plugin_icon_color = ACCENT
+
+    #: Pairs this plugin with widgets/my_widget/widget.json.
+    widget_id = "my_widget"
+
+    @action("ping", "Ping", icon="fa5s.satellite-dish")
+    def _ping(self, step):
+        self.push_widget_data("status", "pong!")   # → WDATA,my_widget.status,pong!
+
+    def on_widget_shown(self, widget_id):
+        self.push_widget_data("status", "idle")
+
+    def on_widget_event(self, widget_id, element_id, action):
+        if element_id == "ping_btn" and action == "press":
+            self._ping({})
+```
+
+That's a complete plugin: a macro action, a bundled device widget pairing,
+and a button handler. No boilerplate quartet of empty methods to override —
+`MacroActions` derives `get_macro_actions()` / `get_macro_action_groups()` /
+`get_macro_action_icons()` / `execute_macro_step()` from the `@action`
+decorators for you (see [`docs/plugin-api.md`](docs/plugin-api.md)).
+
+## How this maps onto the app
+
+Everything in this SDK is a faithful, importable port of code that already
+lives inline in `PC Software/mixlar_mini.py` — `MixlarPlugin`, `PluginRegistry`,
+the color palette, the ed25519 package signing, the widget/manifest linters.
+Off-app you get standalone reimplementations (so imports resolve in your
+editor and this SDK has no dependency on the app). **Inside the running app**,
+`mixlar.plugin.MixlarPlugin`, `mixlar.registry.PluginRegistry`, and
+`mixlar.colors.*` detect that `mixlar_mini` is already imported and
+transparently re-export the app's own live objects instead — same class,
+same registry, same palette — so a plugin written against this SDK needs zero
+changes to run for real, and `push_widget_data` reaches the actual serial
+link. This "single source of truth" seam is documented in each module's
+docstring and in [`docs/migration.md`](docs/migration.md).
+
+Package trust works the same way both places: `mixlar.signing.package_digest`
+computes the exact SHA-256 the app's `_plugin_package_digest` computes, so a
+package signed with this SDK verifies in the real app. See
+[`docs/signing-and-packaging.md`](docs/signing-and-packaging.md).
+
+## Documentation
+
+Start at [`docs/index.md`](docs/index.md). Highlights:
+
+- [`docs/getting-started.md`](docs/getting-started.md) — install, scaffold, the author loop
+- [`docs/plugin-api.md`](docs/plugin-api.md) — the `MixlarPlugin` hook reference
+- [`docs/widgets.md`](docs/widgets.md) — building device widgets with `Widget`
+- [`docs/settings.md`](docs/settings.md) — declarative `settings.schema.json`
+- [`docs/signing-and-packaging.md`](docs/signing-and-packaging.md) — trust, keys, `.mixplugin`
+- [`docs/emulator.md`](docs/emulator.md) — testing without hardware
+- [`docs/events.md`](docs/events.md) — the system-events contract
+- [`docs/cli.md`](docs/cli.md) — every command in detail
+- [`docs/migration.md`](docs/migration.md) — converting a legacy plugin, and adopting the SDK app-side
+- [`docs/roadmap.md`](docs/roadmap.md) — shipped vs. what still needs app-side wiring
+
+A complete worked example — a Pomodoro timer plugin with macros, a settings
+schema, and a bundled countdown widget — lives in
+[`examples/pomodoro/`](examples/pomodoro/).
+
+For the underlying specs this SDK implements, see the repo root's
+`PLUGINS.md` (package format, install/trust flow) and `WIDGETS.md` (widget
+spec, serial protocol).

mixlar_sdk-0.1.0/README.md

@@ -0,0 +1,154 @@
+# Mixlar SDK
+
+[![PyPI](https://img.shields.io/pypi/v/mixlar-sdk.svg)](https://pypi.org/project/mixlar-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/mixlar-sdk.svg)](https://pypi.org/project/mixlar-sdk/)
+
+The official SDK and CLI for building **Mixlar Control** plugins and M1X device
+widgets. Write a plugin once, against typed, importable classes — the same
+classes the desktop app itself uses — and test it end-to-end without a device
+plugged in: lint the manifest, run it against a headless mock device, render
+its widget to a PNG, sign it, and package it, all from the command line.
+
+Off-app, `from mixlar import MixlarPlugin` gives you a faithful standalone
+implementation with autocomplete and type checking. Inside the running Mixlar
+Control app, that same import transparently becomes the app's own live class —
+so a plugin authored against this SDK loads completely unmodified. See
+[How this maps onto the app](#how-this-maps-onto-the-app) below.
+
+## Install
+
+```bash
+pip install mixlar-sdk
+```
+
+Or, to hack on the SDK itself, from a checkout of this folder:
+
+```bash
+pip install -e .
+```
+
+Optional extras, added as needed:
+
+| extra | adds | needed for |
+|---|---|---|
+| `[render]` | Pillow | `mixlar emulate --render` (widget PNG previews) |
+| `[publish]` | requests | `mixlar publish` (nicer HTTP errors; stdlib fallback works without it) |
+| `[dev]` | pytest, Pillow, requests | running this SDK's own test suite |
+| `[all]` | everything above | "just give me all of it" |
+
+```bash
+pip install -e ".[all]"
+```
+
+This installs the `mixlar` console script. You can also run it in place with
+`python -m mixlar_cli` (handy before `pip install -e .`, or in CI).
+
+## Quickstart
+
+```bash
+mixlar create "My Plugin" --template full   # scaffold into ./my_plugin/
+cd my_plugin
+mixlar validate                             # lint plugin.json + widgets/
+mixlar emulate --render preview.png         # render the widget, no hardware
+mixlar emulate --interactive                # press/toggle/slide it from a REPL
+mixlar keygen --key-id my-key               # once, if you plan to sign
+mixlar pack --sign my-key                   # build a signed .mixplugin
+mixlar link                                 # copy it into the app's plugins dir
+```
+
+`create` names the output folder after the plugin **id** (a slug derived from
+the display name, or `--id`), not the display name itself — `"My Plugin"`
+becomes `./my_plugin/`.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `create` | scaffold a new plugin package from a template (`macro`, `slider`, `widget`, `full`) |
+| `validate` | lint `plugin.json` and every bundled `widgets/<id>/widget.json` |
+| `link` | copy (or symlink) a package into the app's plugins directory |
+| `dev` | validate + link once, then watch the folder and re-sync on save |
+| `emulate` | run a package against a headless mock device — render a PNG or drive it interactively |
+| `pack` | zip a validated package into a `.mixplugin`, optionally signing it first |
+| `sign` | sign a package in place with a publisher key |
+| `verify` | check a package's signature against the pinned publisher keyset |
+| `keygen` | generate an ed25519 publisher keypair |
+| `publish` | upload a `.mixplugin` to the marketplace (stub until the endpoint ships) |
+
+Full reference with flags and example output: [`docs/cli.md`](docs/cli.md).
+
+## The SDK in a nutshell
+
+```python
+from mixlar import MixlarPlugin
+from mixlar.macros import MacroActions, action
+from mixlar.colors import ACCENT
+
+class MyPlugin(MacroActions, MixlarPlugin):
+    plugin_id = "my_plugin"
+    plugin_name = "My Plugin"
+    plugin_icon_color = ACCENT
+
+    #: Pairs this plugin with widgets/my_widget/widget.json.
+    widget_id = "my_widget"
+
+    @action("ping", "Ping", icon="fa5s.satellite-dish")
+    def _ping(self, step):
+        self.push_widget_data("status", "pong!")   # → WDATA,my_widget.status,pong!
+
+    def on_widget_shown(self, widget_id):
+        self.push_widget_data("status", "idle")
+
+    def on_widget_event(self, widget_id, element_id, action):
+        if element_id == "ping_btn" and action == "press":
+            self._ping({})
+```
+
+That's a complete plugin: a macro action, a bundled device widget pairing,
+and a button handler. No boilerplate quartet of empty methods to override —
+`MacroActions` derives `get_macro_actions()` / `get_macro_action_groups()` /
+`get_macro_action_icons()` / `execute_macro_step()` from the `@action`
+decorators for you (see [`docs/plugin-api.md`](docs/plugin-api.md)).
+
+## How this maps onto the app
+
+Everything in this SDK is a faithful, importable port of code that already
+lives inline in `PC Software/mixlar_mini.py` — `MixlarPlugin`, `PluginRegistry`,
+the color palette, the ed25519 package signing, the widget/manifest linters.
+Off-app you get standalone reimplementations (so imports resolve in your
+editor and this SDK has no dependency on the app). **Inside the running app**,
+`mixlar.plugin.MixlarPlugin`, `mixlar.registry.PluginRegistry`, and
+`mixlar.colors.*` detect that `mixlar_mini` is already imported and
+transparently re-export the app's own live objects instead — same class,
+same registry, same palette — so a plugin written against this SDK needs zero
+changes to run for real, and `push_widget_data` reaches the actual serial
+link. This "single source of truth" seam is documented in each module's
+docstring and in [`docs/migration.md`](docs/migration.md).
+
+Package trust works the same way both places: `mixlar.signing.package_digest`
+computes the exact SHA-256 the app's `_plugin_package_digest` computes, so a
+package signed with this SDK verifies in the real app. See
+[`docs/signing-and-packaging.md`](docs/signing-and-packaging.md).
+
+## Documentation
+
+Start at [`docs/index.md`](docs/index.md). Highlights:
+
+- [`docs/getting-started.md`](docs/getting-started.md) — install, scaffold, the author loop
+- [`docs/plugin-api.md`](docs/plugin-api.md) — the `MixlarPlugin` hook reference
+- [`docs/widgets.md`](docs/widgets.md) — building device widgets with `Widget`
+- [`docs/settings.md`](docs/settings.md) — declarative `settings.schema.json`
+- [`docs/signing-and-packaging.md`](docs/signing-and-packaging.md) — trust, keys, `.mixplugin`
+- [`docs/emulator.md`](docs/emulator.md) — testing without hardware
+- [`docs/events.md`](docs/events.md) — the system-events contract
+- [`docs/cli.md`](docs/cli.md) — every command in detail
+- [`docs/migration.md`](docs/migration.md) — converting a legacy plugin, and adopting the SDK app-side
+- [`docs/roadmap.md`](docs/roadmap.md) — shipped vs. what still needs app-side wiring
+
+A complete worked example — a Pomodoro timer plugin with macros, a settings
+schema, and a bundled countdown widget — lives in
+[`examples/pomodoro/`](examples/pomodoro/).
+
+For the underlying specs this SDK implements, see the repo root's
+`PLUGINS.md` (package format, install/trust flow) and `WIDGETS.md` (widget
+spec, serial protocol).

mixlar_sdk-0.1.0/docs/cli.md

@@ -0,0 +1,227 @@
+# CLI reference
+
+Installed as `mixlar` (`pip install -e .`), or run in place with
+`python -m mixlar_cli` — identical behavior, useful before installing or in
+CI. Every subcommand takes an optional `pkg` positional argument (a package
+directory); omitted, it defaults to the current directory, and every command
+resolves it by looking for `plugin.json` (`mixlar_cli.util.find_package`) —
+a clear error if none is found, never a silent wrong-folder operation.
+
+```
+mixlar --version
+mixlar <command> -h      # per-command help
+```
+
+## `create`
+
+Scaffold a new plugin package from a bundled template.
+
+```
+mixlar create [name] --dir DIR --template {macro,slider,widget,full}
+              --id PLUGIN_ID --author AUTHOR --force
+```
+
+| flag | default | meaning |
+|---|---|---|
+| `name` (positional) | `"My Plugin"` | display name |
+| `--dir` | `.` | where to create the package folder |
+| `--template` | `full` | `macro` / `slider` / `widget` / `full` |
+| `--id` | slug of `name` | plugin id (also the output folder name) |
+| `--author` | `""` | written into `plugin.json` |
+| `--force` | off | overwrite an existing folder of the same name |
+
+```console
+$ mixlar create "Weather Widget" --template widget --author "Jane Dev"
+[ok] created 'widget' plugin 'Weather Widget' (weather_widget) at C:\...\weather_widget
+Next steps:
+  cd C:\...\weather_widget
+  mixlar validate
+  mixlar emulate --render preview.png
+  mixlar pack
+```
+
+The output folder is named after the **id**, not the display name — `"My
+Plugin"` → `./my_plugin/`.
+
+## `validate`
+
+Lint `plugin.json` and every bundled `widgets/<id>/widget.json`.
+
+```
+mixlar validate [pkg]
+```
+
+```console
+$ mixlar validate
+[warn] no 'author' — shown on the plugin card
+[ok] package valid (Weather Widget v0.1.0)
+```
+
+Exit code `0` if valid (warnings allowed), `1` on any error.
+
+## `link`
+
+Copy (or symlink) a package into the app's plugins directory.
+
+```
+mixlar link [pkg] --plugins-dir DIR --symlink
+```
+
+| flag | default | meaning |
+|---|---|---|
+| `--plugins-dir` | `%APPDATA%\Mixlar\config\plugins` | destination |
+| `--symlink` | off | try a real symlink (needs Windows privilege) instead of copying; falls back to copy on failure |
+
+```console
+$ mixlar link
+[ok] copied C:\...\weather_widget -> C:\Users\you\AppData\Roaming\Mixlar\config\plugins\weather_widget
+```
+
+Copying is the default because Windows symlinks usually need
+Administrator/Developer Mode — most authors won't have that enabled, so
+`link` "just works" without it.
+
+## `dev`
+
+Validate once, link once, then poll the package for changes and re-sync.
+
+```
+mixlar dev [pkg] --plugins-dir DIR --interval SECONDS
+```
+
+```console
+$ mixlar dev
+mixlar dev — watching C:\...\weather_widget
+[..] syncing into C:\Users\you\AppData\Roaming\Mixlar\config\plugins
+[..] pairs with the app's own hot-reload; Ctrl-C to stop
+[ok] [14:02:11] synced (0 warning(s))
+[ok] [14:03:47] synced (0 warning(s))
+^C
+[..] stopped
+```
+
+Stdlib-only mtime polling, default 1s interval — no filesystem-events
+dependency. It keeps the *linked copy* fresh; getting the running app to
+notice is still on you (see [getting-started.md](getting-started.md)).
+
+## `emulate`
+
+Run a package against a headless mock device.
+
+```
+mixlar emulate [pkg] --widget ID --render OUT.png --data k=v --interactive
+```
+
+| flag | meaning |
+|---|---|
+| `--widget` | widget id to load (default: the package's first declared widget) |
+| `--render OUT.png` | render the current widget state to a PNG (needs `[render]`) |
+| `--data k=v` | seed a `WDATA` value before rendering/inspecting (repeatable) |
+| `--interactive` | drop into a REPL — see [emulator.md](emulator.md) |
+
+```console
+$ mixlar emulate --data pomodoro.pct=40 --data pomodoro.remaining=12:34 --render preview.png
+[..] loaded widget 'pomodoro' from C:\...\widgets\pomodoro\widget.json
+Data snapshot:
+  pomodoro.pct = 40
+  pomodoro.remaining = 12:34
+Interactive elements:
+  reset
+  start_pause
+[ok] rendered preview to preview.png
+```
+
+## `pack`
+
+Build a `.mixplugin` archive, optionally signing first.
+
+```
+mixlar pack [pkg] --out PATH --sign KEY_ID --key-file PATH
+```
+
+```console
+$ mixlar pack --sign my-studio
+[ok] packed C:\...\weather_widget-0.1.0.mixplugin (18,204 bytes)
+[..] signed with key 'my-studio'
+```
+
+## `sign`
+
+Sign a package folder in place (writes `publisher`/`sig` into `plugin.json`).
+
+```
+mixlar sign [pkg] --key-id KEY_ID --key-file PATH
+```
+
+`--key-id` defaults to `mixlar-official-1`; `--key-file` defaults to the
+conventional `%APPDATA%\Mixlar\keys\<key-id>.ed25519.key`.
+
+```console
+$ mixlar sign --key-id my-studio
+[ok] signed as 'my-studio'
+[..] digest:    a1b2c3d4e5f6a7b8...
+[..] signature: 9f8e7d6c5b4a3210...
+```
+
+## `verify`
+
+Check a package's signature against the pinned publisher keyset.
+
+```
+mixlar verify [pkg]
+```
+
+```console
+$ mixlar verify
+[error] INVALID — unknown publisher or tampered package
+```
+
+See [signing-and-packaging.md](signing-and-packaging.md) for what each
+outcome means and how to get a key pinned. Exit `1` only on `INVALID`;
+`UNSIGNED` and `VALID` both exit `0`.
+
+## `keygen`
+
+Generate an ed25519 signing keypair.
+
+```
+mixlar keygen --key-id KEY_ID --out PATH
+```
+
+```console
+$ mixlar keygen --key-id my-studio
+[ok] generated keypair 'my-studio'
+[..] private key saved to: C:\Users\you\AppData\Roaming\Mixlar\keys\my-studio.ed25519.key
+Public key (share this, keep the private key secret):
+  AjxJeR5Ns4h1GdUYEzP3biW6vWoStOG1/ydMccDFWZU=
+To be trusted by the app, a maintainer must add:
+  "my-studio": "AjxJeR5Ns4h1GdUYEzP3biW6vWoStOG1/ydMccDFWZU="
+to plugin-verify.php / the app's _PUBLISHER_KEYS and to
+mixlar.signing.PUBLISHER_KEYS. Until then, 'mixlar verify' will report
+packages signed with this key as INVALID (unknown publisher) — that's
+expected for an unpinned key.
+```
+
+## `publish`
+
+Pack (if needed) and upload a `.mixplugin` to the marketplace.
+
+```
+mixlar publish [pkg] --url URL --token TOKEN
+```
+
+Reads `--url`/`MIXLAR_MARKETPLACE_URL` and `--token`/`MIXLAR_DEV_TOKEN`. This
+is deliberately a **stub** — the marketplace upload endpoint is being
+reworked, so without a URL configured it explains that and exits `0` rather
+than failing against a guessed endpoint:
+
+```console
+$ mixlar publish
+[warn] the marketplace upload endpoint is being reworked — no URL
+configured. Pass --url or set $MIXLAR_MARKETPLACE_URL once it's available.
+This command is currently a stub.
+```
+
+With a URL set, it packs fresh (so what's uploaded matches the folder on
+disk right now) and POSTs it multipart, preferring `requests` when installed
+and falling back to stdlib `urllib` otherwise.