@calimero-network/agent-skills 0.2.0 → 0.3.0

package/SKILL.md

@@ -6,8 +6,9 @@ This package provides AI agent skills for building on the Calimero Network stack
 
 | Skill | Install command | When to use |
 | --- | --- | --- |
-| `calimero-rust-sdk` | `npx @calimero-network/agent-skills calimero-rust-sdk` | Building Rust WASM applications |
-| `calimero-client-js` | `npx @calimero-network/agent-skills calimero-client-js` | Frontend / Node.js clients connecting to a node |
+| `calimero-rust-sdk` | `npx @calimero-network/agent-skills calimero-rust-sdk` | Building Rust WASM applications that run on a node |
+| `calimero-sdk-js` | `npx @calimero-network/agent-skills calimero-sdk-js` | Building TypeScript/JS WASM applications that run on a node |
+| `calimero-client-js` | `npx @calimero-network/agent-skills calimero-client-js` | Browser/Node.js frontends connecting to a node (not building apps) |
 | `calimero-registry` | `npx @calimero-network/agent-skills calimero-registry` | Signing and publishing apps to the registry |
 | `calimero-desktop` | `npx @calimero-network/agent-skills calimero-desktop` | Integrating apps with Calimero Desktop SSO |
 | `calimero-node` | `npx @calimero-network/agent-skills calimero-node` | Node operators and meroctl scripting |
@@ -22,11 +23,15 @@ Skills should be loaded when the following are detected in the project:
 | Signal | Load skill |
 | --- | --- |
 | `calimero-sdk` in `Cargo.toml` | `calimero-rust-sdk` |
+| `@calimero-network/calimero-sdk-js` in `package.json` | `calimero-sdk-js` |
+| `@State` / `@Logic` decorators in TypeScript source | `calimero-sdk-js` |
+| `calimero-sdk build` in any script | `calimero-sdk-js` |
 | `@calimero-network/calimero-client` in `package.json` | `calimero-client-js` |
 | `@calimero-network/mero-js` in `package.json` | `calimero-client-js` |
 | `mero-sign` in any script or Makefile | `calimero-registry` |
 | `calimero-registry` CLI usage | `calimero-registry` |
 | `access_token` read from `window.location.hash` | `calimero-desktop` |
+| `readDesktopSSO` / `hash.get('access_token')` pattern in frontend code | `calimero-desktop` |
 | `merobox` in `package.json` or `requirements.txt` | `calimero-merobox` |
 | `calimero-client-py` in `requirements.txt` or `pyproject.toml` | `calimero-client-py` |
 | `calimero-abi-codegen` or `abi.json` in project | `calimero-abi-codegen` |

package/package.json

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

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

@@ -1,6 +1,12 @@
 # calimero-client-js — Agent Instructions
 
-You are helping a developer connect a **browser or Node.js frontend** to a Calimero node using `@calimero-network/calimero-client` or `@calimero-network/mero-js`.
+You are helping a developer connect a **browser or Node.js frontend** to a Calimero node
+using `@calimero-network/calimero-client` or `@calimero-network/mero-js`.
+
+> **NOT this skill** if the developer is building the application logic that *runs on the
+> node* in TypeScript — that is `calimero-sdk-js` (`@calimero-network/calimero-sdk-js`).
+> This skill is for the *client* side: auth, RPC calls, and WebSocket subscriptions from
+> a browser or backend service.
 
 ## Package versions
 
@@ -9,6 +15,10 @@ You are helping a developer connect a **browser or Node.js frontend** to a Calim
 | `@calimero-network/calimero-client` | latest | Stable client for browser/Node — auth, RPC, WebSocket |
 | `@calimero-network/mero-js` | `>=2.0.0-beta.1` | v2 API — all request fields are **camelCase** |
 
+**Which to use:** new projects should prefer `@calimero-network/mero-js` v2. If you are
+maintaining an existing codebase that uses `calimero-client`, check for snake_case field
+names before migrating — do not mix both packages in the same project.
+
 ## Critical: mero-js v2 uses camelCase
 
 v2 changed all request field names from `snake_case` to `camelCase`.

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

@@ -97,6 +97,39 @@ ws.disconnect();
 
 ---
 
+## Connection errors and reconnection
+
+`WsSubscriptionsClient` does **not** reconnect automatically. If the connection drops
+or the initial connect fails, you must retry manually.
+
+```typescript
+async function connectWithRetry(ws: WsSubscriptionsClient, contextId: string, retries = 3): Promise<void> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      await ws.connect();
+      ws.subscribe([contextId]);
+      return;
+    } catch (err: any) {
+      if (err?.status === 401) {
+        // Token expired — cannot reconnect until re-authenticated
+        clientLogout();
+        return;
+      }
+      if (i === retries - 1) throw err;
+      await new Promise(r => setTimeout(r, 1000 * (i + 1))); // exponential backoff
+    }
+  }
+}
+```
+
+To detect drops after the connection is established, check if events stop arriving and
+reconnect periodically, or listen to `ws.onClose` if exposed.
+
+> WebSocket tokens are **not** auto-refreshed unlike `rpcClient` RPC calls.
+> See `rules/token-refresh.md` for details.
+
+---
+
 ## React hook pattern
 
 ```typescript

package/skills/calimero-client-js/rules/token-refresh.md

@@ -1,41 +1,79 @@
-# Rule: Always handle 401 with token refresh
+# Rule: rpcClient handles token refresh automatically — but not all 401s
 
-Access tokens expire. Any RPC call or WebSocket connection can return `401 Unauthorized`. Never let this surface as an unhandled error.
+`rpcClient` (from `@calimero-network/calimero-client`) automatically retries with a
+refreshed token when the server returns `401 token_expired`. **You do not need to
+implement a refresh wrapper around `rpcClient.execute()` calls.**
 
-## Pattern
+What you DO need to handle: 401s that cannot be refreshed.
+
+## WRONG — manual refresh wrapper (not needed for rpcClient):
 
 ```typescript
-async function callWithRefresh<T>(callFn: () => Promise<T>): Promise<T> {
+// ✗ Don't do this — rpcClient already retries on token_expired
+async function callWithRefresh<T>(fn: () => Promise<T>) {
   try {
-    return await callFn();
+    return await fn();
   } catch (err: any) {
-    if (err?.code === 401 || err?.status === 401) {
-      await refreshAccessToken();
-      return callFn(); // retry once
+    if (err?.code === 401) {
+      await refreshAccessToken(); // rpcClient already does this
+      return fn();
     }
     throw err;
   }
 }
+```
+
+## CORRECT — handle only non-refreshable auth failures:
+
+```typescript
+const response = await rpcClient.execute({ ... });
+
+if (response.error) {
+  const authError = response.error.headers?.['x-auth-error'];
 
-async function refreshAccessToken() {
-  const jwt = getJWTObject();
-  if (!jwt?.refresh_token) {
-    // No refresh token — redirect to login
-    window.location.href = '/login';
+  if (response.error.code === 401) {
+    if (authError === 'token_revoked' || authError === 'invalid_token') {
+      // Token is invalid — cannot be refreshed. Send user to login.
+      clientLogout();
+      return;
+    }
+    // token_expired: rpcClient already retried and the retry failed.
+    // This means the refresh token is also expired — send to login.
+    clientLogout();
     return;
   }
 
-  const newTokens = await client.refreshToken(jwt.refresh_token);
-  localStorage.setItem('calimero_jwt', JSON.stringify(newTokens));
+  throw new Error(response.error.error.cause.info?.message ?? 'Unknown error');
 }
 ```
 
-## Why
+## WebSocket connections are different — no auto-refresh
+
+`WsSubscriptionsClient` does **not** auto-refresh tokens. If the token expires while
+a WebSocket connection is open, events will stop arriving silently. Reconnect manually:
 
-Access tokens are short-lived by design. Without refresh handling, users will see
-random authentication errors mid-session. The refresh token is longer-lived and
-should be used to silently re-authenticate.
+```typescript
+async function connectWithAuth() {
+  const ws = new WsSubscriptionsClient(getAppEndpointKey()!, '/ws');
+  try {
+    await ws.connect();
+    ws.subscribe([getContextId()!]);
+    ws.addCallback(handleEvent);
+  } catch (err: any) {
+    if (err?.status === 401) {
+      // Token expired before WS connect — logout and re-authenticate
+      clientLogout();
+    }
+    throw err;
+  }
+}
+```
 
-## What to do if refresh also fails
+## Summary
 
-Redirect to login. Do not retry the refresh indefinitely.
+| Scenario | Handled by |
+| --- | --- |
+| `401 token_expired` on RPC call | `rpcClient` automatically (transparent retry) |
+| `401 token_revoked` on RPC call | You — redirect to login |
+| `401 invalid_token` on RPC call | You — redirect to login |
+| Auth failure on WebSocket connect | You — catch and redirect to login |

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

@@ -3,6 +3,10 @@
 You are helping a developer use the **Calimero Python client** (`calimero-client-py`) to
 interact with a Calimero node from Python — automation scripts, backend services, or CLI tools.
 
+> **NOT this skill** if the developer is building the application logic that runs on the
+> node — that is `calimero-rust-sdk` (Rust/WASM) or `calimero-sdk-js` (TypeScript/WASM).
+> This skill is for Python code that *calls* the node from outside.
+
 ## What it is
 
 `calimero-client-py` is a Python package built with PyO3 (Rust bindings). It provides:

package/skills/calimero-desktop/SKILL.md

@@ -1,6 +1,12 @@
 # calimero-desktop — Agent Instructions
 
-You are helping a developer integrate their app frontend with **Calimero Desktop SSO**.
+You are helping a developer integrate their app frontend with **Calimero Desktop SSO** —
+the flow where users open an app from the Desktop and are automatically logged in without
+a manual auth screen.
+
+> **NOT this skill** if the developer just needs to authenticate manually via the login
+> form — that is handled entirely by `calimero-client-js`. This skill is specifically for
+> reading SSO tokens that Calimero Desktop passes in the URL hash.
 
 ## What Desktop does
 

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

@@ -2,28 +2,39 @@
 
 ## Full startup flow
 
+Use the storage helpers from `@calimero-network/calimero-client` — do **not** write to
+`localStorage` directly. The helpers ensure correct key names and extract contextId +
+executorPublicKey from the JWT automatically.
+
 ```typescript
+import {
+  setAppEndpointKey,
+  setAccessToken,
+  setRefreshToken,
+  setApplicationId,
+  setContextAndIdentityFromJWT,
+  getAuthConfig,
+} from '@calimero-network/calimero-client';
+
 interface SSOParams {
   accessToken: string;
-  refreshToken: string;
+  refreshToken: string | null;
   nodeUrl: string;
-  applicationId: string;
+  applicationId: string | null;
 }
 
 function readDesktopSSO(): SSOParams | null {
   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 applicationId = hash.get('application_id');
 
   if (!accessToken || !nodeUrl) return null;
 
   return {
     accessToken,
-    refreshToken: refreshToken ?? '',
+    refreshToken: hash.get('refresh_token'),
     nodeUrl,
-    applicationId: applicationId ?? '',
+    applicationId: hash.get('application_id'),
   };
 }
 
@@ -31,21 +42,29 @@ async function bootstrap() {
   const sso = readDesktopSSO();
 
   if (sso) {
+    // Store tokens via SDK helpers (sets localStorage keys correctly)
+    setAppEndpointKey(sso.nodeUrl);
+    setAccessToken(sso.accessToken);
+    if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+    if (sso.applicationId) setApplicationId(sso.applicationId);
+    // Extracts contextId + executorPublicKey from JWT claims
+    setContextAndIdentityFromJWT(sso.accessToken);
+
     // Clear hash from URL bar (tokens shouldn't sit in browser history)
     history.replaceState(null, '', window.location.pathname + window.location.search);
 
-    // Store for use by the client
-    localStorage.setItem('calimero_node_url', sso.nodeUrl);
-    localStorage.setItem('calimero_jwt', JSON.stringify({
-      access_token: sso.accessToken,
-      refresh_token: sso.refreshToken,
-    }));
-    localStorage.setItem('calimero_app_id', sso.applicationId);
-
-    await renderAuthenticatedApp(sso);
-  } else {
-    renderLoginScreen();
+    renderAuthenticatedApp();
+    return;
+  }
+
+  // No SSO hash — check if already authenticated from a prior session
+  const config = getAuthConfig();
+  if (config.error === null) {
+    renderAuthenticatedApp();
+    return;
   }
+
+  renderLoginScreen();
 }
 
 document.addEventListener('DOMContentLoaded', bootstrap);
@@ -53,7 +72,8 @@ document.addEventListener('DOMContentLoaded', bootstrap);
 
 ## How Desktop discovers your app's frontend URL
 
-Desktop reads the `links.frontend` field from your app's `manifest.json` inside the installed bundle. To ensure Desktop can open your app correctly, set this field:
+Desktop reads the `links.frontend` field from your app's `manifest.json` inside the
+installed bundle. Set this field so Desktop can open your app:
 
 ```json
 {
@@ -70,18 +90,25 @@ Desktop opens this URL and appends the SSO hash params.
 
 ```typescript
 // App.tsx
+import { getAuthConfig, setAccessToken, setAppEndpointKey,
+         setRefreshToken, setApplicationId, setContextAndIdentityFromJWT } from '@calimero-network/calimero-client';
+
 function App() {
   const [authState, setAuthState] = useState<'loading' | 'authenticated' | 'unauthenticated'>('loading');
 
   useEffect(() => {
     const sso = readDesktopSSO();
     if (sso) {
-      storeTokens(sso);
-      setAuthState('authenticated');
-    } else if (hasStoredTokens()) {
+      setAppEndpointKey(sso.nodeUrl);
+      setAccessToken(sso.accessToken);
+      if (sso.refreshToken) setRefreshToken(sso.refreshToken);
+      if (sso.applicationId) setApplicationId(sso.applicationId);
+      setContextAndIdentityFromJWT(sso.accessToken);
+      history.replaceState(null, '', window.location.pathname);
       setAuthState('authenticated');
     } else {
-      setAuthState('unauthenticated');
+      const config = getAuthConfig();
+      setAuthState(config.error === null ? 'authenticated' : 'unauthenticated');
     }
   }, []);
 

package/skills/calimero-node/SKILL.md

@@ -67,6 +67,12 @@ meroctl --node-url http://localhost:2428 <command>   # connect to specific node
 meroctl --home ~/.calimero <command>                  # use alternate config path
 ```
 
+`--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.
+
+`--node-url` defaults to `http://localhost:2428` if not specified (the default port
+`merod` listens on after `merod --home ~/.calimero run`).
+
 ## References
 
 See `references/` for full meroctl command reference and context lifecycle.

package/skills/calimero-rust-sdk/rules/state-derives.md

@@ -0,0 +1,46 @@
+# Rule: State struct must derive Default, BorshDeserialize, BorshSerialize
+
+The three derives are all required. Missing any one of them causes a **runtime panic**,
+not a compile error — the app will install and start, then crash when the context is
+first accessed.
+
+## WRONG — missing derives:
+
+```rust
+// ✗ Missing all derives — runtime panic on first call
+pub struct AppState {
+    items: UnorderedMap<String, String>,
+}
+
+// ✗ Missing BorshSerialize — state cannot be persisted
+#[derive(Default, BorshDeserialize)]
+pub struct AppState {
+    items: UnorderedMap<String, String>,
+}
+```
+
+## CORRECT:
+
+```rust
+#[derive(Default, BorshDeserialize, BorshSerialize)]
+pub struct AppState {
+    items: UnorderedMap<String, String>,
+}
+```
+
+## What each derive does
+
+| Derive | Required for |
+| --- | --- |
+| `Default` | `#[app::init]` calls `AppState::default()` as the baseline |
+| `BorshDeserialize` | Loading state from node storage on every method call |
+| `BorshSerialize` | Saving state to node storage after every mutation |
+
+## Import
+
+```rust
+use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
+```
+
+Do not use `borsh` crate directly — import from `calimero_sdk::borsh` to ensure
+version compatibility.

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

@@ -0,0 +1,137 @@
+# calimero-sdk-js — Agent Instructions
+
+You are helping a developer **build a Calimero P2P application in TypeScript** using
+`@calimero-network/calimero-sdk-js`. The app compiles to WebAssembly and runs inside the
+`merod` node runtime.
+
+> **NOT this skill** if the developer is connecting a browser/Node.js *frontend* to a node
+> (that's `calimero-client-js` / `@calimero-network/calimero-client`). This skill is for
+> writing the application logic that *runs on the node*.
+
+## Install
+
+```bash
+pnpm add @calimero-network/calimero-sdk-js
+pnpm add -D @calimero-network/calimero-cli-js typescript
+```
+
+The CLI's `postinstall` hook downloads QuickJS, WASI-SDK, and Binaryen automatically.
+If you used `--ignore-scripts`, re-run with `pnpm install --ignore-scripts=false`.
+
+## Core concepts
+
+| Concept | What it is |
+| --- | --- |
+| `@State` class | Persisted data — fields must be CRDT types |
+| `@Logic(StateClass)` class | Entry points callable via JSON-RPC; must extend the state class |
+| `@Init` static method | Seeds the initial state when context is first created |
+| `@View()` method | Read-only — skips persistence; required for query methods |
+| CRDT collection | Conflict-free type (`Counter`, `UnorderedMap`, etc.) — all state fields must use these |
+
+## Minimal app
+
+```typescript
+import { State, Logic, Init, View } from '@calimero-network/calimero-sdk-js';
+import { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections';
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+@State
+export class KvState {
+  items: UnorderedMap<string, string> = new UnorderedMap();
+}
+
+@Logic(KvState)
+export class KvLogic extends KvState {
+  @Init
+  static init(): KvState {
+    return new KvState();
+  }
+
+  set(key: string, value: string): void {
+    env.log(`set ${key}`);
+    this.items.set(key, value);
+  }
+
+  @View()
+  get(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+}
+```
+
+## CRDT collections quick reference
+
+| Type | Use case | Key ops |
+| --- | --- | --- |
+| `Counter` | Distributed counting (returns `bigint`) | `increment()`, `incrementBy(n)`, `value()` |
+| `UnorderedMap<K,V>` | Key-value store (LWW per key) | `set()`, `get()`, `has()`, `remove()`, `entries()` |
+| `UnorderedSet<T>` | Unique membership (LWW per element) | `add()`, `has()`, `delete()`, `toArray()` |
+| `Vector<T>` | Ordered list | `push()`, `get(i)`, `pop()`, `len()` |
+| `LwwRegister<T>` | Single value (timestamp LWW) | `set()`, `get()` |
+
+Nested collections (`Map<K, Set<V>>`) propagate changes automatically — no manual
+re-serialization.
+
+## Build & deploy
+
+```bash
+# Build to WASM
+npx calimero-sdk build src/index.ts -o build/service.wasm
+
+# Install on node
+meroctl --node-name <NODE> app install \
+  --path build/service.wasm \
+  --context-id <CONTEXT_ID>
+
+# Call a method
+meroctl --node-name <NODE> call \
+  --context-id <CONTEXT_ID> \
+  --method set \
+  --args '{"key":"hello","value":"world"}'
+
+# Call a view
+meroctl --node-name <NODE> call \
+  --context-id <CONTEXT_ID> \
+  --method get \
+  --args '{"key":"hello"}'
+```
+
+## Key rules
+
+- All `@State` fields must be CRDT types — never plain `Map`, `Set`, `Array`, or primitives
+- `@View()` is **required** on every read-only method — omitting it causes unnecessary persistence
+- Use `env.log()` not `console.log()` — `console` is not available in the WASM runtime
+- `Counter.value()` returns `bigint`, not `number`
+- `@Init` must be a static method that returns the state class instance
+- `@Logic(StateClass)` must extend the state class
+- No async, no I/O, no threads in app logic — the WASM runtime is synchronous
+- **Windows: building is not supported natively — use WSL** (QuickJS/WASI-SDK toolchain requires Linux/macOS)
+
+## Events
+
+```typescript
+import { emit } from '@calimero-network/calimero-sdk-js';
+
+// Inside a mutation method:
+emit({ type: 'ItemAdded', key: 'foo', value: 'bar' });
+```
+
+Events are pushed to all context members via WebSocket. Clients subscribe using
+`WsSubscriptionsClient` from `@calimero-network/calimero-client`.
+
+## Private storage (node-local)
+
+```typescript
+import { createPrivateEntry } from '@calimero-network/calimero-sdk-js';
+
+const secret = createPrivateEntry<string>();
+secret.set('my-api-key');
+const val = secret.get();
+```
+
+Private entries are never broadcast to other nodes.
+
+## References
+
+See `references/` for CRDT collections, events, and build pipeline details.
+See `rules/` for hard constraints.

package/skills/calimero-sdk-js/references/build-pipeline.md

@@ -0,0 +1,98 @@
+# Build Pipeline
+
+`@calimero-network/calimero-cli-js` compiles your TypeScript app to a `.wasm` binary.
+
+## Pipeline stages
+
+```
+TypeScript  →  Rollup  →  QuickJS  →  WASI-SDK  →  Binaryen  →  .wasm
+  Source       Bundle    C bytecode     WASM        Optimized
+```
+
+## Setup
+
+```bash
+# Install SDK and CLI
+pnpm add @calimero-network/calimero-sdk-js
+pnpm add -D @calimero-network/calimero-cli-js typescript
+
+# If postinstall didn't run (--ignore-scripts was set):
+pnpm install --ignore-scripts=false
+# Or manually:
+pnpm --filter @calimero-network/calimero-cli-js run install-deps
+```
+
+## package.json (minimal)
+
+```json
+{
+  "dependencies": {
+    "@calimero-network/calimero-sdk-js": "^0.1.0"
+  },
+  "devDependencies": {
+    "@calimero-network/calimero-cli-js": "^0.1.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "calimero-sdk build src/index.ts -o build/service.wasm"
+  }
+}
+```
+
+## Build command
+
+```bash
+# Build
+npx calimero-sdk build src/index.ts -o build/service.wasm
+
+# Or via npm script
+pnpm build
+```
+
+## Deploy to node
+
+```bash
+# Install the app
+meroctl --node-name <NODE> app install \
+  --path build/service.wasm \
+  --context-id <CONTEXT_ID>
+
+# Create a new context (runs @Init)
+meroctl --node-name <NODE> context create \
+  --app-id <APP_ID>
+
+# Call a mutation
+meroctl --node-name <NODE> call \
+  --context-id <CONTEXT_ID> \
+  --method set \
+  --args '{"key":"hello","value":"world"}'
+
+# Call a view
+meroctl --node-name <NODE> call \
+  --context-id <CONTEXT_ID> \
+  --method get \
+  --args '{"key":"hello"}'
+```
+
+## End-to-end test with Merobox
+
+Each example in the SDK ships a Merobox workflow for multi-node E2E testing:
+
+```bash
+merobox bootstrap run examples/counter/workflows/counter-js.yml --log-level=trace
+```
+
+## Platform support
+
+| Platform | Supported |
+| --- | --- |
+| macOS (x64, arm64) | Yes |
+| Linux (x64, arm64) | Yes |
+| Windows (native) | No — use WSL |
+
+## Definition of done (before PR)
+
+1. `pnpm lint` passes
+2. `pnpm format:check` passes
+3. `pnpm test` passes
+4. Example app builds: `cd examples/counter && pnpm build`

package/skills/calimero-sdk-js/references/collections.md

@@ -0,0 +1,132 @@
+# CRDT Collections
+
+All persistent state in a `calimero-sdk-js` app must use CRDT types from
+`@calimero-network/calimero-sdk-js/collections`.
+
+## Counter (G-Counter)
+
+Distributed counting. The value is the sum across all contributing nodes.
+
+```typescript
+import { Counter } from '@calimero-network/calimero-sdk-js/collections';
+
+const counter = new Counter();
+counter.increment();            // +1
+counter.incrementBy(5n);        // +5 (bigint)
+const total = counter.value();  // bigint
+```
+
+> Counter values are always `bigint`. Do not compare with `=== 0` — use `=== 0n`.
+
+## UnorderedMap\<K, V\>
+
+Key-value store with Last-Write-Wins conflict resolution per key.
+
+```typescript
+import { UnorderedMap } from '@calimero-network/calimero-sdk-js/collections';
+
+const map = new UnorderedMap<string, string>();
+map.set('key', 'value');
+const val = map.get('key');       // 'value' | undefined
+const exists = map.has('key');    // boolean
+map.remove('key');
+const all = map.entries();        // [['key', 'value'], ...]
+```
+
+## UnorderedSet\<T\>
+
+Set of unique values with Last-Write-Wins per element.
+
+```typescript
+import { UnorderedSet } from '@calimero-network/calimero-sdk-js/collections';
+
+const set = new UnorderedSet<string>();
+set.add('item');          // true on first insert, false if already present
+set.has('item');          // true
+set.delete('item');
+const items = set.toArray();
+```
+
+## Vector\<T\>
+
+Ordered list. Conflicts resolved by position.
+
+```typescript
+import { Vector } from '@calimero-network/calimero-sdk-js/collections';
+
+const vec = new Vector<string>();
+vec.push('first');
+vec.push('second');
+const item = vec.get(0);   // 'first'
+const last = vec.pop();    // 'second'
+const len = vec.len();     // 1 (bigint)
+```
+
+## LwwRegister\<T\>
+
+Holds a single value. Last write wins based on timestamp.
+
+```typescript
+import { LwwRegister } from '@calimero-network/calimero-sdk-js/collections';
+
+const reg = new LwwRegister<string>();
+reg.set('current value');
+const current = reg.get(); // 'current value' | undefined
+```
+
+## UserStorage
+
+User-owned signed data. Writes are verified by the owner's signature.
+
+```typescript
+import { UserStorage } from '@calimero-network/calimero-sdk-js/collections';
+
+const storage = new UserStorage<string>();
+storage.set(executorId, 'my value');
+const val = storage.get(executorId);
+```
+
+## FrozenStorage
+
+Immutable, content-addressed storage. Write once; content never changes.
+
+```typescript
+import { FrozenStorage } from '@calimero-network/calimero-sdk-js/collections';
+
+const frozen = new FrozenStorage<string>();
+const id = frozen.store('immutable content');
+const val = frozen.get(id);
+```
+
+## Nested collections
+
+Nested structures propagate changes automatically — no manual re-serialization needed.
+
+```typescript
+// Map<projectId, Set<tags>> — just works
+const projectTags = new UnorderedMap<string, UnorderedSet<string>>();
+
+const tags = new UnorderedSet<string>();
+tags.add('urgent');
+projectTags.set('proj:123', tags);
+
+// Modifying the inner set propagates automatically
+projectTags.get('proj:123')?.add('high-priority');
+```
+
+## State field initialization
+
+CRDT fields must be initialized inline in the `@State` class:
+
+```typescript
+@State
+export class AppState {
+  // ✅ Inline initialization
+  items: UnorderedMap<string, string> = new UnorderedMap();
+  count: Counter = new Counter();
+
+  // ❌ Never use plain JS types for state
+  // plainMap: Map<string, string> = new Map();
+  // array: string[] = [];
+}
+```

package/skills/calimero-sdk-js/references/events.md

@@ -0,0 +1,59 @@
+# Events
+
+Events let your app push real-time notifications to all context members.
+They are emitted during mutation methods and received by clients via WebSocket.
+
+## Emitting events
+
+```typescript
+import { emit, emitWithHandler } from '@calimero-network/calimero-sdk-js';
+
+// Simple event — clients receive it and dispatch themselves
+emit({ type: 'ItemAdded', key: 'foo', value: 'bar' });
+
+// Event with a named handler — clients call `onItemAdded(event)` if defined
+emitWithHandler({ type: 'ItemAdded', key: 'foo' }, 'onItemAdded');
+```
+
+Events can only be emitted inside mutation methods (not `@View()` methods).
+
+## Receiving events on the client
+
+Clients use `WsSubscriptionsClient` from `@calimero-network/calimero-client`:
+
+```typescript
+import { WsSubscriptionsClient, getAppEndpointKey, getContextId } from '@calimero-network/calimero-client';
+
+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) {
+      // e.kind — matches the `type` field from emit()
+      // e.data — the rest of the emitted object
+      console.log(e.kind, e.data);
+    }
+  }
+});
+```
+
+## Event typing (recommended)
+
+Define a discriminated union to type your events:
+
+```typescript
+type AppEvent =
+  | { type: 'ItemAdded'; key: string; value: string }
+  | { type: 'ItemRemoved'; key: string };
+
+// Emit
+emit({ type: 'ItemAdded', key: 'foo', value: 'bar' } satisfies AppEvent);
+```
+
+## Important
+
+- Events are best-effort — clients may miss them if disconnected
+- Do not rely on events for state consistency — use RPC calls to query current state
+- Emitting from a `@View()` method is not supported

package/skills/calimero-sdk-js/rules/crdt-only-state.md

@@ -0,0 +1,47 @@
+# Rule: All @State fields must be CRDT types
+
+Every field on a `@State` class must be a CRDT collection from
+`@calimero-network/calimero-sdk-js/collections`. Plain JavaScript types are not
+persisted or synchronized.
+
+## WRONG — plain JS types in state:
+
+```typescript
+@State
+export class AppState {
+  items: Map<string, string> = new Map();   // ✗ — not a CRDT, not synced
+  tags: string[] = [];                       // ✗ — not a CRDT, not synced
+  name: string = '';                         // ✗ — use LwwRegister instead
+  count: number = 0;                         // ✗ — use Counter instead
+}
+```
+
+## CORRECT — CRDT types:
+
+```typescript
+@State
+export class AppState {
+  items: UnorderedMap<string, string> = new UnorderedMap();
+  tags: UnorderedSet<string> = new UnorderedSet();
+  name: LwwRegister<string> = new LwwRegister();
+  count: Counter = new Counter();
+}
+```
+
+## Why this matters
+
+Plain JS types are not serialized to the node's CRDT storage. State that uses
+`Map`, `Set`, `Array`, or primitives directly will be lost on the next call and
+will never sync to other nodes in the context.
+
+## Choosing the right CRDT
+
+| Data shape | Use |
+| --- | --- |
+| Counting (monotonic) | `Counter` |
+| Key-value lookup | `UnorderedMap<K, V>` |
+| Unique membership | `UnorderedSet<T>` |
+| Ordered list | `Vector<T>` |
+| Single value (overwrites) | `LwwRegister<T>` |
+| User-owned signed data | `UserStorage<T>` |
+| Immutable content | `FrozenStorage<T>` |

package/skills/calimero-sdk-js/rules/no-console-log.md

@@ -0,0 +1,38 @@
+# Rule: Use env.log() — not console.log()
+
+`console` is not available in the QuickJS/WASM runtime. Calling `console.log()` will
+throw a runtime error. Use `env.log()` from the SDK's env module instead.
+
+## WRONG:
+
+```typescript
+console.log('Processing item:', key);        // ✗ — throws at runtime
+console.error('Something went wrong');       // ✗ — throws at runtime
+```
+
+## CORRECT:
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+env.log(`Processing item: ${key}`);          // ✓ — output appears in node logs
+env.log(`Error: ${error}`);                  // ✓
+```
+
+## env.log() format
+
+`env.log()` accepts a single string. Use template literals for dynamic values:
+
+```typescript
+env.log(`set called: key=${key}, value=${value}`);
+env.log(`counter is now ${this.count.value()}`);
+```
+
+## Other env utilities
+
+```typescript
+import * as env from '@calimero-network/calimero-sdk-js/env';
+
+// Get the calling executor's public key (Uint8Array, 32 bytes)
+const executorId = env.executorId();
+```

package/skills/calimero-sdk-js/rules/view-decorator.md

@@ -0,0 +1,46 @@
+# Rule: @View() is required on read-only methods
+
+Every method that does not modify state must be decorated with `@View()`. Without it,
+the runtime will persist state after every call — even when nothing changed — causing
+unnecessary storage writes and cross-node syncs.
+
+## WRONG — read-only method without @View():
+
+```typescript
+@Logic(AppState)
+export class AppLogic extends AppState {
+  // ✗ — no @View(), triggers persistence on every call
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+
+  // ✗ — returning a count without @View()
+  getCount(): bigint {
+    return this.count.value();
+  }
+}
+```
+
+## CORRECT:
+
+```typescript
+@Logic(AppState)
+export class AppLogic extends AppState {
+  @View()
+  getItem(key: string): string | null {
+    return this.items.get(key) ?? null;
+  }
+
+  @View()
+  getCount(): bigint {
+    return this.count.value();
+  }
+}
+```
+
+## How to tell if a method needs @View()
+
+A method is read-only if it:
+- Does not call any mutation methods on CRDT fields (`set`, `insert`, `add`, `push`, `increment`, etc.)
+- Does not call `emit()` or `emitWithHandler()`
+- Only reads values and returns results