@cloudglue/tinycloud 0.3.4 → 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.4` always runs tinycloud 0.3.4. 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.4   # 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.4",
+  "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
@@ -118,6 +118,8 @@ tinycloud publish list --json
 
 # Share a video itself (hosted share page + HLS stream, like a Loom link)
 tinycloud publish video ./demo.mp4 --visibility public --json
+# Share a single moment — also returns data.moment_url (0.3.5+)
+tinycloud publish video ./demo.mp4 --clip-start 18 --clip-end 33 --json
 ```
 
 Per-verb details and all flags: [reference/verbs.md](reference/verbs.md).
@@ -185,11 +187,19 @@ Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow
   are signed and short-lived (never hard-code them) — embed via
   `data.embed_snippet` (`<cg-video>`), which only plays on a private site of
   the same account. When writing HTML around an embed, use the component's
-  built-ins (`autoplay`+`muted`, `loop`, `start-time`, `exclusive`; JS
+  built-ins (`autoplay`+`muted`, `loop`, `start-time`, `exclusive`,
+  `clip-start`/`clip-end` to frame one "back to moment" clip; JS
   `playSegment(start, end?)`) and the container components
   (`<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;
@@ -88,14 +97,26 @@ connector?" or an envelope field needs explaining.
   `publish unpublish <site-id | site-name | label>`.
 - **Video share (shareable asset)** — `tinycloud publish video <source>`
   wraps a Cloudglue file in a hosted share page (`data.share.share_url`) plus
-  an HLS stream; one active share per (file, visibility). Private shares
+  an HLS stream; one active share per (file, visibility). Adding
+  `--clip-start`/`--clip-end` (seconds, 0.3.5+) also returns `data.moment_url`,
+  the share page bounded to that "back to moment" window (also reachable as
+  `?s=<start>&e=<end>` on a `share_url`). Private shares
   embed via the `data.embed_snippet` `<cg-video>` tag, which only plays on a
   private published site of the same account. The embed has playback
   attributes (`autoplay`+`muted`, `loop`, `start-time`, `poster`,
-  `accent-color`, `exclusive`) and a JS API (`playSegment`, `seekTo`, media
+  `accent-color`, `exclusive`, and `clip-start`/`clip-end` to frame a single
+  "back to moment" clip) and a JS API (`playSegment`, `seekTo`, media
   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`,
@@ -278,7 +280,7 @@ generated site name, or your `--name` label.
 
 ```bash
 tinycloud publish video <source> [--visibility public|private]   # default public
-  [--name <title>] [--segment-id <id>] --json
+  [--name <title>] [--segment-id <id>] [--clip-start <s> --clip-end <e>] --json
 tinycloud publish video list [--in <source>] [--visibility public|private] --json
 tinycloud publish video unpublish <share-id | source> --json   # --visibility disambiguates
 ```
@@ -297,6 +299,14 @@ feature id.
   `data.embed_snippet` (a `<cg-video share-id="...">` tag), which only plays
   on a PRIVATE published site of the same account — `tinycloud publish`
   rejects an artifact with a private embed targeted at a public site.
+- Moment window (0.3.5+): pass `--clip-start <s> --clip-end <e>` (seconds,
+  `clip-end > clip-start >= 0`, both required together or the command errors)
+  to also get `data.moment_url` — the hosted share page bounded to
+  `[start, end]`, with the same length badge, region strip, and "↺ Back to
+  moment" pill as the `<cg-video>` clip embed, and it survives the
+  private-share sign-in. Optional — omit it for a plain full-video share. The
+  same window is just `?s=<start>&e=<end>` appended to a `share_url`, so you
+  can hand-build a moment link from an existing share without re-publishing.
 
 When generating custom site HTML around a `<cg-video>` embed, use the
 component's built-ins instead of reinventing them. It defaults to a
@@ -309,6 +319,17 @@ rest). Its JS API queues until ready — `playSegment(start, end?)`,
 element (`timeupdate`, `ended`, `cg-ready`); prefer `playSegment` over
 hand-rolled seek logic for "click a moment to play that segment" pages.
 
+To frame a single moment inside the full recording — a cited highlight you
+want to share on its own — add `clip-start`/`clip-end` (seconds) to a bare
+`<cg-video>`: the player draws a clip-length badge, a clip-region strip with a
+live playhead, snaps the first play to `clip-start`, and auto-pauses at
+`clip-end` (via `playSegment`). Scrubbing out of the window fades in a soft
+"↺ Back to moment" pill — a manual scrub-out is never forced back. Both are
+required and `clip-end` is ignored unless it is greater than `clip-start`; the
+pair is `<cg-video>`-only (not read on `<cg-playlist-item>`/`<cg-grid-item>`).
+Rule of thumb: one moment → `clip-start`/`clip-end` on a `<cg-video>`; several
+segments a viewer navigates between → `<cg-chapters>` (below).
+
 For multi-video or segment-navigation pages, prefer the container components
 over hand-rolled galleries and segment-list JS:
 
@@ -327,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.4",
+  "skill_version": "0.3.6",
   "tinycloud": {
     "min_version": "0.3.4",
     "supported_range": ">=0.3.4 <0.4.0",