@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-core/references/websocket-events.md

@@ -0,0 +1,142 @@
+# WebSocket Events
+
+The Calimero node pushes real-time events to subscribers over WebSocket.
+
+## Connect and subscribe
+
+```text
+ws://localhost:2428/ws
+```
+
+After connecting, send:
+
+```json
+{ "action": "subscribe", "contextIds": ["<context-id-1>", "<context-id-2>"] }
+```
+
+You can subscribe to multiple context IDs in one message.
+
+---
+
+## Event types
+
+| Type             | When fired                                            | Payload                        |
+| ---------------- | ----------------------------------------------------- | ------------------------------ |
+| `ExecutionEvent` | App called `app::emit!()` (Rust) or `env.emit()` (JS) | `{ events: ExecutionEvent[] }` |
+| `StateMutation`  | Any context member mutated shared state               | `{ newRoot: string }`          |
+
+---
+
+## ExecutionEvent schema
+
+```typescript
+interface WsMessage {
+  contextId: string;
+  type: 'ExecutionEvent';
+  data: {
+    events: Array<{
+      kind: string; // matches Rust enum variant name or JS event name
+      data: number[] | object; // byte array (UTF-8 JSON) or plain object
+    }>;
+  };
+}
+```
+
+`data` is typically a UTF-8 JSON byte array when coming from a Rust app. Decode it:
+
+```typescript
+function decodeEventData(data: unknown): unknown {
+  if (Array.isArray(data) && data.every((n) => typeof n === 'number')) {
+    try {
+      return JSON.parse(new TextDecoder().decode(new Uint8Array(data as number[])));
+    } catch {
+      return data; // leave as-is if not valid JSON
+    }
+  }
+  return data;
+}
+```
+
+Full consumption pattern:
+
+```typescript
+ws.onmessage = (msg) => {
+  const envelope = JSON.parse(msg.data);
+  if (envelope.type === 'ExecutionEvent') {
+    for (const e of envelope.data.events) {
+      const payload = decodeEventData(e.data);
+      switch (e.kind) {
+        case 'PostCreated':
+          handlePostCreated(payload);
+          break;
+        case 'PostDeleted':
+          handlePostDeleted(payload);
+          break;
+      }
+    }
+  }
+  if (envelope.type === 'StateMutation') {
+    // A peer mutated shared state — refetch data if needed
+    refreshData();
+  }
+};
+```
+
+---
+
+## StateMutation schema
+
+```typescript
+interface WsMessage {
+  contextId: string;
+  type: 'StateMutation';
+  data: {
+    newRoot: string; // hex hash of the new CRDT state root after merge
+  };
+}
+```
+
+Use `StateMutation` to know when to refetch state from the node — it fires on every mutation from
+any member, including the local node's own mutations.
+
+---
+
+## Unsubscribe
+
+```json
+{ "action": "unsubscribe", "contextIds": ["<context-id>"] }
+```
+
+---
+
+## Emitting events from Rust
+
+```rust
+#[app::event]
+pub enum Event<'a> {
+    PostCreated { title: &'a str },
+    PostDeleted { id: u32 },
+}
+
+#[app::logic]
+impl AppState {
+    pub fn create_post(&mut self, title: String) -> app::Result<()> {
+        // ...
+        app::emit!(Event::PostCreated { title: &title });
+        Ok(())
+    }
+}
+```
+
+The `kind` field in the WebSocket message will be `"PostCreated"` or `"PostDeleted"`.
+
+## Emitting events from TypeScript (SDK JS)
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+set(key: string, value: string): void {
+  this.items.set(key, value);
+  env.emit({ kind: 'ItemSet', data: { key, value } });
+}
+```

package/skills/calimero-core/rules/context-is-not-app.md

@@ -0,0 +1,35 @@
+# Rule: Application ≠ Context
+
+**An application is not a context. Installing an app does not create a context.**
+
+## What this means
+
+- `meroctl app install` → registers the WASM binary. Returns an `application-id`. No state exists
+  yet. No context exists yet.
+- `meroctl context create --application-id <id>` → creates a context. Calls `init()`. State now
+  exists. The context has a `context-id`.
+
+These are always **two separate commands**. You cannot skip the first step and jump straight to
+calling methods.
+
+## Why this matters
+
+When a developer says "install and run my app", the correct sequence is:
+
+```bash
+meroctl app install --path app.wasm          # → application-id
+meroctl context create --application-id <id> # → context-id
+meroctl call <context-id> my_method --args '{}'
+```
+
+Not:
+
+```bash
+meroctl app install --path app.wasm
+meroctl call ???                             # WRONG — no context yet
+```
+
+## Analogy
+
+Think of an Application as a class definition and a Context as an instance of that class. You can
+have many contexts (instances) from one application (class), each with completely isolated state.

package/skills/calimero-core/rules/crdt-types-only.md

@@ -0,0 +1,55 @@
+# Rule: CRDT Types Only for Shared State
+
+**Never use `std::collections` (Rust) or plain `Map`/`Array` (JS/TS) for shared application state.**
+
+## Forbidden for state fields
+
+```rust
+// WRONG — will compile but cause data loss on concurrent writes:
+struct AppState {
+    items: std::collections::HashMap<String, String>,  // ❌
+    log:   Vec<String>,                                // ❌
+    seen:  std::collections::HashSet<String>,          // ❌
+}
+```
+
+```typescript
+// WRONG — same problem in TypeScript:
+@State
+class AppState {
+  items: Map<string, string> = new Map(); // ❌
+  log: string[] = []; // ❌
+}
+```
+
+## Required: use CRDT collections
+
+```rust
+// CORRECT:
+use calimero_storage::collections::{UnorderedMap, Vector, LwwRegister};
+
+struct AppState {
+    items: UnorderedMap<String, LwwRegister<String>>,  // ✓
+    log:   Vector<String>,                              // ✓
+}
+```
+
+```typescript
+// CORRECT:
+import { UnorderedMap, Vector } from '@calimero-network/calimero-sdk-js/collections';
+
+@State
+class AppState {
+  items: UnorderedMap<string, string> = new UnorderedMap(); // ✓
+  log: Vector<string> = new Vector(); // ✓
+}
+```
+
+## Why
+
+Standard collections have no merge semantics. When two context members both write to a `HashMap`
+while offline, merging their states is undefined — the CRDT engine cannot resolve conflicts
+automatically and data will be silently lost or overwritten.
+
+CRDT collections are designed for exactly this scenario: they guarantee that all members converge to
+the same state regardless of write order or network partitions.

package/skills/calimero-desktop/SKILL.md

@@ -1,30 +1,30 @@
 # calimero-desktop — Agent Instructions
 
-You are helping a developer integrate their app frontend with **Calimero Desktop SSO** —
-the flow where users open an app from the Desktop and are automatically logged in without
-a manual auth screen.
+You are helping a developer integrate their app frontend with **Calimero Desktop SSO** — the flow
+where users open an app from the Desktop and are automatically logged in without a manual auth
+screen.
 
-> **NOT this skill** if the developer just needs to authenticate manually via the login
-> form — that is handled entirely by `calimero-client-js`. This skill is specifically for
-> reading SSO tokens that Calimero Desktop passes in the URL hash.
+> **NOT this skill** if the developer just needs to authenticate manually via the login form — that
+> is handled entirely by `calimero-client-js`. This skill is specifically for reading SSO tokens
+> that Calimero Desktop passes in the URL hash.
 
 ## What Desktop does
 
-Calimero Desktop opens app frontends in a browser window and passes auth tokens via the
-URL hash — so users are automatically logged in without going through the manual auth flow.
+Calimero Desktop opens app frontends in a browser window and passes auth tokens via the URL hash —
+so users are automatically logged in without going through the manual auth flow.
 
 ## Hash parameters passed by Desktop
 
-| Parameter | Type | Description |
-| --- | --- | --- |
-| `access_token` | string | JWT for authenticated node calls |
-| `refresh_token` | string | Token to obtain a new access token |
-| `node_url` | string | URL of the local node (`http://localhost:PORT`) |
-| `application_id` | string | The installed app's ID on this node |
+| Parameter        | Type   | Description                                     |
+| ---------------- | ------ | ----------------------------------------------- |
+| `access_token`   | string | JWT for authenticated node calls                |
+| `refresh_token`  | string | Token to obtain a new access token              |
+| `node_url`       | string | URL of the local node (`http://localhost:PORT`) |
+| `application_id` | string | The installed app's ID on this node             |
 
 ## Example URL
 
-```
+```text
 https://your-app.com/#access_token=eyJ...&refresh_token=eyJ...&node_url=http://localhost:2428&application_id=abc123
 ```
 
@@ -44,10 +44,15 @@ if (accessToken && nodeUrl) {
 
 ## Critical rule
 
-Always fall back to manual login when hash params are absent. The app must work when
-opened in a regular browser, not only from Desktop.
+Always fall back to manual login when hash params are absent. The app must work when opened in a
+regular browser, not only from Desktop.
+
+## Related skills
+
+- **`calimero-client-js`** — mero-js / mero-react API for auth, RPC, and WebSocket subscriptions
+- **`calimero-core`** — auth flow (JWT tokens, login, refresh) and JSON-RPC protocol detail
 
 ## References
 
-See `references/` for full integration pattern and how Desktop discovers app URLs.
-See `rules/` for the fallback requirement.
+See `references/` for full integration pattern and how Desktop discovers app URLs. See `rules/` for
+the fallback requirement.

package/skills/calimero-desktop/references/sso-integration.md

@@ -72,8 +72,8 @@ document.addEventListener('DOMContentLoaded', bootstrap);
 
 ## How Desktop discovers your app's frontend URL
 
-Desktop reads the `links.frontend` field from your app's `manifest.json` inside the
-installed bundle. Set this field so Desktop can open your app:
+Desktop reads the `links.frontend` field from your app's `manifest.json` inside the installed
+bundle. Set this field so Desktop can open your app:
 
 ```json
 {

package/skills/calimero-desktop/rules/sso-fallback.md

@@ -1,6 +1,7 @@
 # Rule: Always fall back to manual login if hash params are absent
 
 Your app must work in two scenarios:
+
 1. Opened from Calimero Desktop — SSO hash params present
 2. Opened directly in a browser — no hash params
 
@@ -29,5 +30,5 @@ if (token) {
 
 ## Why
 
-Desktop is not the only way users access apps. Developers test in browsers directly.
-Organizations may embed apps in other contexts. The app must be self-sufficient.
+Desktop is not the only way users access apps. Developers test in browsers directly. Organizations
+may embed apps in other contexts. The app must be self-sufficient.

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`