@cloudglue/tinycloud 0.3.5 → 0.3.6

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.5` always runs tinycloud 0.3.5. It also adds two
+`npx @cloudglue/tinycloud@0.3.6` always runs tinycloud 0.3.6. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.5   # pre-download a version
+tinycloud install --version 0.3.6   # pre-download a version
 tinycloud install --latest          # install latest stable and pin to it
 tinycloud update                    # move to latest stable, prune old versions
 ```
@@ -143,7 +143,7 @@ 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+)
+# Detect faces, or match a known face against a video (0.3.4+; query image: JPEG/PNG)
 tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Agent CLI for deep video work, by Cloudglue. Downloads the tinycloud binary on first run.",
   "bin": {
     "tinycloud": "bin/tinycloud.js"

package/skills/tinycloud/SKILL.md

@@ -91,7 +91,7 @@ tinycloud clip burn ./demo.mp4 --subtitle-file ./captions/demo.srt -o ./out.mp4
 
 # 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
+tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json   # query image (JPEG/PNG), ranked 0–100 similarity
 
 # Remote videos, async jobs
 tinycloud grab https://youtu.be/<id> -o ./tinycloud-output/grabbed/ --json
@@ -193,6 +193,13 @@ Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow
   (`<cg-playlist>`, `<cg-grid>`, `<cg-chapters>`) rather than hand-rolled
   players, galleries, or segment-list JS — details in
   [reference/verbs.md](reference/verbs.md).
+- Live-API discovery components (0.3.6+): the same embed script also defines
+  collection-scoped, **private-site-only** elements that let viewers search/chat
+  inside a published site — `<cg-chat>`, `<cg-search>`, `<cg-deep-search>`,
+  `<cg-face-search>` (chat/search/deep-search need a media-descriptions or
+  rich-transcripts collection; face-search needs face-analysis). `publish`
+  **hard-rejects** them on a public site → publish with `--visibility private`.
+  See [reference/verbs.md](reference/verbs.md).
 
 ## 5. Reference (load on demand)
 

package/skills/tinycloud/reference/envelope.md

@@ -60,10 +60,12 @@ the exit code alone.
 
 `upstream` on a piped command means the upstream envelope was not `ready` —
 fix the upstream failure, don't retry downstream. `upstream` from a cloud
-call itself is a Cloudglue API failure; when it's a request deadline
-(retryable, message names `TINYCLOUD_HTTP_TIMEOUT_MS` /
-`TINYCLOUD_UPLOAD_TIMEOUT_MS`), the server may still be processing — retry
-or raise the knob.
+call itself is a Cloudglue API failure; transient ones (request deadline,
+408/429/5xx, idle-timeout abort) are marked `retryable`, and idempotent reads
+are already auto-retried with backoff before surfacing — so a retryable
+`upstream` means the server may still be processing or retries were exhausted:
+retry later or raise the knob the message names (`TINYCLOUD_HTTP_TIMEOUT_MS` /
+`TINYCLOUD_UPLOAD_TIMEOUT_MS`).
 
 ## JSON vs JSONL vs text
 

package/skills/tinycloud/reference/glossary.md

@@ -41,6 +41,15 @@ connector?" or an envelope field needs explaining.
   `cloudglue://files/<id>` URI, connector URI, collection, or a bare file-id
   UUID (normalized to `cloudglue://files/<id>`; an existing local path of the
   same name wins).
+- **Supported inputs** — local uploads (`watch`, `extract`, `face`,
+  `library collections add`) map by extension: video `.mp4 .mov .webm .mkv .m4v`,
+  audio `.mp3 .wav .m4a`. Other extensions upload as `application/octet-stream`
+  and may be rejected upstream — transcode to a mapped container first
+  (`clip transcode`). Local uploads are bounded by Cloudglue at ~3 GB and
+  2 s–3 h (connector ingests allow more). `face match`/`face search` query
+  images must be **JPEG or PNG**. Use `grab` for YouTube and
+  `library connectors sync` for share links rather than passing those URLs to
+  upload verbs.
 - **`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;
@@ -100,6 +109,14 @@ connector?" or an envelope field needs explaining.
   events re-dispatched on the element) for custom site HTML, and plays
   standalone or inside the container components (`<cg-playlist>`,
   `<cg-grid>`, `<cg-chapters>`) — see reference/verbs.md.
+- **Discovery components (live API, 0.3.6+)** — the same embed script also
+  defines four collection-scoped, **private-site-only** elements that let a
+  viewer search or chat inside a published site and play results inline via
+  `<cg-video>`: `<cg-chat>`, `<cg-search>`, `<cg-deep-search>` (over a
+  media-descriptions / rich-transcripts collection) and `<cg-face-search>` (over
+  a face-analysis collection). They carry no share id, but `tinycloud publish`
+  rejects them on a public site — publish `--visibility private`. See
+  reference/verbs.md.
 
 ## State and isolation (0.3.3+)
 

package/skills/tinycloud/reference/pipelines.md

@@ -22,6 +22,11 @@ cat sources.txt | tinycloud watch --json
 
 - Piping watch envelopes into `search` / `probe` / `ask` auto-scopes them via
   `ref.cloudglue_file_id` / collection ids.
+- A verb invoked with an explicit source/scope never reads stdin — only the
+  pipe form above (a source-less verb after `|`), `setup --stdin`, and a bare
+  `tinycloud` prompt do. When spawning tinycloud non-interactively (a subprocess
+  or a script), close or ignore its stdin (`</dev/null`, or Node
+  `stdio: ["ignore", …]`) and wrap the call in a timeout as a backstop.
 
 ## Multi-video batching
 

package/skills/tinycloud/reference/setup.md

@@ -99,11 +99,19 @@ binary reports in `--version --json`.
 | `TINYCLOUD_HOME` | Isolated state home — config, sessions, cache, jobs, artifacts, skills (default `~/.tinycloud`; same as `--home`). 0.3.3+ |
 | `TINYCLOUD_OUT` | Output base for generated files (wins over a config `outputBase`) |
 | `TINYCLOUD_HTTP_TIMEOUT_MS` | Hard deadline per Cloudglue request (default 120s; `0` disables) |
-| `TINYCLOUD_UPLOAD_TIMEOUT_MS` | Deadline for upload-shaped requests (default 60min; `0` disables) |
+| `TINYCLOUD_UPLOAD_TIMEOUT_MS` | Total deadline for upload-shaped requests (default 60min; `0` disables) |
+| `TINYCLOUD_UPLOAD_IDLE_TIMEOUT_MS` | Idle (no-progress) deadline for an upload — aborts a wedged transfer in ~1min instead of waiting out the total upload deadline (default 60s; `0` disables) |
+| `TINYCLOUD_HTTP_RETRIES` | Bounded auto-retries for idempotent (GET/HEAD) Cloudglue calls on transient errors — 408/429/5xx, network blips (default 3; `0` disables) |
+| `TINYCLOUD_JOB_WAIT_TIMEOUT_MS` | Wall-clock budget for async job waits (the `waitForReady` poll behind `watch`/`extract`/`face`) (default 10min; `0` disables) |
 
 Every Cloudglue request carries a hard deadline, so a stalled route can never
 hang the CLI indefinitely; a timeout surfaces as a retryable `upstream` error
-envelope whose message names the knob to adjust.
+envelope whose message names the knob to adjust. Idempotent reads (GET/HEAD,
+including the status polls behind async waits) auto-retry transient failures
+(408/429/5xx, network blips, idle-timeout aborts) with backoff + jitter before
+surfacing, and uploads abort early if no progress is seen within the idle
+window. Non-idempotent mutations (upload/create/add/delete) are never
+auto-retried — a retryable `upstream` there is yours to re-issue.
 
 ## Profiles & isolated homes (0.3.3+)
 

package/skills/tinycloud/reference/verbs.md

@@ -143,7 +143,9 @@ tinycloud face search <image> --in collection:col_… [col_…]
 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`
+`similarity`. The query image must be a **JPEG or PNG** (Cloudglue face matching
+decodes only JPEG/PNG — webp/heic/gif/bmp are rejected at preflight; a URL must
+likewise point at a JPEG/PNG). 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`,
@@ -346,6 +348,27 @@ private share — directly or through a container — on a public site. The full
 reference ships with the binary as `references/cg-video.md` inside the
 bundled media-artifact skill (under the install's `skills/` directory).
 
+Discovery components (live API, 0.3.6+): the same `/__cg/embed.js` script also
+defines four **collection-scoped** components that let a viewer search or chat
+*inside* a published site and play the referenced moment inline via `<cg-video>`
+— `<cg-chat>` (conversational Q&A, streaming answers + inline moment citations;
+optional `placeholder`), `<cg-search>` (keyword/transcript text search),
+`<cg-deep-search>` (agentic semantic search), and `<cg-face-search>` (upload or
+paste a face image → matching moments). Each takes `collection="<id>"` (plus
+optional `accent-color` and `--cg-height` CSS sizing); the collection's `--type`
+must match the element — `<cg-chat>`/`<cg-search>`/`<cg-deep-search>` need a
+`media-descriptions` or `rich-transcripts` collection, `<cg-face-search>` needs a
+`face-analysis` collection. Unlike the playback elements they carry **no share
+id**, but their live calls are refused on a public site, so `tinycloud publish`
+**hard-rejects** a page that embeds any of them on a public site — publish with
+`--visibility private`. End to end: build a collection of the right type
+(`library collections create … --type …` → `library collections add` → poll
+`library collections show` until each file is `completed`) → author HTML with
+the component → `tinycloud publish <html> --visibility private`. Full reference
+plus a kitchen-sink page wiring every component (props, JS API, events) ships
+with the binary as `references/cg-video.md` and `references/kitchen-sink.html`
+inside the bundled media-artifact skill.
+
 ### setup — credentials
 
 ```bash

package/skills/tinycloud/tinycloud-skill.json

@@ -1,5 +1,5 @@
 {
-  "skill_version": "0.3.5",
+  "skill_version": "0.3.6",
   "tinycloud": {
     "min_version": "0.3.4",
     "supported_range": ">=0.3.4 <0.4.0",