@cloudglue/tinycloud 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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,6 +91,7 @@ tinycloud clip burn ./demo.mp4 --subtitle-file ./captions/demo.srt -o ./out.mp4
 
 # Remote videos, collections, 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
@@ -105,6 +106,9 @@ tinycloud publish video ./demo.mp4 --visibility public --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).
+Evaluating a video the host project's code rendered (render → evaluate →
+edit → rerender): the render-review loop in
+[reference/pipelines.md](reference/pipelines.md).
 
 ## 3. Workflows (packaged recipes)
 
@@ -159,7 +163,9 @@ Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow
   `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
-  `playSegment(start, end?)`) rather than hand-rolled players — details in
+  `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).
 
 ## 5. Reference (load on demand)

package/skills/tinycloud/reference/envelope.md

@@ -59,7 +59,11 @@ the exit code alone.
 `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.
+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.
 
 ## JSON vs JSONL vs text
 

package/skills/tinycloud/reference/glossary.md

@@ -48,7 +48,9 @@ connector?" or an envelope field needs explaining.
   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).
+  (semantic), `shots` (visual cuts; bounds tunable via
+  `--shot-min-seconds`/`--shot-max-seconds`, sub-second min allowed),
+  `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`.
@@ -83,5 +85,6 @@ connector?" or an envelope field needs explaining.
   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
-  events re-dispatched on the element) for custom site HTML — see
-  reference/verbs.md.
+  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.

package/skills/tinycloud/reference/pipelines.md

@@ -102,3 +102,50 @@ tinycloud watch ./talk.mp4 --json \
   | tinycloud extract "the three strongest quotes with timestamps" --json \
   | tinycloud clip cut --from-findings -o ./tinycloud-output/quotes/ --json
 ```
+
+## Render-review loop (videos your code generates)
+
+When the host project's code produces a video (Remotion, Manim, ffmpeg
+filter graphs, slide-render pipelines, recorded E2E runs), don't stop at a
+successful render exit code — a clean render is not a good video. Use
+tinycloud as the eyes in the edit loop:
+
+```bash
+# 1. Render with the project's own tooling (example: Remotion).
+npx remotion render Promo out/promo.mp4
+
+# 2. Evaluate the result.
+tinycloud watch ./out/promo.mp4 --segment shots --json \
+  | tinycloud extract "Evaluate pacing, text readability and clipping, scene \
+      continuity, and audio/visual sync. Return timestamped findings with \
+      severity and concrete edit instructions." --json
+
+# 3. Map each finding's timestamp to code (frame = seconds x fps for
+#    frame-based renderers), apply fixes, rerender to the SAME path.
+
+# 4. Re-evaluate, feeding the previous findings back so the model confirms fixes.
+tinycloud watch ./out/promo.mp4 --segment shots --json \
+  | tinycloud extract "Re-evaluate this render. Previous findings: <summarize \
+      prior findings>. Confirm whether each is resolved and report any new \
+      issues." --json
+```
+
+Loop rules:
+
+- Stop when findings are empty or low-severity only; then report done with
+  the final findings summary. "Done" means evaluated, not rendered.
+- Hunting sub-second flash frames or rapid cuts? Tighten the shot pass with
+  `--shot-min-seconds 0.6` (fractional values allowed);
+  `--shot-max-seconds` caps overly long shots the same way.
+- Each rerender is a new file, so each iteration uploads and runs through
+  the configured Cloudglue API key
+  (https://app.cloudglue.dev/home/billing/rate-card). Tell the user, and
+  prefer short/low-res preview renders while iterating when the project
+  supports them.
+- Reuse the same output path between iterations so stale renders don't pile
+  up; the new file content makes the cache treat it as a new source (that is
+  correct — you want the new render evaluated, not the cached old one).
+
+You own the renderer-specific half of the loop (mapping timestamps to frames
+and code, editing, rerendering); tinycloud only ever sees the media file.
+The loop applies to any pipeline that emits video.

package/skills/tinycloud/reference/setup.md

@@ -95,3 +95,9 @@ binary reports in `--version --json`.
 | `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`) |
+| `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) |
+
+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.

package/skills/tinycloud/reference/verbs.md

@@ -31,20 +31,31 @@ Flags shared by most verbs are listed once at the bottom.
 
 ```bash
 tinycloud watch <source> [--segment uniform:20|chapters|shots|segments]
+  [--shot-min-seconds <s>] [--shot-max-seconds <s>]
   [--profile default|light|custom] [--speech-only | --visual-only]
   [--start <t>] [--end <t>] [--transcript] [--content] [--json-index]
   [--background]
 ```
 
+Shot bounds tune `--segment shots` only: min 0.6–600 (fractional/sub-second
+values catch flash frames and rapid cuts), max 1–600, min ≤ max. Out-of-range
+or wrong-mode values fail with a validation envelope before any upload. The
+bounds are part of the cache key, so tuned and default shot passes never
+collide.
+
 ### extract — structured facts
 
 ```bash
 tinycloud extract "<query>" <source> --json          # free-form query
 tinycloud extract --schema ./schema.json <source>    # JSON-schema-shaped output
   [--segment-level] [--segmentation chapters|shots|segments]
+  [--shot-min-seconds <s>] [--shot-max-seconds <s>]
   [--include-thumbnails] [--transcript-mode] [--background]
 ```
 
+`--shot-min-seconds`/`--shot-max-seconds` work exactly as on `watch`, against
+`--segmentation shots`.
+
 ### caption — subtitles and transcripts
 
 ```bash
@@ -105,9 +116,23 @@ tinycloud library collections show <col_id> --json
 tinycloud library collections sync <col_id> --artifacts descriptions,transcripts,thumbnails,metadata --json
 tinycloud library connectors list --json
 tinycloud library connectors files <connector-id> [--limit 25] [--page-token <t>] --json
-tinycloud library connectors sync <connector-id> <uri> --json   # e.g. grain://recording/<id>
+tinycloud library connectors sync [<connector-id>] <uri-share-link-or-public-url> --json
 ```
 
+`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
+(`grain://recording/<id>`, `gdrive://file/<id>`, `dropbox://<path>`,
+`zoom://uuid/<uuid>`, `s3://<bucket>/<key>`, …) and share links are accepted:
+Dropbox file share links sync server-side via the connector's OAuth
+(including login-gated links); `zoom.us/rec/share` links resolve best-effort
+(Zoom mints a new token per copy — the recording-detail link is the reliable
+form). Link warnings are advisory and surface in `data.warnings` rather than
+blocking the sync. Non-connector public URLs (direct media URLs, TikTok,
+Loom, public Dropbox links without a connector) sync into a standalone
+Cloudglue file via direct URL ingestion — same command, no connector needed.
+YouTube URLs cannot sync; use `tinycloud grab` instead.
+
 `connectors files` also takes provider-specific filters: `--from`/`--to`
 (Zoom, Grain dates), `--folder-id` (Google Drive), `--path` (Dropbox),
 `--bucket`/`--prefix` (S3/GCS), `--title-search`/`--team`/`--meeting-type`
@@ -196,8 +221,24 @@ browsers block it), `loop`, `start-time`, `poster`, `accent-color`, and
 rest). Its JS API queues until ready — `playSegment(start, end?)`,
 `seekTo()`, `play()`/`pause()` — and media events are re-dispatched on the
 element (`timeupdate`, `ended`, `cg-ready`); prefer `playSegment` over
-hand-rolled seek logic for "click a moment to play that segment" pages. The
-full reference ships with the binary as `references/cg-video.md` inside the
+hand-rolled seek logic for "click a moment to play that segment" pages.
+
+For multi-video or segment-navigation pages, prefer the container components
+over hand-rolled galleries and segment-list JS:
+
+- `<cg-playlist>` + `<cg-playlist-item share-id="…">` — one player plus a
+  clickable track list, with auto-advance.
+- `<cg-grid>` + `<cg-grid-item share-id="…">` — lazy poster-card gallery,
+  inline or lightbox modal, at most one live player.
+- `<cg-chapters>` + `<cg-chapter start="…" [end="…"]>` — segment navigation
+  bound to a player by id; an `end` attribute plays just that clip via
+  `playSegment`. Hand-rolled `playSegment` calls remain the fallback for
+  fully custom layouts.
+
+Share ids inside `<cg-playlist-item>`/`<cg-grid-item>` tags count toward the
+private-embed guard: `tinycloud publish` rejects an artifact embedding a
+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).
 
 ### setup — credentials

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.1"
+MIN_VERSION="0.3.2"
 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 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 jobs.v1 library.collections.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.2.0",
+  "skill_version": "0.3.0",
   "tinycloud": {
-    "min_version": "0.3.1",
-    "supported_range": ">=0.3.1 <0.4.0",
+    "min_version": "0.3.2",
+    "supported_range": ">=0.3.2 <0.4.0",
     "required_features": [
       "envelope.v1",
       "watch.v1",
@@ -15,6 +15,7 @@
       "grab.v1",
       "jobs.v1",
       "library.collections.v1",
+      "library.sync.url.v1",
       "workflow.v1",
       "publish.v1",
       "publish.manage.v1",