@calimero-network/agent-skills 0.1.0

package/skills/calimero-abi-codegen/references/generated-output.md

@@ -0,0 +1,89 @@
+# Generated Output
+
+Running `calimero-abi-codegen -i abi.json -o src/generated --client-name KvStoreClient` produces:
+
+```
+src/generated/
+├── types.ts
+└── KvStoreClient.ts
+```
+
+## types.ts
+
+Contains all TypeScript types matching the ABI types, plus event payload types:
+
+```typescript
+// Generated from abi.json — do not edit manually
+
+export interface Entry {
+  key: string;
+  value: string;
+}
+
+// Event union type
+export type AppEvent =
+  | { type: 'ItemSet'; payload: Entry }
+  | { type: 'ItemRemoved'; payload: { key: string } };
+```
+
+## KvStoreClient.ts
+
+Contains the typed client class with a method per ABI function:
+
+```typescript
+// Generated from abi.json — do not edit manually
+import { CalimeroApp, Context } from '@calimero-network/calimero-client';
+import type { Entry } from './types';
+
+export class KvStoreClient {
+  constructor(private app: CalimeroApp, private context: Context) {}
+
+  async set(key: string, value: string): Promise<void> {
+    await this.app.mutate(this.context, 'set', { key, value });
+  }
+
+  async get(key: string): Promise<string | null> {
+    return this.app.query(this.context, 'get', { key });
+  }
+
+  async entries(): Promise<Entry[]> {
+    return this.app.query(this.context, 'entries', {});
+  }
+}
+```
+
+## Using the generated client
+
+```typescript
+import { CalimeroApp, Context, getJWTObject, getStorageAppEndpointKey } from '@calimero-network/calimero-client';
+import { KvStoreClient } from './generated/KvStoreClient';
+
+const app = new CalimeroApp(getStorageAppEndpointKey(), getJWTObject()?.access_token);
+const context = new Context('your-context-id');
+const client = new KvStoreClient(app, context);
+
+// Fully typed — IDE autocomplete works
+await client.set('hello', 'world');
+const value = await client.get('hello'); // string | null
+const all = await client.entries();      // Entry[]
+```
+
+## Regenerating after app changes
+
+When you update your Rust app and the ABI changes, re-run codegen:
+
+```bash
+# After rebuilding your WASM app (which regenerates abi.json):
+npx calimero-abi-codegen -i abi.json -o src/generated --client-name KvStoreClient
+```
+
+Add this to your build script so it stays in sync automatically:
+
+```json
+{
+  "scripts": {
+    "codegen": "calimero-abi-codegen -i abi.json -o src/generated --client-name KvStoreClient",
+    "build": "npm run codegen && tsc"
+  }
+}
+```

package/skills/calimero-abi-codegen/references/programmatic-api.md

@@ -0,0 +1,53 @@
+# Programmatic API
+
+Use the library directly in Node.js scripts for custom code generation pipelines.
+
+## Install
+
+```bash
+npm install @calimero-network/abi-codegen
+```
+
+## Parse an ABI
+
+```typescript
+import { loadAbiManifestFromFile, parseAbiManifest } from '@calimero-network/abi-codegen/parse';
+
+// From file
+const manifest = loadAbiManifestFromFile('./abi.json');
+
+// From already-parsed JSON
+const json = JSON.parse(fs.readFileSync('./abi.json', 'utf8'));
+const manifest = parseAbiManifest(json);
+// Throws if invalid — schema_version wrong, dangling refs, duplicate names, etc.
+```
+
+## Generate types and client
+
+```typescript
+import { generateTypes } from '@calimero-network/abi-codegen/generate/types';
+import { generateClient } from '@calimero-network/abi-codegen/generate/client';
+import { deriveClientNameFromPath } from '@calimero-network/abi-codegen';
+
+const manifest = loadAbiManifestFromFile('./abi.json');
+
+// Generate types.ts content
+const typesContent = generateTypes(manifest);
+
+// Generate client content
+const clientName = deriveClientNameFromPath('kv_store.wasm'); // → "KvStore"
+const clientContent = generateClient(manifest, clientName);
+
+// Write to disk
+fs.writeFileSync('src/generated/types.ts', typesContent);
+fs.writeFileSync(`src/generated/${clientName}.ts`, clientContent);
+```
+
+## Export paths
+
+```typescript
+import { deriveClientNameFromPath } from '@calimero-network/abi-codegen';
+import { loadAbiManifestFromFile, parseAbiManifest } from '@calimero-network/abi-codegen/parse';
+import { generateTypes } from '@calimero-network/abi-codegen/generate/types';
+import { generateClient } from '@calimero-network/abi-codegen/generate/client';
+```

package/skills/calimero-abi-codegen/rules/schema-version.md

@@ -0,0 +1,36 @@
+# Rule: ABI manifest must have schema_version "wasm-abi/1"
+
+The codegen tool rejects any ABI file that doesn't have the exact string `"wasm-abi/1"` as its `schema_version`.
+
+## WRONG:
+
+```json
+{
+  "schema_version": "1",
+  "types": {}, "methods": [], "events": []
+}
+```
+
+```json
+{
+  "types": {}, "methods": [], "events": []
+}
+```
+
+## CORRECT:
+
+```json
+{
+  "schema_version": "wasm-abi/1",
+  "types": {}, "methods": [], "events": []
+}
+```
+
+## Validate before generating
+
+Use `--validate` to check an ABI file without generating code — useful as a CI step:
+
+```bash
+npx calimero-abi-codegen --validate -i abi.json
+# exits 0 if valid, non-zero if invalid
+```

package/skills/calimero-abi-codegen/rules/unique-names.md

@@ -0,0 +1,52 @@
+# Rule: Method, event, and type names must all be unique
+
+The ABI validator rejects manifests where names clash — across methods, events, and types.
+
+## WRONG — duplicate method names:
+
+```json
+{
+  "methods": [
+    { "name": "get", "params": [...] },
+    { "name": "get", "params": [...] }
+  ]
+}
+```
+
+## WRONG — type name same as method name:
+
+```json
+{
+  "types": {
+    "set": { "kind": "record", "fields": [] }
+  },
+  "methods": [
+    { "name": "set", "params": [] }
+  ]
+}
+```
+
+## WRONG — map key is not string:
+
+```json
+{
+  "kind": "map",
+  "key": { "kind": "u64" },
+  "value": { "kind": "string" }
+}
+```
+
+Map keys **must** be `{ "kind": "string" }`.
+
+## WRONG — dangling $ref:
+
+```json
+{
+  "types": {},
+  "methods": [
+    { "name": "get", "returns": { "$ref": "NonExistentType" } }
+  ]
+}
+```
+
+Every `$ref` must point to a name defined in the `types` object.

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

@@ -0,0 +1,44 @@
+# 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`.
+
+## Package versions
+
+| Package | Version | Notes |
+| --- | --- | --- |
+| `@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** |
+
+## Critical: mero-js v2 uses camelCase
+
+v2 changed all request field names from `snake_case` to `camelCase`.
+
+```typescript
+// WRONG (v1 / old):
+{ context_id: '...', context_identity: '...' }
+
+// CORRECT (v2):
+{ contextId: '...', contextIdentity: '...' }
+```
+
+This applies to `GenerateClientKeyRequest` and all other request types.
+
+## Install
+
+```bash
+pnpm add @calimero-network/calimero-client
+# or
+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
+
+## References
+
+See `references/` for auth flow, RPC calls, WebSocket events, and SSO.
+See `rules/` for camelCase API and token refresh requirements.

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

@@ -0,0 +1,58 @@
+# Authentication
+
+## Login flow
+
+```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);
+```
+
+## Token storage
+
+Tokens should be stored in `localStorage` or `sessionStorage`. The client library reads
+them automatically if you use the provided storage helpers:
+
+```typescript
+import { getStorageAppEndpointKey, getJWTObject } from '@calimero-network/calimero-client';
+
+const nodeUrl = getStorageAppEndpointKey();
+const jwt = getJWTObject();
+// jwt.access_token, jwt.refresh_token
+```
+
+## Checking auth status
+
+```typescript
+import { getJWTObject } from '@calimero-network/calimero-client';
+
+function isLoggedIn(): boolean {
+  const jwt = getJWTObject();
+  return !!(jwt?.access_token);
+}
+```
+
+## Logout
+
+```typescript
+localStorage.removeItem('calimero_jwt');
+localStorage.removeItem('calimero_node_url');
+// redirect to login
+```

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

@@ -0,0 +1,75 @@
+# RPC Calls
+
+Calling application methods on a Calimero node.
+
+## Setup
+
+```typescript
+import {
+  JsonRpcClient,
+  getStorageAppEndpointKey,
+  getJWTObject,
+} from '@calimero-network/calimero-client';
+
+const nodeUrl = getStorageAppEndpointKey() ?? 'http://localhost:2428';
+const jwt = getJWTObject();
+
+const client = new JsonRpcClient(nodeUrl, '/jsonrpc', jwt?.access_token);
+```
+
+## Calling a mutation (changes state)
+
+```typescript
+const response = await client.mutate<{ key: string; value: string }, void>({
+  contextId: 'your-context-id',
+  method: 'set',
+  argsJson: { key: 'hello', value: 'world' },
+  executorPublicKey: jwt?.executor_public_key ?? '',
+});
+
+if (response.error) {
+  console.error(response.error);
+}
+```
+
+## Calling a view (read-only)
+
+```typescript
+const response = await client.query<{ key: string }, string | null>({
+  contextId: 'your-context-id',
+  method: 'get',
+  argsJson: { key: 'hello' },
+  executorPublicKey: jwt?.executor_public_key ?? '',
+});
+
+console.log(response.result?.output); // "world"
+```
+
+## Response shape
+
+```typescript
+interface RpcResponse<T> {
+  result?: {
+    output: T;
+  };
+  error?: {
+    code: number;
+    message: string;
+  };
+}
+```
+
+## Error handling
+
+```typescript
+const response = await client.query({ ... });
+
+if (response.error) {
+  if (response.error.code === 401) {
+    // token expired — refresh and retry
+    await refreshTokens();
+    return callAgain();
+  }
+  throw new Error(response.error.message);
+}
+```

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

@@ -0,0 +1,67 @@
+# SSO — Calimero Desktop Integration
+
+When a user opens your app from Calimero Desktop, auth tokens are passed via the URL hash.
+Reading them lets users skip the manual login flow entirely.
+
+## Hash parameters
+
+| Parameter | Description |
+| --- | --- |
+| `access_token` | JWT for authenticated node calls |
+| `refresh_token` | Token to obtain a new access token |
+| `node_url` | URL of the local node to connect to |
+| `application_id` | The installed application's ID on the node |
+
+## Reading from hash
+
+```typescript
+function readSSOParams(): {
+  accessToken: string | null;
+  refreshToken: string | null;
+  nodeUrl: string | null;
+  applicationId: string | null;
+} {
+  const hash = window.location.hash.slice(1); // remove leading #
+  const params = new URLSearchParams(hash);
+  return {
+    accessToken: params.get('access_token'),
+    refreshToken: params.get('refresh_token'),
+    nodeUrl: params.get('node_url'),
+    applicationId: params.get('application_id'),
+  };
+}
+```
+
+## Using SSO tokens on app startup
+
+```typescript
+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
+    history.replaceState(null, '', window.location.pathname);
+    renderApp();
+  } else {
+    // No SSO — show manual login
+    renderLogin();
+  }
+}
+```
+
+## 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
+when opened directly in a browser, not only from Desktop.

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

@@ -0,0 +1,66 @@
+# WebSocket Events
+
+Subscribe to real-time events emitted by the application running on the node.
+
+## Connect and subscribe
+
+```typescript
+import { WsSubscriptionsClient } from '@calimero-network/calimero-client';
+
+const nodeUrl = getStorageAppEndpointKey() ?? 'http://localhost:2428';
+const jwt = getJWTObject();
+
+const ws = new WsSubscriptionsClient(nodeUrl, '/ws', jwt?.access_token);
+
+ws.subscribe([contextId], (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;
+}
+
+ws.subscribe([contextId], (event) => {
+  const appEvent = event.data as AppEvent;
+
+  switch (appEvent.type) {
+    case 'ItemAdded':
+      addItemToUI(appEvent.key!, appEvent.value!);
+      break;
+    case 'ItemRemoved':
+      removeItemFromUI(appEvent.key!);
+      break;
+  }
+});
+```
+
+## Cleanup
+
+```typescript
+// Unsubscribe when component unmounts
+ws.unsubscribe([contextId]);
+
+// Or close connection entirely
+ws.close();
+```
+
+## React hook pattern
+
+```typescript
+useEffect(() => {
+  const ws = new WsSubscriptionsClient(nodeUrl, '/ws', token);
+  ws.subscribe([contextId], handleEvent);
+
+  return () => {
+    ws.unsubscribe([contextId]);
+  };
+}, [contextId, token]);
+```

package/skills/calimero-client-js/rules/camelcase-api.md

@@ -0,0 +1,37 @@
+# Rule: mero-js v2 uses camelCase — not snake_case
+
+`@calimero-network/mero-js` v2 (`>=2.0.0-beta.1`) changed all request object field names from `snake_case` to `camelCase`.
+
+## WRONG (v1 / old code):
+
+```typescript
+await client.generateClientKey({
+  context_id: contextId,        // ✗
+  context_identity: identity,   // ✗
+});
+```
+
+## CORRECT (v2):
+
+```typescript
+await client.generateClientKey({
+  contextId: contextId,         // ✓
+  contextIdentity: identity,    // ✓
+});
+```
+
+## Affected types
+
+- `GenerateClientKeyRequest` — `contextId`, `contextIdentity`
+- All other request types in the v2 API
+
+## Why this matters
+
+The v2 mero-js package does not alias the old snake_case keys. Passing `context_id` silently
+sends `undefined` to the server, which returns a cryptic error rather than a clear "wrong field name" message.
+
+## How to detect if a codebase is on v1 or v2
+
+Check `package.json`:
+- `"@calimero-network/mero-js": "^2.0.0-beta.1"` or higher → v2, use camelCase
+- `"@calimero-network/calimero-client": "..."` → original client, check its docs

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

@@ -0,0 +1,41 @@
+# Rule: Always handle 401 with token refresh
+
+Access tokens expire. Any RPC call or WebSocket connection can return `401 Unauthorized`. Never let this surface as an unhandled error.
+
+## Pattern
+
+```typescript
+async function callWithRefresh<T>(callFn: () => Promise<T>): Promise<T> {
+  try {
+    return await callFn();
+  } catch (err: any) {
+    if (err?.code === 401 || err?.status === 401) {
+      await refreshAccessToken();
+      return callFn(); // retry once
+    }
+    throw err;
+  }
+}
+
+async function refreshAccessToken() {
+  const jwt = getJWTObject();
+  if (!jwt?.refresh_token) {
+    // No refresh token — redirect to login
+    window.location.href = '/login';
+    return;
+  }
+
+  const newTokens = await client.refreshToken(jwt.refresh_token);
+  localStorage.setItem('calimero_jwt', JSON.stringify(newTokens));
+}
+```
+
+## Why
+
+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.
+
+## What to do if refresh also fails
+
+Redirect to login. Do not retry the refresh indefinitely.

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

@@ -0,0 +1,53 @@
+# calimero-client-py — Agent Instructions
+
+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.
+
+## What it is
+
+`calimero-client-py` is a Python package built with PyO3 (Rust bindings). It provides:
+- Full async API for managing contexts, applications, identities, blobs
+- Automatic JWT token caching and refresh (tokens stored in `~/.merobox/auth_cache/`)
+- A CLI for common node operations
+
+## Install
+
+```bash
+pip install calimero-client-py
+```
+
+**Build from source (requires Rust 1.70+ and maturin):**
+```bash
+pip install maturin
+git clone https://github.com/calimero-network/calimero-client-py
+cd calimero-client-py
+maturin develop --release
+```
+
+## Minimal working example
+
+```python
+import asyncio
+from calimero_client_py import create_connection, create_client
+
+async def main():
+    connection = create_connection(
+        api_url="http://localhost:2428",
+        node_name="my-local-node"   # must be stable — see rules/
+    )
+    client = create_client(connection)
+    contexts = await client.list_contexts()
+    print(contexts)
+
+asyncio.run(main())
+```
+
+## Critical: `node_name` must be stable
+
+`node_name` is used to derive the token cache filename. If it changes between runs,
+the client loses its stored tokens and will need to re-authenticate.
+
+## References
+
+See `references/` for the full API, authentication flow, and CLI commands.
+See `rules/` for the `node_name` stability requirement and async usage.