@cloudglue/tinycloud 0.3.0

package/skills/tinycloud/reference/verbs.md

@@ -0,0 +1,180 @@
+# Verbs: commands, flags, and cost classes
+
+`tinycloud commands --json` is the machine-readable source of truth — name,
+aliases, summary, cost class, auth requirement, flags, and subcommands for
+every verb. Regenerate doubts from it instead of trusting prose.
+
+| Verb | Cost | Auth | Use |
+|---|---|---|---|
+| `watch` | cloud | yes | Analyze a video → reusable context + Cloudglue-ready ref |
+| `extract` | cloud | yes | Pull structured facts, entities, or moments |
+| `caption` | varies | no | Subtitles and transcripts (SRT/VTT/ASS) |
+| `search` | local | no | Local keyword search over cached context |
+| `probe` | cloud | yes | Semantic moment/video search over a Cloudglue-ready scope |
+| `ask` | cloud | yes | Grounded Q&A over one or more videos |
+| `clip` | local | no | Cuts, thumbs, audio, stitch, split, transcode, burn, explore |
+| `grab` | network | no | Download a remote video (YouTube, TikTok, Loom, direct) |
+| `library` | varies | no | Collections, connectors, local mirrors, sync |
+| `jobs` | network | yes | Poll/wait/forget tracked async jobs |
+| `workflow` | varies | no | Validate/plan/run workflow recipes |
+| `publish` | cloud | yes | Publish HTML/code artifacts as Cloudglue Sites |
+| `setup` | local | no | Credentials and service connections |
+
+Cloud verbs run through the configured Cloudglue API key.
+`caption`/`library`/`workflow` vary by what they end up doing.
+
+## Per-verb flags
+
+Flags shared by most verbs are listed once at the bottom.
+
+### watch — analyze a video
+
+```bash
+tinycloud watch <source> [--segment uniform:20|chapters|shots|segments]
+  [--profile default|light|custom] [--speech-only | --visual-only]
+  [--start <t>] [--end <t>] [--transcript] [--content] [--json-index]
+  [--background]
+```
+
+### extract — structured facts
+
+```bash
+tinycloud extract "<query>" <source> --json          # free-form query
+tinycloud extract --schema ./schema.json <source>    # JSON-schema-shaped output
+  [--segment-level] [--segmentation chapters|shots|segments]
+  [--include-thumbnails] [--transcript-mode] [--background]
+```
+
+### caption — subtitles and transcripts
+
+```bash
+tinycloud caption <source> [--format srt|vtt|ass] [--transcript]
+  [--diarize] [--word-level] [-o <file-or-dir>]
+```
+
+### search — local keyword search (free)
+
+```bash
+tinycloud search "<keyword>" [--in <paths|source-ids|collection-ids|all>]
+  [--field speech|visual|text|entities] [--limit 50]
+```
+
+### probe — semantic search (cloud)
+
+```bash
+tinycloud probe "<query>" --in collection:col_… [--scope file|segment] [--limit 20]
+```
+
+### ask — grounded Q&A (cloud)
+
+```bash
+tinycloud ask "<question>" --in <source|collection:col_…|all>
+  [--include-citations[=false]]
+```
+
+Never pass `--background` to `ask`.
+
+### clip — local derivatives (free, ffmpeg-backed)
+
+Subcommands: `cut thumbs stitch transcode burn extract-audio split info explore`
+
+```bash
+tinycloud clip info <source> --json
+tinycloud clip cut <source> --start 12 --end 28 -o out.mp4
+tinycloud clip thumbs <source> --interval 5 -o thumbs/
+tinycloud clip stitch <a> <b> … -o out.mp4 [--reencode]
+tinycloud clip transcode <source> --resolution 1920x1080 [--fps 30] [--preset fast] -o out.mp4
+tinycloud clip burn <source> --subtitle-file subs.srt [--subtitle-style <ass-style>] -o out.mp4
+tinycloud clip extract-audio <source> --audio-format mp3 -o out.mp3
+tinycloud clip split <source> --target-size-mb 50 [--min-chunk-seconds 30] -o chunks/
+tinycloud clip explore <source> --title "Explorer" -o explorer.html
+tinycloud clip cut --from-findings -o clips/        # cut timestamped findings piped from extract
+```
+
+### grab — download remote video
+
+```bash
+tinycloud grab <url> [-o <file-or-dir>] [--audio-only] [--format <yt-dlp-selector>]
+```
+
+### library — collections and connectors
+
+```bash
+tinycloud library collections list --json
+tinycloud library collections show <col_id> --json
+tinycloud library collections sync <col_id> --artifacts descriptions,transcripts,thumbnails,metadata --json
+tinycloud library connectors list --json
+tinycloud library connectors files <connector-id> [--limit 25] [--page-token <t>] --json
+tinycloud library connectors sync <connector-id> <uri> --json   # e.g. grain://recording/<id>
+```
+
+`connectors files` also takes provider-specific filters: `--from`/`--to`
+(Zoom, Grain dates), `--folder-id` (Google Drive), `--path` (Dropbox),
+`--bucket`/`--prefix` (S3/GCS), `--title-search`/`--team`/`--meeting-type`
+(Grain). Collection IDs (`col_…`) are stable; collection names are
+display-only.
+
+### jobs — async work
+
+```bash
+tinycloud jobs list [--status pending|running|completed|failed] [--limit N] --json
+tinycloud jobs poll <job-id> --json
+tinycloud jobs wait <job-id> --timeout 120s --json
+tinycloud jobs forget <job-id> --json
+```
+
+### workflow — packaged recipes
+
+```bash
+tinycloud workflow list --json
+tinycloud workflow validate <name-or-path.yaml> --json
+tinycloud workflow plan <name-or-path.yaml> <source> --json    # free, no side effects
+tinycloud workflow <name> <source> [--param k=v] [--segment <s>] [--out <dir>]
+  [--allow-command | --no-command] [--max-parallel N] [--yes] --json
+```
+
+`workflow status` and `workflow resume` are NOT implemented in 0.3.x.
+
+### publish — Cloudglue Sites
+
+```bash
+tinycloud publish <html-file-or-dir> [--name <site-name>]
+  [--visibility public|private] --json
+tinycloud publish list --json                       # sites for this account, with URLs
+tinycloud publish unpublish <site-ref> --json       # site_id, site name, or the --name label
+```
+
+`public` = anyone with the link; `private` = Cloudglue account members only
+(same URL, edge-gated). Default keeps the site's current visibility.
+Republishing identical content makes no network calls; flipping visibility
+patches without re-uploading. `list`/`unpublish` are gated by the
+`publish.manage.v1` feature id.
+
+Note: `--name` is a label for the artifact (republishing reuses it) — the
+site itself gets a generated name (e.g. `young-fire-2486`) shown by
+`publish list`. `unpublish` resolves any of: the `site_id` UUID, the
+generated site name, or your `--name` label.
+
+### setup — credentials
+
+```bash
+tinycloud setup --check --json      # probe configured services (exit 0 always)
+tinycloud setup --list --json       # known services
+tinycloud setup cloudglue --api-key <key>   # or --stdin
+```
+
+## Shared flags
+
+Output: `--json` (force JSONL envelopes), `--pretty` (one JSON array),
+`--text`, `--format json|text|tsv`,
+`--view envelopes|segments|findings|citations|outputs|matches`,
+`--data raw`, `--raw-output` (raw backend payload; disables pipe protocol),
+`--quiet`, `--verbose`.
+
+Cache/spend — on `watch`, `extract`, `caption`, and `workflow` only:
+`--refresh` (recompute), `--no-cache` (no persistence), `--cached` (reuse
+exact-match history), `--no-upload` (refuse cloud upload → `needs_upload`),
+`--no-download` (refuse local materialization → `needs_download`).
+`ask`/`probe` always call the cloud; use `search` for a free cached lookup.
+
+Source reuse (`watch`/`extract`/`caption`): `--source-id <id>`, `--result-id <id>`.

package/skills/tinycloud/reference/workflow-authoring.md

@@ -0,0 +1,145 @@
+# Authoring workflow recipes
+
+Workflows are YAML/JSON DAGs over the same operation verbs as the direct CLI.
+Use one when the task is a repeatable recipe with stable inputs and declared
+outputs. Workflow schema version: `"1"`.
+
+```bash
+tinycloud workflow validate ./my-skill.yaml --json        # check before shipping
+tinycloud workflow plan ./my-skill.yaml demo.mp4 --json   # resolve graph, no side effects, free
+tinycloud workflow run ./my-skill.yaml demo.mp4 --allow-command --json
+```
+
+## Recipe shape
+
+```yaml
+name: video-report
+version: 1
+description: Analyze a video and render an HTML report.
+permissions: [command]        # only if the recipe has command steps
+
+inputs:
+  source: { type: source, required: true }
+  out: { type: path, default: "${{ run.dir }}/video-report.html" }
+
+steps:
+  - id: context
+    run: watch
+    with:
+      source: "${{ inputs.source }}"
+
+  - id: fields
+    run: extract
+    from: context            # pipe the prior envelope in
+    needs: [context]         # ordering
+    with:
+      query: "Key topics, important moments, and takeaways."
+
+  - id: render
+    run: command
+    needs: [context, fields]
+    with:
+      command: node
+      args:
+        - ./scripts/render.js
+        - --describe-file
+        - "${{ steps.context.file }}"
+        - --extract-file
+        - "${{ steps.fields.file }}"
+        - --out
+        - "${{ inputs.out }}"
+    output: { type: file, as: html, path: "${{ inputs.out }}" }
+
+outputs:
+  html: "${{ steps.render.path }}"
+```
+
+Bind inputs from the CLI positionally for `source`, or `--param k=v` for
+named values.
+
+## Step nodes
+
+| Node | `run` | Purpose |
+|---|---|---|
+| Operation | any dispatchable verb (`watch extract caption search probe ask clip grab library jobs workflow publish setup`) | Same handler as `tinycloud <verb>` |
+| Command | `command` | Custom local code; cwd is the recipe directory |
+
+Operation steps take CLI flags under `with` (long names, no dashes). Known
+positional names (`query question source url input artifact action group
+subcommand collection connector job id`) become positionals. For subcommands
+where order matters, use an explicit `args` array:
+
+```yaml
+- id: thumbs
+  run: clip
+  needs: [context]
+  with:
+    args: [thumbs, "${{ inputs.source }}"]
+    interval: 5
+    out: "${{ run.dir }}/thumbs"
+```
+
+Booleans become `--flag` when true; arrays repeat the flag. Relative `schema`
+and command paths resolve against the recipe directory, so a skill can bundle
+SKILL.md, YAML, scripts, schemas, and templates together.
+
+## Step fields
+
+| Field | Purpose |
+|---|---|
+| `id` | Unique step id |
+| `run` | Operation verb or `command` |
+| `needs` | Earlier step ids that must have run (ordering) |
+| `from` | Pipe a prior step envelope into this operation |
+| `foreach` | Run once per item of an input/prior value (`${{ inputs.item }}`) |
+| `with` | Arguments and flags |
+| `output` | Declare a produced file: `{ type: file\|files\|json\|text\|refs, as: html\|code\|data\|image\|file, path: … }` |
+
+## Interpolation
+
+| Reference | Meaning |
+|---|---|
+| `${{ inputs.source }}` | Top-level input |
+| `${{ inputs.item }}` | Current `foreach` item |
+| `${{ run.id }}` / `${{ run.dir }}` | Run id / run directory |
+| `${{ steps.<id>.file }}` | Materialized JSON output path of a verb step (alias `path`) |
+| `${{ steps.<id>.result_id }}` / `source_id` / `status` / `ref` / `data` | Prior step envelope fields |
+| `${{ steps.<id>.describe_raw }}` | Raw describe JSON path for a `watch` step |
+
+A value that is exactly one expression keeps its type; embedded expressions
+stringify.
+
+## Command gating
+
+- `permissions: [command]` in the recipe allows command steps for trusted
+  skills.
+- `--allow-command` allows them for an ad hoc run.
+- `--no-command` always disables command execution.
+
+## Outputs and run semantics
+
+Top-level `outputs` declares machine-readable final values; per-step `output`
+declares produced files. The final workflow envelope carries `data.steps`,
+`data.artifacts[].path`, and `data.outputs` — report `data.outputs.<name>` to
+the user. Run files live under `./tinycloud-output/runs/<run_id>/` (the
+`--out` flag moves the output base).
+
+`--background` is not inherited by steps; a step that returns `pending` or
+`paused` finalizes the workflow as `partial`. `workflow status` / `resume`
+are not implemented in 0.3.x — treat `partial`/`paused` as terminal.
+
+## Installing a custom recipe as a tinycloud-agent skill
+
+```text
+~/.tinycloud/skills/my-skill/    (or .tinycloud/skills/my-skill/ project-local)
+  SKILL.md
+  my-skill.yaml
+  scripts/render.js
+  package.json                   ({"type": "module"})
+```
+
+The tinycloud agent picks it up on next start; from any shell it runs by
+path: `tinycloud workflow run ~/.tinycloud/skills/my-skill/my-skill.yaml demo.mp4 --allow-command --json`.
+
+To wrap a recipe as a skill for *this* host agent instead, see the
+`tinycloud-skill-creator` skill in this repo.

package/skills/tinycloud/scripts/preflight.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Tinycloud skill preflight. Prints exactly ONE actionable line and exits:
+#   0  ok — tinycloud is installed, compatible, and configured
+#   10 tinycloud binary missing (or broken)
+#   11 installed version outside the supported range (too old or too new)
+#   12 installed version lacks required feature ids
+#   13 installed and compatible but Cloudglue credentials are missing
+set -u
+
+# Mirror tinycloud-skill.json: min_version / supported_range upper bound
+# (CI diffs these against the manifest).
+MIN_VERSION="0.3.0"
+MAX_VERSION_EXCLUSIVE="0.4.0"
+INSTALL_CMD='curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash'
+# Kept in sync with ../tinycloud-skill.json required_features (CI diffs them).
+REQUIRED_FEATURES="envelope.v1 watch.v1 extract.v1 caption.v1 search.v1 probe.v1 ask.v1 clip.v1 grab.v1 jobs.v1 library.collections.v1 workflow.v1 publish.v1 publish.manage.v1 setup.v1"
+
+# 1) Binary present and responsive?
+if ! command -v tinycloud >/dev/null 2>&1; then
+  echo "preflight: tinycloud not installed — run: ${INSTALL_CMD}"
+  exit 10
+fi
+
+# </dev/null matters: pre-0.3.0 binaries open an interactive TUI on this
+# invocation and would otherwise hang waiting for input.
+VERSION_JSON="$(tinycloud --version --json </dev/null 2>/dev/null)" || VERSION_JSON=""
+if [ -z "$VERSION_JSON" ]; then
+  echo "preflight: tinycloud found but 'tinycloud --version --json' failed — reinstall: ${INSTALL_CMD}"
+  exit 10
+fi
+
+# 2) Version >= minimum?
+VERSION="$(printf '%s' "$VERSION_JSON" | sed -n 's/.*"version":[[:space:]]*"\([^"]*\)".*/\1/p')"
+if [ -z "$VERSION" ]; then
+  echo "preflight: tinycloud did not report machine-readable version info (older than ${MIN_VERSION}?) — upgrade: ${INSTALL_CMD}"
+  exit 11
+fi
+LOWEST="$(printf '%s\n%s\n' "$VERSION" "$MIN_VERSION" | sort -t. -k1,1n -k2,2n -k3,3n | head -n1)"
+if [ "$LOWEST" != "$MIN_VERSION" ]; then
+  echo "preflight: tinycloud ${VERSION} is below required ${MIN_VERSION} — upgrade: ${INSTALL_CMD}"
+  exit 11
+fi
+
+# Upper bound of the skill's supported_range: version must be < MAX_VERSION_EXCLUSIVE
+LOWEST_MAX="$(printf '%s\n%s\n' "$VERSION" "$MAX_VERSION_EXCLUSIVE" | sort -t. -k1,1n -k2,2n -k3,3n | head -n1)"
+if [ "$VERSION" = "$MAX_VERSION_EXCLUSIVE" ] || [ "$LOWEST_MAX" != "$VERSION" ]; then
+  echo "preflight: tinycloud ${VERSION} is newer than this skill supports (< ${MAX_VERSION_EXCLUSIVE}) — update the skill: npx @cloudglue/tinycloud skills install --force"
+  exit 11
+fi
+
+# 3) Required feature ids present? (feature ids are quoted JSON strings, so
+#    substring matching against the raw JSON is safe)
+MISSING=""
+for f in $REQUIRED_FEATURES; do
+  case "$VERSION_JSON" in
+    *"\"$f\""*) : ;;
+    *) MISSING="${MISSING}${MISSING:+,}$f" ;;
+  esac
+done
+if [ -n "$MISSING" ]; then
+  echo "preflight: tinycloud ${VERSION} lacks required features [${MISSING}] — upgrade: ${INSTALL_CMD}"
+  exit 12
+fi
+
+# 4) Credentials? setup --check --json reports data.ok (no-space JSON output;
+#    keep the spaced variant as belt-and-braces)
+CHECK_JSON="$(tinycloud setup --check --json </dev/null 2>/dev/null)" || CHECK_JSON=""
+case "$CHECK_JSON" in
+  *'"ok":true'*|*'"ok": true'*)
+    echo "preflight: ok — tinycloud ${VERSION} ready (all features + credentials present)"
+    exit 0
+    ;;
+  *)
+    echo "preflight: tinycloud ${VERSION} installed but Cloudglue credentials missing — run: tinycloud setup cloudglue --api-key <key>  (or export CLOUDGLUE_API_KEY=...)"
+    exit 13
+    ;;
+esac

package/skills/tinycloud/tinycloud-skill.json

@@ -0,0 +1,26 @@
+{
+  "skill_version": "0.1.0",
+  "tinycloud": {
+    "min_version": "0.3.0",
+    "supported_range": ">=0.3.0 <0.4.0",
+    "required_features": [
+      "envelope.v1",
+      "watch.v1",
+      "extract.v1",
+      "caption.v1",
+      "search.v1",
+      "probe.v1",
+      "ask.v1",
+      "clip.v1",
+      "grab.v1",
+      "jobs.v1",
+      "library.collections.v1",
+      "workflow.v1",
+      "publish.v1",
+      "publish.manage.v1",
+      "setup.v1"
+    ],
+    "envelope_schema": "1",
+    "workflow_schema": "1"
+  }
+}

package/skills/tinycloud-init/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: tinycloud-init
+description: >-
+  Set up tinycloud from scratch: install the CLI, configure the Cloudglue API
+  key, verify everything works, and run a first command. Use when the user
+  wants to get started with tinycloud, set up / initialize / onboard
+  tinycloud, or when another tinycloud skill reports the CLI or credentials
+  are missing.
+argument-hint: "[optional: a video file to test with]"
+arguments: video
+---
+
+# Set up tinycloud
+
+Walk the user from nothing to a working, verified tinycloud install. End the
+session with one successful command, not a checklist. Work through the steps
+in order, skipping any that already pass.
+
+## 1. Is the CLI installed?
+
+```bash
+command -v tinycloud && tinycloud --version --json </dev/null
+```
+
+If installed and the JSON reports `"version"` ≥ 0.3.0, go to step 2. If
+missing (or no machine-readable version), install it — ask the user which
+they prefer:
+
+```bash
+npm install -g @cloudglue/tinycloud          # canonical (Node >= 18)
+# or
+curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+```
+
+The first run downloads the platform distribution (~90 MB, one time). More
+at https://tinycloud.sh. Windows is unsupported — use WSL2.
+
+## 2. Is a Cloudglue API key configured?
+
+```bash
+tinycloud setup --check --json </dev/null
+```
+
+If `data.ok` is `true`, go to step 3. Otherwise tell the user: cloud
+features run through a Cloudglue account — keys live at
+[app.cloudglue.dev](https://app.cloudglue.dev) (usage billed per the
+[rate card](https://app.cloudglue.dev/home/billing/rate-card)). Ask them to
+paste their API key, then configure it via stdin so the key never lands in
+shell history or process args:
+
+```bash
+printf '%s' "<key>" | tinycloud setup cloudglue --stdin
+```
+
+Re-run `tinycloud setup --check --json` and confirm `data.ok == true`.
+
+## 3. Prove it works (free)
+
+```bash
+tinycloud workflow validate summary --json    # exercises the recipe engine, no cloud calls
+```
+
+Expect `status: "ready"`. If the user provided a video (`$video`) or has one
+handy, also show them something real — still free and local:
+
+```bash
+tinycloud clip info <video> --json            # duration/resolution/codecs via bundled ffprobe
+```
+
+## 4. Hand off
+
+Report what's now working and point forward:
+
+- "Analyze a video": `tinycloud watch <video> --json` (first cloud call —
+  uses the API key)
+- One-command workflows: `tinycloud workflow list --json` (sales-coaching,
+  blog-post, ad-analysis, meeting-breakdown, youtube-publish, …)
+- If the general `tinycloud` skill is installed alongside this one, it
+  documents the full CLI, envelope contract, and a glossary; its
+  `scripts/preflight.sh` re-checks this setup any time.
+
+## Troubleshooting
+
+- `tinycloud` found but `--version --json` prints a UI instead of JSON →
+  pre-0.3.0 install; upgrade via either install command above.
+- `setup --check` reports `ok: false` after configuring → key was rejected;
+  re-paste it (watch for stray whitespace) or generate a fresh key.
+- Corporate proxy: the npm launcher honors `HTTPS_PROXY` (falls back to
+  curl for the download).

package/skills/tinycloud-skill-creator/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: tinycloud-skill-creator
+description: >-
+  Create a new tinycloud-powered skill: a SKILL.md plus optional workflow
+  recipe and render script that run tinycloud CLI commands and produce
+  deliverables (HTML reports, markdown, JSON, clips, published sites). Use
+  when the user wants to build, scaffold, or package a custom repeatable
+  video workflow as a skill — for this agent, for another agent, or for the
+  tinycloud agent itself. Requires the tinycloud CLI.
+argument-hint: "[skill goal or name]"
+arguments: goal
+---
+
+# Create a tinycloud-powered skill
+
+Walk the user from an idea ("turn a sales call into a follow-up email page")
+to an installed, validated skill. The skills you create run tinycloud verbs
+and workflows, but their OUTPUT is a deliverable consumed outside the
+conversation: an HTML page, a markdown doc, a JSON payload, clip files,
+captions, a published site URL. Author for that external consumer.
+
+Prerequisite: the tinycloud CLI configured with a Cloudglue API key. If the
+general `tinycloud` skill is installed alongside this one, run its
+`scripts/preflight.sh` first; otherwise check
+`tinycloud setup --check --json` → `data.ok` (install:
+`npm install -g @cloudglue/tinycloud`, see https://tinycloud.sh). For the
+recipe YAML schema, use the `tinycloud` skill's reference/workflow-authoring.md
+if installed, or the schema reference bundled with the binary at
+`<install>/skills/skill-creator/references/workflow-schema.md`.
+
+## 1. Interview
+
+Before writing anything, establish:
+
+- **Deliverable**: what file(s) does the skill produce, and who consumes
+  them? (HTML report, markdown summary, JSON for an API, clips, captions, a
+  published site URL.)
+- **Inputs**: one video? a URL? a collection? several sources?
+- **Shape**: a repeatable recipe with known steps → workflow-backed; or
+  exploratory work where the agent picks each next command → direct-verb.
+- **Where it lives** (pick the target before scaffolding):
+  - *This host agent* (Claude Code, etc.): a skill directory in the agent's
+    skills location (e.g. `~/.claude/skills/<name>/` or the project's
+    `.claude/skills/<name>/`) whose SKILL.md runs the recipe **by path**.
+  - *The tinycloud agent*: `~/.tinycloud/skills/<name>/` (global) or
+    `.tinycloud/skills/<name>/` (project), picked up as `/skills:<name>`.
+
+## 2. Scaffold
+
+The tinycloud distribution bundles a scaffolder next to the binary. Locate
+it (try in order; fall back to hand-authoring from the workflow-authoring
+reference if absent):
+
+```bash
+TC_DIR="$(dirname "$(command -v tinycloud)")"                      # curl install
+SCAFFOLDER="$TC_DIR/skills/skill-creator/scripts/init-skill.js"
+# npm-wrapper installs keep versions under ~/.tinycloud/versions/<v>/
+[ -f "$SCAFFOLDER" ] || SCAFFOLDER="$(ls -d ~/.tinycloud/versions/*/skills/skill-creator/scripts/init-skill.js 2>/dev/null | tail -1)"
+
+node "$SCAFFOLDER" <skill-name> --description "<one-line description>" \
+  --dir <target-dir> --pattern workflow|direct
+```
+
+It creates `<target-dir>/<skill-name>/`: a SKILL.md skeleton, and for the
+workflow pattern a `<skill-name>.yaml` recipe plus `scripts/render.js` and
+`package.json`. It never overwrites an existing directory.
+
+## 3. Author
+
+Edit the scaffolded files with the user's specifics.
+
+- **Description is the trigger.** Name the deliverable and the input ("Turn
+  a sales call into a follow-up email HTML page"), not the mechanism ("uses
+  watch and extract").
+- **Body**: imperative instructions — the exact commands to run, how to
+  branch on envelope `status`, what to report back. Keep SKILL.md short;
+  push schemas, examples, and template detail into files next to it.
+  Relative paths in workflow YAML resolve against the recipe directory.
+- **Generalize**: the skill will run on videos you have not seen — never
+  hard-code anything from the example video used while authoring.
+- For a host-agent skill, the SKILL.md body invokes the recipe by path:
+
+  ```bash
+  tinycloud workflow run ${CLAUDE_SKILL_DIR}/<skill-name>.yaml $source --allow-command --json
+  ```
+
+**Output contract** (the "outside the agent" rules):
+
+- Write deliverables under `./tinycloud-output/` or `${{ run.dir }}` and
+  report the absolute path; never leave outputs only in conversation text.
+- stdout is machine output (envelopes/paths); logs and progress go to stderr.
+- In render scripts, inject data into HTML templates via one single-token
+  placeholder (replace `DATA_JSON_HERE` with `JSON.stringify(data)`), not
+  interpolated JS object literals.
+- If the deliverable should be a URL, finish with
+  `tinycloud publish <html-or-dir> --visibility public|private --json` and
+  ask the user public-or-private before the first publish.
+
+## 4. Validate and dry-run
+
+```bash
+tinycloud workflow validate <dir>/<skill-name>/<skill-name>.yaml --json
+tinycloud workflow plan <dir>/<skill-name>/<skill-name>.yaml <test-source> --json
+tinycloud workflow run <dir>/<skill-name>/<skill-name>.yaml <test-source> --allow-command --json
+```
+
+`validate` checks the recipe (free), `plan` resolves the graph with no side
+effects (free), `run` executes — cloud steps run through the configured
+Cloudglue API key. Branch on the envelope `status` — `ready` means consume
+`data.outputs`; anything else means stop and surface the next action. Open
+the produced deliverable and check it against the user's intent before
+declaring success.
+
+## 5. Gate and distribute
+
+- Command steps are gated: keep `permissions: [command]` in the recipe for
+  trusted skills, or require `--allow-command` per run. `--no-command`
+  always wins.
+- For skills distributed to other machines, gate on the installed binary:
+  `tinycloud --version --json` reports `version` and `features` — document a
+  `min_version` in the skill (the general `tinycloud` skill's
+  `tinycloud-skill.json` shows the manifest pattern, when installed).
+
+## Iterating on an existing skill
+
+Read its SKILL.md and recipe, re-run `workflow validate`/`plan` after edits,
+and re-test with the same source the user reported the problem on. Tighten
+the description if the skill failed to trigger; move detail out of SKILL.md
+if it grew past ~150 lines.