@cloudglue/tinycloud 0.3.1 → 0.3.3

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.0` always runs tinycloud 0.3.0. It also adds two
+`npx @cloudglue/tinycloud@0.3.3` always runs tinycloud 0.3.3. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.0   # pre-download a version
+tinycloud install --version 0.3.3   # pre-download a version
 tinycloud install --latest          # install latest stable and pin to it
 tinycloud update                    # move to latest stable, prune old versions
 ```
@@ -50,14 +50,21 @@ This repo also distributes agent skills that teach coding agents (Claude
 Code, Codex, and anything else following the
 [Agent Skills](https://agentskills.io) standard) to drive the tinycloud CLI.
 
-**One command** (detects your agent and installs the bundled skills):
+**One command** (in a terminal it prompts you to pick the target agents):
 
 ```bash
-npx @cloudglue/tinycloud skills install          # project-level (.claude/skills, .agents/skills)
-npx @cloudglue/tinycloud skills install --global # ~/.claude/skills (all your projects)
+npx @cloudglue/tinycloud skills install                       # menu: claude-code, agents, codex, cursor
+npx @cloudglue/tinycloud skills install --harness cursor,codex  # pick targets non-interactively
+npx @cloudglue/tinycloud skills install --global              # ~/.claude/skills (Claude Code only)
 npx @cloudglue/tinycloud skills install --skill tinycloud,blog-post   # just some
 ```
 
+Each agent reads skills from its own `<dir>/skills`: `claude-code` → `.claude`,
+`agents` → `.agents` (the universal [Agent Skills](https://agentskills.io)
+layout), `codex` → `.codex`, `cursor` → `.cursor`. The menu preselects dirs
+that already exist; piped/CI runs (or `--yes`) skip it and install into
+whichever dirs exist, defaulting to `.claude/skills` when none do.
+
 **Claude Code** (as a plugin):
 
 ```text
@@ -91,14 +98,114 @@ To give every agent session in a repo the same skills, commit them:
 
 ```bash
 cd your-project
-npx @cloudglue/tinycloud skills install     # writes .claude/skills/ (and .agents/skills/ if present)
-git add .claude .agents 2>/dev/null; git commit -m "Add tinycloud agent skills"
+npx @cloudglue/tinycloud skills install --harness claude-code,agents   # or pick from the menu
+git add .claude .agents .codex .cursor 2>/dev/null; git commit -m "Add tinycloud agent skills"
 ```
 
 Optionally add a line to your project's `CLAUDE.md` so agents reach for them:
 `Video work (analysis, captions, clips, workflows) goes through the tinycloud
 CLI — see the tinycloud skill; run tinycloud-init if the CLI isn't set up.`
 
+## Commands
+
+Cloud commands run through your configured Cloudglue API key (billed per the
+[rate card](https://app.cloudglue.dev/home/billing/rate-card)); local and
+network commands are free. Every command prints a JSON envelope on stdout (logs
+go to stderr) — pass `--json`.
+
+| Command | What it does |
+|---|---|
+| `watch` | Analyze a video → reusable cached context + Cloudglue-ready ref |
+| `extract` | Pull structured facts, entities, or moments (free-form or JSON-schema) |
+| `caption` | Subtitles and transcripts (SRT/VTT/ASS) |
+| `search` | Keyword search over cached video context |
+| `probe` | Semantic moment/video search over a Cloudglue scope |
+| `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 |
+| `jobs` | Poll, wait on, or forget async jobs |
+| `workflow` | Run packaged pipeline recipes (see below) |
+| `publish` | Publish HTML artifacts as Cloudglue Sites; share videos |
+| `setup` | Configure the Cloudglue API key and service connections |
+
+A few common invocations:
+
+```bash
+# Analyze a video into reusable, cached context + a Cloudglue-ready ref
+tinycloud watch ./demo.mp4 --json
+# Pull structured findings (free-form query here; pass --schema for a fixed shape)
+tinycloud extract "key moments with timestamps" ./demo.mp4 --json
+# Subtitles plus a markdown transcript
+tinycloud caption ./demo.mp4 --format srt --transcript --json
+# Trim a clip locally — no upload, ffmpeg-backed
+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
+```
+
+`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).
+The envelope contract — statuses (`ready`, `pending`, `needs_credentials`, …)
+and exit codes:
+[skills/tinycloud/reference/envelope.md](skills/tinycloud/reference/envelope.md).
+
+### Global flags & profiles (0.3.3+)
+
+A few options are host-level — they isolate state rather than run a video
+operation, so they go *before* the verb and don't appear in `commands --json`:
+
+- `--home <dir>` (or `$TINYCLOUD_HOME`) — run against an isolated state home
+  (config, sessions, cache, jobs, artifacts, skills) instead of `~/.tinycloud`.
+- `--profile <name>` — use a named profile's home, so multiple accounts or
+  installs run side by side without cross-contamination.
+
+```bash
+tinycloud --home ./.tc watch ./demo.mp4 --json      # isolated state for this repo
+tinycloud profile list                              # profiles and their homes
+tinycloud profile create work --default             # create one and make it default
+tinycloud profile create staging --copy-from work   # clone an existing home
+tinycloud --profile work ask "..." --in ./demo.mp4 --json
+```
+
+Sessions are scoped per project (keyed by the git root), the agent takes a
+`--skills <list>` allowlist alongside `--tools`, and a project-local
+`.tinycloud/config.json` can pin tool/skill allowlists and an output base.
+Details:
+[skills/tinycloud/reference/setup.md](skills/tinycloud/reference/setup.md).
+
+## Workflows
+
+Workflows are packaged, repeatable pipelines that run with a single command
+and write their outputs into a run directory under
+`./tinycloud-output/runs/<run_id>/`. The five flagship recipes — each with a
+matching agent skill — are:
+
+| Workflow | Turns a video into |
+|---|---|
+| `sales-coaching` | Coaching dashboard — call scores, speech metrics, objections |
+| `blog-post` | Rich blog post — sections, thumbnails, takeaways |
+| `ad-analysis` | Ad breakdown — shot timeline, hook, pacing, CTA |
+| `meeting-breakdown` | Speaker timeline, chapter summaries, action items |
+| `youtube-publish` | YouTube title, description, chapters, tags, subtitles |
+
+```bash
+tinycloud workflow list --json                       # all available recipes
+tinycloud workflow sales-coaching ./call.mp4 --json  # run one
+tinycloud workflow plan blog-post ./demo.mp4 --json  # preview steps (free, no side effects)
+tinycloud workflow validate ad-analysis --json       # check a recipe (or a path)
+```
+
+The final envelope reports `data.status`
+(`completed | partial | failed | paused`), `data.outputs` (named outputs such
+as `outputs.html`), and `data.artifacts[].path`. The five above each have a
+matching agent skill (see the table), so coding agents can run them directly;
+`tinycloud workflow list` shows the full set, including building blocks like
+`summary` and `clip-highlights`. Author your own recipes:
+[skills/tinycloud/reference/workflow-authoring.md](skills/tinycloud/reference/workflow-authoring.md)
+(or scaffold one with the `tinycloud-skill-creator` skill).
+
 ## License
 
 © Aviary Inc. (d/b/a Cloudglue). All rights reserved. Use is subject to [Aviary Inc. Terms of Service](https://cloudglue.dev/terms).

package/lib/skills.js

@@ -3,6 +3,7 @@
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
+const readline = require("node:readline");
 
 // Agent skills bundled with this package (the npm tarball includes skills/).
 function bundledSkillsDir() {
@@ -19,28 +20,95 @@ function listBundledSkills() {
 }
 
 /**
- * Pick install targets. Each harness keeps skills in its own directory; we
- * detect harnesses by their config dir to avoid littering projects that
- * don't use them.
+ * Known agent harnesses. Each keeps skills in its own <configDir>/skills dir,
+ * all using the SKILL.md layout. `id` is both the menu label and the
+ * --harness token; `aliases` are extra accepted tokens.
  *   claude-code: <project>/.claude/skills  (global: ~/.claude/skills)
- *   codex:       <project>/.agents/skills  (agentskills.io layout)
+ *   agents:      <project>/.agents/skills  (universal agentskills.io layout)
+ *   codex:       <project>/.codex/skills
+ *   cursor:      <project>/.cursor/skills
  */
-function resolveTargets({ global: isGlobal, dir, cwd = process.cwd() }) {
+const HARNESSES = [
+  { id: "claude-code", aliases: ["claude"], configDir: ".claude" },
+  { id: "agents", aliases: [], configDir: ".agents" },
+  { id: "codex", aliases: [], configDir: ".codex" },
+  { id: "cursor", aliases: [], configDir: ".cursor" },
+];
+
+function harnessIds() {
+  return HARNESSES.map((h) => h.id);
+}
+
+// Resolve a --harness token (id or alias, case-insensitive) to its entry.
+function findHarness(token) {
+  const t = String(token).trim().toLowerCase();
+  return HARNESSES.find((h) => h.id === t || h.aliases.includes(t));
+}
+
+function harnessTarget(h, cwd) {
+  return { name: h.id, dir: path.join(cwd, h.configDir, "skills") };
+}
+
+function detectHarnesses(cwd) {
+  return HARNESSES.filter((h) => fs.existsSync(path.join(cwd, h.configDir)));
+}
+
+/**
+ * Pick install targets from flags/detection only — no prompting or I/O beyond
+ * existence checks, so it stays deterministic for tests. The interactive menu
+ * lives in promptForTargets(). Precedence: --dir > --global > --harness >
+ * detection (and .claude when nothing is detected).
+ */
+function resolveTargets({ global: isGlobal, dir, harness, cwd = process.cwd() }) {
   if (dir) return [{ name: "custom", dir: path.resolve(dir) }];
   if (isGlobal) return [{ name: "claude-code (global)", dir: path.join(os.homedir(), ".claude", "skills") }];
 
-  const targets = [];
-  if (fs.existsSync(path.join(cwd, ".claude"))) {
-    targets.push({ name: "claude-code", dir: path.join(cwd, ".claude", "skills") });
-  }
-  if (fs.existsSync(path.join(cwd, ".agents"))) {
-    targets.push({ name: "codex", dir: path.join(cwd, ".agents", "skills") });
+  if (harness && harness.length) {
+    return harness.map((token) => {
+      const h = findHarness(token);
+      if (!h) throw new Error(`Unknown harness: ${token}. Valid: ${harnessIds().join(", ")}`);
+      return harnessTarget(h, cwd);
+    });
   }
-  if (targets.length === 0) {
-    // No harness detected: default to claude-code project layout.
-    targets.push({ name: "claude-code", dir: path.join(cwd, ".claude", "skills") });
+
+  const detected = detectHarnesses(cwd);
+  if (detected.length) return detected.map((h) => harnessTarget(h, cwd));
+  // No harness detected: default to claude-code project layout.
+  return [harnessTarget(HARNESSES[0], cwd)];
+}
+
+/**
+ * Interactive picker: list the four harnesses (detected ones preselected) and
+ * read a comma-separated choice. Streams are injectable for testing; empty or
+ * unparseable input falls back to the preselection.
+ */
+async function promptForTargets({ cwd = process.cwd(), input = process.stdin, output = process.stdout } = {}) {
+  const detected = new Set(detectHarnesses(cwd).map((h) => h.id));
+  const rows = HARNESSES.map((h, i) => ({ n: i + 1, h, detected: detected.has(h.id) }));
+  const preselected = rows.some((r) => r.detected)
+    ? rows.filter((r) => r.detected).map((r) => r.n)
+    : [1];
+
+  output.write("Which agents should get the skills?\n");
+  for (const r of rows) {
+    const mark = preselected.includes(r.n) ? "x" : " ";
+    const tag = r.detected ? "   (detected)" : "";
+    output.write(`  ${r.n}) [${mark}] ${r.h.id.padEnd(11)} ${path.join(r.h.configDir, "skills")}${tag}\n`);
   }
-  return targets;
+
+  const rl = readline.createInterface({ input, output });
+  const answer = await new Promise((resolve) => {
+    rl.question(`Enter numbers (comma-separated) [${preselected.join(",")}]: `, resolve);
+  });
+  rl.close();
+
+  let nums = answer
+    .split(",")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => Number.isInteger(n) && n >= 1 && n <= rows.length);
+  if (!nums.length) nums = preselected;
+
+  return rows.filter((r) => nums.includes(r.n)).map((r) => harnessTarget(r.h, cwd));
 }
 
 function installSkills({ skills, targets, force }) {
@@ -70,12 +138,17 @@ const USAGE = `Usage: tinycloud skills <list|install> [options]
 
 Install options:
   --skill <a,b,...>        Only these skills (default: all)
-  --global                 Install to ~/.claude/skills instead of the project
+  --harness <a,b,...>      Install into these agents: claude-code, agents, codex, cursor
+                           (default: pick from a menu in a terminal; auto-detect otherwise)
+  --global                 Install to ~/.claude/skills instead of the project (Claude Code only)
   --dir <path>             Install to an explicit directory
+  --yes, -y                Skip the interactive menu; use auto-detection
   --force                  Overwrite skills that are already installed
 
-Detection: a project .claude/ dir targets Claude Code (.claude/skills),
-a .agents/ dir targets Codex (.agents/skills); both when both exist.
+Each harness holds skills under <dir>/skills: claude-code → .claude, agents → .agents
+(universal agentskills.io layout), codex → .codex, cursor → .cursor. Run in a terminal
+with no target and you'll be prompted to pick (detected dirs preselected); piped/CI runs
+install into whichever dirs exist, or .claude when none do.
 `;
 
 async function cmdSkills(args) {
@@ -97,7 +170,9 @@ async function cmdSkills(args) {
   let wanted = available;
   let isGlobal = false;
   let force = false;
+  let yes = false;
   let dir;
+  let harness;
   for (let i = 1; i < args.length; i++) {
     if (args[i] === "--skill" && args[i + 1]) {
       const names = args[++i].split(",").map((s) => s.trim()).filter(Boolean);
@@ -106,8 +181,15 @@ async function cmdSkills(args) {
         throw new Error(`Unknown skill(s): ${unknown.join(", ")}. Available: ${available.join(", ")}`);
       }
       wanted = names;
+    } else if (args[i] === "--harness" && args[i + 1]) {
+      harness = args[++i].split(",").map((s) => s.trim()).filter(Boolean);
+      const unknown = harness.filter((id) => !findHarness(id));
+      if (unknown.length) {
+        throw new Error(`Unknown harness(es): ${unknown.join(", ")}. Valid: ${harnessIds().join(", ")}`);
+      }
     } else if (args[i] === "--global") isGlobal = true;
     else if (args[i] === "--force") force = true;
+    else if (args[i] === "--yes" || args[i] === "-y") yes = true;
     else if (args[i] === "--dir" && args[i + 1]) dir = args[++i];
     else throw new Error(`Unknown install option: ${args[i]}\n${USAGE}`);
   }
@@ -116,11 +198,24 @@ async function cmdSkills(args) {
     throw new Error("No bundled skills found in this package installation");
   }
 
-  const targets = resolveTargets({ global: isGlobal, dir });
+  const explicit = dir || isGlobal || (harness && harness.length);
+  const targets =
+    !explicit && !yes && process.stdin.isTTY && process.stdout.isTTY
+      ? await promptForTargets({})
+      : resolveTargets({ global: isGlobal, dir, harness });
+
   const results = installSkills({ skills: wanted, targets, force });
   for (const r of results) console.log(`${r.status === "installed" ? "✓" : "-"} ${r.skill} → ${r.dir} [${r.status}]`);
   const installed = results.filter((r) => r.status === "installed").length;
   console.log(`\n${installed} skill(s) installed${installed ? ". Restart your agent session to pick them up." : "."}`);
 }
 
-module.exports = { cmdSkills, resolveTargets, installSkills, listBundledSkills, bundledSkillsDir };
+module.exports = {
+  cmdSkills,
+  resolveTargets,
+  promptForTargets,
+  installSkills,
+  listBundledSkills,
+  bundledSkillsDir,
+  HARNESSES,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglue/tinycloud",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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,16 @@ 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).
+
+Isolation & scope (0.3.3+): `--home <dir>` / `$TINYCLOUD_HOME` and
+`--profile <name>` are leading flags (before the verb) that run against an
+isolated state home; the agent also takes `--skills <list>` alongside
+`--tools <list>`, and a project-local `.tinycloud/config.json` can pin those
+allowlists and an output base. Sessions are scoped per project. Details:
+[reference/setup.md](reference/setup.md).
 
 ## 3. Workflows (packaged recipes)
 
@@ -159,12 +170,14 @@ 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)
 
-- [reference/setup.md](reference/setup.md) — install, credentials, env vars, preflight details
+- [reference/setup.md](reference/setup.md) — install, credentials, env vars, preflight, profiles & project scope
 - [reference/verbs.md](reference/verbs.md) — every verb, flag, and cost class
 - [reference/envelope.md](reference/envelope.md) — full envelope schema, statuses, error codes, exit codes
 - [reference/pipelines.md](reference/pipelines.md) — pipes, batching, jobs, cache/spend-control flags

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,20 @@ 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.
+
+## State and isolation (0.3.3+)
+
+- **Home** — the directory holding all tinycloud state for a run: config,
+  sessions, cache, jobs, artifacts, and skills. Default `~/.tinycloud`;
+  relocate it with `--home <dir>` or `$TINYCLOUD_HOME`.
+- **Profile** — a named, fully isolated home, selected with `--profile <name>`
+  and managed by `tinycloud profile list|show|create|use|remove`. Lets multiple
+  accounts or installs run side by side without cross-contamination. (Distinct
+  from `watch --profile`, which selects an analysis profile.)
+- **Project scope** — sessions and capabilities keyed to a project (its git
+  root). Sessions live under `<home>/projects/<project-key>/sessions`, and a
+  project-local `.tinycloud/config.json` can pin tool/skill allowlists and an
+  output base — precedence is CLI flags > project config > global config.

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,57 @@ 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_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) |
+
+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.
+
+## Profiles & isolated homes (0.3.3+)
+
+Every piece of tinycloud state — config, sessions, cache, jobs, artifacts, and
+skills — lives under one home (default `~/.tinycloud`). Relocate it to run
+multiple accounts or installs side by side without cross-contamination. Both
+options are *leading* (before the verb) and work with any command:
+
+- `--home <dir>` (or `$TINYCLOUD_HOME`) — use that directory as the home.
+- `--profile <name>` — use a named profile's home (from the profiles registry).
+
+Named profiles are managed by the host-level `profile` verb (a CLI/host
+concern, so it is not in `commands --json`):
+
+```bash
+tinycloud profile list                     # profiles and their homes (active marked *)
+tinycloud profile show [<name>]            # home path + exists/default/active
+tinycloud profile create <name> [--home <dir>] [--copy-from <name>] \
+                                 [--description <text>] [--default]
+tinycloud profile use <name>               # set the default profile
+tinycloud profile remove <name>            # unregister (does not delete the home)
+```
+
+`--copy-from` seeds the new profile's home from an existing one. The registry
+lives at `$XDG_CONFIG_HOME/tinycloud/profiles.json`; `default` is reserved.
+This global `--profile <name>` is unrelated to `watch --profile
+default|light|custom` (that flag selects an analysis profile).
+
+## Project scope (0.3.3+)
+
+Within a home, sessions are scoped per project — keyed by the canonical git
+root — under `<home>/projects/<project-key>/sessions`. In the interactive
+agent, `/sessions` lists the current project's sessions (`/sessions all` spans
+every project); `-c` resumes the most recent and still falls back to legacy
+flat sessions (read-only, migrated forward on resume).
+
+A project can also carry a local `.tinycloud/config.json` that scopes a run:
+
+- `preferences.tools` / `preferences.skills` — allowlists of agent tool / skill
+  names (omit = all; the `--tools` / `--skills` flags override them).
+- `preferences.outputBase` — where generated files land (a relative path is
+  anchored to the project root; `$TINYCLOUD_OUT` still wins).
+
+Precedence is **CLI flags > project-local `.tinycloud/config.json` > global
+config**; a more specific scope replaces (does not merge) a broader one.
+Read-only mode always keeps the `read` and `bash` tools.

package/skills/tinycloud/reference/verbs.md

@@ -23,6 +23,24 @@ every verb. Regenerate doubts from it instead of trusting prose.
 Cloud verbs run through the configured Cloudglue API key.
 `caption`/`library`/`workflow` vary by what they end up doing.
 
+## Global flags (0.3.3+)
+
+Leading options (placed *before* the verb) and agent-level allowlists, separate
+from the per-verb flags below. `--home`/`--profile` and the `profile` verb are
+host concerns and are intentionally absent from `commands --json`.
+
+- `--home <dir>` / `$TINYCLOUD_HOME` — run against an isolated state home
+  (config, sessions, cache, jobs, artifacts, skills) instead of `~/.tinycloud`.
+- `--profile <name>` — use a named profile's home. Managed by
+  `tinycloud profile list|show|create|use|remove`
+  (`create <name> [--home <dir>] [--copy-from <name>] [--description <text>] [--default]`).
+  Unrelated to `watch --profile default|light|custom` (an analysis profile).
+- `--skills <list>` (0.3.3+) / `--tools <list>` — comma-separated agent skill /
+  tool allowlists (omit = all); also settable per project via
+  `.tinycloud/config.json`.
+
+Profiles, project-scoped sessions, and `.tinycloud/config.json`: [setup.md](setup.md).
+
 ## Per-verb flags
 
 Flags shared by most verbs are listed once at the bottom.
@@ -31,20 +49,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 +134,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 +239,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/reference/workflow-authoring.md

@@ -141,5 +141,9 @@ are not implemented in 0.3.x — treat `partial`/`paused` as terminal.
 The tinycloud agent picks it up on next start; from any shell it runs by
 path: `tinycloud workflow run ~/.tinycloud/skills/my-skill/my-skill.yaml demo.mp4 --allow-command --json`.
 
+With `--home`/`--profile` (0.3.3+) the global skills dir moves under the active
+home (`<home>/skills/`); a project-local `.tinycloud/config.json` can also pin
+which skills load via a `preferences.skills` allowlist.
+
 To wrap a recipe as a skill for *this* host agent instead, see the
 `tinycloud-skill-creator` skill in this repo.

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",

package/skills/tinycloud-init/SKILL.md

@@ -75,6 +75,9 @@ Report what's now working and point forward:
   uses the API key)
 - One-command workflows: `tinycloud workflow list --json` (sales-coaching,
   blog-post, ad-analysis, meeting-breakdown, youtube-publish, …)
+- Multiple accounts or isolated installs (0.3.3+): `tinycloud profile create
+  <name> --default`, then `--profile <name>` (or `--home <dir>` /
+  `$TINYCLOUD_HOME`) on any command to switch state homes
 - If the general `tinycloud` skill is installed alongside this one, it
   documents the full CLI, envelope contract, and a glossary; its
   `scripts/preflight.sh` re-checks this setup any time.

package/skills/tinycloud-skill-creator/SKILL.md

@@ -44,6 +44,8 @@ Before writing anything, establish:
     `.claude/skills/<name>/`) whose SKILL.md runs the recipe **by path**.
   - *The tinycloud agent*: `~/.tinycloud/skills/<name>/` (global) or
     `.tinycloud/skills/<name>/` (project), picked up as `/skills:<name>`.
+    (With `--home`/`--profile`, 0.3.3+, the global dir is the active home's
+    `skills/`; a project's `.tinycloud/config.json` can allowlist skills.)
 
 ## 2. Scaffold