@calimero-network/agent-skills 0.2.0 → 0.4.0

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

@@ -5,17 +5,39 @@ Full CLI for managing a running Calimero node.
 ## Global flags
 
 ```bash
-meroctl --node-url http://localhost:2428 <command>   # connect to specific node
-meroctl --home ~/.calimero <command>                  # alternate config path
+meroctl --node node1 <command>              # use registered node by name
+meroctl --api http://localhost:2428 <command>  # connect directly by URL
+meroctl --home ~/.calimero <command>        # alternate config path
+```
+
+Register a node once, then use by name:
+
+```bash
+meroctl node add node1 /path/to/home       # local node
+meroctl node add mynode http://node.com    # remote node
+meroctl node use node1                     # set as active (default)
 ```
 
 ---
 
-## Node commands
+## Node management commands
 
 ```bash
-# Check node health (returns "alive" when running)
-meroctl --node-url http://localhost:2428 node health
+# Add / connect to a node
+meroctl node add node1 /path/to/calimero/home
+meroctl node add remote1 http://node.example.com
+
+# Set active node
+meroctl node use node1
+
+# List configured nodes
+meroctl node ls
+
+# Remove a node connection
+meroctl node remove node1
+
+# Show node peer identity
+meroctl node identity
 ```
 
 ---
@@ -23,22 +45,22 @@ meroctl --node-url http://localhost:2428 node health
 ## App commands
 
 ```bash
-# 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 local file (.wasm or .mpk)
+meroctl --node node1 app install --path myapp.wasm
+meroctl --node node1 app install --path myapp.mpk
 
 # Install app from registry URL
-meroctl --node-url http://localhost:2428 app install \
-  --url https://registry.calimero.network/com.yourorg.myapp/1.0.0
+meroctl --node node1 app install \
+  --url https://apps.calimero.network/com.yourorg.myapp/1.0.0
 
 # List installed apps
-meroctl --node-url http://localhost:2428 app ls
+meroctl --node node1 app ls
 
 # Get details of a specific app
-meroctl --node-url http://localhost:2428 app get <app-id>
+meroctl --node node1 app get <application-id>
 
-# Remove an app (only works if no active contexts reference it)
-meroctl --node-url http://localhost:2428 app remove <app-id>
+# Remove an app
+meroctl --node node1 app remove <application-id>
 ```
 
 ---
@@ -47,44 +69,23 @@ meroctl --node-url http://localhost:2428 app remove <app-id>
 
 ```bash
 # Create a context (instantiates the app — calls init())
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
+meroctl --node node1 context create --application-id <application-id>
 # Returns: context-id
 
+# Dev mode — watch a WASM file for changes and hot-reload
+meroctl --node node1 context create --watch path/to/app.wasm
+
 # List all contexts on this node
-meroctl --node-url http://localhost:2428 context ls
+meroctl --node node1 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>
+meroctl --node node1 context get <context-id>
 
-# List members of a context
-meroctl --node-url http://localhost:2428 context members <context-id>
+# Delete a context (wipes all state and storage)
+meroctl --node node1 context delete <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
+# Sync a context with peers
+meroctl --node node1 context sync <context-id>
 ```
 
 ---
@@ -92,16 +93,16 @@ meroctl --node-url http://localhost:2429 context join \
 ## Calling app methods
 
 ```bash
-# Mutation — changes shared state (no --view flag)
-meroctl --node-url http://localhost:2428 call <context-id> <method> \
+# Mutation — changes shared state
+meroctl --node node1 call <context-id> set \
   --args '{"key":"hello","value":"world"}'
 
 # View — read-only, does NOT change state
-meroctl --node-url http://localhost:2428 call <context-id> <method> \
+meroctl --node node1 call <context-id> get \
   --args '{"key":"hello"}' --view
 
 # Method with no arguments
-meroctl --node-url http://localhost:2428 call <context-id> list_all \
+meroctl --node node1 call <context-id> list_all \
   --args '{}' --view
 ```
 
@@ -110,74 +111,63 @@ meroctl --node-url http://localhost:2428 call <context-id> list_all \
 ## Identity commands
 
 ```bash
-# Create a new identity (root keypair for this node)
-meroctl --node-url http://localhost:2428 identity create
+# Create a new identity
+meroctl --node node1 identity create
 
-# List all identities on this node
-meroctl --node-url http://localhost:2428 identity ls
+# List all identities
+meroctl --node node1 identity ls
 
 # Get details of a specific identity
-meroctl --node-url http://localhost:2428 identity get <identity>
+meroctl --node node1 identity get <identity>
 ```
 
 ---
 
-## Step-by-step: full local development flow
+## Multi-node context sharing (namespace + group model)
 
-```bash
-# 1. Build the WASM app
-cargo build --target wasm32-unknown-unknown --release
+Multi-node participation uses namespaces (root groups) and group membership.
 
-# 2. Start the node (in a separate terminal)
-merod --home ~/.calimero run
+```bash
+# ── Node A: create a namespace and context ──
+meroctl --node node1 namespace create
+# → <namespace-id>
 
-# 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
+meroctl --node node1 context create --application-id <app-id>
+# → <context-id>
 
-# 4. Create a context
-meroctl --node-url http://localhost:2428 context create --app-id <app-id>
-# Copy the context-id from output
+# Generate an invitation for another node to join
+meroctl --node node1 namespace invite <namespace-id>
+# → invitation JSON payload
 
-# 5. Interact with the app
-meroctl --node-url http://localhost:2428 call <context-id> set \
-  --args '{"key":"foo","value":"bar"}'
+# ── Node B: join via invitation ──
+meroctl --node node2 namespace join <namespace-id> '<invitation-json>'
 
-meroctl --node-url http://localhost:2428 call <context-id> get \
-  --args '{"key":"foo"}' --view
+# ── Node B: join the context (after joining namespace/group) ──
+meroctl --node node2 group join-context <context-id>
 ```
 
 ---
 
-## Step-by-step: multi-node context sharing
+## Step-by-step: full local development flow
 
 ```bash
-# ── 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>
+# 1. Initialize and start a node
+merod --node node1 init --server-port 2428 --swarm-port 2528
+merod --node node1 run &  # run in background
+
+# 2. Register the node in meroctl
+meroctl node add node1 ~/.calimero/node1
+meroctl node use node1
+
+# 3. Install the app
+meroctl app install --path target/wasm32-unknown-unknown/release/myapp.wasm
+# → copy the application-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)
+# 4. Create a context
+meroctl context create --application-id <application-id>
+# → copy the context-id
+
+# 5. Interact with the app
+meroctl call <context-id> set --args '{"key":"foo","value":"bar"}'
+meroctl call <context-id> get --args '{"key":"foo"}' --view
 ```

package/skills/calimero-node/rules/app-vs-context.md

@@ -26,8 +26,8 @@ meroctl call <context-id> get --args '{"key":"hello"}' --view
 
 ## Why this matters
 
-API calls take a `context-id`, not an `app-id`. If you try to call a method with an
-`app-id` instead of a `context-id` you will get a "context not found" error.
+API calls take a `context-id`, not an `app-id`. If you try to call a method with an `app-id` instead
+of a `context-id` you will get a "context not found" error.
 
-One app can have multiple independent contexts — each with its own members and state.
-For example, a chat app might have one context per chat room.
+One app can have multiple independent contexts — each with its own members and state. For example, a
+chat app might have one context per chat room.

package/skills/calimero-registry/SKILL.md

@@ -1,51 +1,130 @@
 # calimero-registry — Agent Instructions
 
-You are helping a developer **sign and publish a Calimero app bundle** to the App Registry.
+You are helping a developer **build and publish a Calimero app bundle** to the App Registry.
 
-## Two tools required
+## Two tools
 
-| Tool | Install | Purpose |
-| --- | --- | --- |
-| `mero-sign` | `cargo install mero-sign` | Ed25519 key management and manifest signing |
-| `calimero-registry` | `npm install -g calimero-registry` | Bundle creation and registry push |
+| Tool                | Install                                         | Purpose                                                     |
+| ------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
+| `calimero-registry` | `npm install -g @calimero-network/registry-cli` | Bundle creation and registry push                           |
+| `mero-sign`         | `cargo install mero-sign`                       | Ed25519 key management and manifest signing (for ownership) |
 
-## Critical: sign BEFORE bundling
+## Quick workflow
 
-mero-sign operates on `manifest.json` **before** it is packed. The registry verifies the
-signature on upload — signing after bundling will fail.
+```bash
+# 1. Install registry CLI
+npm install -g @calimero-network/registry-cli
 
-**Correct order:**
-1. Build WASM
-2. Write `manifest.json`
-3. `mero-sign sign manifest.json --key key.json`  ← sign first
-4. `calimero-registry bundle create ...`           ← bundle second
-5. `calimero-registry bundle push ...`             ← then push
+# 2. Configure registry (one-time)
+calimero-registry config set registry-url https://apps.calimero.network
+calimero-registry config set api-key your-api-key
 
-## Quick reference
+# 3. Build WASM (your app's build script)
+./build.sh
 
-```bash
-# 1. Install tools
-cargo install mero-sign
-npm install -g calimero-registry
+# 4. Create bundle (WASM + metadata → .mpk)
+calimero-registry bundle create \
+  --output myapp-1.0.0.mpk \
+  --name "My App" \
+  --description "Does something useful" \
+  --author "Your Name" \
+  --frontend "https://my-app.com" \
+  --github "https://github.com/yourorg/myapp" \
+  path/to/app.wasm \
+  com.yourorg.myapp \
+  1.0.0
+
+# 5. Push to registry
+calimero-registry bundle push myapp-1.0.0.mpk --remote
+```
+
+## Signing for ownership (optional but recommended)
+
+The registry tracks package ownership via Ed25519 signatures. If you sign the manifest, your key
+becomes the package owner — only your key (or keys in `manifest.owners`) can push future versions.
 
-# 2. Generate signing key (one-time per developer)
+```bash
+# Generate signing key (one-time)
 mero-sign generate-key --output my-key.json
 echo "my-key.json" >> .gitignore
 
-# 3. Sign
-mero-sign sign dist/myapp/manifest.json --key my-key.json
+# After bundle create, sign the manifest inside the bundle:
+mero-sign sign path/to/manifest.json --key my-key.json
+
+# Then push
+calimero-registry bundle push myapp-1.0.0.mpk --remote
+```
+
+## Bundle create flags
+
+| Flag                    | Required | Description                                            |
+| ----------------------- | -------- | ------------------------------------------------------ |
+| `<wasm-file>`           | Yes      | Path to WASM binary (positional)                       |
+| `[package]`             | Yes      | Reverse-domain package name (e.g. `com.yourorg.myapp`) |
+| `[version]`             | Yes      | SemVer version (e.g. `1.0.0`)                          |
+| `-o, --output <path>`   | No       | Output `.mpk` filename                                 |
+| `-m, --manifest <path>` | No       | Read config from a manifest JSON file                  |
+| `--name <name>`         | No       | App display name                                       |
+| `--description <text>`  | No       | Short description                                      |
+| `--author <name>`       | No       | Author name                                            |
+| `--frontend <url>`      | No       | Frontend URL (used by Desktop to open the app)         |
+| `--github <url>`        | No       | Source repository URL                                  |
+| `--docs <url>`          | No       | Documentation URL                                      |
+
+## Bundle push flags
+
+```bash
+# Push to local registry (default)
+calimero-registry bundle push myapp-1.0.0.mpk --local
 
-# 4. Bundle
+# Push to remote registry (uses config file)
+calimero-registry bundle push myapp-1.0.0.mpk --remote
+
+# Override config with flags
+calimero-registry bundle push myapp-1.0.0.mpk \
+  --remote \
+  --url https://apps.calimero.network \
+  --api-key your-api-key
+```
+
+## Configuration
+
+```bash
+# Set defaults (stored in ~/.calimero-registry/remote-config.json)
+calimero-registry config set registry-url https://apps.calimero.network
+calimero-registry config set api-key your-api-key
+calimero-registry config list
+
+# Or use environment variables
+export CALIMERO_REGISTRY_URL=https://apps.calimero.network
+export CALIMERO_API_KEY=your-api-key
+```
+
+## Package naming rules
+
+- Must be reverse-domain format: `com.yourorg.appname`
+- Version must be SemVer without `v` prefix: `1.0.0` not `v1.0.0`
+
+## Updating an existing app (new version)
+
+```bash
 calimero-registry bundle create \
-  --output myapp-1.0.0.mpk \
-  dist/myapp/app.wasm \
-  com.yourorg.myapp
+  --output myapp-1.1.0.mpk \
+  --name "My App" \
+  path/to/app.wasm \
+  com.yourorg.myapp \
+  1.1.0
 
-# 5. Push
-calimero-registry bundle push myapp-1.0.0.mpk --key my-key.json
+calimero-registry bundle push myapp-1.1.0.mpk --remote
 ```
 
+## Related skills
+
+- **`calimero-rust-sdk`** — building the WASM app that gets published
+- **`calimero-core`** — application/context model and how the registry integrates with node app
+  install
+
 ## References
 
-See `references/` for manifest format, signing details, and push workflow.
-See `rules/` for hard constraints.
+See `references/` for manifest format, signing details, and push workflow. See `rules/` for hard
+constraints.

package/skills/calimero-registry/references/bundle-and-push.md

@@ -1,16 +1,31 @@
 # Bundle Create & Push
 
-## calimero-registry CLI
+## Install
 
 ```bash
-npm install -g calimero-registry
+npm install -g @calimero-network/registry-cli
 # or
-pnpm add -g calimero-registry
+pnpm add -g @calimero-network/registry-cli
+```
+
+## One-time configuration
+
+```bash
+calimero-registry config set registry-url https://apps.calimero.network
+calimero-registry config set api-key your-api-key
+calimero-registry config list
+```
+
+Or use environment variables:
+
+```bash
+export CALIMERO_REGISTRY_URL=https://apps.calimero.network
+export CALIMERO_API_KEY=your-api-key
 ```
 
 ## Bundle create
 
-Packages the signed manifest and WASM binary into a `.mpk` file:
+Creates an `.mpk` bundle from a WASM file:
 
 ```bash
 calimero-registry bundle create \
@@ -18,52 +33,102 @@ calimero-registry bundle create \
   --name "My App" \
   --description "Does something useful" \
   --author "Your Name" \
-  --frontend "https://my-app-frontend.com" \
-  --github "https://github.com/yourorg/your-app" \
+  --frontend "https://my-app.com" \
+  --github "https://github.com/yourorg/myapp" \
   path/to/app.wasm \
-  com.yourorg.myapp
+  com.yourorg.myapp \
+  1.0.0
 ```
 
-| Flag | Required | Description |
-| --- | --- | --- |
-| `--output` | Yes | Output `.mpk` filename |
-| `--name` | Yes | App display name |
-| `--description` | Yes | Short description |
-| `--author` | Yes | Author name |
-| `--frontend` | No | Frontend URL (used by Desktop) |
-| `--github` | No | Source repository URL |
+Positional arguments: `<wasm-file> [package] [version]`
+
+| Flag                    | Required | Description                                      |
+| ----------------------- | -------- | ------------------------------------------------ |
+| `-o, --output <path>`   | No       | Output `.mpk` filename                           |
+| `-m, --manifest <path>` | No       | Read metadata from a manifest JSON file          |
+| `--name <name>`         | No       | App display name                                 |
+| `--description <text>`  | No       | Short description                                |
+| `--author <name>`       | No       | Author name                                      |
+| `--frontend <url>`      | No       | Frontend URL (Desktop uses this to open the app) |
+| `--github <url>`        | No       | Source repository URL                            |
+| `--docs <url>`          | No       | Documentation URL                                |
 
-The positional args are: `<wasm-path>` `<app-id>` (reverse-domain, e.g. `com.yourorg.appname`).
+After creating, the CLI prints sign instructions:
+
+```text
+1. Sign the manifest:  mero-sign sign <output>/manifest.json --key key.json
+2. Push the bundle:    calimero-registry bundle push <output> --remote
+```
 
 ## Bundle push
 
 ```bash
-calimero-registry bundle push myapp-1.0.0.mpk --key my-key.json
+# Push to remote registry (uses config file values)
+calimero-registry bundle push myapp-1.0.0.mpk --remote
+
+# Push to local registry
+calimero-registry bundle push myapp-1.0.0.mpk --local
+
+# Override config
+calimero-registry bundle push myapp-1.0.0.mpk \
+  --remote \
+  --url https://apps.calimero.network \
+  --api-key your-api-key
 ```
 
-The registry will:
-1. Unpack the `.mpk`
-2. Verify the Ed25519 signature against the manifest
-3. Validate your authenticated email against org membership (if publishing to an org)
-4. Store the bundle and make it discoverable
+## Full publish workflow
 
-## On signature mismatch
+```bash
+# 1. Build WASM
+./build.sh
 
-If the manifest was modified after signing, the push returns:
-```
-400 invalid_signature
-```
+# 2. Create bundle
+calimero-registry bundle create \
+  --output myapp-1.0.0.mpk \
+  --name "My App" \
+  --frontend "https://my-app.com" \
+  path/to/app.wasm \
+  com.yourorg.myapp \
+  1.0.0
 
-Re-sign the manifest and recreate the bundle.
+# 3. (Optional) Sign manifest for ownership
+mero-sign sign myapp-1.0.0/manifest.json --key my-key.json
+
+# 4. Push
+calimero-registry bundle push myapp-1.0.0.mpk --remote
+```
 
 ## Updating an existing app (new version)
 
 ```bash
-# Bump version in manifest.json
-mero-sign sign dist/myapp-1.1.0/manifest.json --key my-key.json
-calimero-registry bundle create --output myapp-1.1.0.mpk ...
-calimero-registry bundle push myapp-1.1.0.mpk --key my-key.json
+calimero-registry bundle create \
+  --output myapp-1.1.0.mpk \
+  --name "My App" \
+  path/to/app.wasm \
+  com.yourorg.myapp \
+  1.1.0
+
+calimero-registry bundle push myapp-1.1.0.mpk --remote
 ```
 
-The registry accepts any new semver version. The first publisher of an app name becomes
-the owner; only org members can push subsequent versions (validated by email).
+## CI/CD (GitHub Actions)
+
+```yaml
+- name: Install Registry CLI
+  run: npm install -g @calimero-network/registry-cli
+
+- name: Create Bundle
+  run: |
+    calimero-registry bundle create \
+      --output app-${{ github.event.release.tag_name }}.mpk \
+      --name "My Application" \
+      ./app.wasm \
+      com.yourorg.myapp \
+      ${{ github.event.release.tag_name }}
+
+- name: Publish Bundle
+  env:
+    CALIMERO_API_KEY: ${{ secrets.CALIMERO_API_KEY }}
+  run: |
+    calimero-registry bundle push app-${{ github.event.release.tag_name }}.mpk --remote
+```