@calimero-network/agent-skills 0.3.0 → 0.4.0

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
+```

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`.