@calimero-network/agent-skills 0.2.0 → 0.4.0

package/skills/calimero-merobox/SKILL.md

@@ -1,54 +1,281 @@
 # calimero-merobox — Agent Instructions
 
-You are helping a developer set up a **local multi-node Calimero network** using Merobox.
+You are helping a developer set up and test a **local Calimero network** using Merobox.
 
 ## What Merobox is
 
-Merobox is a Docker-based toolchain for running Calimero nodes locally. It handles:
-- Spinning up multiple nodes in Docker containers
-- Bootstrapping identities and contexts
-- Defining reusable network topologies via workflow YAML files
-- CI/CD integration
+Merobox is a Python CLI tool for running Calimero nodes in Docker containers. It handles:
+
+- Starting/stopping nodes with `merobox run` / `merobox stop`
+- App installation and method execution
+- Identity and context management
+- Automated multi-step test workflows via YAML (`merobox bootstrap run`)
+- Multi-node orchestration for integration testing
 
 ## Install
 
 ```bash
-# Using pipx (recommended)
+# macOS
+brew install merobox
+
+# Ubuntu/Debian
+curl -fsSL https://calimero-network.github.io/merobox/gpg.key \
+  | sudo tee /usr/share/keyrings/merobox.gpg > /dev/null
+echo "deb [signed-by=/usr/share/keyrings/merobox.gpg] https://calimero-network.github.io/merobox stable main" \
+  | sudo tee /etc/apt/sources.list.d/merobox.list
+sudo apt update && sudo apt install merobox
+
+# pipx (any platform)
 pipx install merobox
 
-# macOS with Homebrew
-brew install calimero-network/tap/merobox
+merobox --version  # verify
+```
+
+Requires Docker 20.10+ running.
+
+## Node management
+
+```bash
+# Start a node
+merobox run --name my-node
+
+# Start with custom ports
+merobox run --name my-node --server-port 2428 --swarm-port 2528
+
+# List running nodes
+merobox list
+
+# Check node health
+merobox health my-node
+
+# View logs
+merobox logs my-node
+merobox logs my-node --follow   # follow in real-time
 
-# Requires: Docker 20.10+ running
+# Stop a node
+merobox stop my-node
+
+# Delete all node data (destructive)
+merobox nuke my-node
 ```
 
-## Quick start
+## App and context management
 
 ```bash
-# Create a workflow file
-cat > workflow.yml << EOF
+# Install a WASM app on a node
+merobox install --node my-node --path ./app.wasm --dev
+
+# List installed apps
+merobox application list --node my-node
+
+# Create a context
+merobox context create --node my-node --application-id <app-id>
+
+# List contexts
+merobox context list --node my-node
+
+# Call a method
+merobox call my-node <context-id> <method> '{"key":"hello","value":"world"}'
+```
+
+## Identity management
+
+```bash
+merobox identity generate --node my-node
+```
+
+## Blob storage
+
+```bash
+merobox blob upload   --node my-node --file ./data.txt
+merobox blob list-blobs --node my-node
+merobox blob download --node my-node --blob-id <id> --output ./out.txt
+merobox blob delete   --node my-node --blob-id <id> --yes
+```
+
+## Workflow automation (bootstrap)
+
+Workflows are the most powerful feature — YAML files that orchestrate multi-step scenarios.
+
+```bash
+merobox bootstrap run workflow.yml       # execute
+merobox bootstrap validate workflow.yml  # validate only
+merobox bootstrap create-sample          # scaffold example
+```
+
+### Minimal workflow example
+
+```yaml
+name: KV Store Test
+steps:
+  - type: install_application
+    node: node-1
+    path: ./kv_store.wasm
+    outputs:
+      app_id: 'application_id'
+
+  - type: create_context
+    node: node-1
+    application_id: '{{app_id}}'
+    outputs:
+      ctx_id: 'context.context_id'
+
+  - type: create_identity
+    node: node-1
+    outputs:
+      pub: 'public_key'
+
+  - type: call
+    node: node-1
+    context_id: '{{ctx_id}}'
+    method: set
+    args:
+      key: 'hello'
+      value: 'world'
+    executor_public_key: '{{pub}}'
+    outputs:
+      result: 'output'
+
+  - type: assert
+    statements:
+      - 'is_set({{result}})'
+```
+
+### Available step types
+
+| Step                  | What it does                                            |
+| --------------------- | ------------------------------------------------------- |
+| `install_application` | Install WASM app, capture `application_id`              |
+| `create_context`      | Create context, capture `context_id` and `seed`         |
+| `create_identity`     | Create identity, capture `private_key` and `public_key` |
+| `join_context`        | Join a node to a context (targeted invitation)          |
+| `invite_open`         | Create open invitation (anyone can join)                |
+| `join_open`           | Join via open invitation                                |
+| `call`                | Execute app method, capture output                      |
+| `wait`                | Sleep N seconds                                         |
+| `repeat`              | Loop with index variable                                |
+| `assert`              | Validate values (`is_set`, `contains`, `==`)            |
+| `json_assert`         | JSON equality/subset checks                             |
+| `upload_blob`         | Upload file to blob storage, capture `blob_id`          |
+| `script`              | Run a shell script                                      |
+| `fuzzy_test`          | Randomized load test (30-60+ min)                       |
+
+### Multi-node example
+
+```yaml
+name: Two-Node Sync Test
+steps:
+  - type: install_application
+    node: node-1
+    path: ./app.wasm
+    outputs:
+      app_id: 'application_id'
+
+  - type: create_context
+    node: node-1
+    application_id: '{{app_id}}'
+    outputs:
+      ctx: 'context.context_id'
+
+  - type: create_identity
+    node: node-1
+    outputs:
+      pub1: 'public_key'
+
+  - type: create_identity
+    node: node-2
+    outputs:
+      pub2: 'public_key'
+
+  # invite node-2 to join the context
+  - type: invite_open
+    node: node-1
+    context_id: '{{ctx}}'
+    granter_id: '{{pub1}}'
+    outputs:
+      invite: 'invitation'
+
+  - type: join_open
+    node: node-2
+    invitee_id: '{{pub2}}'
+    invitation: '{{invite}}'
+
+  - type: wait
+    seconds: 2 # allow sync
+
+  - type: call
+    node: node-1
+    context_id: '{{ctx}}'
+    method: set
+    args:
+      key: 'msg'
+      value: 'hello'
+    executor_public_key: '{{pub1}}'
+
+  - type: wait
+    seconds: 1
+
+  - type: call
+    node: node-2
+    context_id: '{{ctx}}'
+    method: get
+    args:
+      key: 'msg'
+    executor_public_key: '{{pub2}}'
+    outputs:
+      val: 'output'
+
+  - type: assert
+    statements:
+      - "contains({{val}}, 'hello')"
+```
+
+### Auth service (production-like setup)
+
+```yaml
+name: Workflow with Auth
+auth_service: true # enables Traefik + auth middleware
+
 nodes:
-  - name: node1
-    port: 2428
-  - name: node2
-    port: 2429
-EOF
+  count: 1
+  prefix: 'calimero-node'
+  image: 'ghcr.io/calimero-network/merod:edge'
+
+steps:
+  - type: wait
+    seconds: 5
+    message: 'Waiting for auth service...'
+```
 
-# Start the network
-merobox up --workflow workflow.yml
+Node URL with auth: `http://node1.127.0.0.1.nip.io`
 
-# Stop it
-merobox down
+## Variable substitution
+
+```yaml
+{{variable_name}}           # step output
+{{env.MY_VAR}}              # environment variable
+{{iteration}}               # loop index in repeat
+{{random_int(1, 100)}}      # random integer
+{{random_string(8)}}        # random string
+{{uuid}}                    # UUID v4
+{{timestamp}}               # Unix timestamp
+{{random_node}}             # random node from list
 ```
 
 ## When to use Merobox vs meroctl
 
-| Task | Use |
-| --- | --- |
-| Local multi-node dev and testing | Merobox |
-| Managing a single production node | meroctl |
-| CI pipeline with multi-node scenarios | Merobox |
-| One-off command against a live node | meroctl |
+| Task                                     | Use     |
+| ---------------------------------------- | ------- |
+| Local multi-node dev and testing         | Merobox |
+| CI pipeline with multi-step scenarios    | Merobox |
+| Quick single command against a live node | meroctl |
+| Managing a production node               | meroctl |
+
+## Related skills
+
+- **`calimero-merod`** — `merod` daemon setup (init, ports, health endpoint)
+- **`calimero-meroctl`** — full `meroctl` CLI reference for scripting against a live node
+- **`calimero-core`** — context/app model and namespace/group participation model
 
 ## References
 

package/skills/calimero-merobox/references/ci-integration.md

@@ -1,6 +1,7 @@
 # CI Integration
 
-Use Merobox in GitHub Actions or other CI systems to run integration tests against a real multi-node network.
+Use Merobox in GitHub Actions or other CI systems to run integration tests against a real multi-node
+network.
 
 ## GitHub Actions example
 
@@ -49,4 +50,4 @@ jobs:
 ## Reference workflow files
 
 The Battleships repo has well-structured workflow examples:
-https://github.com/calimero-network/battleships/tree/main/workflows
+<https://github.com/calimero-network/battleships/tree/main/workflows>

package/skills/calimero-merobox/references/workflow-files.md

@@ -1,6 +1,7 @@
 # Merobox Workflow Files
 
-Workflow files define reusable network topologies. Commit them to your repo for repeatable local dev and CI environments.
+Workflow files define reusable network topologies. Commit them to your repo for repeatable local dev
+and CI environments.
 
 ## Minimal workflow
 
@@ -30,16 +31,16 @@ setup:
 
   - step: create_context
     node: node1
-    app_id: "{{ install_app.app_id }}"
+    app_id: '{{ install_app.app_id }}'
 
   - step: invite_member
     node: node1
-    context_id: "{{ create_context.context_id }}"
-    identity: "{{ node2.identity }}"
+    context_id: '{{ create_context.context_id }}'
+    identity: '{{ node2.identity }}'
 
   - step: join_context
     node: node2
-    invitation: "{{ invite_member.invitation }}"
+    invitation: '{{ invite_member.invitation }}'
 ```
 
 ## Commands
@@ -64,6 +65,7 @@ merobox down --purge
 ## Accessing nodes after startup
 
 Each node exposes its JSON-RPC at the configured port:
+
 - `node1` → `http://localhost:2428`
 - `node2` → `http://localhost:2429`
 

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
+```