@calimero-network/agent-skills 0.3.0 → 0.4.0

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,66 +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
+```
 
-# 5. Check node is running
-meroctl --node-url http://localhost:2428 node health
+After setup, use `--node node1` or rely on the active node:
+
+```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
 ```
 
-`--home` defaults to `~/.calimero`. The home directory contains `config.toml`,
-the node's key material, and local storage. Each node must have its own home directory.
+## Related skills
 
-`--node-url` defaults to `http://localhost:2428` if not specified (the default port
-`merod` listens on after `merod --home ~/.calimero run`).
+- **`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>`

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

@@ -5,17 +5,39 @@ Full CLI for managing a running Calimero node.
 ## Global flags
 
 ```bash
-meroctl --node-url http://localhost:2428 <command>   # connect to specific node
-meroctl --home ~/.calimero <command>                  # alternate config path
+meroctl --node node1 <command>              # use registered node by name
+meroctl --api http://localhost:2428 <command>  # connect directly by URL
+meroctl --home ~/.calimero <command>        # alternate config path
+```
+
+Register a node once, then use by name:
+
+```bash
+meroctl node add node1 /path/to/home       # local node
+meroctl node add mynode http://node.com    # remote node
+meroctl node use node1                     # set as active (default)
 ```
 
 ---
 
-## Node commands
+## Node management commands
 
 ```bash
-# Check node health (returns "alive" when running)
-meroctl --node-url http://localhost:2428 node health
+# Add / connect to a node
+meroctl node add node1 /path/to/calimero/home
+meroctl node add remote1 http://node.example.com
+
+# Set active node
+meroctl node use node1
+
+# List configured nodes
+meroctl node ls
+
+# Remove a node connection
+meroctl node remove node1
+
+# Show node peer identity
+meroctl node identity
 ```
 
 ---
@@ -23,22 +45,22 @@ meroctl --node-url http://localhost:2428 node health
 ## App commands
 
 ```bash
-# Install app from local bundle (.mpk or .wasm)
-meroctl --node-url http://localhost:2428 app install --path myapp.mpk
-meroctl --node-url http://localhost:2428 app install --path target/wasm32-unknown-unknown/release/myapp.wasm
+# Install app from local file (.wasm or .mpk)
+meroctl --node node1 app install --path myapp.wasm
+meroctl --node node1 app install --path myapp.mpk
 
 # Install app from registry URL
-meroctl --node-url http://localhost:2428 app install \
-  --url https://registry.calimero.network/com.yourorg.myapp/1.0.0
+meroctl --node node1 app install \
+  --url https://apps.calimero.network/com.yourorg.myapp/1.0.0
 
 # List installed apps
-meroctl --node-url http://localhost:2428 app ls
+meroctl --node node1 app ls
 
 # Get details of a specific app
-meroctl --node-url http://localhost:2428 app get <app-id>
+meroctl --node node1 app get <application-id>
 
-# Remove an app (only works if no active contexts reference it)
-meroctl --node-url http://localhost:2428 app remove <app-id>
+# Remove an app
+meroctl --node node1 app remove <application-id>
 ```
 
 ---
@@ -47,44 +69,23 @@ meroctl --node-url http://localhost:2428 app remove <app-id>
 
 ```bash
 # Create a context (instantiates the app — calls init())
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+meroctl --node node1 context create --application-id <application-id>
 # Returns: context-id
 
+# Dev mode — watch a WASM file for changes and hot-reload
+meroctl --node node1 context create --watch path/to/app.wasm
+
 # List all contexts on this node
-meroctl --node-url http://localhost:2428 context ls
+meroctl --node node1 context ls
 
 # Get details of a specific context
-meroctl --node-url http://localhost:2428 context get <context-id>
-
-# Delete a context (wipes all state and storage for this context)
-meroctl --node-url http://localhost:2428 context delete <context-id>
+meroctl --node node1 context get <context-id>
 
-# List members of a context
-meroctl --node-url http://localhost:2428 context members <context-id>
+# Delete a context (wipes all state and storage)
+meroctl --node node1 context delete <context-id>
 
-# Invite a member to a context (generates an invitation payload)
-meroctl --node-url http://localhost:2428 context invite \
-  <context-id> --identity <identity>
-# Returns: invitation payload JSON — share this with the invitee
-
-# Join a context using an invitation payload (run on the joining node)
-meroctl --node-url http://localhost:2428 context join \
-  --invitation '<invitation-payload-json>'
-# After this, the node syncs state from the inviting node
-```
-
-### Full invite + join example
-
-```bash
-# ── Node A (inviter) ──
-meroctl --node-url http://localhost:2428 context invite \
-  abc123ctx --identity ed25519:AAAA...
-# Prints: {"payload":"..."}
-
-# ── Node B (joiner) ──
-meroctl --node-url http://localhost:2429 context join \
-  --invitation '{"payload":"..."}'
-# Node B now participates in the context and syncs CRDT state
+# Sync a context with peers
+meroctl --node node1 context sync <context-id>
 ```
 
 ---
@@ -92,16 +93,16 @@ meroctl --node-url http://localhost:2429 context join \
 ## Calling app methods
 
 ```bash
-# Mutation — changes shared state (no --view flag)
-meroctl --node-url http://localhost:2428 call <context-id> <method> \
+# Mutation — changes shared state
+meroctl --node node1 call <context-id> set \
   --args '{"key":"hello","value":"world"}'
 
 # View — read-only, does NOT change state
-meroctl --node-url http://localhost:2428 call <context-id> <method> \
+meroctl --node node1 call <context-id> get \
   --args '{"key":"hello"}' --view
 
 # Method with no arguments
-meroctl --node-url http://localhost:2428 call <context-id> list_all \
+meroctl --node node1 call <context-id> list_all \
   --args '{}' --view
 ```
 
@@ -110,74 +111,63 @@ meroctl --node-url http://localhost:2428 call <context-id> list_all \
 ## Identity commands
 
 ```bash
-# Create a new identity (root keypair for this node)
-meroctl --node-url http://localhost:2428 identity create
+# Create a new identity
+meroctl --node node1 identity create
 
-# List all identities on this node
-meroctl --node-url http://localhost:2428 identity ls
+# List all identities
+meroctl --node node1 identity ls
 
 # Get details of a specific identity
-meroctl --node-url http://localhost:2428 identity get <identity>
+meroctl --node node1 identity get <identity>
 ```
 
 ---
 
-## Step-by-step: full local development flow
+## Multi-node context sharing (namespace + group model)
 
-```bash
-# 1. Build the WASM app
-cargo build --target wasm32-unknown-unknown --release
+Multi-node participation uses namespaces (root groups) and group membership.
 
-# 2. Start the node (in a separate terminal)
-merod --home ~/.calimero run
+```bash
+# ── Node A: create a namespace and context ──
+meroctl --node node1 namespace create
+# → <namespace-id>
 
-# 3. Install the app
-meroctl --node-url http://localhost:2428 app install \
-  --path target/wasm32-unknown-unknown/release/myapp.wasm
-# Copy the app-id from output
+meroctl --node node1 context create --application-id <app-id>
+# → <context-id>
 
-# 4. Create a context
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
-# Copy the context-id from output
+# Generate an invitation for another node to join
+meroctl --node node1 namespace invite <namespace-id>
+# → invitation JSON payload
 
-# 5. Interact with the app
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"foo","value":"bar"}'
+# ── Node B: join via invitation ──
+meroctl --node node2 namespace join <namespace-id> '<invitation-json>'
 
-meroctl --node-url http://localhost:2428 call <context-id> get \
-  --args '{"key":"foo"}' --view
+# ── Node B: join the context (after joining namespace/group) ──
+meroctl --node node2 group join-context <context-id>
 ```
 
 ---
 
-## Step-by-step: multi-node context sharing
+## Step-by-step: full local development flow
 
 ```bash
-# ── Node A (port 2428) ──
-# Install app and create context
-meroctl --node-url http://localhost:2428 app install --path myapp.mpk
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
-# → <context-id>
+# 1. Initialize and start a node
+merod --node node1 init --server-port 2428 --swarm-port 2528
+merod --node node1 run &  # run in background
+
+# 2. Register the node in meroctl
+meroctl node add node1 ~/.calimero/node1
+meroctl node use node1
+
+# 3. Install the app
+meroctl app install --path target/wasm32-unknown-unknown/release/myapp.wasm
+# → copy the application-id
 
-# Create identity for node B to use
-meroctl --node-url http://localhost:2428 identity create
-# → <identity-b>
-
-# Generate invitation
-meroctl --node-url http://localhost:2428 context invite \
-  <context-id> --identity <identity-b>
-# → <invitation-payload>
-
-# ── Node B (port 2429) ──
-# Accept invitation
-meroctl --node-url http://localhost:2429 context join \
-  --invitation '<invitation-payload>'
-# Node B syncs all existing state from node A
-
-# Both nodes can now call methods and see each other's mutations:
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"shared","value":"data"}'
-meroctl --node-url http://localhost:2429 call <context-id> get \
-  --args '{"key":"shared"}' --view
-# → "data"  (synced from node A)
+# 4. Create a context
+meroctl context create --application-id <application-id>
+# → copy the context-id
+
+# 5. Interact with the app
+meroctl call <context-id> set --args '{"key":"foo","value":"bar"}'
+meroctl call <context-id> get --args '{"key":"foo"}' --view
 ```

package/skills/calimero-node/rules/app-vs-context.md

@@ -26,8 +26,8 @@ meroctl call <context-id> get --args '{"key":"hello"}' --view
 
 ## Why this matters
 
-API calls take a `context-id`, not an `app-id`. If you try to call a method with an
-`app-id` instead of a `context-id` you will get a "context not found" error.
+API calls take a `context-id`, not an `app-id`. If you try to call a method with an `app-id` instead
+of a `context-id` you will get a "context not found" error.
 
-One app can have multiple independent contexts — each with its own members and state.
-For example, a chat app might have one context per chat room.
+One app can have multiple independent contexts — each with its own members and state. For example, a
+chat app might have one context per chat room.