@cloudglue/tinycloud 0.3.3 → 0.3.4

package/README.md

@@ -16,11 +16,11 @@ The npm package is a small launcher: on first run it downloads the matching
 platform distribution from Cloudglue's CDN (cached under
 `~/.tinycloud/versions/<version>/`), verifies its checksum, and execs the real
 binary. The package version pins the binary version, so
-`npx @cloudglue/tinycloud@0.3.3` always runs tinycloud 0.3.3. It also adds two
+`npx @cloudglue/tinycloud@0.3.4` always runs tinycloud 0.3.4. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.3   # pre-download a version
+tinycloud install --version 0.3.4   # pre-download a version
 tinycloud install --latest          # install latest stable and pin to it
 tinycloud update                    # move to latest stable, prune old versions
 ```
@@ -123,7 +123,8 @@ go to stderr) — pass `--json`.
 | `ask` | Grounded Q&A over one or more videos |
 | `clip` | ffmpeg-backed cut, thumbs, stitch, transcode, burn, split, audio, info |
 | `grab` | Download a remote video (YouTube, TikTok, Loom, direct) |
-| `library` | Browse and sync Cloudglue collections and connectors |
+| `face` | Detect faces in a video, or match/search a known face, ranked by similarity |
+| `library` | Build & query Cloudglue collections (create/add/remove/delete) and browse connectors |
 | `jobs` | Poll, wait on, or forget async jobs |
 | `workflow` | Run packaged pipeline recipes (see below) |
 | `publish` | Publish HTML artifacts as Cloudglue Sites; share videos |
@@ -142,8 +143,26 @@ tinycloud caption ./demo.mp4 --format srt --transcript --json
 tinycloud clip cut ./demo.mp4 --start 12 --end 28 -o clip.mp4 --json
 # Grounded Q&A over one or more videos
 tinycloud ask "What objections came up?" --in ./demo.mp4 --json
+# Detect faces, or match a known face against a video (0.3.4+)
+tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json
 ```
 
+**Collections (0.3.4+)** turn a set of videos into a reusable, queryable
+knowledge base. Build one and query it — every type follows the same
+`create → add → poll show → query → delete` shape, differing only in `--type`
+and the verb that reads it:
+
+```bash
+tinycloud library collections create "calls" --type media-descriptions --json
+tinycloud library collections add ./call.mp4 --to col_123 --json   # enrichment is async
+tinycloud library collections show col_123 --json                  # poll files[].status → completed
+tinycloud ask "What did customers object to?" --in collection:col_123 --json
+```
+
+`media-descriptions` backs `ask`/`probe`/`search`, `face-analysis` backs
+`face list`/`face search`, and `entities` (created with `--prompt`/`--schema`)
+backs `library collections entities`.
+
 `tinycloud commands --json` is the authoritative, machine-readable list of
 every command and flag. Full per-verb flags and cost classes:
 [skills/tinycloud/reference/verbs.md](skills/tinycloud/reference/verbs.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Agent CLI for deep video work, by Cloudglue. Downloads the tinycloud binary on first run.",
   "bin": {
     "tinycloud": "bin/tinycloud.js"
@@ -23,6 +23,6 @@
     "url": "git+https://github.com/cloudglue/tinycloud.git"
   },
   "homepage": "https://tinycloud.sh",
-  "keywords": ["video", "cloudglue", "cli", "agent", "captions", "clips"],
+  "keywords": ["video", "cloudglue", "cli", "agent", "captions", "clips", "face-detection"],
   "license": "SEE LICENSE IN LICENSE.md"
 }

package/skills/tinycloud/SKILL.md

@@ -61,8 +61,8 @@ 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
+Cloud verbs (`watch extract probe ask publish face`) 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.
@@ -89,13 +89,29 @@ tinycloud clip cut ./demo.mp4 --start 12 --end 28 -o ./tinycloud-output/clip.mp4
 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
+# Faces on a single video (cloud, 0.3.4+) — for collection-scale face search/list, see Collections below
+tinycloud face detect ./demo.mp4 --json                       # every face → normalized box + timestamp
+tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json   # query image, ranked 0–100 similarity
+
+# Remote videos, async jobs
 tinycloud grab https://youtu.be/<id> -o ./tinycloud-output/grabbed/ --json
 tinycloud library connectors sync https://example.com/clip.mp4 --json  # public URL → Cloudglue file (not YouTube — use grab)
-tinycloud library collections list --json
 tinycloud watch ./long.mp4 --background --json   # returns pending + meta.job_id
 tinycloud jobs wait <job-id> --timeout 120s --json
 
+# Collections (0.3.4+) — turn videos into a reusable, queryable knowledge base.
+# Lifecycle (every --type): create → add → poll show → query → delete.
+tinycloud library collections list --json
+tinycloud library collections create my-desc --type media-descriptions --json  # types: media-descriptions | face-analysis | entities (--prompt) | rich-transcripts
+tinycloud library collections add ./demo.mp4 --to col_desc --json              # uploads a local source first; enrichment is async (pending)
+tinycloud library collections show col_desc --json                            # poll files[].status until completed, then query —
+# the collection's --type decides the read verb (each line below is a DIFFERENT, matching-type collection):
+tinycloud ask "what's discussed?" --in collection:col_desc --json             #   media-descriptions → ask / probe / search
+tinycloud face search ./person.jpg --in collection:col_faces --json           #   face-analysis      → face list / face search
+tinycloud library collections entities col_ents ./demo.mp4 --json             #   entities           → collections entities
+tinycloud library collections remove cloudglue://files/<id> --from col_desc --json
+tinycloud library collections delete col_desc --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

package/skills/tinycloud/reference/glossary.md

@@ -23,7 +23,15 @@ connector?" or an envelope field needs explaining.
   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.
+  ids are stable; display names are not. A collection has a type that decides
+  which verb reads it: `media-descriptions` (default) backs `ask`/`probe`/`search`,
+  `face-analysis` backs `face list`/`face search`, and `entities` (created with
+  `--prompt`/`--schema`) backs `library collections entities` (`rich-transcripts`
+  also exists). Manage them with `library collections create|add|remove|delete`
+  (0.3.4+); every type follows `create → add → poll show → query → delete`. `add`
+  enriches each file asynchronously and returns `pending` — poll
+  `library collections show <col>` until every `files[].status` is `completed`
+  before querying.
 - **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

package/skills/tinycloud/reference/pipelines.md

@@ -92,10 +92,34 @@ tinycloud clip burn ./demo.mp4 \
 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
+# Collections (0.3.4+) all follow one lifecycle — create → add → poll show → query → delete.
+# `add` enriches each file asynchronously and returns pending; poll `collections show`
+# and wait until every files[].status is `completed` before querying.
+
+# media-descriptions (default) → ask / probe / search
+tinycloud library collections create "sales-calls" --type media-descriptions --json
+tinycloud library collections add ./call-1.mp4 --to col_123 --json        # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud probe "pricing objections" --in collection:col_123 --scope segment --json
+tinycloud ask "What did customers object to across these calls?" --in collection:col_123 --json
+tinycloud library collections delete col_123 --json
+
+# face-analysis → face list / face search
+tinycloud library collections create faces --type face-analysis --json
+tinycloud library collections add ./interview.mp4 --to col_123 --json     # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud face list ./interview.mp4 --in collection:col_123 --json         # stored detections for that video
+tinycloud face search ./headshot.jpg --in collection:col_123 --group-by file --json
+
+# entities (create needs --prompt or --schema) → library collections entities
+tinycloud library collections create ents --type entities --prompt "people, places, objects" --json
+tinycloud library collections add ./interview.mp4 --to col_123 --json     # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud library collections entities col_123 ./interview.mp4 --json      # structured entities (video + segment level)
+
+# Already-built collection: mirror description/transcript artifacts locally for free `search`
 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
+tinycloud search "discount" --in collection:col_123 --json
 
 # Extract timestamped findings → cut them into clips
 tinycloud watch ./talk.mp4 --json \

package/skills/tinycloud/reference/setup.md

@@ -25,7 +25,8 @@ supported — use WSL2. More at https://tinycloud.sh.
 
 ## Credentials
 
-Cloud verbs (`watch extract probe ask publish`) need a Cloudglue API key.
+Cloud verbs (`watch extract probe ask publish face`) need a Cloudglue API key
+(as do `library collections add` and the collection reads).
 Usage is billed to that key per the
 [rate card](https://app.cloudglue.dev/home/billing/rate-card).
 

package/skills/tinycloud/reference/verbs.md

@@ -14,7 +14,8 @@ every verb. Regenerate doubts from it instead of trusting prose.
 | `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 |
+| `face` | cloud | yes | Detect faces in a video, or match/search a query face (0.3.4+) |
+| `library` | varies | no | Collections (incl. create/add/remove/delete), connectors, 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; share videos |
@@ -126,17 +127,84 @@ tinycloud clip cut --from-findings -o clips/        # cut timestamped findings p
 tinycloud grab <url> [-o <file-or-dir>] [--audio-only] [--format <yt-dlp-selector>]
 ```
 
+### face — detect & match faces (cloud, 0.3.4+)
+
+```bash
+tinycloud face detect <source> [--fps <n>] [--start <t>] [--end <t>]
+  [--thumbnails] [--limit <n>] --json
+tinycloud face match <image> <source> [--max-faces <n>] [--min-similarity <0-100>]
+  [--fps <n>] [--start <t>] [--end <t>] [--thumbnails] --json
+tinycloud face list <source> --in collection:col_… [--limit <n>] [--offset <n>] --json
+tinycloud face search <image> --in collection:col_… [col_…]
+  [--min-score <n>] [--group-by file] [--limit <n>] --json
+```
+
+`detect` runs Cloudglue face detection over a video and returns every face as
+a normalized 0–1 bounding box (`{top,left,width,height}`) plus a timestamp.
+`match` takes a query image — a local file (downscaled and sent inline, **never
+uploaded**) or an http(s) URL — and returns the closest faces ranked by a 0–100
+`similarity`. Both upload the *video* first like `watch`/`extract`
+(`needs_upload` without `--no-upload`) and cache by source + options, so re-runs
+are free. `--fps`/`--start`/`--end` tune sampling and window;
+`--max-faces`/`--min-similarity` bound `match`, `--limit` bounds `detect`,
+`--thumbnails` adds per-face frame URLs.
+
+`list` and `search` operate over a **face-analysis collection** (create one with
+`library collections create --type face-analysis` and add videos with
+`library collections add`): `list` reads a video's stored detections; `search`
+finds the query face across one or more collections (`--min-score`,
+`--group-by file`). `total` reports the server-available count across all modes
+(never rewritten by client `--min-*`/`--limit` filters).
+
 ### library — collections and connectors
 
 ```bash
 tinycloud library collections list --json
-tinycloud library collections show <col_id> --json
+tinycloud library collections show <col_id> --json     # files[].status: pending|processing|completed (readiness)
 tinycloud library collections sync <col_id> --artifacts descriptions,transcripts,thumbnails,metadata --json
+# Collection writes (0.3.4+) — the only write paths in library:
+tinycloud library collections create <name> [--type media-descriptions|entities|rich-transcripts|face-analysis] [--description <text>] [--prompt <text> | --schema <file>] --json
+tinycloud library collections add <source> --to <col_id> [--no-upload] [--no-download] --json
+tinycloud library collections remove <source> --from <col_id> --json
+tinycloud library collections delete <col_id> --json
+tinycloud library collections entities <col_id> <source> [--limit <n>] [--offset <n>] --json   # read a video's entities
 tinycloud library connectors list --json
 tinycloud library connectors files <connector-id> [--limit 25] [--page-token <t>] --json
 tinycloud library connectors sync [<connector-id>] <uri-share-link-or-public-url> --json
 ```
 
+`collections create|add|remove|delete` are the only writes in an otherwise
+read-only `library` (gated by the `library.collections.create.v1` /
+`library.collections.mutate.v1` feature ids). `create` defaults to
+`--type media-descriptions`; an `entities` collection also needs an extraction
+spec — `--prompt <text>` or `--schema <file.json>` — or `create` errors. `add`
+(`--to <col>`, or `--collection`) resolves the source like `watch`/`extract` —
+a local file uploads first (or `needs_upload` with `--no-upload`) — and records
+the file→collection mapping; `remove` (`--from <col>`) takes a Cloudglue file
+id/uri; `delete` removes the whole collection (and cleans the local mirror).
+Collection ids accept a bare uuid, a `col_…` slug, or `collection:<id>` /
+`cloudglue://collections/<id>` forms, consistently across read and write paths.
+
+**Readiness — always poll before querying.** `add` enriches each file
+asynchronously and returns `pending`. Poll `collections show <col> --json` and
+wait until every `files[].status` is `completed` (`pending → processing →
+completed`; `failed` is terminal) — a query before then returns empty or errors.
+
+The collection's `--type` decides which verb reads it (every type follows the
+same `create → add → poll show → query → delete` lifecycle):
+
+| `--type` | read with |
+|---|---|
+| `media-descriptions` (default) | `ask` / `probe` / `search` (`--in collection:<col>`) |
+| `face-analysis` | `face list` / `face search` |
+| `entities` (needs `--prompt`/`--schema`) | `library collections entities <col> <source>` |
+| `rich-transcripts` | `collections sync --artifacts transcripts` |
+
+`collections entities <col> <source>` returns a video's extracted entities
+(video- and segment-level, `--limit`/`--offset`) from an `entities` collection.
+For a one-off per-video pull without standing up a collection, `extract` returns
+entities/facts directly (free-form query or `--schema`).
+
 `connectors sync` materializes its argument into a Cloudglue file without
 starting analysis (idempotent). The connector id is optional — with just a
 URI or link, sync routes through the matching connector type. Connector URIs
@@ -275,11 +343,16 @@ Output: `--json` (force JSONL envelopes), `--pretty` (one JSON array),
 `--data raw`, `--raw-output` (raw backend payload; disables pipe protocol),
 `--quiet`, `--verbose`.
 
-Cache/spend — on `watch`, `extract`, `caption`, and `workflow` only:
+Cache — on `watch`, `extract`, `caption`, `face`, 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.
+exact-match history). `ask`/`probe` always call the cloud; use `search` for a
+free cached lookup.
+
+Upload/download refusal — on every verb that resolves a source:
+`--no-upload` (refuse cloud upload → `needs_upload`) on `watch`/`extract`/
+`caption`/`face`/`workflow`/`publish` and `library collections add`;
+`--no-download` (refuse local materialization → `needs_download`) on the same
+set minus `publish`.
 
 Source reuse (`watch`/`extract`/`caption`): `--source-id <id>`, `--result-id <id>`.
 

package/skills/tinycloud/scripts/preflight.sh

@@ -9,11 +9,11 @@ set -u
 
 # Mirror tinycloud-skill.json: min_version / supported_range upper bound
 # (CI diffs these against the manifest).
-MIN_VERSION="0.3.2"
+MIN_VERSION="0.3.4"
 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 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 setup.v1"
+REQUIRED_FEATURES="envelope.v1 watch.v1 extract.v1 caption.v1 search.v1 probe.v1 ask.v1 clip.v1 grab.v1 face.v1 jobs.v1 library.collections.v1 library.collections.create.v1 library.collections.mutate.v1 library.collections.entities.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 setup.v1"
 
 # 1) Binary present and responsive?
 if ! command -v tinycloud >/dev/null 2>&1; then

package/skills/tinycloud/tinycloud-skill.json

@@ -1,8 +1,8 @@
 {
-  "skill_version": "0.3.0",
+  "skill_version": "0.3.4",
   "tinycloud": {
-    "min_version": "0.3.2",
-    "supported_range": ">=0.3.2 <0.4.0",
+    "min_version": "0.3.4",
+    "supported_range": ">=0.3.4 <0.4.0",
     "required_features": [
       "envelope.v1",
       "watch.v1",
@@ -13,8 +13,12 @@
       "ask.v1",
       "clip.v1",
       "grab.v1",
+      "face.v1",
       "jobs.v1",
       "library.collections.v1",
+      "library.collections.create.v1",
+      "library.collections.mutate.v1",
+      "library.collections.entities.v1",
       "library.sync.url.v1",
       "workflow.v1",
       "publish.v1",

package/skills/tinycloud-init/SKILL.md

@@ -22,14 +22,16 @@ in order, skipping any that already pass.
 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:
+If installed and the JSON reports `"version"` ≥ 0.3.4 (the floor the tinycloud
+skill requires), go to step 2. If missing, older than 0.3.4, or no
+machine-readable version, install or upgrade it — ask the user which they
+prefer:
 
 ```bash
-npm install -g @cloudglue/tinycloud          # canonical (Node >= 18)
+npm install -g @cloudglue/tinycloud          # canonical (Node >= 18); reinstall to upgrade
 # or
 curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+tinycloud update                             # already installed but older → move to latest stable
 ```
 
 The first run downloads the platform distribution (~90 MB, one time). More