@calimero-network/agent-skills 0.3.0 → 0.4.0

package/skills/calimero-client-py/rules/stable-node-name.md

@@ -1,7 +1,7 @@
 # Rule: node_name must be stable and unique per node
 
-`node_name` is used to derive the token cache filename. Changing it between runs
-means the client can't find the cached tokens and will fail to authenticate.
+`node_name` is used to derive the token cache filename. Changing it between runs means the client
+can't find the cached tokens and will fail to authenticate.
 
 ## WRONG — dynamic or None:
 
@@ -29,11 +29,11 @@ connection = create_connection(api_url=url, node_name=node_name)
 
 ## Why
 
-Token cache files are named `{sanitized_node_name}-{hash}.json` in `~/.merobox/auth_cache/`.
-If `node_name` varies, a new cache file is created each run and existing tokens are never
-reused — forcing re-authentication on every invocation.
+Token cache files are named `{sanitized_node_name}-{hash}.json` in `~/.merobox/auth_cache/`. If
+`node_name` varies, a new cache file is created each run and existing tokens are never reused —
+forcing re-authentication on every invocation.
 
 ## Also: unique per remote node
 
-If you connect to multiple nodes in the same script, use a different `node_name` for each.
-Sharing a `node_name` across two different nodes will mix up their token caches.
+If you connect to multiple nodes in the same script, use a different `node_name` for each. Sharing a
+`node_name` across two different nodes will mix up their token caches.

package/skills/calimero-core/SKILL.md

@@ -0,0 +1,135 @@
+# calimero-core — Agent Instructions
+
+You are helping a developer understand the **core Calimero runtime** — the mental model, protocols,
+and primitives that every application, client library, and node operator needs to know.
+
+> Use this skill alongside a language-specific skill (`calimero-rust-sdk`, `calimero-sdk-js`,
+> `calimero-client-js`, etc.) to give the AI full-stack context.
+
+## The three-layer model
+
+```text
+┌─────────────────────────────────────────────────────┐
+│  Application logic (WASM)                            │  calimero-rust-sdk / calimero-sdk-js
+│  @State / #[app::state], CRDT collections           │
+└────────────────────────┬────────────────────────────┘
+                         │ JSON-RPC calls + WebSocket events
+┌────────────────────────▼────────────────────────────┐
+│  merod node runtime                                  │  calimero-merod
+│  Hosts WASM, manages storage, exposes HTTP/WS API   │
+└────────────────────────┬────────────────────────────┘
+                         │ meroctl CLI / HTTP clients / Python client
+┌────────────────────────▼────────────────────────────┐
+│  Clients & tooling                                   │  calimero-client-js / calimero-client-py
+│  mero-js, mero-react, calimero-client-py            │  calimero-meroctl
+└─────────────────────────────────────────────────────┘
+```
+
+## Core concepts
+
+### Application vs Context
+
+| Concept         | What it is                                                         | Analogy              |
+| --------------- | ------------------------------------------------------------------ | -------------------- |
+| **Application** | WASM binary + manifest; the code                                   | A class / template   |
+| **Context**     | A running instance of an app; has isolated state, members, storage | An object / instance |
+
+One application can power many independent contexts. State is never shared across contexts.
+
+### Identity
+
+An **identity** is an Ed25519 keypair. Each context member has an identity on the node. The
+identity's public key is used:
+
+- As `executorPublicKey` in RPC calls (who is calling)
+- For signing mutations in the CRDT sync protocol
+
+### Namespace and Group
+
+| Concept       | Role                                                                                       |
+| ------------- | ------------------------------------------------------------------------------------------ |
+| **Namespace** | A root trust anchor shared across nodes; created by one node, others join via invite token |
+| **Group**     | Sub-grouping within a namespace; contexts are joined via group membership                  |
+
+Multi-node participation requires: create namespace → invite peer → peer joins namespace → peer
+joins context via group.
+
+## How calls work (JSON-RPC)
+
+All application method calls go through the node's JSON-RPC endpoint:
+
+```text
+POST http://localhost:2428/api/v0/context/{contextId}/execute
+Authorization: Bearer <access_token>
+
+{
+  "method": "get_posts",
+  "argsJson": "{}",
+  "executorPublicKey": "<base58-pubkey>"
+}
+```
+
+- **Mutations** (methods taking `&mut self`) change shared CRDT state; changes are synced to all
+  context members automatically.
+- **Views** (methods taking `&self`, annotated `@View` or returning read-only) do NOT persist state.
+- There is no separate "query" endpoint — mutations and views use the same call path. The `--view`
+  flag in `meroctl call` tells the client to skip state persistence.
+
+## How events work (WebSocket)
+
+Applications emit events with `app::emit!()` (Rust) or `env.emit()` (JS). Clients subscribe via
+WebSocket to receive them in real time.
+
+Two event types the node sends to subscribers:
+
+| Type             | When                          | Payload                        |
+| ---------------- | ----------------------------- | ------------------------------ |
+| `ExecutionEvent` | App called `app::emit!()`     | `{ events: [{ kind, data }] }` |
+| `StateMutation`  | A member mutated shared state | `{ newRoot: string }`          |
+
+WebSocket endpoint: `ws://localhost:2428/ws`
+
+## CRDT storage types
+
+All shared application state uses conflict-free replicated data types from
+`calimero_storage::collections`. Plain `HashMap`, `Vec`, or `HashSet` must never be used for shared
+state.
+
+| Type                        | Use for                                 |
+| --------------------------- | --------------------------------------- |
+| `UnorderedMap<K, V>`        | Key-value store (most common)           |
+| `Vector<T>`                 | Append-only ordered log                 |
+| `UnorderedSet<T>`           | Unique value set                        |
+| `LwwRegister<T>`            | Single last-write-wins scalar           |
+| `Counter` / `Counter<true>` | Grow-only / PN counter                  |
+| `FrozenStorage<T>`          | Immutable content-addressed blobs       |
+| `UserStorage<T>`            | Per-member private storage (not synced) |
+| `ReplicatedGrowableArray`   | Collaborative text / ordered sequence   |
+
+## Authentication
+
+The node uses short-lived JWT access tokens + long-lived refresh tokens:
+
+```bash
+# Get tokens
+POST /api/v0/identity/login
+{ "username": "admin", "password": "..." }
+→ { "accessToken": "...", "refreshToken": "..." }
+
+# Refresh
+POST /api/v0/identity/refresh
+{ "refreshToken": "..." }
+→ { "accessToken": "..." }
+```
+
+Tokens are passed as `Authorization: Bearer <accessToken>` on all API calls.
+
+## References
+
+See `references/` for:
+
+- Full JSON-RPC protocol and endpoint list
+- WebSocket event schemas with decoding examples
+- CRDT storage type guide
+- Namespace and group model detail
+- Architecture overview

package/skills/calimero-core/references/architecture.md

@@ -0,0 +1,101 @@
+# Calimero Architecture
+
+## What merod is
+
+`merod` is the Calimero node daemon. It:
+
+- Hosts and executes WASM applications inside isolated contexts
+- Manages persistent CRDT storage per context
+- Exposes a JSON-RPC + WebSocket API on a configurable HTTP port
+- Participates in a P2P network on a separate swarm port for state sync
+- Issues and validates JWT tokens for client auth
+
+One `merod` process = one node. Multiple nodes can be run on the same machine with different
+`--node` names and different ports.
+
+## What a Context is
+
+A **context** is a sandboxed instance of a WASM application with:
+
+- Its own isolated CRDT state (not shared with other contexts, even of the same app)
+- Its own set of **members** (identities that can call methods and receive events)
+- Its own blob storage
+- A unique `context-id` (hex string)
+
+When a context is created, the app's `init()` / `@Init` method is called once to seed the initial
+state.
+
+## What an Application is
+
+An **application** is a compiled WASM binary + optional manifest. It has:
+
+- A unique `application-id` assigned at install time
+- No state of its own — state lives in contexts that instantiate it
+- One app can power many independent contexts
+
+Installing an app does NOT create a context. These are always two separate steps.
+
+## What an Identity is
+
+An **identity** is an Ed25519 keypair managed by the node:
+
+- `identityId` — the base58-encoded public key, used as `executorPublicKey` in RPC calls
+- Identities are created per node (`meroctl identity create`)
+- An identity participates in a context as a member
+
+## Call path for an app method
+
+```text
+Client
+  │  POST /api/v0/context/{contextId}/execute
+  │  { method, argsJson, executorPublicKey }
+  ▼
+merod HTTP handler
+  │  validates JWT, resolves context
+  ▼
+WASM executor
+  │  deserializes state from CRDT storage
+  │  calls the method
+  │  serializes mutations back to storage
+  ▼
+CRDT sync engine
+  │  broadcasts mutation to all context members (P2P)
+  ▼
+WebSocket subscribers
+     receive ExecutionEvent / StateMutation
+```
+
+## Sync model
+
+State sync is automatic and happens over the P2P network:
+
+- All context members receive all mutations from all other members
+- Conflicts are resolved deterministically by the CRDT merge rules
+- Sync works offline — mutations queue and merge on reconnect
+- Manual sync trigger: `meroctl context sync <context-id>`
+
+## Multi-node participation
+
+Nodes join contexts through the namespace + group model:
+
+```text
+Node A creates a namespace (trust root)
+  → Node A creates a context
+  → Node A generates namespace invite token
+  → Node B accepts the invite (joins namespace)
+  → Node B joins the context via group membership
+  → Both nodes now sync CRDT state for that context
+```
+
+Once joined, state sync is fully automatic. Node B receives all future mutations from Node A (and
+vice versa) without any further configuration.
+
+## Port assignment
+
+| Port                           | Purpose                                            |
+| ------------------------------ | -------------------------------------------------- |
+| `--server-port` (default 2428) | HTTP/WS API — clients and meroctl connect here     |
+| `--swarm-port` (default 2528)  | P2P swarm — inter-node state sync, invite protocol |
+
+These ports must be accessible to meroctl and app clients (server port), and to other nodes for sync
+(swarm port).

package/skills/calimero-core/references/jsonrpc-protocol.md

@@ -0,0 +1,192 @@
+# JSON-RPC Protocol
+
+The Calimero node exposes its application and admin APIs over HTTP/REST at
+`http://localhost:2428/api/v0/` by default.
+
+## Base URL
+
+```text
+http://<node-host>:<server-port>/api/v0
+```
+
+Default: `http://localhost:2428/api/v0`
+
+All endpoints require `Authorization: Bearer <accessToken>` except `/identity/login`.
+
+---
+
+## Authentication endpoints
+
+### Login
+
+```text
+POST /api/v0/identity/login
+
+Body: { "username": "admin", "password": "..." }
+
+Response: {
+  "accessToken":  "eyJ...",
+  "refreshToken": "eyJ..."
+}
+```
+
+### Refresh
+
+```text
+POST /api/v0/identity/refresh
+
+Body: { "refreshToken": "eyJ..." }
+
+Response: { "accessToken": "eyJ..." }
+```
+
+---
+
+## Application method execution
+
+This is how frontends and clients invoke WASM app logic.
+
+### Execute a method (mutation or view)
+
+```text
+POST /api/v0/context/{contextId}/execute
+
+Headers:
+  Authorization: Bearer <accessToken>
+
+Body: {
+  "method": "method_name",
+  "argsJson": "{\"key\":\"hello\"}",
+  "executorPublicKey": "<base58-identity-pubkey>"
+}
+
+Response (success): {
+  "output": <json-value>        // method return value, null for void
+}
+
+Response (error): {
+  "error": {
+    "cause": {
+      "info": { "message": "..." }
+    }
+  }
+}
+```
+
+- `argsJson` is a **JSON string** (double-encoded) — not an inline object.
+- `executorPublicKey` is the base58 public key of the identity making the call.
+- Mutations and views use the same endpoint; views skip state persistence. The `mero-js` /
+  `mero-react` SDK handles this transparently.
+
+---
+
+## Context management endpoints
+
+### List contexts
+
+```text
+GET /api/v0/contexts
+
+Response: [
+  { "id": "<context-id>", "applicationId": "<app-id>", ... },
+  ...
+]
+```
+
+### Get context details
+
+```text
+GET /api/v0/contexts/{contextId}
+```
+
+### Create context
+
+```text
+POST /api/v0/contexts
+
+Body: { "applicationId": "<app-id>" }
+
+Response: { "id": "<context-id>" }
+```
+
+### Delete context
+
+```text
+DELETE /api/v0/contexts/{contextId}
+```
+
+---
+
+## Application management endpoints
+
+### List installed applications
+
+```text
+GET /api/v0/applications
+```
+
+### Install application from local file
+
+```text
+POST /api/v0/applications
+Content-Type: multipart/form-data
+
+file: <wasm-binary>
+
+Response: { "applicationId": "<id>" }
+```
+
+### Get application details
+
+```text
+GET /api/v0/applications/{applicationId}
+```
+
+---
+
+## Identity endpoints
+
+### List identities
+
+```text
+GET /api/v0/identities
+```
+
+### Create identity
+
+```text
+POST /api/v0/identities
+
+Response: { "publicKey": "<base58>", "privateKey": "<base58>" }
+```
+
+---
+
+## WebSocket endpoint
+
+```text
+ws://localhost:2428/ws
+```
+
+After connecting, send a subscribe message:
+
+```json
+{ "action": "subscribe", "contextIds": ["<context-id>"] }
+```
+
+The node will push `ExecutionEvent` and `StateMutation` messages. See `websocket-events.md` for the
+full schema.
+
+---
+
+## Error codes
+
+| HTTP status | Meaning                                                       |
+| ----------- | ------------------------------------------------------------- |
+| `400`       | Bad request — malformed JSON, missing fields                  |
+| `401`       | Unauthorized — missing or expired access token                |
+| `403`       | Forbidden — identity not a context member                     |
+| `404`       | Not found — unknown context or application ID                 |
+| `500`       | Internal server error — WASM execution panic or storage error |
+
+On `401`, refresh the access token and retry.

package/skills/calimero-core/references/namespaces-groups.md

@@ -0,0 +1,94 @@
+# Namespaces and Groups
+
+Namespaces and groups are the multi-node participation primitives in Calimero. They control which
+nodes can join which contexts and how trust is established between nodes.
+
+## Concepts
+
+| Concept       | Role                                                                                                             |
+| ------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Namespace** | A root trust anchor created by one node. Other nodes join by accepting an invite token generated by the creator. |
+| **Group**     | A sub-grouping within a namespace. Contexts are joined via group membership, not directly.                       |
+
+A node must be in the correct namespace/group before it can participate in a context.
+
+---
+
+## Full multi-node setup
+
+### Node A: Create and invite
+
+```bash
+# 1. Create a namespace (trust root)
+meroctl --node node1 namespace create
+# → <namespace-id>
+
+# 2. Create a context from an installed app
+meroctl --node node1 context create --application-id <app-id>
+# → <context-id>
+
+# 3. Generate an invite for Node B
+meroctl --node node1 namespace invite <namespace-id>
+# → prints invitation JSON payload — share this with Node B out-of-band
+```
+
+### Node B: Accept and join
+
+```bash
+# 4. Accept the namespace invite
+meroctl --node node2 namespace join <namespace-id> '<invitation-json>'
+
+# 5. Join the context via group membership
+meroctl --node node2 group join-context <context-id>
+# Node B is now a context member and will sync CRDT state from Node A
+```
+
+After step 5, state sync is fully automatic. Both nodes send and receive mutations through the P2P
+swarm.
+
+---
+
+## Namespace commands
+
+```bash
+# Create a new namespace
+meroctl --node node1 namespace create
+
+# List namespaces on this node
+meroctl --node node1 namespace ls
+
+# Generate an invite token for a namespace
+meroctl --node node1 namespace invite <namespace-id>
+
+# Join a namespace (Node B)
+meroctl --node node2 namespace join <namespace-id> '<invitation-json>'
+```
+
+---
+
+## Group commands
+
+```bash
+# List groups
+meroctl --node node1 group ls
+
+# Join a context via group
+meroctl --node node2 group join-context <context-id>
+```
+
+---
+
+## What happens after a node joins
+
+1. The new member receives the full CRDT state from existing members.
+2. Future mutations from any member are broadcast to all other members.
+3. Offline mutations are queued and merged on reconnect — no data is lost.
+4. The new member's identity can execute methods and its mutations are accepted by other members.
+
+---
+
+## Single-node vs multi-node
+
+For local development on a single node you do not need namespaces or groups — create a context
+directly and call methods. Namespaces/groups are only required when two or more `merod` instances
+need to share a context.

package/skills/calimero-core/references/storage-types.md

@@ -0,0 +1,118 @@
+# CRDT Storage Types
+
+All shared application state must use conflict-free replicated data types (CRDTs). These types
+handle concurrent writes from multiple context members automatically.
+
+## Why CRDTs
+
+When two nodes both mutate state while offline and then reconnect, the CRDT engine merges both sets
+of changes deterministically — no manual conflict resolution needed. Standard `HashMap`, `Vec`, or
+`HashSet` do not have this property and must never be used for state that is shared across context
+members.
+
+---
+
+## Type reference
+
+| Type                      | Use for                               | Key rule                                          |
+| ------------------------- | ------------------------------------- | ------------------------------------------------- |
+| `UnorderedMap<K, V>`      | Key-value store                       | Wrap values in `LwwRegister<V>` for scalar values |
+| `Vector<T>`               | Append-only ordered log               | Cannot remove items                               |
+| `UnorderedSet<T>`         | Unique value collection               | Grow-only by default                              |
+| `LwwRegister<T>`          | Single mutable scalar                 | Last write wins — safe for simple values          |
+| `Counter`                 | Grow-only integer counter             | `.increment()`, `.value()`                        |
+| `Counter<true>`           | PN counter (supports decrement)       | `.increment()`, `.decrement()`, `.value()`        |
+| `FrozenStorage<T>`        | Immutable content-addressed entries   | Write once; identified by hash                    |
+| `UserStorage<T>`          | Per-member private storage            | NOT synced to other members                       |
+| `ReplicatedGrowableArray` | Collaborative text / ordered sequence | For collaborative editing                         |
+
+---
+
+## Rust import
+
+```rust
+use calimero_storage::collections::{
+    Counter, FrozenStorage, LwwRegister, ReplicatedGrowableArray,
+    UnorderedMap, UnorderedSet, UserStorage, Vector,
+};
+```
+
+> **Critical:** Do NOT use `calimero_sdk::state::*` — that path no longer exists.
+
+---
+
+## Common patterns
+
+### Key-value store
+
+```rust
+items: UnorderedMap<String, LwwRegister<String>>,
+
+// Write
+self.items.insert(key, LwwRegister::new(value))?;
+
+// In-place update (no clone needed)
+if let Some(mut guard) = self.items.get_mut(&key)? {
+    guard.set(new_value);
+}
+
+// Read
+let val = self.items.get(&key)?.map(|v| v.get().clone());
+```
+
+### Append-only log
+
+```rust
+log: Vector<String>,
+
+self.log.push(entry)?;
+let all: Vec<String> = self.log.iter()?.collect();
+```
+
+### Counter
+
+```rust
+counter: Counter,
+
+self.counter.increment()?;
+let n = self.counter.value()?;
+```
+
+### Per-member private data (not synced)
+
+```rust
+notes: UserStorage<String>,
+
+self.notes.set("my private note".to_string())?;
+let note = self.notes.get()?;
+```
+
+---
+
+## TypeScript (SDK JS) equivalents
+
+The JS SDK provides equivalent CRDT types:
+
+```typescript
+import { UnorderedMap, Vector, Counter } from '@calimero-network/calimero-sdk-js/collections';
+
+@State
+class AppState {
+  items: UnorderedMap<string, string> = new UnorderedMap();
+  log: Vector<string> = new Vector();
+  counter: Counter = new Counter();
+}
+```
+
+JS state fields must also be CRDT types — no plain `Map`, `Set`, or `Array`.
+
+---
+
+## Rules
+
+1. **Never use `std::collections` for shared state.** `HashMap`, `BTreeMap`, `Vec`, `HashSet` are
+   not CRDTs and will cause data loss on concurrent writes.
+2. **All collection operations are fallible in Rust.** Always use `?` to propagate errors.
+3. **`FrozenStorage` is write-once.** Use it for immutable content (images, blobs) that are
+   identified by hash.
+4. **`UserStorage` is per-member.** Only the local member can read/write it — it is never synced.