@calimero-network/agent-skills 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calimero-network/agent-skills",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AI agent skills for Calimero Network development — Rust SDK, JS client, registry publishing, desktop SSO, and more.",
   "keywords": [
     "calimero",

package/skills/calimero-client-js/SKILL.md

@@ -33,10 +33,53 @@ pnpm add @calimero-network/mero-js
 
 ## Core workflow
 
-1. Read auth tokens (from URL hash if opened by Desktop, otherwise prompt login)
-2. Initialize client with `node_url` + tokens
-3. Call app methods via JSON-RPC
-4. Subscribe to events via WebSocket
+1. On startup: read SSO tokens from URL hash (if opened by Desktop), otherwise check `localStorage` for existing session, otherwise show login
+2. Store tokens using the provided storage helpers (`setAppEndpointKey`, `setAccessToken`, etc.)
+3. Call app methods via the `rpcClient` singleton using `rpcClient.execute()`
+4. Subscribe to events via `WsSubscriptionsClient`
+
+## Minimal working example
+
+```typescript
+import {
+  rpcClient,
+  getContextId,
+  getExecutorPublicKey,
+  getAppEndpointKey,
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setContextAndIdentityFromJWT,
+  WsSubscriptionsClient,
+} from '@calimero-network/calimero-client';
+
+// 1. Store auth tokens (after SSO or login)
+setAppEndpointKey('http://localhost:2428');
+setAccessToken(accessToken);
+setRefreshToken(refreshToken);
+setContextAndIdentityFromJWT(accessToken); // extracts contextId + executorPublicKey
+
+// 2. Call an app method
+const response = await rpcClient.execute<{ key: string }, string | null>({
+  contextId: getContextId()!,
+  method: 'get',
+  argsJson: { key: 'hello' },
+  executorPublicKey: getExecutorPublicKey()!,
+});
+console.log(response.result?.output);
+
+// 3. Subscribe to real-time events
+const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
+await ws.connect();
+ws.subscribe([getContextId()!]);
+ws.addCallback((event) => {
+  if (event.type === 'ExecutionEvent') {
+    for (const e of event.data.events) {
+      console.log(e.kind, e.data);
+    }
+  }
+});
+```
 
 ## References
 

package/skills/calimero-client-js/references/auth.md

@@ -1,58 +1,163 @@
 # Authentication
 
-## Login flow
+## Storage helpers
+
+`@calimero-network/calimero-client` provides these storage functions (backed by `localStorage`):
 
 ```typescript
-import { setupWalletSelector } from '@near-wallet-selector/core';
-import { ClientLogin } from '@calimero-network/calimero-client';
-
-const client = new ClientLogin({ nodeUrl: 'http://localhost:2428' });
-
-// 1. Generate a client key for this device
-const { contextId, contextIdentity } = await client.generateClientKey({
-  contextId: 'your-context-id',
-  contextIdentity: 'your-identity',
-});
-
-// 2. Login — returns access_token + refresh_token
-const tokens = await client.login({
-  contextId,
-  contextIdentity,
-});
-
-// 3. Store tokens
-localStorage.setItem('access_token', tokens.access_token);
-localStorage.setItem('refresh_token', tokens.refresh_token);
+import {
+  // Node URL
+  setAppEndpointKey,
+  getAppEndpointKey,
+  // JWT tokens
+  setAccessToken,
+  getAccessToken,
+  setRefreshToken,
+  getRefreshToken,
+  // Context and identity (extracted from JWT)
+  setContextId,
+  getContextId,
+  setExecutorPublicKey,
+  getExecutorPublicKey,
+  setContextAndIdentityFromJWT,  // extracts + stores contextId + executorPublicKey from JWT
+  // App ID
+  setApplicationId,
+  getApplicationId,
+  // Auth endpoint (separate from node URL)
+  setAuthEndpointURL,
+  getAuthEndpointURL,
+  // Decoded JWT payload
+  getJWTObject,     // returns { context_id, context_identity, exp, permissions, ... }
+  // Full auth config (throws if required fields are missing)
+  getAuthConfig,    // returns { appEndpointKey, contextId, executorPublicKey, jwtToken }
+  // Logout (clears all tokens + reloads)
+  clientLogout,
+} from '@calimero-network/calimero-client';
 ```
 
-## Token storage
+---
+
+## SSO login (from Calimero Desktop — recommended path)
 
-Tokens should be stored in `localStorage` or `sessionStorage`. The client library reads
-them automatically if you use the provided storage helpers:
+When the app is opened by Desktop, tokens arrive in the URL hash. Store them:
 
 ```typescript
-import { getStorageAppEndpointKey, getJWTObject } from '@calimero-network/calimero-client';
+function initFromDesktopSSO(): boolean {
+  const hash = new URLSearchParams(window.location.hash.slice(1));
+  const accessToken  = hash.get('access_token');
+  const refreshToken = hash.get('refresh_token');
+  const nodeUrl      = hash.get('node_url');
+  const appId        = hash.get('application_id');
 
-const nodeUrl = getStorageAppEndpointKey();
-const jwt = getJWTObject();
-// jwt.access_token, jwt.refresh_token
+  if (!accessToken || !nodeUrl) return false;
+
+  // Store everything
+  setAppEndpointKey(nodeUrl);
+  setAccessToken(accessToken);
+  if (refreshToken) setRefreshToken(refreshToken);
+  if (appId) setApplicationId(appId);
+
+  // Extract contextId and executorPublicKey from JWT claims
+  setContextAndIdentityFromJWT(accessToken);
+
+  // Remove tokens from URL bar (don't let them sit in browser history)
+  history.replaceState(null, '', window.location.pathname + window.location.search);
+
+  return true;
+}
 ```
 
-## Checking auth status
+---
+
+## Manual login (no Desktop)
 
 ```typescript
-import { getJWTObject } from '@calimero-network/calimero-client';
+import { setAppEndpointKey, setAccessToken, setRefreshToken, setContextAndIdentityFromJWT } from '@calimero-network/calimero-client';
 
-function isLoggedIn(): boolean {
-  const jwt = getJWTObject();
-  return !!(jwt?.access_token);
+async function login(nodeUrl: string, accessToken: string, refreshToken: string) {
+  setAppEndpointKey(nodeUrl);
+  setAccessToken(accessToken);
+  setRefreshToken(refreshToken);
+  setContextAndIdentityFromJWT(accessToken);
 }
 ```
 
+---
+
+## Checking if authenticated
+
+```typescript
+import { getAuthConfig } from '@calimero-network/calimero-client';
+
+function isAuthenticated(): boolean {
+  const config = getAuthConfig();
+  return config.error === null;
+}
+```
+
+---
+
+## Reading the JWT payload
+
+```typescript
+import { getJWTObject } from '@calimero-network/calimero-client';
+
+const jwt = getJWTObject();
+// jwt.context_id        — the context this token is scoped to
+// jwt.context_identity  — the identity (executor public key)
+// jwt.exp               — expiry timestamp (seconds)
+// jwt.permissions       — array of permission strings
+```
+
+---
+
 ## Logout
 
 ```typescript
-localStorage.removeItem('calimero_jwt');
-localStorage.removeItem('calimero_node_url');
-// redirect to login
+import { clientLogout } from '@calimero-network/calimero-client';
+
+// Clears all tokens from localStorage and reloads the page
+clientLogout();
+```
+
+---
+
+## App startup pattern (SSO + fallback)
+
+```typescript
+import {
+  setAppEndpointKey, setAccessToken, setRefreshToken,
+  setApplicationId, setContextAndIdentityFromJWT,
+  getAuthConfig,
+} from '@calimero-network/calimero-client';
+
+async function bootstrap() {
+  // Try SSO from Desktop hash
+  const hash = new URLSearchParams(window.location.hash.slice(1));
+  const accessToken = hash.get('access_token');
+  const nodeUrl     = hash.get('node_url');
+
+  if (accessToken && nodeUrl) {
+    setAppEndpointKey(nodeUrl);
+    setAccessToken(accessToken);
+    const rt = hash.get('refresh_token');
+    if (rt) setRefreshToken(rt);
+    const appId = hash.get('application_id');
+    if (appId) setApplicationId(appId);
+    setContextAndIdentityFromJWT(accessToken);
+    history.replaceState(null, '', window.location.pathname);
+    renderApp();
+    return;
+  }
+
+  // Check if already authenticated from a previous session
+  const config = getAuthConfig();
+  if (config.error === null) {
+    renderApp();
+    return;
+  }
+
+  // Not authenticated — show manual login
+  renderLogin();
+}
 ```

package/skills/calimero-client-js/references/rpc-calls.md

@@ -2,74 +2,165 @@
 
 Calling application methods on a Calimero node.
 
-## Setup
+## The `rpcClient` singleton
+
+`@calimero-network/calimero-client` exports a pre-configured `rpcClient` singleton.
+Import it directly — do not construct `JsonRpcClient` manually.
 
 ```typescript
 import {
-  JsonRpcClient,
-  getStorageAppEndpointKey,
-  getJWTObject,
+  rpcClient,
+  getContextId,
+  getExecutorPublicKey,
 } from '@calimero-network/calimero-client';
+```
+
+---
+
+## Execute a method (mutation or view — same call)
 
-const nodeUrl = getStorageAppEndpointKey() ?? 'http://localhost:2428';
-const jwt = getJWTObject();
+```typescript
+const response = await rpcClient.execute<ArgsType, OutputType>({
+  contextId: getContextId()!,
+  method: 'methodName',
+  argsJson: { /* your args */ },
+  executorPublicKey: getExecutorPublicKey()!,
+});
 
-const client = new JsonRpcClient(nodeUrl, '/jsonrpc', jwt?.access_token);
+if (response.error) {
+  console.error(response.error.error.cause.info?.message);
+} else {
+  console.log(response.result?.output);
+}
 ```
 
+---
+
 ## Calling a mutation (changes state)
 
 ```typescript
-const response = await client.mutate<{ key: string; value: string }, void>({
-  contextId: 'your-context-id',
+const response = await rpcClient.execute<{ key: string; value: string }, void>({
+  contextId: getContextId()!,
   method: 'set',
   argsJson: { key: 'hello', value: 'world' },
-  executorPublicKey: jwt?.executor_public_key ?? '',
+  executorPublicKey: getExecutorPublicKey()!,
 });
 
 if (response.error) {
-  console.error(response.error);
+  console.error('set failed:', response.error.error.cause.info?.message);
 }
 ```
 
 ## Calling a view (read-only)
 
 ```typescript
-const response = await client.query<{ key: string }, string | null>({
-  contextId: 'your-context-id',
+const response = await rpcClient.execute<{ key: string }, string | null>({
+  contextId: getContextId()!,
   method: 'get',
   argsJson: { key: 'hello' },
-  executorPublicKey: jwt?.executor_public_key ?? '',
+  executorPublicKey: getExecutorPublicKey()!,
 });
 
-console.log(response.result?.output); // "world"
+if (!response.error) {
+  console.log(response.result?.output); // "world"
+}
 ```
 
+---
+
 ## Response shape
 
 ```typescript
-interface RpcResponse<T> {
-  result?: {
-    output: T;
-  };
-  error?: {
-    code: number;
-    message: string;
-  };
+// Success:
+{ result: { output: T } }
+
+// Error:
+{
+  error: {
+    id: number;
+    jsonrpc: string;
+    code: number;                  // HTTP-like code (400, 401, 500)
+    error: {
+      name: string;                // e.g. "FunctionCallError"
+      cause: {
+        name: string;
+        info?: { message: string };
+      };
+    };
+    headers?: Record<string, string>;
+  }
 }
 ```
 
-## Error handling
+---
+
+## Error names
+
+| name | meaning |
+|---|---|
+| `FunctionCallError` | App method returned an error |
+| `RpcExecutionError` | Node couldn't execute the method |
+| `InvalidRequestError` | Malformed request (wrong context-id, missing args) |
+| `AuthenticationError` | JWT expired, revoked, or missing |
+| `UnknownServerError` | Unexpected server error |
+
+---
+
+## Error handling with 401
+
+The HTTP client inside `rpcClient` automatically refreshes tokens on `401 token_expired`.
+For `token_revoked` or `invalid_token` you need to re-authenticate:
 
 ```typescript
-const response = await client.query({ ... });
+const response = await rpcClient.execute({ ... });
 
 if (response.error) {
-  if (response.error.code === 401) {
-    // token expired — refresh and retry
-    await refreshTokens();
-    return callAgain();
+  const { code, headers } = response.error;
+  const authError = headers?.['x-auth-error'];
+
+  if (code === 401 && (authError === 'token_revoked' || authError === 'invalid_token')) {
+    // Token cannot be refreshed — send user to login
+    clientLogout();
+    return;
+  }
+
+  throw new Error(response.error.error.cause.info?.message ?? 'Unknown error');
+}
+```
+
+---
+
+## Complete example: typed wrapper
+
+```typescript
+import {
+  rpcClient,
+  getContextId,
+  getExecutorPublicKey,
+} from '@calimero-network/calimero-client';
+
+async function setItem(key: string, value: string): Promise<void> {
+  const response = await rpcClient.execute<{ key: string; value: string }, void>({
+    contextId: getContextId()!,
+    method: 'set',
+    argsJson: { key, value },
+    executorPublicKey: getExecutorPublicKey()!,
+  });
+  if (response.error) {
+    throw new Error(response.error.error.cause.info?.message);
+  }
+}
+
+async function getItem(key: string): Promise<string | null> {
+  const response = await rpcClient.execute<{ key: string }, string | null>({
+    contextId: getContextId()!,
+    method: 'get',
+    argsJson: { key },
+    executorPublicKey: getExecutorPublicKey()!,
+  });
+  if (response.error) {
+    throw new Error(response.error.error.cause.info?.message);
   }
-  throw new Error(response.error.message);
+  return response.result?.output ?? null;
 }
 ```

package/skills/calimero-client-js/references/sso.md

@@ -34,18 +34,29 @@ function readSSOParams(): {
 
 ## Using SSO tokens on app startup
 
+Use the storage helpers from `@calimero-network/calimero-client`:
+
 ```typescript
+import {
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setApplicationId,
+  setContextAndIdentityFromJWT,
+} from '@calimero-network/calimero-client';
+
 async function initApp() {
   const sso = readSSOParams();
 
   if (sso.accessToken && sso.nodeUrl) {
     // Opened from Desktop — store tokens and skip login
-    localStorage.setItem('calimero_node_url', sso.nodeUrl);
-    localStorage.setItem('calimero_jwt', JSON.stringify({
-      access_token: sso.accessToken,
-      refresh_token: sso.refreshToken,
-    }));
-    // clear hash so tokens aren't in browser history
+    setAppEndpointKey(sso.nodeUrl);
+    setAccessToken(sso.accessToken);
+    if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+    if (sso.applicationId) setApplicationId(sso.applicationId);
+    // Extract contextId + executorPublicKey from the JWT claims
+    setContextAndIdentityFromJWT(sso.accessToken);
+    // Clear hash so tokens aren't in browser history
     history.replaceState(null, '', window.location.pathname);
     renderApp();
   } else {
@@ -55,12 +66,6 @@ async function initApp() {
 }
 ```
 
-## calimero-client reads hash automatically
-
-If you use `@calimero-network/calimero-client`'s built-in auth helpers, the library
-reads `window.location.hash` automatically and stores the tokens. You don't need the
-manual parsing above unless you're building a custom auth flow.
-
 ## Important
 
 Always fall back to manual login if the hash params are absent — the app must work

package/skills/calimero-client-js/references/websocket-events.md

@@ -2,65 +2,125 @@
 
 Subscribe to real-time events emitted by the application running on the node.
 
-## Connect and subscribe
+## Event types
 
-```typescript
-import { WsSubscriptionsClient } from '@calimero-network/calimero-client';
+The node sends two kinds of events to subscribers:
+
+| type | when | payload |
+|---|---|---|
+| `StateMutation` | Another member mutated shared state | `{ newRoot: string }` |
+| `ExecutionEvent` | App emitted `app::emit!()` | `{ events: ExecutionEvent[] }` |
 
-const nodeUrl = getStorageAppEndpointKey() ?? 'http://localhost:2428';
-const jwt = getJWTObject();
+An `ExecutionEvent` has: `{ kind: string; data: any }` where `kind` matches the Rust event variant name.
 
-const ws = new WsSubscriptionsClient(nodeUrl, '/ws', jwt?.access_token);
+---
+
+## Connect and subscribe
 
-ws.subscribe([contextId], (event) => {
+```typescript
+import {
+  WsSubscriptionsClient,
+  getAppEndpointKey,
+  getContextId,
+} from '@calimero-network/calimero-client';
+
+const nodeUrl = getAppEndpointKey()!;
+const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
+
+// Connect first, then subscribe and add callback
+await ws.connect();
+ws.subscribe([getContextId()!]);
+ws.addCallback((event) => {
   console.log('Event received:', event);
-  // event.data contains the serialized app event payload
 });
 ```
 
-## Handling specific event types
+---
 
-```typescript
-interface AppEvent {
-  type: 'ItemAdded' | 'ItemRemoved' | 'MemberJoined';
-  key?: string;
-  value?: string;
-  identity?: string;
-}
+## Handling ExecutionEvents from app logic
 
-ws.subscribe([contextId], (event) => {
-  const appEvent = event.data as AppEvent;
+```typescript
+import type {
+  NodeEvent,
+  ExecutionEventPayload,
+  StateMutationPayload,
+} from '@calimero-network/calimero-client';
+
+ws.addCallback((event: NodeEvent) => {
+  if (event.type === 'ExecutionEvent') {
+    for (const e of event.data.events) {
+      // e.kind matches the Rust event variant name, e.g. 'ItemAdded'
+      // e.data contains the event payload
+      switch (e.kind) {
+        case 'ItemAdded':
+          console.log('Item added:', e.data);
+          addItemToUI(e.data.key, e.data.value);
+          break;
+        case 'ItemRemoved':
+          removeItemFromUI(e.data.key);
+          break;
+      }
+    }
+  }
 
-  switch (appEvent.type) {
-    case 'ItemAdded':
-      addItemToUI(appEvent.key!, appEvent.value!);
-      break;
-    case 'ItemRemoved':
-      removeItemFromUI(appEvent.key!);
-      break;
+  if (event.type === 'StateMutation') {
+    // Another member changed shared state — refresh data from node
+    console.log('State root changed:', event.data.newRoot);
+    refreshDataFromNode();
   }
 });
 ```
 
+---
+
+## Subscribe to multiple contexts
+
+```typescript
+ws.subscribe([contextId1, contextId2]);
+// Events include event.contextId to identify which context emitted them
+```
+
+---
+
 ## Cleanup
 
 ```typescript
-// Unsubscribe when component unmounts
+// Remove a specific callback
+ws.removeCallback(myCallback);
+
+// Unsubscribe from specific contexts
 ws.unsubscribe([contextId]);
 
-// Or close connection entirely
-ws.close();
+// Close connection entirely
+ws.disconnect();
 ```
 
+---
+
 ## React hook pattern
 
 ```typescript
-useEffect(() => {
-  const ws = new WsSubscriptionsClient(nodeUrl, '/ws', token);
-  ws.subscribe([contextId], handleEvent);
-
-  return () => {
-    ws.unsubscribe([contextId]);
-  };
-}, [contextId, token]);
+import { useEffect } from 'react';
+import { WsSubscriptionsClient, getAppEndpointKey, getContextId } from '@calimero-network/calimero-client';
+
+function useNodeEvents(onEvent: (event: NodeEvent) => void) {
+  useEffect(() => {
+    const nodeUrl = getAppEndpointKey();
+    const contextId = getContextId();
+    if (!nodeUrl || !contextId) return;
+
+    const ws = new WsSubscriptionsClient(nodeUrl, '/ws');
+
+    ws.connect().then(() => {
+      ws.subscribe([contextId]);
+      ws.addCallback(onEvent);
+    });
+
+    return () => {
+      ws.removeCallback(onEvent);
+      ws.unsubscribe([contextId]);
+      ws.disconnect();
+    };
+  }, [onEvent]);
+}
 ```

package/skills/calimero-node/SKILL.md

@@ -10,25 +10,63 @@ You are helping a developer manage a **Calimero node** using `merod` and `meroct
 - **Application** — the WASM code; one app can power many contexts
 - Installing an app and creating a context are two separate steps
 
-## Quick reference
+## Node setup (first time)
 
 ```bash
-# Start a node
+# Initialize node configuration
+merod --home ~/.calimero init
+
+# Start the node
 merod --home ~/.calimero run
+# Node listens on http://localhost:2428 by default
+```
+
+## Complete workflow: app → context → call
+
+```bash
+# 1. Install an app
+meroctl --node-url http://localhost:2428 app install \
+  --path myapp.mpk
+# → prints app-id
+
+# 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
+
+# 3. Call a mutation (changes state)
+meroctl --node-url http://localhost:2428 call <context-id> set \
+  --args '{"key":"hello","value":"world"}'
 
-# Install an app from a .mpk bundle
-meroctl --node-url http://localhost:2428 app install --path myapp.mpk
+# 4. Call a view (read-only)
+meroctl --node-url http://localhost:2428 call <context-id> get \
+  --args '{"key":"hello"}' --view
 
-# Create a context (instance of an app)
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# 5. Check node is running
+meroctl --node-url http://localhost:2428 node health
+```
+
+## Multi-node context (invite + join)
 
-# List contexts
-meroctl --node-url http://localhost:2428 context ls
+```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)
 
-# Call a method
-meroctl --node-url http://localhost:2428 call <context-id> <method> --args '{"key":"value"}'
+# 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
+```
+
+## Global flags
+
+```bash
+meroctl --node-url http://localhost:2428 <command>   # connect to specific node
+meroctl --home ~/.calimero <command>                  # use alternate config path
 ```
 
 ## References
 
-See `references/` for node setup, full meroctl command reference, and context lifecycle.
+See `references/` for full meroctl command reference and context lifecycle.

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

@@ -5,76 +5,179 @@ Full CLI for managing a running Calimero node.
 ## Global flags
 
 ```bash
-meroctl --node-url http://localhost:2428 <command>
-meroctl --home ~/.calimero <command>   # alternate config path
+meroctl --node-url http://localhost:2428 <command>   # connect to specific node
+meroctl --home ~/.calimero <command>                  # alternate config path
 ```
 
+---
+
+## Node commands
+
+```bash
+# Check node health (returns "alive" when running)
+meroctl --node-url http://localhost:2428 node health
+```
+
+---
+
 ## App commands
 
 ```bash
-# Install app from bundle
-meroctl app install --path myapp.mpk
+# 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 registry
-meroctl app install --url https://registry.calimero.network/myapp/1.0.0
+# Install app from registry URL
+meroctl --node-url http://localhost:2428 app install \
+  --url https://registry.calimero.network/com.yourorg.myapp/1.0.0
 
 # List installed apps
-meroctl app ls
+meroctl --node-url http://localhost:2428 app ls
 
-# Get app details
-meroctl app get <app-id>
+# Get details of a specific app
+meroctl --node-url http://localhost:2428 app get <app-id>
 
-# Remove app (only if no contexts use it)
-meroctl app remove <app-id>
+# Remove an app (only works if no active contexts reference it)
+meroctl --node-url http://localhost:2428 app remove <app-id>
 ```
 
+---
+
 ## Context commands
 
 ```bash
-# Create context (instance of an app)
-meroctl context create --app-id <app-id>
+# Create a context (instantiates the app — calls init())
+meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# Returns: context-id
+
+# List all contexts on this node
+meroctl --node-url http://localhost:2428 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>
+
+# List members of a context
+meroctl --node-url http://localhost:2428 context members <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
+```
 
-# List contexts
-meroctl context ls
+---
 
-# Get context info
-meroctl context get <context-id>
+## Calling app methods
 
-# Delete context
-meroctl context delete <context-id>
+```bash
+# Mutation — changes shared state (no --view flag)
+meroctl --node-url http://localhost:2428 call <context-id> <method> \
+  --args '{"key":"hello","value":"world"}'
 
-# Invite a member (generates invitation payload)
-meroctl context invite <context-id> --identity <identity>
+# View — read-only, does NOT change state
+meroctl --node-url http://localhost:2428 call <context-id> <method> \
+  --args '{"key":"hello"}' --view
 
-# Join a context (accepts an invitation)
-meroctl context join --invitation <invitation-payload>
+# Method with no arguments
+meroctl --node-url http://localhost:2428 call <context-id> list_all \
+  --args '{}' --view
 ```
 
+---
+
 ## Identity commands
 
 ```bash
-# Create a new identity
-meroctl identity create
+# Create a new identity (root keypair for this node)
+meroctl --node-url http://localhost:2428 identity create
 
-# List identities
-meroctl identity ls
+# List all identities on this node
+meroctl --node-url http://localhost:2428 identity ls
 
-# Get identity details
-meroctl identity get <identity>
+# Get details of a specific identity
+meroctl --node-url http://localhost:2428 identity get <identity>
 ```
 
-## Calling app methods
+---
+
+## Step-by-step: full local development flow
 
 ```bash
-# Mutation (changes state)
-meroctl call <context-id> set --args '{"key":"hello","value":"world"}'
+# 1. Build the WASM app
+cargo build --target wasm32-unknown-unknown --release
+
+# 2. Start the node (in a separate terminal)
+merod --home ~/.calimero run
+
+# 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
 
-# View (read-only)
-meroctl call <context-id> get --args '{"key":"hello"}' --view
+# 4. Create a context
+meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# Copy the context-id from output
+
+# 5. Interact with the app
+meroctl --node-url http://localhost:2428 call <context-id> set \
+  --args '{"key":"foo","value":"bar"}'
+
+meroctl --node-url http://localhost:2428 call <context-id> get \
+  --args '{"key":"foo"}' --view
 ```
 
-## Node health
+---
+
+## Step-by-step: multi-node context sharing
 
 ```bash
-meroctl node health
+# ── 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>
+
+# 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)
 ```

package/skills/calimero-rust-sdk/SKILL.md

@@ -12,19 +12,14 @@ You are helping a developer build a **Calimero WASM application** in Rust using
 - Private storage is per-member and isolated; shared state syncs across all members
 - There is no `main()` — the SDK provides the entry point
 
-## Crate to add
+## Cargo.toml setup
 
-```toml
-[dependencies]
-calimero-sdk = { path = "..." }
-# or from crates.io once published:
-calimero-sdk = "0.x"
-```
-
-Also add to `Cargo.toml`:
 ```toml
 [lib]
 crate-type = ["cdylib"]
+
+[dependencies]
+calimero-sdk = "0.x"
 ```
 
 ## Minimal app skeleton
@@ -32,10 +27,11 @@ crate-type = ["cdylib"]
 ```rust
 use calimero_sdk::app;
 use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+use calimero_sdk::state::UnorderedMap;
 
 #[derive(Default, BorshDeserialize, BorshSerialize)]
 pub struct AppState {
-    // use CRDT collections here
+    items: UnorderedMap<String, String>,
 }
 
 #[app::state]
@@ -48,24 +44,66 @@ impl AppState {
         AppState::default()
     }
 
-    pub fn my_mutation(&mut self, value: String) -> Result<(), String> {
-        // mutate state
+    pub fn set(&mut self, key: String, value: String) -> Result<(), String> {
+        self.items.insert(key, value);
         Ok(())
     }
 
-    pub fn my_view(&self) -> String {
-        // read-only
-        String::new()
+    pub fn get(&self, key: String) -> Option<String> {
+        self.items.get(&key).cloned()
     }
 }
 ```
 
+## Building
+
+```bash
+# Add WASM target (one-time)
+rustup target add wasm32-unknown-unknown
+
+# Build
+cargo build --target wasm32-unknown-unknown --release
+
+# Output: target/wasm32-unknown-unknown/release/<crate_name>.wasm
+```
+
+## Installing and running on a node (dev workflow)
+
+```bash
+# 1. Install app from WASM file
+meroctl --node-url http://localhost:2428 app install \
+  --path target/wasm32-unknown-unknown/release/myapp.wasm
+# Returns: app-id
+
+# 2. Create a context (instance of the app)
+meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# Returns: context-id
+
+# 3. Call a method
+meroctl --node-url http://localhost:2428 call <context-id> set \
+  --args '{"key":"hello","value":"world"}'
+
+# 4. Call a view
+meroctl --node-url http://localhost:2428 call <context-id> get \
+  --args '{"key":"hello"}' --view
+```
+
 ## Key rules
 
 - State struct **must** derive `Default`, `BorshDeserialize`, `BorshSerialize`
 - Never use `HashMap`, `Vec`, `BTreeMap` directly for state — use CRDT collections
 - No blocking I/O, no threads, no `async` in app logic
-- Use `calimero_sdk::env::log()` not `println!`
+- Use `calimero_sdk::env::log!()` not `println!`
+- Mutations use `&mut self`, views use `&self`
+
+## Logging
+
+```rust
+use calimero_sdk::env;
+
+// Inside any app method:
+env::log!("Processing key: {}", key);
+```
 
 ## References