@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-merobox/rules/docker-required.md

@@ -1,6 +1,7 @@
 # Rule: Docker must be running before merobox commands
 
-Merobox uses Docker to run node containers. All `merobox up`, `merobox down`, and `merobox status` commands require the Docker daemon to be running.
+Merobox uses Docker to run node containers. All `merobox up`, `merobox down`, and `merobox status`
+commands require the Docker daemon to be running.
 
 ## Check before running
 
@@ -11,11 +12,11 @@ merobox up --workflow workflow.yml
 
 ## Common errors and fixes
 
-| Error | Fix |
-| --- | --- |
-| `Cannot connect to the Docker daemon` | Start Docker Desktop or `sudo systemctl start docker` |
-| `port is already allocated` | Another process (or a previous merobox run) is using that port. Run `merobox down` first or change the port in `workflow.yml` |
-| `image not found` | First run pulls images — ensure internet access. Re-run after pull completes. |
+| Error                                 | Fix                                                                                                                           |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Cannot connect to the Docker daemon` | Start Docker Desktop or `sudo systemctl start docker`                                                                         |
+| `port is already allocated`           | Another process (or a previous merobox run) is using that port. Run `merobox down` first or change the port in `workflow.yml` |
+| `image not found`                     | First run pulls images — ensure internet access. Re-run after pull completes.                                                 |
 
 ## Minimum Docker version
 

package/skills/calimero-meroctl/SKILL.md

@@ -0,0 +1,68 @@
+# calimero-meroctl — Agent Instructions
+
+You are helping a developer use **`meroctl`** — the Calimero CLI for administering a running `merod`
+node (apps, contexts, identities, calls, namespaces, groups).
+
+## What meroctl is
+
+`meroctl` is a standalone CLI that connects to a running `merod` node over HTTP. It does **not**
+start or stop the node — use `merod` for that. `meroctl` is for everything you would do after the
+node is running.
+
+## Connecting to a node
+
+```bash
+# Register a local node once (recommended)
+meroctl node add node1 /path/to/calimero/home
+meroctl node use node1           # set as default
+
+# Or use a remote node
+meroctl node add prod http://my-node.example.com
+meroctl node use prod
+
+# Or pass URL directly on any command (no registration needed)
+meroctl --api http://localhost:2428 context ls
+```
+
+Once a node is registered and set as active, you can omit `--node` from every command.
+
+## Core workflow: app → context → call
+
+```bash
+# 1. Install app
+meroctl app install --path myapp.wasm
+# → prints application-id
+
+# 2. Create context (calls init())
+meroctl context create --application-id <application-id>
+# → prints context-id
+
+# 3. Call a mutation
+meroctl call <context-id> set --args '{"key":"hello","value":"world"}'
+
+# 4. Call a view
+meroctl call <context-id> get --args '{"key":"hello"}' --view
+```
+
+## Global flags
+
+| Flag            | Purpose                                                         |
+| --------------- | --------------------------------------------------------------- |
+| `--node <name>` | Use a registered node by name                                   |
+| `--api <url>`   | Connect to a node directly by URL (skips registration)          |
+| `--home <path>` | Alternate meroctl config directory (default: system config dir) |
+
+## Key rules
+
+- `app install` and `context create` are always two separate steps.
+- Use `--view` on calls that only read state — it skips state persistence.
+- Register a node with `meroctl node add` + `meroctl node use` once; after that no `--node` flag is
+  needed.
+
+## References
+
+See `references/` for:
+
+- Full command reference for all subcommand groups
+- Scripting patterns for CI and automation
+- Multi-node setup with namespaces and groups

package/skills/calimero-meroctl/references/commands.md

@@ -0,0 +1,177 @@
+# meroctl Command Reference
+
+## Global flags
+
+```bash
+meroctl --node <name> <cmd>           # registered node by name
+meroctl --api <url> <cmd>             # direct URL, no registration
+meroctl --home <path> <cmd>           # alternate config directory
+```
+
+---
+
+## node — manage node connections
+
+```bash
+# Register a local node
+meroctl node add <name> <path-to-calimero-home>
+
+# Register a remote node
+meroctl node add <name> <http-url>
+
+# Set active (default) node
+meroctl node use <name>
+
+# List registered nodes
+meroctl node ls
+
+# Remove a node connection
+meroctl node remove <name>
+
+# Show this node's peer identity (public key)
+meroctl node identity
+```
+
+---
+
+## app — manage installed applications
+
+```bash
+# Install from local WASM file
+meroctl app install --path path/to/app.wasm
+
+# Install from local .mpk bundle
+meroctl app install --path path/to/app.mpk
+
+# Install from registry URL
+meroctl app install --url https://apps.calimero.network/<app-id>/<version>
+
+# List installed apps
+meroctl app ls
+
+# Get details of a specific app
+meroctl app get <application-id>
+
+# Remove an app (does not delete existing contexts)
+meroctl app remove <application-id>
+```
+
+---
+
+## context — manage contexts
+
+```bash
+# Create a context (instantiates app — calls init())
+meroctl context create --application-id <application-id>
+
+# Create in dev mode (auto-reinstall when WASM file changes)
+meroctl context create --watch path/to/app.wasm
+
+# List all contexts on this node
+meroctl context ls
+
+# Get details of a specific context
+meroctl context get <context-id>
+
+# Delete a context (wipes all state — irreversible)
+meroctl context delete <context-id>
+
+# Manually trigger state sync with peers
+meroctl context sync <context-id>
+```
+
+---
+
+## call — invoke app methods
+
+```bash
+# Mutation — changes shared CRDT state
+meroctl call <context-id> <method-name> --args '{"key":"val"}'
+
+# View — read-only, skips state persistence
+meroctl call <context-id> <method-name> --args '{"key":"val"}' --view
+
+# Method with no arguments
+meroctl call <context-id> list_all --args '{}' --view
+
+# Specify executor identity explicitly
+meroctl call <context-id> <method> --args '{}' --as <identity-id>
+```
+
+The `--view` flag should be used for any method that is annotated `@View()` (JS) or takes `&self`
+without state mutation (Rust). Omitting `--view` on a read method is not harmful but wastes a
+storage write.
+
+---
+
+## identity — manage identities
+
+```bash
+# Create a new identity (Ed25519 keypair)
+meroctl identity create
+
+# List all identities
+meroctl identity ls
+
+# Get details of a specific identity
+meroctl identity get <identity-id>
+
+# Delete an identity
+meroctl identity delete <identity-id>
+```
+
+---
+
+## namespace — multi-node trust
+
+```bash
+# Create a namespace (this node is the trust root)
+meroctl namespace create
+
+# List namespaces on this node
+meroctl namespace ls
+
+# Generate an invite token (share with the joining node)
+meroctl namespace invite <namespace-id>
+
+# Join a namespace using an invite token
+meroctl namespace join <namespace-id> '<invitation-json>'
+```
+
+---
+
+## group — context membership
+
+```bash
+# List groups
+meroctl group ls
+
+# Join a context via group membership (after joining the namespace)
+meroctl group join-context <context-id>
+```
+
+---
+
+## Full local dev flow (single machine)
+
+```bash
+# 1. Start the node (in another terminal)
+merod --node node1 init --server-port 2428 --swarm-port 2528
+merod --node node1 run
+
+# 2. Register the node
+meroctl node add node1 ~/.calimero/node1
+meroctl node use node1
+
+# 3. Install app
+meroctl app install --path target/wasm32-unknown-unknown/release/myapp.wasm
+# → save application-id
+
+# 4. Create context
+meroctl context create --application-id <application-id>
+# → save context-id
+
+# 5. Develop interactively
+meroctl call <context-id> set --args '{"key":"foo","value":"bar"}'
+meroctl call <context-id> get --args '{"key":"foo"}' --view
+```

package/skills/calimero-meroctl/references/scripting.md

@@ -0,0 +1,80 @@
+# Scripting with meroctl
+
+## Capturing output for use in scripts
+
+Most `create` commands print an ID on stdout. Capture it with shell variable assignment:
+
+```bash
+APP_ID=$(meroctl app install --path app.wasm | grep -oP '(?<=application-id: )[\w-]+')
+CTX_ID=$(meroctl context create --application-id "$APP_ID" | grep -oP '(?<=context-id: )[\w-]+')
+meroctl call "$CTX_ID" set --args '{"key":"hello","value":"world"}'
+```
+
+> Check the actual output format of your `merod` version — the label text may vary. Use `--as-json`
+> if available to get machine-readable output.
+
+## JSON output (if supported)
+
+Some `meroctl` commands support a `--as-json` flag for machine-readable output:
+
+```bash
+meroctl --as-json context ls
+meroctl --as-json app ls
+```
+
+## Minimal CI script (GitHub Actions)
+
+```yaml
+- name: Deploy and test
+  run: |
+    # Register node (assumes merod is running in a service container)
+    meroctl node add ci http://localhost:2428
+    meroctl node use ci
+
+    # Install app
+    APP_ID=$(meroctl app install --path app.wasm)
+    echo "APP_ID=$APP_ID" >> $GITHUB_ENV
+
+    # Create context
+    CTX_ID=$(meroctl context create --application-id "$APP_ID")
+    echo "CTX_ID=$CTX_ID" >> $GITHUB_ENV
+
+- name: Run integration tests
+  run: |
+    meroctl call "$CTX_ID" set --args '{"key":"test","value":"1"}'
+    RESULT=$(meroctl call "$CTX_ID" get --args '{"key":"test"}' --view)
+    echo "$RESULT" | grep -q '"1"' || (echo "FAIL: unexpected value" && exit 1)
+```
+
+## Dev-mode hot reload
+
+Use `--watch` during development to automatically reinstall the WASM and update the context whenever
+the file changes:
+
+```bash
+# Watches app.wasm, reinstalls on change
+meroctl context create --watch path/to/app.wasm
+```
+
+## Calling methods in a loop
+
+```bash
+for key in foo bar baz; do
+  meroctl call "$CTX_ID" set --args "{\"key\":\"$key\",\"value\":\"$key-val\"}"
+done
+```
+
+## Multi-node scripting
+
+```bash
+# Node A: setup
+meroctl --node node1 namespace create
+NS_ID=<paste namespace-id>
+meroctl --node node1 context create --application-id "$APP_ID"
+CTX_ID=<paste context-id>
+INVITE=$(meroctl --node node1 namespace invite "$NS_ID")
+
+# Node B: join
+meroctl --node node2 namespace join "$NS_ID" "$INVITE"
+meroctl --node node2 group join-context "$CTX_ID"
+```

package/skills/calimero-meroctl/rules/call-view-flag.md

@@ -0,0 +1,28 @@
+# Rule: Use --view for Read-Only Methods
+
+**Always pass `--view` when calling a method that only reads state.**
+
+## Why
+
+Without `--view`, the node treats the call as a mutation — it persists the state after the call and
+broadcasts a `StateMutation` event to all context members. For read-only methods this is wasteful
+(unnecessary writes and network traffic) and may cause unexpected state mutation events in
+subscribers.
+
+## How to identify view methods
+
+- **Rust SDK**: method takes `&self` (not `&mut self`)
+- **JS SDK**: method is annotated with `@View()`
+- **meroctl call**: you cannot tell from the CLI alone — check the app source
+
+## Correct usage
+
+```bash
+# Read-only — use --view
+meroctl call <ctx-id> get_posts --args '{}' --view
+meroctl call <ctx-id> get --args '{"key":"foo"}' --view
+
+# Mutation — no --view
+meroctl call <ctx-id> create_post --args '{"title":"Hello"}'
+meroctl call <ctx-id> set --args '{"key":"foo","value":"bar"}'
+```

package/skills/calimero-meroctl/rules/register-node-once.md

@@ -0,0 +1,34 @@
+# Rule: Register Node Once, Then Use by Name
+
+**Run `meroctl node add` + `meroctl node use` once. After that, omit `--node` from all commands.**
+
+## Pattern
+
+```bash
+# One-time setup:
+meroctl node add node1 /path/to/calimero/home   # or http://url for remote
+meroctl node use node1
+
+# All subsequent commands use the active node automatically:
+meroctl app install --path app.wasm              # no --node needed
+meroctl context ls                               # no --node needed
+meroctl call <ctx-id> get --args '{}' --view     # no --node needed
+```
+
+## Don't do this
+
+```bash
+# Repetitive and error-prone:
+meroctl --node node1 app install --path app.wasm
+meroctl --node node1 context create --application-id <id>
+meroctl --node node1 call <ctx-id> get --args '{}' --view
+```
+
+## Exception: multiple nodes
+
+When scripting across multiple nodes in one session, use explicit `--node` to avoid ambiguity:
+
+```bash
+meroctl --node node1 namespace invite <ns-id>   # Node A generates invite
+meroctl --node node2 namespace join <ns-id> ... # Node B accepts
+```

package/skills/calimero-merod/SKILL.md

@@ -0,0 +1,49 @@
+# calimero-merod — Agent Instructions
+
+You are helping a developer run and configure the **`merod` Calimero node daemon**.
+
+## What merod is
+
+`merod` is the Calimero node runtime. It:
+
+- Executes WASM applications inside isolated contexts
+- Manages persistent CRDT storage
+- Exposes a JSON-RPC + WebSocket HTTP API (default port 2428)
+- Participates in the P2P swarm for state sync with other nodes (default port 2528)
+- Issues and validates JWT tokens for client authentication
+
+`merod` is a long-running daemon. Use `meroctl` for administration after startup.
+
+## Two-step startup
+
+```bash
+# Step 1 — initialise (run ONCE on a fresh home directory)
+merod --node node1 init --server-port 2428 --swarm-port 2528
+
+# Step 2 — run (run every time)
+merod --node node1 run
+```
+
+**Never run `merod run` on an uninitialised home.** Run `init` first.
+
+## Key flags
+
+| Flag                   | Purpose                                             | Default           |
+| ---------------------- | --------------------------------------------------- | ----------------- |
+| `--node <name>`        | Node identity name (used to namespace config files) | required          |
+| `--home <path>`        | Base directory for all config and data              | system config dir |
+| `--server-port <port>` | HTTP/WS API port (init only)                        | `2428`            |
+| `--swarm-port <port>`  | P2P swarm port (init only)                          | `2528`            |
+
+## Port responsibilities
+
+| Port                   | What connects to it                                             |
+| ---------------------- | --------------------------------------------------------------- |
+| `--server-port` (2428) | meroctl, app clients, browser frontends, Python client          |
+| `--swarm-port` (2528)  | Other `merod` nodes (P2P state sync, namespace invite protocol) |
+
+Both ports must be open / reachable for multi-node setups.
+
+## References
+
+See `references/` for init flags, config file schema, health endpoints, and Docker setup.

package/skills/calimero-merod/references/health-endpoints.md

@@ -0,0 +1,90 @@
+# Health Endpoints and API Discovery
+
+## Health check
+
+```text
+GET http://localhost:2428/health
+```
+
+Returns `200 OK` with a JSON body when the node is running and ready.
+
+```json
+{ "status": "alive" }
+```
+
+> **Note:** The status value is `"alive"`, not `"healthy"`. Code that checks for `"healthy"` will
+> incorrectly treat a live node as unhealthy.
+
+## Wait for node ready (shell)
+
+```bash
+until curl -sf http://localhost:2428/health > /dev/null; do
+  echo "waiting for node..."
+  sleep 1
+done
+echo "node is ready"
+```
+
+## Wait for node ready (CI — GitHub Actions)
+
+```yaml
+- name: Wait for node
+  run: |
+    for i in $(seq 1 30); do
+      if curl -sf http://localhost:2428/health; then
+        echo "Node ready"
+        break
+      fi
+      echo "Waiting... ($i/30)"
+      sleep 2
+    done
+```
+
+---
+
+## API base URL
+
+```text
+http://localhost:2428/api/v0/
+```
+
+All management endpoints are under `/api/v0/`. Clients must authenticate with
+`Authorization: Bearer <accessToken>` on all endpoints except `/api/v0/identity/login`.
+
+## Key API paths
+
+| Path                            | Method | Purpose                                |
+| ------------------------------- | ------ | -------------------------------------- |
+| `/health`                       | GET    | Node liveness check (no auth required) |
+| `/api/v0/identity/login`        | POST   | Get access + refresh tokens            |
+| `/api/v0/identity/refresh`      | POST   | Refresh access token                   |
+| `/api/v0/contexts`              | GET    | List contexts                          |
+| `/api/v0/contexts`              | POST   | Create context                         |
+| `/api/v0/contexts/{id}/execute` | POST   | Call app method                        |
+| `/api/v0/applications`          | GET    | List installed apps                    |
+| `/api/v0/applications`          | POST   | Install app (multipart)                |
+
+WebSocket: `ws://localhost:2428/ws`
+
+---
+
+## Docker health check
+
+```dockerfile
+HEALTHCHECK --interval=5s --timeout=3s --retries=10 \
+  CMD curl -sf http://localhost:2428/health || exit 1
+```
+
+## Docker Compose health check
+
+```yaml
+services:
+  node:
+    image: calimero/merod:latest
+    healthcheck:
+      test: ['CMD', 'curl', '-sf', 'http://localhost:2428/health']
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+```

package/skills/calimero-merod/references/init-flags.md

@@ -0,0 +1,84 @@
+# merod Init and Run Flags
+
+## merod init
+
+Initialises a new node home directory: generates key material, writes the config file, and creates
+the storage directory. Run **once** per node, before the first `merod run`.
+
+```bash
+merod --node <name> init [flags]
+```
+
+### Flags
+
+| Flag                   | Required | Default       | Description                                                         |
+| ---------------------- | -------- | ------------- | ------------------------------------------------------------------- |
+| `--node <name>`        | Yes      | —             | Node identity name. Namespaces config files under `<home>/<name>/`. |
+| `--home <path>`        | No       | OS config dir | Base directory. All node data lives under `<home>/<name>/`.         |
+| `--server-port <port>` | No       | `2428`        | HTTP/WS API port. Clients and meroctl connect here.                 |
+| `--swarm-port <port>`  | No       | `2528`        | P2P port. Other merod nodes connect here for state sync.            |
+
+### Examples
+
+```bash
+# Minimal (uses defaults)
+merod --node node1 init
+
+# Custom ports
+merod --node node1 init --server-port 3000 --swarm-port 3001
+
+# Custom home directory
+merod --home ./data --node node1 init --server-port 2428 --swarm-port 2528
+
+# Multiple nodes on the same machine (must use different ports)
+merod --home ./data --node node1 init --server-port 2428 --swarm-port 2528
+merod --home ./data --node node2 init --server-port 2429 --swarm-port 2529
+```
+
+---
+
+## merod run
+
+Starts the node daemon. The home directory must already be initialised.
+
+```bash
+merod --node <name> run [flags]
+```
+
+### Run flags
+
+| Flag            | Required | Default       | Description                             |
+| --------------- | -------- | ------------- | --------------------------------------- |
+| `--node <name>` | Yes      | —             | Must match the name used during `init`. |
+| `--home <path>` | No       | OS config dir | Must match the home used during `init`. |
+
+### Run examples
+
+```bash
+# Run in foreground
+merod --node node1 run
+
+# Run in background (Unix)
+merod --node node1 run &
+
+# Run with custom home
+merod --home ./data --node node1 run
+```
+
+---
+
+## Data directory layout
+
+After `init`, the following structure is created under `<home>/<node-name>/`:
+
+```text
+<home>/
+└── <node-name>/
+    ├── config.toml      # node configuration (server port, swarm port, etc.)
+    ├── identity/        # Ed25519 node keypair
+    └── data/            # CRDT storage, application binaries
+```
+
+**Do not edit `config.toml` manually unless you know what you are changing.** Port numbers are
+written to config during `init` and cannot be changed without re-initialising or manually editing
+the config.

package/skills/calimero-merod/rules/init-before-run.md

@@ -0,0 +1,40 @@
+# Rule: Always Init Before Run
+
+**`merod init` must be run once before `merod run` on any new home directory.**
+
+## Correct order
+
+```bash
+# 1. Init (ONCE — creates config, keypair, storage dirs)
+merod --node node1 init --server-port 2428 --swarm-port 2528
+
+# 2. Run (every time after)
+merod --node node1 run
+```
+
+## What goes wrong without init
+
+Running `merod run` on an uninitialised home fails immediately — the node has no config file, no
+keypair, and no storage directory. The error will be something like `config not found` or
+`identity not found`.
+
+## Re-initialising loses all data
+
+Running `merod init` on a home that already has data will **overwrite the config and generate a new
+keypair**, effectively destroying the node's identity and making all existing contexts unreachable
+(their members' trust roots refer to the old keypair).
+
+**Never re-init a production node home.**
+
+## Multiple nodes on one machine
+
+Each node needs its own `--node` name and different ports:
+
+```bash
+merod --home ./data --node node1 init --server-port 2428 --swarm-port 2528
+merod --home ./data --node node2 init --server-port 2429 --swarm-port 2529
+
+# Run both (separate terminals or background)
+merod --home ./data --node node1 run &
+merod --home ./data --node node2 run &
+```