miravo 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Industrial environment platform. Canonical asset models, multi-protocol output, structured plant topology.
 
-Miravo simulates industrial assets with realistic physics — correlated signals, lifecycle degradation, cascading faults — and projects them over MQTT and OPC UA from a single canonical asset model. One command gives you a fully structured namespace with typed members that behave like a real plant.
+Miravo simulates industrial assets with realistic physics -- correlated signals, lifecycle degradation, cascading faults -- and projects them over MQTT and OPC UA from a single canonical asset model.
 
 ```
 MiravoWorks/smart-factory
@@ -42,9 +42,6 @@ miravo start
 # Start with a specific template
 miravo start --template smart-factory
 
-# Validate without running
-miravo start --template smart-factory --dry-run
-
 # Deterministic replay
 miravo start --seed 42
 
@@ -54,244 +51,25 @@ miravo start --speed 10 --tick 500
 
 Connect any MQTT client to `localhost:1883` and subscribe to `#` to see the data.
 
-## Built-In Models
-
-Miravo ships with 8 canonical asset models, each with typed members, lifecycle stages, and fault modes:
-
-| Model              | Key Signals                               | Fault Examples                     |
-| ------------------ | ----------------------------------------- | ---------------------------------- |
-| Centrifugal Pump   | pressure, flow, vibration, temperature    | cavitation, bearing wear           |
-| AC Induction Motor | speed, current, vibration, winding temp   | rotor imbalance, inner race defect |
-| Air Compressor     | header pressure, current, oil temp        | valve leak, oil degradation        |
-| Belt Conveyor      | speed, tension, current, pulley temp      | belt slip, misalignment            |
-| Hot Water Boiler   | firing rate, supply/return temp, pressure | scale buildup, flame instability   |
-| HVAC RTU           | supply/return air temp, compressor stages | refrigerant leak, dirty filter     |
-| Storage Tank       | inflow, outflow, level, valve position    | sensor drift, outlet leak          |
-| Diesel Generator   | load, frequency, voltage, coolant temp    | fuel filter clog, governor fault   |
-
-## Built-In Templates
-
-Templates combine models into full plant topologies. Use `miravo templates list` to see all available templates, or `miravo templates inspect <name>` for details.
-
-```bash
-# Copy a template and its models locally for customization
-miravo templates inspect smart-factory --copy --content-dir ./my-content
-
-# Run with your customized content
-miravo start --content-dir ./my-content
-```
-
-## Commands
-
-### `miravo start`
-
-Start a simulation from a template.
-
-| Option                            | Description                                                                   |
-| --------------------------------- | ----------------------------------------------------------------------------- |
-| `-t, --template <id\|name\|path>` | Template to run (env: `MIRAVO_TEMPLATE`, flag takes precedence)               |
-| `-n, --name <name>`               | Simulation name (env: `MIRAVO_NAME`, flag takes precedence)                   |
-| `--content-dir <path>`            | User content root with `/templates` and `/models` (env: `MIRAVO_CONTENT_DIR`) |
-| `--models-dir <path>`             | Additional `.twin.yaml` model directory                                       |
-| `-s, --speed <multiplier>`        | Time multiplier (default: `1`)                                                |
-| `--seed <number>`                 | Deterministic RNG seed                                                        |
-| `--tick <ms>`                     | Tick interval in ms (default: `1000`)                                         |
-| `-p, --mqtt-port <number>`        | MQTT port (default: `1883`, env: `MIRAVO_MQTT_PORT`)                          |
-| `--mqtt-host <host>`              | MQTT bind host (default: `127.0.0.1`, env: `MIRAVO_MQTT_HOST`)                |
-| `--mqtt-mode <mode>`              | `embedded` or `external` (env: `MIRAVO_MQTT_MODE`)                            |
-| `--mqtt-url <url>`                | External broker URL (env: `MIRAVO_MQTT_URL`)                                  |
-| `--mqtt-username <user>`          | External broker username (env: `MIRAVO_MQTT_USERNAME`)                        |
-| `--mqtt-password <pass>`          | External broker password (env: `MIRAVO_MQTT_PASSWORD`)                        |
-| `--no-mqtt`                       | Disable MQTT broker                                                           |
-| `--opcua`                         | Enable OPC UA server                                                          |
-| `--opcua-port <number>`           | OPC UA port (default: `4840`, env: `MIRAVO_OPCUA_PORT`)                       |
-| `--opcua-host <host>`             | OPC UA bind host (default: `0.0.0.0`, env: `MIRAVO_OPCUA_HOST`)               |
-| `--admin-host <host>`             | Admin server host (default: `127.0.0.1`, env: `MIRAVO_ADMIN_HOST`)            |
-| `--admin-port <number>`           | Admin server port (default: `8080`, env: `MIRAVO_ADMIN_PORT`)                 |
-| `-d, --detach`                    | Start simulation in background (daemon mode)                                  |
-| `--dry-run`                       | Validate and print summary without starting                                   |
-| `--summary-interval <s>`          | Seconds between periodic summaries (default: `5`)                             |
-
-### Daemon Mode
-
-```bash
-# Start in background
-miravo start -d --name my-sim
-
-# List running simulations
-miravo ps
-
-# Stream live events
-miravo logs my-sim
-
-# Stop gracefully
-miravo stop my-sim
-
-# Remove stale registry entry
-miravo rm my-sim --force
-```
-
-### Runtime Control
-
-All runtime commands communicate with the running simulation via the admin HTTP server.
-Timeouts are specified in seconds (default: 5).
+## 3-Command Demo
 
 ```bash
-# Spawn new instances
-miravo spawn centrifugal-pump -c 3
-
-# Remove an instance
-miravo remove pump-001
-
-# Pause / resume
-miravo pause
-miravo resume
-
-# Change simulation speed
-miravo speed 10
-
-# Load additional template
-miravo load ./extra.miravo.yaml
-
-# Reset simulation
-miravo reset --clear-persistence
-
-# Inject / clear faults
-miravo inject pump-001 cavitation
-miravo inject pump-001 cavitation --clear
-```
-
-### Adapter Management
-
-```bash
-# Enable OPC UA at runtime
-miravo adapter enable opcua -p 4841
-
-# Disable MQTT
-miravo adapter disable mqtt
-```
-
-### `miravo status`
-
-Show live status, metrics, and instances of a running simulation.
-
-| Option              | Description                                                 |
-| ------------------- | ----------------------------------------------------------- |
-| `--admin-url <url>` | Admin server URL (env: `MIRAVO_ADMIN_URL`)                  |
-| `-w, --watch`       | Poll and re-render on updates                               |
-| `--instance <id>`   | Show one instance instead of fleet overview                 |
-| `--json`            | Machine-readable JSON output                                |
-| `--discover`        | Discover running simulations via MQTT                       |
-| `--template <path>` | Template for MQTT discovery only (env: `MIRAVO_TEMPLATE`)   |
-| `--timeout <s>`     | Request timeout in seconds (default: `5`)                   |
-
-### `miravo inject [instanceId] [fault]`
-
-Trigger or clear faults on running instances.
-
-| Option              | Description                                                 |
-| ------------------- | ----------------------------------------------------------- |
-| `--clear`           | Clear fault instead of triggering                           |
-| `--json`            | Machine-readable JSON output                                |
-| `--admin-url <url>` | Admin server URL (env: `MIRAVO_ADMIN_URL`)                  |
-| `--timeout <s>`     | Request timeout in seconds (default: `5`)                   |
-
-If `instanceId` and `fault` are omitted in a TTY, an interactive picker is shown.
-
-### `miravo templates list`
-
-List all discovered templates (built-in and local).
-
-| Option         | Description                  |
-| -------------- | ---------------------------- |
-| `--dir <path>` | Additional directory to scan |
-
-### `miravo templates inspect <id|name|path>`
-
-Show template details or copy it locally.
-
-| Option                 | Description                                          |
-| ---------------------- | ---------------------------------------------------- |
-| `--raw`                | Print raw YAML                                       |
-| `--copy`               | Copy template and referenced models to content dir   |
-| `--content-dir <path>` | Target content directory (env: `MIRAVO_CONTENT_DIR`) |
-
-### `miravo models list`
-
-List all discovered canonical asset models.
-
-| Option         | Description                  |
-| -------------- | ---------------------------- |
-| `--dir <path>` | Additional directory to scan |
-
-### `miravo models inspect <name>`
-
-Show model details — typed members, lifecycle stages, fault definitions.
-
-| Option  | Description    |
-| ------- | -------------- |
-| `--raw` | Print raw YAML |
-
-## Global Options
-
-| Option                        | Description                    |
-| ----------------------------- | ------------------------------ |
-| `-V, --version`               | Print version                  |
-| `-h, --help`                  | Show help                      |
-| `-v, --verbose`               | Enable debug logging           |
-| `-q, --quiet`                 | Suppress output (errors only)  |
-| `--plain`                     | Disable ANSI styling           |
-| `--log-format <pretty\|json>` | Log format (default: `pretty`) |
-
-## Output Control
-
-- `NO_COLOR=1` — disables colors (same as `--plain`)
-- `--json` — machine-readable JSON on write commands (`spawn`, `remove`, `pause`, `resume`, `speed`, `reset`, `load`, `inject`, `stop`, `rm`)
-- All `--timeout` flags accept seconds (converted to ms internally)
-
-## Environment Variables
-
-| Variable              | Description                       | Used by            |
-| --------------------- | --------------------------------- | ------------------ |
-| `MIRAVO_NAME`         | Simulation name                   | `start`            |
-| `MIRAVO_TEMPLATE`     | Template id, name, or path        | `start`, `status`  |
-| `MIRAVO_ADMIN_URL`    | Admin server URL                  | Runtime commands   |
-| `MIRAVO_ADMIN_HOST`   | Admin bind host                   | `start`            |
-| `MIRAVO_ADMIN_PORT`   | Admin bind port                   | `start`            |
-| `MIRAVO_MQTT_PORT`    | MQTT broker port                  | `start`            |
-| `MIRAVO_MQTT_HOST`    | MQTT bind host                    | `start`            |
-| `MIRAVO_MQTT_MODE`    | `embedded` or `external`          | `start`            |
-| `MIRAVO_MQTT_URL`     | External broker URL               | `start`            |
-| `MIRAVO_OPCUA_PORT`   | OPC UA server port                | `start`            |
-| `MIRAVO_OPCUA_HOST`   | OPC UA bind host                  | `start`            |
-| `MIRAVO_ADMIN_TOKEN`  | Bearer token for admin auth       | All admin commands |
-| `NO_COLOR`            | Disable ANSI colors when non-empty | All commands       |
-
-## Docker
-
-```bash
-# Start with defaults
-docker run --rm -p 1883:1883 -p 8080:8080 amineamaach/miravo:latest
-
-# Pass options to the start command
-docker run --rm -p 1883:1883 -p 8080:8080 amineamaach/miravo:latest start --template smart-factory --seed 42
-
-# Use JSON logs for container environments
-docker run --rm -p 1883:1883 -p 8080:8080 amineamaach/miravo:latest --log-format json start
-
-# Mount custom content
-docker run --rm -p 1883:1883 -p 8080:8080 \
-  -v ./my-content:/data/miravo \
-  amineamaach/miravo:latest start --template my-template
+miravo start -d --name my-sim     # Start in daemon mode
+miravo inject pump-001 cavitation  # Inject a fault at runtime
+miravo ps                          # List running simulations
 ```
 
-The admin server exposes `/healthz`, `/readyz`, `/state`, `/metrics`, and `/commands` on port 8080.
+## Documentation
 
-## Links
+For the full command reference, all options, environment variables, and advanced usage, visit **[miravo.dev/docs/cli-reference](https://miravo.dev/docs/cli-reference/)**.
 
-- [GitHub](https://github.com/amine-amaach/miravo)
-- [Built-in Models & Templates Reference](https://github.com/amine-amaach/miravo/blob/main/docs/ai/05-builtin-twins-and-templates.md)
-- [Writing Custom Twin Models](https://github.com/amine-amaach/miravo/blob/main/docs/ai/05-builtin-twins-and-templates.md)
+| Topic | Link |
+| --- | --- |
+| CLI Reference | [miravo.dev/docs/cli-reference](https://miravo.dev/docs/cli-reference/) |
+| Environment Variables | [miravo.dev/docs/environment-variables](https://miravo.dev/docs/environment-variables/) |
+| Docker | [miravo.dev/docs/docker](https://miravo.dev/docs/docker/) |
+| Twin Models | [miravo.dev/docs/twin-models](https://miravo.dev/docs/twin-models/) |
+| Built-in Content | [miravo.dev/docs/built-in-content](https://miravo.dev/docs/built-in-content/) |
 
 ## License