@cloudglue/tinycloud 0.3.0

package/skills/tinycloud/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: tinycloud
+description: >-
+  Deep video work via the tinycloud CLI (Cloudglue). Use whenever the task
+  involves understanding or manipulating video or audio-visual media: analyze
+  or summarize a video, extract structured facts/moments/entities, generate
+  captions or transcripts (SRT/VTT), search inside videos, answer questions
+  about footage, cut/stitch/thumbnail/transcode clips, download remote videos,
+  browse Cloudglue collections, or run packaged video workflows. Triggers on
+  video files (.mp4, .mov, .webm, ...), YouTube/video URLs, Cloudglue
+  collections, or any "what's in this video / make clips / caption this"
+  request. Every command returns a machine-readable JSON envelope.
+---
+
+# Tinycloud: video operations for agents
+
+`tinycloud` is a CLI for video understanding and editing, backed by Cloudglue.
+Drive it with shell commands and parse JSON from stdout. Never scrape its
+human-readable output; always pass `--json` (single envelope) or rely on JSONL
+when piping.
+
+## 0. Preflight (always do this first)
+
+```bash
+bash ${CLAUDE_SKILL_DIR}/scripts/preflight.sh
+```
+
+(Outside Claude Code, run `scripts/preflight.sh` from this skill's directory.)
+It prints exactly one line telling you what to do: install, upgrade, configure
+credentials, or proceed. If `tinycloud` is missing entirely:
+
+```bash
+npm install -g @cloudglue/tinycloud
+# or: curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+```
+
+Credentials (required for cloud verbs): `tinycloud setup cloudglue --api-key <key>`
+(or `export CLOUDGLUE_API_KEY=...`). Verify with
+`tinycloud setup --check --json` → `data.ok == true`.
+
+## 1. The envelope contract
+
+Every command emits a Tinycloud envelope on stdout. Logs go to stderr. Fields
+you branch on: `status`, `data` (verb-specific payload), `ref` (reusable
+source reference), `next` (suggested follow-ups), `setup` (how to fix missing
+credentials), `error` (`{code, message, retryable}`).
+
+| status | what you do |
+|---|---|
+| `ready` | consume `data` / `ref` / file paths and continue |
+| `pending` | async job started — `tinycloud jobs wait <meta.job_id> --timeout 120s --json` |
+| `needs_credentials` | run the command in `setup.command` or set the env in `setup.env` |
+| `needs_upload` | cloud upload required (runs through the user's Cloudglue account) — rerun without `--no-upload` or confirm with the user |
+| `needs_download` | fetch locally first: `tinycloud grab <url> --json` |
+| `paused` | stop; surface `resume` info to the user (resume is not automated in 0.3.x) |
+| `error` | stop; report `error.message`; retry only if `error.retryable` |
+
+Exit codes: 0 = ready/pending/paused, 1 = error, 2 = needs_credentials,
+3 = needs_upload/needs_download. Branch on `status`, not exit code alone.
+Full schema and error codes: [reference/envelope.md](reference/envelope.md).
+
+## 2. Core verbs (cheat sheet)
+
+Cloud verbs (`watch extract probe ask publish`) call the Cloudglue API using
+the configured key — usage is billed per the
+[rate card](https://app.cloudglue.dev/home/billing/rate-card). `search clip
+setup` are local and free; `grab jobs` are network-only.
+`tinycloud commands --json` is the authoritative command/flag list.
+
+```bash
+# Understand a video (creates reusable cached context + cloud-ready ref)
+tinycloud watch ./demo.mp4 --json
+
+# Pipe context into structured extraction (JSONL flows between pipes)
+tinycloud watch ./demo.mp4 --json | tinycloud extract "key moments with timestamps" --json
+tinycloud extract --schema ./schema.json ./demo.mp4 --segment-level --json
+
+# Captions / transcripts
+tinycloud caption ./demo.mp4 --format srt --transcript -o ./tinycloud-output/captions/ --json
+
+# Find things: local keyword search vs cloud semantic search vs Q&A
+tinycloud search "pricing" --in ./demo.mp4 --json
+tinycloud probe "product demo moments" --in collection:col_123 --scope segment --limit 5 --json
+tinycloud ask "What objections came up?" --in ./demo.mp4 --json
+
+# Local editing (free, ffmpeg-backed)
+tinycloud clip info ./demo.mp4 --json
+tinycloud clip cut ./demo.mp4 --start 12 --end 28 -o ./tinycloud-output/clip.mp4 --json
+tinycloud clip thumbs ./demo.mp4 --interval 5 -o ./tinycloud-output/thumbs/ --json
+tinycloud clip burn ./demo.mp4 --subtitle-file ./captions/demo.srt -o ./out.mp4 --json
+
+# Remote videos, collections, async jobs
+tinycloud grab https://youtu.be/<id> -o ./tinycloud-output/grabbed/ --json
+tinycloud library collections list --json
+tinycloud watch ./long.mp4 --background --json   # returns pending + meta.job_id
+tinycloud jobs wait <job-id> --timeout 120s --json
+
+# Publish an HTML artifact to Cloudglue Sites (manage with list / unpublish)
+tinycloud publish ./tinycloud-output/html/report.html --name report --visibility private --json
+tinycloud publish list --json
+```
+
+Per-verb details and all flags: [reference/verbs.md](reference/verbs.md).
+Multi-video batching and pipe semantics: [reference/pipelines.md](reference/pipelines.md).
+
+## 3. Workflows (packaged recipes)
+
+Repeatable pipelines run with one command and write outputs into a run
+directory:
+
+```bash
+tinycloud workflow list --json
+tinycloud workflow validate sales-coaching --json
+tinycloud workflow plan sales-coaching ./call.mp4 --json     # resolves the graph; free, no side effects
+tinycloud workflow sales-coaching ./call.mp4 --json
+```
+
+Parse the final envelope: `data.status` (`completed|partial|failed|paused`),
+`data.outputs` (named outputs, e.g. `outputs.html`), `data.artifacts[].path`.
+Files land under `./tinycloud-output/runs/<run_id>/`. Recipe render steps run
+local scripts: built-in recipes self-permit them (`permissions: [command]`),
+so no extra flag is needed; pass `--allow-command` only for a recipe run by
+path that lacks that permission. `--no-command` always disables them.
+Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow-authoring.md).
+
+## 4. Gotchas
+
+- Machine output is stdout; logs/progress are stderr. Keep stderr visible for
+  debugging, but never parse it.
+- Built-in recipes already permit their render steps (`permissions:
+  [command]`) — don't add `--allow-command` for them (host-agent permission
+  classifiers may flag it); it's only needed for path-run recipes without
+  that permission.
+- Sources: local paths, URLs, `cloudglue://files/<id>` URIs, or
+  `collection:col_…` — a bare file-id UUID is not accepted.
+- Do not pass `--background` to `ask`; background jobs exist only for tracked
+  async ops (`watch`, `extract`).
+- `workflow status` / `workflow resume` are not implemented in 0.3.x; treat
+  `paused`/`partial` as terminal and surface `resume` metadata to the user.
+- `--no-upload` / `--no-download` make commands refuse cloud upload / local
+  materialization and return `needs_upload` / `needs_download` instead — use
+  them to control spend, then branch.
+- Piping: downstream verbs consume JSONL envelopes from stdin; a non-`ready`
+  upstream envelope produces a blocked envelope downstream instead of running.
+- Keep generated files under `./tinycloud-output/` (override with the
+  `--out` flag where supported).
+- Cached results are reused automatically; `--refresh` forces re-computation,
+  `--no-cache` disables persistence.
+
+## 5. Reference (load on demand)
+
+- [reference/setup.md](reference/setup.md) — install, credentials, env vars, preflight details
+- [reference/verbs.md](reference/verbs.md) — every verb, flag, and cost class
+- [reference/envelope.md](reference/envelope.md) — full envelope schema, statuses, error codes, exit codes
+- [reference/pipelines.md](reference/pipelines.md) — pipes, batching, jobs, cache/spend-control flags
+- [reference/workflow-authoring.md](reference/workflow-authoring.md) — workflow YAML schema and custom recipes
+- [reference/glossary.md](reference/glossary.md) — tinycloud/Cloudglue terms (files, collections, connectors, refs, …)

package/skills/tinycloud/reference/envelope.md

@@ -0,0 +1,73 @@
+# The Tinycloud envelope
+
+Every command emits one envelope (or a JSONL stream of them) on stdout.
+Envelope schema version: `"1"` (reported in `--version --json` as
+`envelope_schema`). Absent fields are omitted, never `null` or `[]`.
+
+```json
+{
+  "tinycloud": "1",
+  "kind": "watch",
+  "status": "ready",
+  "result_id": "res_…",
+  "source_id": "src_…",
+  "ref": { "…": "reusable source reference" },
+  "data": { "…": "verb-specific payload" },
+  "meta": { "elapsed_ms": 1234, "requires": "cloud", "cache": { "identity": "hit" } },
+  "summary": "one-line human summary",
+  "next": [ { "…": "suggested follow-up commands" } ],
+  "setup": { "service": "cloudglue", "env": ["CLOUDGLUE_API_KEY"], "command": "tinycloud setup cloudglue" },
+  "resume": { "run_id": "…", "paused_step": "…", "resume_command": "…" },
+  "error": { "code": "validation", "message": "…", "retryable": false }
+}
+```
+
+| Field | Purpose |
+|---|---|
+| `status` | The branching field — see table below |
+| `kind` | Operation kind: `watch`, `extract`, `ask`, `workflow`, `setup`, … |
+| `result_id` | Stable result id for `--result-id` reuse and logs |
+| `source_id` | Stable source id when the operation targets media |
+| `ref` | Reusable source reference (carries `cloud_ready`, Cloudglue file/collection ids) for piping or later ops |
+| `data` | Verb-specific payload |
+| `meta` | `elapsed_ms`, `requires` (local\|network\|cloud\|varies), `cache` states (hit\|miss\|written\|skipped), `job_id`, `usage`, `model` |
+| `summary` | One-line human summary (do not parse) |
+| `next` | Suggested follow-up actions |
+| `setup` | Present with `needs_credentials`: how to fix |
+| `resume` | Present with `paused`: run/step info to surface to the user |
+| `error` | Present with `error` status: `{code, message, retryable, detail?}` |
+
+## Statuses and exit codes
+
+| status | exit | invariant | what you do |
+|---|---|---|---|
+| `ready` | 0 | `data` usable | consume and continue |
+| `pending` | 0 | `meta.job_id` set | `tinycloud jobs wait <id> --timeout 120s --json`; do NOT start downstream work |
+| `paused` | 0 | `resume` present | stop; surface resume info (resume not automated in 0.3.x) |
+| `needs_credentials` | 2 | `setup` present | run `setup.command` or set `setup.env` |
+| `needs_upload` | 3 | — | cloud upload required (runs through the user's Cloudglue account); rerun without `--no-upload` after confirming |
+| `needs_download` | 3 | — | materialize locally first (`tinycloud grab …`) |
+| `error` | 1 | `error` present | stop; report `error.message`; retry only if `error.retryable` |
+
+Batch runs exit with the worst status seen. Always branch on `status`, not
+the exit code alone.
+
+## Error codes
+
+`missing_api_key`, `insufficient_credits`, `file_not_found`,
+`file_not_ready`, `not_found`, `validation`, `needs_upload`,
+`needs_download`, `visual_analysis_requires_download`, `upstream`.
+
+`upstream` on a piped command means the upstream envelope was not `ready` —
+fix the upstream failure, don't retry downstream.
+
+## JSON vs JSONL vs text
+
+- On a TTY, commands default to human text. **Always pass `--json`.**
+- When piped, output defaults to JSONL (one envelope per line) — this is the
+  pipe protocol downstream verbs consume.
+- `--pretty` emits a single JSON array instead of JSONL.
+- `--view segments|findings|citations|outputs|matches` selects a data subset;
+  `--format tsv` renders tabular views for shell processing.
+- `--raw-output` prints the raw backend payload and disables the pipe
+  protocol — only for debugging.

package/skills/tinycloud/reference/glossary.md

@@ -0,0 +1,73 @@
+# Glossary: tinycloud and Cloudglue terms
+
+Quick definitions for terms that appear in tinycloud output, flags, and these
+docs. Use this when the user asks "what is a Cloudglue file / collection /
+connector?" or an envelope field needs explaining.
+
+## Platform
+
+- **Cloudglue** — the video-understanding API platform that powers
+  tinycloud's cloud verbs (analysis, extraction, semantic search, Q&A,
+  publishing). Account, API keys, and billing live at
+  [app.cloudglue.dev](https://app.cloudglue.dev); usage is billed per the
+  [rate card](https://app.cloudglue.dev/home/billing/rate-card).
+- **tinycloud** — the agent CLI distributed from this repo
+  (https://tinycloud.sh). Local verbs (`clip`, `search`, `setup`) run on your
+  machine; cloud verbs call Cloudglue with your API key.
+
+## Media and identity
+
+- **Cloudglue file** — a video uploaded to (or registered with) Cloudglue,
+  identified by a file id and addressable as `cloudglue://files/<id>`. The
+  first cloud operation on a local video uploads it once; later operations
+  reuse the file.
+- **Collection** — a named group of Cloudglue files (id `col_…`), e.g. "all
+  sales calls". Verbs scope to one with `--in collection:col_…`. Collection
+  ids are stable; display names are not.
+- **Data connector** — a linked external source of recordings (Zoom, Grain,
+  Google Drive, Dropbox, Loom, S3/GCS). `tinycloud library connectors …`
+  lists, browses (`files`, with provider-specific filters), and syncs
+  individual items by URI (e.g. `grain://recording/<id>`) so they become
+  Cloudglue files.
+- **Source** — anything a verb accepts as input: a local path, URL,
+  `cloudglue://files/<id>` URI, connector URI, or collection. Bare file-id
+  UUIDs are not accepted — wrap them as `cloudglue://files/<id>`.
+- **`ref` / `source_id` / `result_id`** — stable identifiers in every
+  envelope. `ref` is a reusable pointer to the analyzed source (including
+  `cloud_ready` and the Cloudglue file id) that pipes between verbs;
+  `--source-id`/`--result-id` flags reuse prior work explicitly.
+
+## Operations
+
+- **Envelope** — the JSON object every command prints on stdout
+  (`status`, `data`, `ref`, `meta`, `error`, …). The machine contract; see
+  reference/envelope.md.
+- **Watch context / describe** — the reusable analysis `tinycloud watch`
+  produces (summary, segments, transcript-ish context). Cached locally and
+  mirrored in Cloudglue, so later `extract`/`ask`/`search` reuse it instead
+  of re-analyzing.
+- **Segmentation** — how a video is split for analysis: `chapters`
+  (semantic), `shots` (visual cuts), `uniform:<seconds>` (fixed windows).
+- **Cache layers** — `meta.cache` reports `identity` (is this the same file
+  we've seen?) and `enrichment` (analysis results) as
+  `hit | miss | written | skipped`.
+- **Job** — a tracked async cloud operation (from `--background`), with
+  `meta.job_id`; managed via `tinycloud jobs list|poll|wait|forget`.
+
+## Workflows and outputs
+
+- **Workflow / recipe** — a YAML DAG of verb steps run by
+  `tinycloud workflow <name|path>`. Built-in recipes (sales-coaching,
+  blog-post, …) ship inside the binary.
+- **Run directory** — where a workflow writes everything:
+  `./tinycloud-output/runs/<run_id>/`. Single-verb outputs default under
+  `./tinycloud-output/`.
+- **Artifacts / outputs** — the workflow envelope's `data.artifacts[]`
+  (produced files with paths) and `data.outputs{}` (named results, e.g.
+  `outputs.html`).
+- **Command step** — a workflow step that runs a local script (e.g. an HTML
+  renderer); gated by `--allow-command` / recipe `permissions: [command]`.
+- **Cloudglue Sites** — hosted pages for published artifacts:
+  `tinycloud publish <html> --visibility public|private` returns a shareable
+  URL (private = Cloudglue account members only, same URL). Manage with
+  `publish list` and `publish unpublish <site-id | site-name | label>`.

package/skills/tinycloud/reference/pipelines.md

@@ -0,0 +1,104 @@
+# Pipelines: pipes, batching, async jobs, and spend control
+
+## The pipe protocol
+
+Tinycloud verbs compose through JSONL envelopes on stdin/stdout:
+
+```bash
+tinycloud watch ./demo.mp4 --json | tinycloud extract "key moments" --json
+```
+
+- The downstream verb parses each stdin line as an envelope; `ref` /
+  `source_id` flow through, so `extract` knows exactly which analyzed source
+  to use without re-uploading.
+- A non-`ready` upstream envelope produces a blocked downstream envelope with
+  `error.code: "upstream"` instead of running — fix upstream, don't retry
+  downstream.
+- Raw stdin lines that are file paths also work as batch sources:
+
+```bash
+cat sources.txt | tinycloud watch --json
+```
+
+- Piping watch envelopes into `search` / `probe` / `ask` auto-scopes them via
+  `ref.cloudglue_file_id` / collection ids.
+
+## Multi-video batching
+
+Most verbs accept multiple sources; output is JSONL with one envelope per
+source. The process exit code is the worst status seen. Iterate the lines and
+branch per envelope.
+
+```bash
+tinycloud watch ./a.mp4 ./b.mp4 --json
+tinycloud caption ./talks/*.mp4 --format srt -o ./tinycloud-output/captions/ --json
+```
+
+## Async jobs
+
+Long cloud operations (`watch`, `extract`) support `--background`:
+
+```bash
+tinycloud watch ./long.mp4 --background --json   # → status:"pending", meta.job_id
+tinycloud jobs wait <job-id> --timeout 120s --json
+tinycloud jobs list --status running --json
+tinycloud jobs poll <job-id> --json              # single non-blocking check
+tinycloud jobs forget <job-id> --json
+```
+
+Never start downstream work while an envelope is `pending`. `ask` does not
+support `--background`.
+
+## Spend control
+
+Cloud verbs run through the configured Cloudglue API key (usage per the
+[rate card](https://app.cloudglue.dev/home/billing/rate-card)). Patterns to
+control spend:
+
+```bash
+# Refuse uploads: returns needs_upload instead of spending
+tinycloud watch ./new.mp4 --no-upload --json
+
+# Reuse a prior watch's enrichment without re-uploading
+tinycloud extract "key moments" ./demo.mp4 --cached --json
+
+# Free local lookup over already-cached context (no cloud call at all)
+tinycloud search "pricing" --in ./demo.mp4 --json
+```
+
+- `--no-upload` → refuse Cloudglue upload/materialization (`needs_upload`).
+- `--no-download` → refuse local materialization (`needs_download`).
+- `--refresh` → force recompute (spends even on cache hits).
+- `--no-cache` → don't persist results (still spends).
+- These four flags exist on `watch`, `extract`, `caption`, and `workflow`
+  only — `ask`/`probe` always go to the cloud (use `search` for a free
+  cached lookup).
+- `meta.cache` in every envelope tells you what was reused vs written.
+
+## Worked examples
+
+```bash
+# Analyze → structured extraction (schema-shaped)
+tinycloud watch ./demo.mp4 --json \
+  | tinycloud extract --schema ./schema.json --segment-level --json
+
+# Caption → burn subtitles into the video
+tinycloud caption ./demo.mp4 --format srt -o ./tinycloud-output/captions/ --json
+tinycloud clip burn ./demo.mp4 \
+  --subtitle-file ./tinycloud-output/captions/demo.srt \
+  -o ./tinycloud-output/demo-captioned.mp4 --json
+
+# Remote video → analyze
+tinycloud grab https://youtu.be/<id> -o ./tinycloud-output/grabbed/ --json
+tinycloud watch ./tinycloud-output/grabbed/<file>.mp4 --json
+
+# Collection: mirror artifacts locally, then search/Q&A against it
+tinycloud library collections sync col_123 --artifacts descriptions,transcripts --json
+tinycloud probe "pricing discussion" --in collection:col_123 --scope segment --json
+tinycloud ask "What did customers object to?" --in collection:col_123 --json
+
+# Extract timestamped findings → cut them into clips
+tinycloud watch ./talk.mp4 --json \
+  | tinycloud extract "the three strongest quotes with timestamps" --json \
+  | tinycloud clip cut --from-findings -o ./tinycloud-output/quotes/ --json
+```

package/skills/tinycloud/reference/setup.md

@@ -0,0 +1,97 @@
+# Setup: install, credentials, and verification
+
+## Install
+
+```bash
+npm install -g @cloudglue/tinycloud     # then run: tinycloud
+# or run directly without installing:
+npx @cloudglue/tinycloud --version --json
+```
+
+The npm package is a small launcher: on first run it downloads the matching
+platform distribution (cached under `~/.tinycloud/versions/<version>/`),
+verifies its checksum, and execs the real binary. The package version pins
+the binary version, so `npx @cloudglue/tinycloud@<v>` always runs that exact
+tinycloud. `tinycloud update` moves to the latest release.
+
+Alternative (shell installer, installs to `~/.tinycloud/bin`):
+
+```bash
+curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+```
+
+Platforms: macOS (arm64, x64) and Linux (x64, arm64). Windows is not
+supported — use WSL2. More at https://tinycloud.sh.
+
+## Credentials
+
+Cloud verbs (`watch extract probe ask publish`) need a Cloudglue API key.
+Usage is billed to that key per the
+[rate card](https://app.cloudglue.dev/home/billing/rate-card).
+
+```bash
+tinycloud setup cloudglue --api-key <key>     # persist the key
+# or
+export CLOUDGLUE_API_KEY=<key>                # env only, nothing persisted
+```
+
+`frameio` is an optional service and requires interactive OAuth
+(`tinycloud setup frameio` inside the tinycloud agent TUI).
+
+## Verifying an install
+
+```bash
+tinycloud --version --json
+```
+
+Returns (annotated):
+
+```json
+{
+  "name": "tinycloud",
+  "version": "0.3.0",            // semver — compare against min_version
+  "git_sha": "…",
+  "build_id": "0.3.0+…",
+  "channel": "stable",
+  "platform": "darwin",
+  "arch": "arm64",
+  "protocol_version": "1",       // CLI protocol contract
+  "envelope_schema": "1",        // envelope shape version
+  "workflow_schema": "1",        // workflow recipe schema version
+  "command_spec_revision": "…",  // changes when commands/flags change
+  "features": ["envelope.v1", "watch.v1", "..."]   // feature ids to gate on
+}
+```
+
+```bash
+tinycloud setup --check --json
+```
+
+Exits 0 even when unconfigured; branch on `data.ok`. `data.services[]` lists
+each service with `configured`, `env`, `interactive_required`, and a
+`message`. `data.capabilities` repeats the protocol/feature contract.
+
+## Preflight script
+
+`scripts/preflight.sh` (next to this skill's SKILL.md) checks everything and
+prints exactly one actionable line:
+
+| exit | meaning |
+|---|---|
+| 0  | ok — install, version, features, and credentials all good |
+| 10 | tinycloud binary missing or broken — install |
+| 11 | version below the skill's `min_version` — upgrade |
+| 12 | required feature ids missing from `features[]` — upgrade |
+| 13 | binary fine, Cloudglue credentials missing — configure key |
+
+The version/feature requirements live in `tinycloud-skill.json`
+(`min_version`, `supported_range`, `required_features`) and mirror what the
+binary reports in `--version --json`.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `CLOUDGLUE_API_KEY` | Cloudglue API key (alternative to `tinycloud setup cloudglue`) |
+| `TINYCLOUD_VERSION` | npm launcher: run a specific binary version |
+| `TINYCLOUD_INSTALL_DIR` | npm launcher: cache root (default `~/.tinycloud`) |