@calimero-network/agent-skills 0.2.0 → 0.4.0

package/skills/calimero-registry/references/manifest-format.md

@@ -1,46 +1,47 @@
-# Manifest Format
+# Manifest Format (V2)
 
-`manifest.json` describes the app bundle. mero-sign reads and signs it.
+The manifest describes the app bundle. It is generated by `calimero-registry bundle create` and can
+optionally be signed with `mero-sign` before pushing.
 
-## Minimal manifest
+## Bundle create generates this automatically
 
-```json
-{
-  "name": "My App",
-  "version": "1.0.0",
-  "description": "A short description of what this app does.",
-  "repository": "https://github.com/yourorg/your-app",
-  "authors": ["Your Name <you@example.com>"],
-  "license": "MIT"
-}
-```
+When you run `calimero-registry bundle create`, the CLI generates a `manifest.json` inside the
+bundle directory. You can also supply a manifest via `-m, --manifest <path>` to pre-fill fields.
 
-## Full manifest with optional fields
+## Manifest V2 format
 
 ```json
 {
-  "name": "My App",
-  "version": "1.0.0",
-  "description": "A short description.",
-  "repository": "https://github.com/yourorg/your-app",
-  "authors": ["Your Name <you@example.com>"],
-  "license": "MIT",
+  "version": "1.0",
+  "package": "com.example.myapp",
+  "appVersion": "1.0.0",
+  "metadata": {
+    "name": "My Application",
+    "description": "Application description",
+    "author": "Your Name"
+  },
+  "wasm": {
+    "path": "app.wasm",
+    "hash": "sha256:...",
+    "size": 12345
+  },
   "links": {
-    "frontend": "https://my-app-frontend.com",
-    "docs": "https://docs.my-app.com"
+    "frontend": "https://example.com",
+    "github": "https://github.com/example/myapp",
+    "docs": "https://example.com/docs"
   },
-  "min_runtime_version": "0.3.0"
+  "minRuntimeVersion": "0.3.0"
 }
 ```
 
-## After signing
+## After signing with mero-sign
 
 mero-sign injects a `signature` block:
 
 ```json
 {
-  "name": "My App",
-  "version": "1.0.0",
+  "version": "1.0",
+  "package": "com.example.myapp",
   ...
   "signature": {
     "alg": "ed25519",
@@ -51,13 +52,33 @@ mero-sign injects a `signature` block:
 }
 ```
 
-## Requirements
+## Package ownership
+
+- The first push establishes the package owner via the Ed25519 `signature.pubkey`
+- Only the owner (or keys in `manifest.owners`) can push subsequent versions
+- For team publishing, add teammates' public keys to `manifest.owners`:
+
+```json
+{
+  "version": "1.0",
+  "package": "com.example.myapp",
+  "owners": [
+    "yuKE404BaldXazEIUC4XrVGFyXxxyoRVjrrGhcKk1P4",
+    "anotherTeammatePubKey..."
+  ],
+  ...
+}
+```
+
+## Package naming
+
+| Rule                        | Example                  |
+| --------------------------- | ------------------------ |
+| Must be reverse-domain      | `com.yourorg.appname` ✅ |
+| Version must be full SemVer | `1.0.0` ✅               |
+| No `v` prefix on version    | `v1.0.0` ❌              |
+
+## `links.frontend` is used by Desktop
 
-| Field | Required | Notes |
-| --- | --- | --- |
-| `name` | Yes | Display name |
-| `version` | Yes | Semver — `MAJOR.MINOR.PATCH` |
-| `description` | Yes | Short description |
-| `repository` | Yes | GitHub or other source URL |
-| `links.frontend` | No | Used by Desktop to open the app UI |
-| `min_runtime_version` | No | Minimum `merod` version required |
+The Desktop app reads `links.frontend` to know which URL to open when a user opens this app. Always
+include it.

package/skills/calimero-registry/references/mero-sign.md

@@ -25,16 +25,16 @@ Produces:
 ```json
 {
   "private_key": "PZbZ5yM9t63qOHMM-CCzExbNv8u79XTxZT9UW8GQJ60",
-  "public_key":  "yuKE404BaldXazEIUC4XrVGFyXxxyoRVjrrGhcKk1P4",
-  "signer_id":   "did:key:z6Mkt7Ejb12a1BxvRiUpd5YWkMrk8KVjaShW2vMt6trm7FGH"
+  "public_key": "yuKE404BaldXazEIUC4XrVGFyXxxyoRVjrrGhcKk1P4",
+  "signer_id": "did:key:z6Mkt7Ejb12a1BxvRiUpd5YWkMrk8KVjaShW2vMt6trm7FGH"
 }
 ```
 
-| Field | Description |
-| --- | --- |
-| `private_key` | Base64url Ed25519 secret (32 bytes). Never share or commit. |
-| `public_key` | Base64url public key (32 bytes). Embedded in every signed manifest. |
-| `signer_id` | `did:key` DID representation. Used as identity reference in the registry. |
+| Field         | Description                                                               |
+| ------------- | ------------------------------------------------------------------------- |
+| `private_key` | Base64url Ed25519 secret (32 bytes). Never share or commit.               |
+| `public_key`  | Base64url public key (32 bytes). Embedded in every signed manifest.       |
+| `signer_id`   | `did:key` DID representation. Used as identity reference in the registry. |
 
 ## Sign a manifest
 
@@ -45,7 +45,7 @@ mero-sign sign manifest.json --key key.json
 
 ## How signing works
 
-```
+```text
   manifest.json (signature field absent or empty)
        │
        ▼  Remove signature + all _* prefixed fields
@@ -63,7 +63,8 @@ mero-sign sign manifest.json --key key.json
 
 ## Team workflow
 
-Each developer keeps their own key — the registry validates org membership via authenticated email, not by which key was used.
+Each developer keeps their own key — the registry validates org membership via authenticated email,
+not by which key was used.
 
 ```bash
 # Each developer once:

package/skills/calimero-registry/rules/key-security.md

@@ -1,7 +1,7 @@
 # Rule: Never commit key.json
 
-The signing key file contains your Ed25519 private key. If committed to version control,
-anyone with repo access can sign bundles as you and publish malicious apps under your identity.
+The signing key file contains your Ed25519 private key. If committed to version control, anyone with
+repo access can sign bundles as you and publish malicious apps under your identity.
 
 ## Required steps
 
@@ -34,6 +34,7 @@ Store `CALIMERO_SIGNING_KEY` as a repository secret (GitHub Secrets, etc.), neve
 ## If you accidentally committed a key
 
 Rotate immediately:
+
 ```bash
 mero-sign generate-key --output new-key.json
 # Update your public key in the registry

package/skills/calimero-registry/rules/sign-before-pack.md

@@ -1,7 +1,7 @@
 # Rule: Sign the manifest BEFORE bundling
 
-mero-sign operates on a standalone `manifest.json` file — not on a `.mpk` archive.
-Signing after `bundle create` will not work because the manifest is already packed.
+mero-sign operates on a standalone `manifest.json` file — not on a `.mpk` archive. Signing after
+`bundle create` will not work because the manifest is already packed.
 
 ## WRONG order:
 
@@ -20,6 +20,6 @@ calimero-registry bundle push app.mpk --key key.json    # ✓ then push
 
 ## Why
 
-The registry verifies the signature by re-running the RFC 8785 canonicalization on the
-manifest fields inside the bundle. If the manifest was modified after signing — including
-by the bundle tool itself — the signature check fails with `400 invalid_signature`.
+The registry verifies the signature by re-running the RFC 8785 canonicalization on the manifest
+fields inside the bundle. If the manifest was modified after signing — including by the bundle tool
+itself — the signature check fails with `400 invalid_signature`.

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

@@ -5,11 +5,15 @@ You are helping a developer build a **Calimero WASM application** in Rust using
 ## What you need to know immediately
 
 - Apps compile to WASM and run inside the `merod` node runtime
-- All persistent state **must** use Calimero CRDT collections — never `std::collections`
-- The `#[app]` macro goes on the **`impl` block**, not the struct
-- All `pub` methods on the `#[app]` impl are callable via JSON-RPC from clients
-- Events are emitted with `app::emit!()` and pushed to all context members
-- Private storage is per-member and isolated; shared state syncs across all members
+- `#[app::state]` goes on the **struct**, `#[app::logic]` goes on the **impl block**
+- All CRDT collections are from `calimero_storage::collections::*` — NOT `calimero_sdk::state::*`
+- Most collection operations return `Result<>` — always use `?`
+- `app::Result<T>` is the correct return type for public methods (not `Result<T, String>`)
+- Use `app::bail!(err)` to early-return errors
+- Use `app::log!()` not `env::log!()` or `println!()`
+- Events are declared with `#[app::event]` on an enum and declared on state with
+  `emits = for<'a> Event<'a>`
+- Private storage uses `#[app::private]` struct + `StructName::private_load_or_default()?`
 - There is no `main()` — the SDK provides the entry point
 
 ## Cargo.toml setup
@@ -19,38 +23,81 @@ You are helping a developer build a **Calimero WASM application** in Rust using
 crate-type = ["cdylib"]
 
 [dependencies]
-calimero-sdk = "0.x"
+calimero-sdk     = "0.10"
+calimero-storage = "0.10"
+
+[build-dependencies]
+calimero-wasm-abi = "0.10"
+serde_json        = "1"
+
+[profile.app-release]
+inherits         = "release"
+codegen-units    = 1
+opt-level        = "z"
+lto              = true
+debug            = false
+strip            = "symbols"
+panic            = "abort"
+overflow-checks  = true
 ```
 
-## Minimal app skeleton
+For the build script, add `build.rs`:
+
+```rust
+fn main() {
+    calimero_wasm_abi::export().unwrap();
+}
+```
+
+## Minimal app skeleton (KV store)
 
 ```rust
 use calimero_sdk::app;
 use calimero_sdk::borsh::{BorshDeserialize, BorshSerialize};
-use calimero_sdk::state::UnorderedMap;
-
-#[derive(Default, BorshDeserialize, BorshSerialize)]
-pub struct AppState {
-    items: UnorderedMap<String, String>,
+use calimero_sdk::serde::Serialize;
+use calimero_storage::collections::{LwwRegister, UnorderedMap};
+
+#[app::state(emits = for<'a> Event<'a>)]
+#[derive(Debug, BorshSerialize, BorshDeserialize)]
+#[borsh(crate = "calimero_sdk::borsh")]
+pub struct KvStore {
+    items: UnorderedMap<String, LwwRegister<String>>,
 }
 
-#[app::state]
-impl AppState {}
+#[app::event]
+pub enum Event<'a> {
+    Inserted { key: &'a str, value: &'a str },
+    Updated  { key: &'a str, value: &'a str },
+    Removed  { key: &'a str },
+}
 
 #[app::logic]
-impl AppState {
+impl KvStore {
     #[app::init]
-    pub fn init() -> AppState {
-        AppState::default()
+    pub fn init() -> KvStore {
+        KvStore {
+            items: UnorderedMap::new(),
+        }
     }
 
-    pub fn set(&mut self, key: String, value: String) -> Result<(), String> {
-        self.items.insert(key, value);
+    pub fn set(&mut self, key: String, value: String) -> app::Result<()> {
+        app::log!("set {:?} = {:?}", key, value);
+        if self.items.contains(&key)? {
+            app::emit!(Event::Updated { key: &key, value: &value });
+        } else {
+            app::emit!(Event::Inserted { key: &key, value: &value });
+        }
+        self.items.insert(key, value.into())?;
         Ok(())
     }
 
-    pub fn get(&self, key: String) -> Option<String> {
-        self.items.get(&key).cloned()
+    pub fn get(&self, key: &str) -> app::Result<Option<String>> {
+        Ok(self.items.get(key)?.map(|v| v.get().clone()))
+    }
+
+    pub fn remove(&mut self, key: &str) -> app::Result<Option<String>> {
+        app::emit!(Event::Removed { key });
+        Ok(self.items.remove(key)?.map(|v| v.get().clone()))
     }
 }
 ```
@@ -61,51 +108,114 @@ impl AppState {
 # Add WASM target (one-time)
 rustup target add wasm32-unknown-unknown
 
-# Build
-cargo build --target wasm32-unknown-unknown --release
+# Build with the app-release profile
+cargo build --target wasm32-unknown-unknown --profile app-release
 
-# Output: target/wasm32-unknown-unknown/release/<crate_name>.wasm
+# Output: target/wasm32-unknown-unknown/app-release/<crate_name>.wasm
 ```
 
 ## Installing and running on a node (dev workflow)
 
 ```bash
+# (Assumes: meroctl node add node1 ... && meroctl node use node1 already done)
+
 # 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
+meroctl app install \
+  --path target/wasm32-unknown-unknown/app-release/myapp.wasm
+# Returns: application-id
 
-# 2. Create a context (instance of the app)
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+# 2. Create a context (instance of the app — init() is called)
+meroctl context create --application-id <application-id>
 # Returns: context-id
 
-# 3. Call a method
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"hello","value":"world"}'
+# 3. Call a mutation
+meroctl call <context-id> set --args '{"key":"hello","value":"world"}'
+
+# 4. Call a view (read-only)
+meroctl call <context-id> get --args '{"key":"hello"}' --view
 
-# 4. Call a view
-meroctl --node-url http://localhost:2428 call <context-id> get \
-  --args '{"key":"hello"}' --view
+# Dev mode: auto-reinstall when WASM changes
+meroctl context create --watch target/wasm32-unknown-unknown/app-release/myapp.wasm
 ```
 
+For `merod` setup and full `meroctl` reference, see `calimero-merod` and `calimero-meroctl` skills.
+
 ## 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!`
+- State struct derives `BorshDeserialize, BorshSerialize` — **not** `Default`
+- Add `#[borsh(crate = "calimero_sdk::borsh")]` to all borsh types
+- Add `#[serde(crate = "calimero_sdk::serde")]` to all serde types
+- Never use `HashMap`, `Vec`, `BTreeMap` directly for **persisted shared state** — use CRDT
+  collections
+- `Vec<T>` and `Option<T>` are fine for local / return types — just not for fields that need CRDT
+  sync
 - Mutations use `&mut self`, views use `&self`
+- Return `app::Result<T>` for all public methods; use `?` on collection ops
+- Use `app::bail!(err)` to return errors early (like `return Err(err.into())`)
+
+## Cross-context calls (xcall)
+
+```rust
+use calimero_sdk::env;
+use calimero_sdk::serde_json;
+
+// Call a method on another context
+let ctx_bytes: [u8; 32] = /* context id bytes */;
+let params = serde_json::json!({ "match_id": id, "winner": w });
+let params_bytes = serde_json::to_vec(&params).unwrap();
+env::xcall(&ctx_bytes, "on_match_finished", &params_bytes);
+```
 
-## Logging
+## Environment functions
 
 ```rust
 use calimero_sdk::env;
 
-// Inside any app method:
-env::log!("Processing key: {}", key);
+env::executor_id()                                // [u8; 32] — caller's public key bytes
+env::context_id()                                 // [u8; 32] — current context ID
+env::time_now()                                   // u64 — current time in milliseconds
+
+env::random_bytes(buf: &mut [u8])                 // fill buf with random bytes
+
+env::ed25519_verify(sig: &[u8; 64], pub_key: &[u8; 32], msg: &[u8]) -> bool
+
+// Blob streaming API
+let fd = env::blob_create();                      // start writing a new blob
+env::blob_write(fd, data: &[u8]) -> u64;          // write bytes
+let blob_id: [u8; 32] = env::blob_close(fd);     // finalize, returns content-addressed ID
+
+let fd = env::blob_open(blob_id: &[u8; 32]);      // open blob for reading (returns 0 if not found)
+env::blob_read(fd, buffer: &mut [u8]) -> u64;     // read bytes (returns 0 at EOF)
+env::blob_close(fd);                              // close read handle
+
+// Make a blob discoverable to all context members
+env::blob_announce_to_context(blob_id: &[u8; 32], context_id: &[u8; 32]) -> bool;
+
+// Cross-context call
+env::xcall(context_id: &[u8; 32], method: &str, params: &[u8]);
 ```
 
+## Additional features
+
+- **UserStorage** — per-member isolated storage (not synced to others): see
+  `references/user-and-frozen-storage.md`
+- **FrozenStorage** — immutable content-addressed entries: see
+  `references/user-and-frozen-storage.md`
+- **Event handlers** — named callbacks triggered when an event is emitted on any peer: see
+  `references/event-handlers.md`
+- **Migrations** — `#[app::migrate]` for upgrading state schema: see `references/migrations.md`
+- **Blob API** — streaming binary storage from app logic: see `references/blob-api.md`
+- **Nested CRDTs** — `#[derive(Mergeable)]` for custom structs used as map values: see
+  `references/nested-crdts.md`
+
+## Related skills
+
+- **`calimero-core`** — runtime concepts (context/app model, JSON-RPC protocol, WebSocket events,
+  CRDT type taxonomy)
+- **`calimero-meroctl`** — full `meroctl` CLI reference for deploying and testing the app
+- **`calimero-merod`** — `merod` daemon setup and health checks
+
 ## References
 
-See `references/` for CRDT collections, events, private storage, and examples.
-See `rules/` for hard constraints the compiler won't catch.
+See `references/` for CRDT collections, events, private storage, and examples. See `rules/` for hard
+constraints the compiler won't catch.

package/skills/calimero-rust-sdk/references/blob-api.md

@@ -0,0 +1,119 @@
+# Blob API
+
+Blobs are binary objects stored outside the CRDT state — large files, images, documents. The app
+stores a blob **ID** (32-byte hash) in state; the binary data lives in blob storage.
+
+Two separate steps: **upload the binary** (client-side, before calling the app method), then **store
+the metadata + announce** (inside the app method).
+
+---
+
+## Streaming write (create a blob from inside the app)
+
+```rust
+use calimero_sdk::env;
+
+// Write arbitrary bytes to a new blob
+let fd = env::blob_create();
+env::blob_write(fd, b"Hello, World!");
+env::blob_write(fd, b" More data...");
+let blob_id: [u8; 32] = env::blob_close(fd);  // finalize; returns content-addressed ID
+
+// Announce to context so other nodes can discover and download it
+let ctx = env::context_id();
+env::blob_announce_to_context(&blob_id, &ctx);
+```
+
+## Streaming read (read a blob from inside the app)
+
+```rust
+let fd = env::blob_open(&blob_id);  // returns 0 if blob not found
+if fd == 0 {
+    app::bail!(/* not found error */);
+}
+
+let mut buf = [0u8; 4096];
+let mut all_bytes = Vec::new();
+loop {
+    let n = env::blob_read(fd, &mut buf);
+    if n == 0 { break; }
+    all_bytes.extend_from_slice(&buf[..n as usize]);
+}
+env::blob_close(fd);
+```
+
+---
+
+## Typical pattern: client uploads, app stores metadata
+
+Most apps let the **client** upload binary data via `blobClient.uploadBlob()` (which returns a blob
+ID), then call an app method that stores the metadata and announces the blob:
+
+```rust
+use calimero_sdk::{app, env};
+use calimero_storage::collections::UnorderedMap;
+
+#[app::state]
+pub struct FileStore {
+    files: UnorderedMap<String, [u8; 32]>,  // name → blob_id
+}
+
+#[app::logic]
+impl FileStore {
+    /// Called after client uploads the blob and gets back blob_id_bytes
+    pub fn store_file(
+        &mut self,
+        name: String,
+        blob_id: [u8; 32],
+    ) -> app::Result<()> {
+        // Announce so all context peers can discover and download it
+        let ctx = env::context_id();
+        env::blob_announce_to_context(&blob_id, &ctx);
+
+        self.files.insert(name, blob_id)?;
+        Ok(())
+    }
+
+    pub fn get_blob_id(&self, name: &str) -> app::Result<Option<[u8; 32]>> {
+        Ok(self.files.get(name)?)
+    }
+}
+```
+
+---
+
+## env functions summary
+
+| Function                                    | Signature                        | Notes                                                                |
+| ------------------------------------------- | -------------------------------- | -------------------------------------------------------------------- |
+| `blob_create()`                             | `() -> u64`                      | Returns write fd                                                     |
+| `blob_write(fd, data)`                      | `(u64, &[u8]) -> u64`            | Returns bytes written                                                |
+| `blob_close(fd)`                            | `(u64) -> [u8; 32]`              | Finalizes; returns blob ID                                           |
+| `blob_open(id)`                             | `(&[u8; 32]) -> u64`             | Returns read fd, 0 if missing                                        |
+| `blob_read(fd, buf)`                        | `(u64, &mut [u8]) -> u64`        | Returns bytes read, 0 at EOF                                         |
+| `blob_announce_to_context(blob_id, ctx_id)` | `(&[u8; 32], &[u8; 32]) -> bool` | Makes blob discoverable to peers; context must match current context |
+
+---
+
+## Encoding blob IDs for JSON
+
+Blob IDs are `[u8; 32]`. For JSON-friendly responses, encode as hex or base58:
+
+```rust
+// hex (add hex = "0.4" to Cargo.toml)
+let hex_id: String = hex::encode(&blob_id);
+let blob_id: [u8; 32] = hex::decode(&hex_str).unwrap().try_into().unwrap();
+
+// base58 (add bs58 to Cargo.toml)
+let b58_id: String = bs58::encode(&blob_id).into_string();
+```
+
+---
+
+## Cargo.toml additions
+
+```toml
+[dependencies]
+hex  = "0.4"   # for hex encoding
+bs58 = "0.5"   # for base58 encoding (optional)
+```