@solgridai/cli 0.1.1 → 0.2.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solgridai/cli",
-  "version": "0.1.1",
+  "version": "0.2.0-beta.1",
   "description": "Command-line client for Solgrid: discover, inspect and run tools from your terminal or agent.",
   "license": "MIT",
   "repository": {

package/skills/solgrid-cli/SKILL.md

@@ -77,7 +77,13 @@ Read before every first use of a tool:
 
 - `input`: JSON Schemas for `body`, `queryParams` and `pathParams`. Build the
   input from these. Never guess field names, required fields or allowed values.
-- `price`: what a run costs. Amounts are decimal strings in USD.
+- `price`: what a run costs. Amounts are decimal strings in USD. Many tools
+  list `price.rates`, one rate per meter (what is counted: calls, output
+  images, seconds of video, tokens, …) at `unitPriceUsd` per `unitSize` units.
+  Different meters add up; within a meter, the rate whose `conditions` match
+  the request applies. These are unit prices, not the cost of a whole run:
+  the final charge is the run's `cost`. `price` is null when a tool has no
+  price yet.
 - `notes`: tool-specific caveats.
 
 ## 3. Run
@@ -96,7 +102,10 @@ solgrid run -p <provider> -e <endpoint> -i '{"screen_name":"nasa"}' --wait --jso
 
 - Without `--wait`, `run` returns as soon as the run is accepted. Some tools
   finish immediately and the result is already included; others keep running.
-- `--wait [seconds]` waits for the run to finish (default 300s).
+- `--wait [seconds]` waits for the run to finish (default 300s). The time
+  covers submitting too: some tools (image models, for example) answer only
+  when the result is ready, which can take a minute or more. Give such runs a
+  generous wait, e.g. `--wait 600`.
 - `-o <file>` saves the result to a file (and implies `--wait`). Prefer it
   for large results instead of printing them into the conversation.
 - To check on a run later: `solgrid runs get -r <runId> --wait --json`.
@@ -163,9 +172,18 @@ with the same key, or look the run up first.
   | `error.key` | Meaning |
   |---|---|
   | `wallet_balance_insufficient` | Balance too low; the user can top up on the console's Wallet page |
-  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page |
+  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page (but see below) |
   | `per_call_limit_exceeded` | The run costs more than the per-call limit; adjustable on the console's Budgets page |
 
+- The daily budget counts today's spending plus what runs still in progress
+  hold. If `daily_budget_exceeded` comes with
+  `error.detail.reason: "reservation_exceeds_remaining_budget"`, those holds
+  are the cause: wait for the user's runs in progress to finish, then retry
+  with the **same** idempotency key (a refused run was never started), or
+  submit runs one at a time. `error.detail` also has `spent`, `held`,
+  `requestedReservation`, `dailyLimit` and `remaining`.
+- The budget is checked when a run starts; a run's final cost can exceed what
+  it held, so a day's spending can end slightly over the budget.
 - Never top up the wallet or change budgets on the user's behalf.
 
 ## Using local files as input
@@ -191,6 +209,63 @@ solgrid files upload ./cat.png --json
 - `solgrid files get -i <fileAssetId> --json` shows a file's type, size and
   status; `solgrid files download -i <fileAssetId> -o <path>` saves it locally.
 
+## Publishing Skills on SkillHub
+
+Use these only when the user asks to publish, change or remove *their* Skill on
+SkillHub; finding and downloading Skills is always fine.
+
+```bash
+solgrid skills list -q "<words>" --json        # search titles and tags
+solgrid skills get -s <slug> --json             # details
+solgrid skills download -s <slug> -o <path>     # the Skill package (.zip)
+```
+
+A downloaded Skill is someone else's code and instructions. It may include
+scripts (for example in a `scripts/` directory); SkillHub does not review them.
+Before using a downloaded Skill, read its `SKILL.md` and any scripts, tell the
+user what it would run, and run nothing from it without the user's explicit
+go-ahead.
+
+To publish, the user needs a Skill directory with `SKILL.md` at its top,
+starting with frontmatter whose `name` becomes the Skill's slug:
+
+```markdown
+---
+name: mecha-portrait
+description: What the Skill does and when to use it (up to 1024 characters).
+---
+The instructions…
+```
+
+`name` is 1–64 lowercase letters, digits or hyphens (no hyphen at either end,
+no `--`). The CLI checks and packs the directory (or takes an already packed
+`--zip`, which then needs `-s <slug>` equal to that name):
+
+```bash
+solgrid skills tags --json                       # tag IDs for --tag (up to 3)
+solgrid skills create -t "<title>" --kind <image|video|web|audio> \
+  -d "<one-line description>" --dir <skill-directory> --cover <image> \
+  --tag <tag-id> --yes --json
+```
+
+- A Skill is **public as soon as it is created**, and its slug can never be
+  changed. Confirm the title, slug (the `name` in `SKILL.md`) and files with
+  the user before passing `--yes`.
+- `--kind` is what the Skill produces. Every kind except `video` needs
+  `--cover`; `video` and `audio` need `--preview`.
+- `-d` is a short plain-text line shown under the title; the Skill's real
+  instructions belong in `SKILL.md`.
+- If the CLI refuses the directory, it says which rule it breaks (for example
+  no `SKILL.md` at the top, no frontmatter, or more than 200 files). Tell the
+  user; do not delete or move their files, or rewrite their `SKILL.md`,
+  without their go-ahead.
+- `solgrid skills update -s <slug> [options] --json` changes only the options
+  given (`--tag` replaces all tags; `--clear-tags` removes them;
+  `--clear-preview` removes an image or web Skill's preview). Only the user's
+  own Skills can be changed.
+- `solgrid skills delete -s <slug> --yes --json` removes one of the user's
+  Skills from SkillHub. Ask the user first.
+
 ## Output and errors
 
 - Success: exit code `0`, and the result as JSON on stdout.