cloudglue · kdr · Jul 30, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "Deep video and image work for coding agents: analyze, describe, search, caption, clip, detect faces, and publish via the tinycloud CLI.",
-    "version": "0.3.15"
+    "version": "0.3.16"
   },
   "plugins": [
     {
       "name": "tinycloud",
       "source": "./",
       "description": "Video and image understanding and editing via the tinycloud CLI (Cloudglue): watch/see/extract/search/ask/face over videos and images, captions, clips, collections, plus one-command workflows for sales coaching, blog posts, ad analysis, meeting breakdowns, and YouTube publishing.",
-      "version": "0.3.15",
+      "version": "0.3.16",
       "author": { "name": "Cloudglue" },
       "homepage": "https://tinycloud.sh",
       "repository": "https://github.com/cloudglue/tinycloud",

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -2,7 +2,7 @@
   "name": "tinycloud",
   "displayName": "Tinycloud Video",
   "description": "Video and image understanding and editing via the tinycloud CLI (Cloudglue): watch/see/extract/search/ask/face over videos and images, captions, clips, collections, and one-command video workflows.",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "author": { "name": "Cloudglue", "url": "https://cloudglue.dev" },
   "homepage": "https://tinycloud.sh",
   "repository": "https://github.com/cloudglue/tinycloud",

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -185,7 +185,30 @@ connector and re-indexes its metadata collections — free (feature
 `library.connectors.refresh.v1`; refresh takes a SOURCE, unlike
 inspect/sync which take `[connector-id] <uri>`). Because the skill teaches
 the new flags/subcommands, the floor was raised to 0.3.15 (same
-merge-after-CDN gate). The host-level `profile` verb and the leading global flags `--home`/`--profile`
+merge-after-CDN gate). 0.3.16 is an envelope-truth and collections release
+(features 38→40, verbs stay 16), fixing the failure modes a live agent
+session surfaced: `watch`'s `data.segmentation` now reports the segmentation
+that actually produced `segments[]` (shots/chapters runs were mislabeled
+`uniform:20`, manufacturing a phantom "silent fallback" — the synthesized
+speech-only label is unchanged), a shots run over cut-less footage that
+max-caps every window gets an explanatory `data.segmentation_note`, and
+per-verb `--help` names every shared flag per group (`[cache: --refresh
+--no-cache …]`) instead of the "[common output/cache/source options]"
+placeholder that hid the cache flags from grepping agents. `library
+collections create` gains `--describe full|speech|light|<comma-list>`
+(feature `library.collections.describe.v1`; media-descriptions only) because
+the Cloudglue API default indexes speech+summary ONLY and the choice is
+immutable post-create — `collections show` now surfaces `describe_config`,
+and the create summary names the indexed modalities. Collections listings
+switch to the API's real offset pagination (feature
+`library.collections.pagination.v1`): `show` returns `data.total` plus a
+working `has_more`/`next_page_token` (numeric offset cursors accepted via
+`--page-token`), pagination cursors are exempt from the `_token` secret
+redaction that shipped the literal `[redacted]` where the cursor belonged,
+and `collections sync` mirrors no longer silently truncate at 100 files
+(pre-0.3.16, every listing was the first 50 rows with `has_more: false`).
+Because the skill teaches `--describe` and show pagination, the floor was
+raised to 0.3.16 (same merge-after-CDN gate). The host-level `profile` verb and the leading global flags `--home`/`--profile`
 (also `$TINYCLOUD_HOME`; 0.3.3+) relocate state and are intentionally absent
 from `commands --json` — like the launcher's install/update, they're CLI/host
 concerns, not video operations.

diff --git a/README.md b/README.md
@@ -17,11 +17,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.15` always runs tinycloud 0.3.15. It also adds two
+`npx @cloudglue/tinycloud@0.3.16` always runs tinycloud 0.3.16. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.15   # pre-download a version
+tinycloud install --version 0.3.16   # pre-download a version
 tinycloud install --latest          # install latest stable and pin to it
 tinycloud update                    # move to latest stable, prune old versions
 ```

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "description": "Agent CLI for deep video and image work, by Cloudglue. Downloads the tinycloud binary on first run.",
   "bin": {
     "tinycloud": "bin/tinycloud.js"

diff --git a/skills/tinycloud/SKILL.md b/skills/tinycloud/SKILL.md
@@ -112,7 +112,10 @@ 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 | metadata (0.3.15+)
+tinycloud library collections create my-desc --type media-descriptions --describe full --json  # types: media-descriptions | face-analysis | entities (--prompt) | rich-transcripts | metadata (0.3.15+)
+# --describe full|speech|light (0.3.16+): which modalities a media-descriptions collection indexes.
+# The API default is speech+summary ONLY (no visuals/scene text) and it is IMMUTABLE after create —
+# pass --describe full when visual probe/ask queries matter. `show` reports describe_config.
 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):

diff --git a/skills/tinycloud/reference/verbs.md b/skills/tinycloud/reference/verbs.md
@@ -65,6 +65,17 @@ bounds are part of the cache key, so tuned and default shot passes never
 collide. `watch` is **video/audio only** — point it at an image and it errors
 ("watch analyzes video/audio; for an image use `tinycloud see`").
 
+`data.segmentation` reports the segmentation that actually produced
+`segments[]` (0.3.16+ — earlier binaries mislabeled shots/chapters runs as
+`uniform:20`; on those, trust `data.describe.primary_segmentation` instead).
+On footage with no detectable cuts (talks, screencasts, locked-off cameras) a
+shots run degenerates to max-duration windows — every shot hits
+`--shot-max-seconds` (default 300), so boundaries land on exact multiples.
+That is shot detection working on cut-less footage, **not** a fallback to
+uniform; 0.3.16+ flags it in `data.segmentation_note`. Re-runs are served
+from cache — `--refresh` recomputes and `--no-cache` bypasses (no `--home`
+workarounds needed).
+
 Segments carry the spoken words (0.3.12+): each segment (and embedded shot)
 inlines its overlapping utterances as `speech: string[]`. A source with
 speech but no visual segmentation — an audio file, `--speech-only`, a very
@@ -234,10 +245,10 @@ finds the query face across one or more collections (`--min-score`,
 
 ```bash
 tinycloud library collections list --json
-tinycloud library collections show <col_id> --json     # files[].status: pending|processing|completed (readiness)
+tinycloud library collections show <col_id> [--limit <n>] [--page-token <t>] --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|metadata] [--description <text>] [--prompt <text> | --schema <file>] --json
+tinycloud library collections create <name> [--type media-descriptions|entities|rich-transcripts|face-analysis|metadata] [--describe full|speech|light|<comma-list>] [--description <text>] [--prompt <text> | --schema <file>] --json
 tinycloud library collections add <source> --to <col_id> [--metadata '<json|file.json>'] [--no-upload] [--no-download] --json
 tinycloud library collections remove <source> --from <col_id> --json
 tinycloud library collections delete <col_id> --json
@@ -255,7 +266,20 @@ read-only `library` (gated by the `library.collections.create.v1` /
 `--type media-descriptions`; an `entities` collection also needs an extraction
 spec — `--prompt <text>` or `--schema <file.json>` — or `create` errors, and a
 `metadata` collection takes NO processing configs (`create` rejects
-`--prompt`/`--schema`). `add`
+`--prompt`/`--schema`).
+
+**A media-descriptions collection indexes only the modalities chosen at
+create time, and the API default is speech+summary ONLY** — no visual scene
+descriptions, no scene text — so visual `probe`/`ask` queries over a
+default-created collection come back empty. `--describe` (0.3.16+, feature
+`library.collections.describe.v1`) picks the modalities: `full`
+(speech+visual+scene-text+audio+summary — matches a standalone `watch`),
+`speech` (the API default, explicit), `light` (speech+visual+summary), or a
+comma list from `speech,visual,scene-text,audio,summary`. The choice is
+**immutable after create** (the API ignores config updates), so pass
+`--describe full` up front when visual search matters; `collections show`
+reports the collection's `describe_config`, and the create summary names the
+indexed modalities. `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; `--metadata '<json|file.json>'` (0.3.15+)
@@ -271,6 +295,12 @@ 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.
 
+`collections show` lists ONE page of files (default 50) with `data.total`,
+`has_more`, and `next_page_token` — page with `--page-token` until the token
+is null (0.3.16+, feature `library.collections.pagination.v1`; earlier
+binaries capped every listing at 50 with a wrong `has_more: false` and a
+redacted token, so a >50-file collection could not be enumerated).
+
 The collection's `--type` decides which verb reads it (every type follows the
 same `create → add → poll show → query → delete` lifecycle):
 

diff --git a/skills/tinycloud/scripts/preflight.sh b/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.15"
+MIN_VERSION="0.3.16"
 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 watch.speech.v1 see.v1 extract.v1 extract.images.v1 caption.v1 search.v1 probe.v1 probe.filters.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.collections.metadata.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 publish.link.preview.v1 setup.v1"
+REQUIRED_FEATURES="envelope.v1 watch.v1 watch.speech.v1 see.v1 extract.v1 extract.images.v1 caption.v1 search.v1 probe.v1 probe.filters.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.collections.metadata.v1 library.collections.describe.v1 library.collections.pagination.v1 library.sync.url.v1 workflow.v1 publish.v1 publish.manage.v1 publish.video.v1 publish.link.preview.v1 setup.v1"
 
 # 1) Binary present and responsive?
 if ! command -v tinycloud >/dev/null 2>&1; then

diff --git a/skills/tinycloud/tinycloud-skill.json b/skills/tinycloud/tinycloud-skill.json
@@ -1,8 +1,8 @@
 {
-  "skill_version": "0.3.15",
+  "skill_version": "0.3.16",
   "tinycloud": {
-    "min_version": "0.3.15",
-    "supported_range": ">=0.3.15 <0.4.0",
+    "min_version": "0.3.16",
+    "supported_range": ">=0.3.16 <0.4.0",
     "required_features": [
       "envelope.v1",
       "watch.v1",
@@ -24,6 +24,8 @@
       "library.collections.mutate.v1",
       "library.collections.entities.v1",
       "library.collections.metadata.v1",
+      "library.collections.describe.v1",
+      "library.collections.pagination.v1",
       "library.sync.url.v1",
       "workflow.v1",
       "publish.v1",