@calimero-network/agent-skills 0.2.0 → 0.4.0

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

package/skills/calimero-merod/rules/port-assignments.md

@@ -0,0 +1,33 @@
+# Rule: Understand Port Assignments
+
+**`merod` uses two distinct ports with different roles. Both matter.**
+
+## Port roles
+
+| Flag            | Default | Connected by                                                            |
+| --------------- | ------- | ----------------------------------------------------------------------- |
+| `--server-port` | `2428`  | `meroctl`, app clients (browser, Python, JS), all HTTP/WS API consumers |
+| `--swarm-port`  | `2528`  | Other `merod` nodes — P2P state sync, namespace invite protocol         |
+
+## What fails when a port is wrong or blocked
+
+| Problem                 | Symptom                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| Server port unreachable | `meroctl` cannot connect; clients get connection refused; apps cannot make API calls |
+| Swarm port unreachable  | Multi-node sync silently fails; namespaces cannot be joined; nodes appear isolated   |
+
+## Multiple nodes on the same machine
+
+Each `merod` instance needs unique 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
+merod --home ./data --node node3 init --server-port 2430 --swarm-port 2530
+```
+
+## Ports are set at init time
+
+Port assignments are written into the config file during `merod init`. You cannot change them with
+`merod run` flags — edit `config.toml` in the node home or re-init if you need different ports
+(re-init destroys the node identity, so prefer editing `config.toml`).

package/skills/calimero-node/SKILL.md

@@ -4,7 +4,8 @@ You are helping a developer manage a **Calimero node** using `merod` and `meroct
 
 ## Key concepts
 
-- `merod` — the node runtime. Runs as a daemon. Hosts WASM apps, manages storage, exposes JSON-RPC + WebSocket
+- `merod` — the node runtime. Runs as a daemon. Hosts WASM apps, manages storage, exposes JSON-RPC +
+  WebSocket
 - `meroctl` — the CLI for administrating a running node (contexts, apps, identities)
 - **Context** — an isolated application instance with its own members, state, and storage
 - **Application** — the WASM code; one app can power many contexts
@@ -13,60 +14,76 @@ You are helping a developer manage a **Calimero node** using `merod` and `meroct
 ## Node setup (first time)
 
 ```bash
-# Initialize node configuration
-merod --home ~/.calimero init
+# Initialize node (creates key material and config)
+merod --node node1 init --server-port 2428 --swarm-port 2528
 
 # Start the node
-merod --home ~/.calimero run
+merod --node node1 run
 # Node listens on http://localhost:2428 by default
 ```
 
-## Complete workflow: app → context → call
+`--home <PATH>` is optional; defaults to the system config directory. Use it to specify a custom
+data directory: `merod --home ./data --node node1 init`.
+
+## Connecting meroctl to a node
 
 ```bash
-# 1. Install an app
-meroctl --node-url http://localhost:2428 app install \
-  --path myapp.mpk
-# → prints app-id
+# Register a local node by name (one-time)
+meroctl node add node1 /path/to/calimero/home
 
-# 2. Create a context (instantiate the app — init() is called)
-meroctl --node-url http://localhost:2428 context create \
-  --app-id <app-id>
-# → prints context-id
+# Or register a remote node
+meroctl node add mynode http://node.example.com
 
-# 3. Call a mutation (changes state)
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"hello","value":"world"}'
+# Set as default (so you don't need --node on every command)
+meroctl node use node1
 
-# 4. Call a view (read-only)
-meroctl --node-url http://localhost:2428 call <context-id> get \
-  --args '{"key":"hello"}' --view
+# List configured nodes
+meroctl node ls
+```
+
+After setup, use `--node node1` or rely on the active node:
 
-# 5. Check node is running
-meroctl --node-url http://localhost:2428 node health
+```bash
+meroctl --node node1 context ls   # explicit
+meroctl context ls                # uses active node
 ```
 
-## Multi-node context (invite + join)
+Alternatively, pass a direct URL without registering:
 
 ```bash
-# On node A — invite a member
-meroctl --node-url http://localhost:2428 context invite \
-  <context-id> --identity <identity-on-node-A>
-# → prints invitation payload (JSON)
-
-# On node B — accept the invitation
-meroctl --node-url http://localhost:2429 context join \
-  --invitation '<paste-invitation-payload>'
-# → node B syncs state from node A
+meroctl --api http://localhost:2428 context ls
 ```
 
-## Global flags
+## Complete workflow: app → context → call
 
 ```bash
-meroctl --node-url http://localhost:2428 <command>   # connect to specific node
-meroctl --home ~/.calimero <command>                  # use alternate config path
+# (Assumes: meroctl node add node1 ... && meroctl node use node1 already done)
+
+# 1. Install an app
+meroctl app install --path myapp.wasm
+# → prints application-id
+
+# 2. Create a context (instantiate the app — init() is called)
+meroctl context create --application-id <application-id>
+# → prints context-id
+
+# 3. Call a mutation (changes state)
+meroctl call <context-id> set --args '{"key":"hello","value":"world"}'
+
+# 4. Call a view (read-only)
+meroctl call <context-id> get --args '{"key":"hello"}' --view
 ```
 
+## Related skills
+
+- **`calimero-merod`** — deep-dive on `merod` daemon: all init flags, config file schema, health
+  endpoints, Docker setup
+- **`calimero-meroctl`** — complete `meroctl` CLI reference: every subcommand, every flag, scripting
+  patterns, multi-node namespace/group workflow
+- **`calimero-core`** — context/app/identity model, JSON-RPC protocol, WebSocket events, CRDT
+  storage types
+
 ## References
 
-See `references/` for full meroctl command reference and context lifecycle.
+See `references/` for context lifecycle detail and multi-node namespace/group setup. For the full
+`meroctl` command reference, use the `calimero-meroctl` skill.

package/skills/calimero-node/references/context-lifecycle.md

@@ -1,26 +1,27 @@
 # Context Lifecycle
 
-A **context** is an isolated instance of an application with its own members, CRDT state, and storage.
+A **context** is an isolated instance of an application with its own members, CRDT state, and
+storage.
 
 ## App vs Context
 
-| Concept | What it is | Analogy |
-| --- | --- | --- |
-| Application | WASM binary + manifest | A class / template |
-| Context | Running instance of an app | An object / instance |
+| Concept     | What it is                 | Analogy              |
+| ----------- | -------------------------- | -------------------- |
+| Application | WASM binary + manifest     | A class / template   |
+| Context     | Running instance of an app | An object / instance |
 
 One application can power many independent contexts. Each context has completely isolated state.
 
 ## Lifecycle
 
-```
+```text
 App installed on node
        │
        ▼
 Context created (init() called → initial state set)
        │
        ▼
-Members invited and joined
+Members join via namespace/group membership
        │
        ├─ Methods called (mutations + views)
        ├─ Events emitted to members
@@ -33,23 +34,38 @@ Context deleted (state and storage wiped)
 ## Creating a context
 
 ```bash
-meroctl context create --app-id <app-id>
+meroctl --node node1 context create --application-id <application-id>
 # Returns: context-id
 ```
 
-## Inviting members
+Dev mode — auto-reinstalls when the WASM file changes:
 
 ```bash
-# On node A — generate an invitation
-meroctl context invite <context-id> --identity <identity-on-node-A>
-# Returns: invitation payload (share this with the new member)
-
-# On node B — accept the invitation
-meroctl context join --invitation <paste-invitation-payload>
+meroctl --node node1 context create --watch path/to/app.wasm
 ```
 
-After joining, node B's state will sync from node A. From that point both nodes
-participate in CRDT state synchronization.
+## Multi-node participation (namespace + group model)
+
+Nodes join a context via **namespaces** (root groups). The inviting node creates a namespace
+invitation; joining nodes accept it, then join the context via group membership.
+
+```bash
+# ── Node A (creator) ──
+meroctl --node node1 namespace create
+# → <namespace-id>
+
+meroctl --node node1 context create --application-id <app-id>
+# → <context-id>
+
+meroctl --node node1 namespace invite <namespace-id>
+# → invitation JSON — share with Node B
+
+# ── Node B (joiner) ──
+meroctl --node node2 namespace join <namespace-id> '<invitation-json>'
+
+meroctl --node node2 group join-context <context-id>
+# Node B now participates and syncs CRDT state from Node A
+```
 
 ## State synchronization
 
@@ -57,3 +73,4 @@ participate in CRDT state synchronization.
 - All context members receive mutations from all other members
 - Conflicts are resolved deterministically by the CRDT engine
 - Sync works offline — changes queue up and merge when reconnected
+- Manual sync: `meroctl --node node1 context sync <context-id>`