@cloudglue/tinycloud 0.3.2 → 0.3.4

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.4` always runs tinycloud 0.3.4. It also adds two
 wrapper commands:
 
 ```bash
-tinycloud install --version 0.3.0   # pre-download a version
+tinycloud install --version 0.3.4   # 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,133 @@ 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) |
+| `face` | Detect faces in a video, or match/search a known face, ranked by similarity |
+| `library` | Build & query Cloudglue collections (create/add/remove/delete) and browse 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
+# Detect faces, or match a known face against a video (0.3.4+)
+tinycloud face match ./person.jpg ./demo.mp4 --max-faces 10 --json
+```
+
+**Collections (0.3.4+)** turn a set of videos into a reusable, queryable
+knowledge base. Build one and query it — every type follows the same
+`create → add → poll show → query → delete` shape, differing only in `--type`
+and the verb that reads it:
+
+```bash
+tinycloud library collections create "calls" --type media-descriptions --json
+tinycloud library collections add ./call.mp4 --to col_123 --json   # enrichment is async
+tinycloud library collections show col_123 --json                  # poll files[].status → completed
+tinycloud ask "What did customers object to?" --in collection:col_123 --json
+```
+
+`media-descriptions` backs `ask`/`probe`/`search`, `face-analysis` backs
+`face list`/`face search`, and `entities` (created with `--prompt`/`--schema`)
+backs `library collections entities`.
+
+`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.2",
+  "version": "0.3.4",
   "description": "Agent CLI for deep video work, by Cloudglue. Downloads the tinycloud binary on first run.",
   "bin": {
     "tinycloud": "bin/tinycloud.js"
@@ -23,6 +23,6 @@
     "url": "git+https://github.com/cloudglue/tinycloud.git"
   },
   "homepage": "https://tinycloud.sh",
-  "keywords": ["video", "cloudglue", "cli", "agent", "captions", "clips"],
+  "keywords": ["video", "cloudglue", "cli", "agent", "captions", "clips", "face-detection"],
   "license": "SEE LICENSE IN LICENSE.md"
 }

package/skills/tinycloud/SKILL.md

@@ -61,8 +61,8 @@ Full schema and error codes: [reference/envelope.md](reference/envelope.md).
 
 ## 2. Core verbs (cheat sheet)
 
-Cloud verbs (`watch extract probe ask publish`) call the Cloudglue API using
-the configured key — usage is billed per the
+Cloud verbs (`watch extract probe ask publish face`) call the Cloudglue API
+using the configured key — usage is billed per the
 [rate card](https://app.cloudglue.dev/home/billing/rate-card). `search clip
 setup` are local and free; `grab jobs` are network-only.
 `tinycloud commands --json` is the authoritative command/flag list.
@@ -89,13 +89,29 @@ tinycloud clip cut ./demo.mp4 --start 12 --end 28 -o ./tinycloud-output/clip.mp4
 tinycloud clip thumbs ./demo.mp4 --interval 5 -o ./tinycloud-output/thumbs/ --json
 tinycloud clip burn ./demo.mp4 --subtitle-file ./captions/demo.srt -o ./out.mp4 --json
 
-# Remote videos, collections, async jobs
+# 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
+
+# Remote videos, 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
 
+# 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
+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):
+tinycloud ask "what's discussed?" --in collection:col_desc --json             #   media-descriptions → ask / probe / search
+tinycloud face search ./person.jpg --in collection:col_faces --json           #   face-analysis      → face list / face search
+tinycloud library collections entities col_ents ./demo.mp4 --json             #   entities           → collections entities
+tinycloud library collections remove cloudglue://files/<id> --from col_desc --json
+tinycloud library collections delete col_desc --json
+
 # Publish an HTML artifact to Cloudglue Sites (manage with list / unpublish)
 tinycloud publish ./tinycloud-output/html/report.html --name report --visibility private --json
 tinycloud publish list --json
@@ -110,6 +126,13 @@ 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)
 
 Repeatable pipelines run with one command and write outputs into a run
@@ -170,7 +193,7 @@ Authoring your own recipes: [reference/workflow-authoring.md](reference/workflow
 
 ## 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/glossary.md

@@ -23,7 +23,15 @@ connector?" or an envelope field needs explaining.
   reuse the file.
 - **Collection** — a named group of Cloudglue files (id `col_…`), e.g. "all
   sales calls". Verbs scope to one with `--in collection:col_…`. Collection
-  ids are stable; display names are not.
+  ids are stable; display names are not. A collection has a type that decides
+  which verb reads it: `media-descriptions` (default) backs `ask`/`probe`/`search`,
+  `face-analysis` backs `face list`/`face search`, and `entities` (created with
+  `--prompt`/`--schema`) backs `library collections entities` (`rich-transcripts`
+  also exists). Manage them with `library collections create|add|remove|delete`
+  (0.3.4+); every type follows `create → add → poll show → query → delete`. `add`
+  enriches each file asynchronously and returns `pending` — poll
+  `library collections show <col>` until every `files[].status` is `completed`
+  before querying.
 - **Data connector** — a linked external source of recordings (Zoom, Grain,
   Google Drive, Dropbox, Loom, S3/GCS). `tinycloud library connectors …`
   lists, browses (`files`, with provider-specific filters), and syncs
@@ -88,3 +96,17 @@ 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.
+
+## 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

@@ -92,10 +92,34 @@ tinycloud clip burn ./demo.mp4 \
 tinycloud grab https://youtu.be/<id> -o ./tinycloud-output/grabbed/ --json
 tinycloud watch ./tinycloud-output/grabbed/<file>.mp4 --json
 
-# Collection: mirror artifacts locally, then search/Q&A against it
+# Collections (0.3.4+) all follow one lifecycle — create → add → poll show → query → delete.
+# `add` enriches each file asynchronously and returns pending; poll `collections show`
+# and wait until every files[].status is `completed` before querying.
+
+# media-descriptions (default) → ask / probe / search
+tinycloud library collections create "sales-calls" --type media-descriptions --json
+tinycloud library collections add ./call-1.mp4 --to col_123 --json        # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud probe "pricing objections" --in collection:col_123 --scope segment --json
+tinycloud ask "What did customers object to across these calls?" --in collection:col_123 --json
+tinycloud library collections delete col_123 --json
+
+# face-analysis → face list / face search
+tinycloud library collections create faces --type face-analysis --json
+tinycloud library collections add ./interview.mp4 --to col_123 --json     # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud face list ./interview.mp4 --in collection:col_123 --json         # stored detections for that video
+tinycloud face search ./headshot.jpg --in collection:col_123 --group-by file --json
+
+# entities (create needs --prompt or --schema) → library collections entities
+tinycloud library collections create ents --type entities --prompt "people, places, objects" --json
+tinycloud library collections add ./interview.mp4 --to col_123 --json     # → pending
+tinycloud library collections show col_123 --json                          # poll files[].status → completed
+tinycloud library collections entities col_123 ./interview.mp4 --json      # structured entities (video + segment level)
+
+# Already-built collection: mirror description/transcript artifacts locally for free `search`
 tinycloud library collections sync col_123 --artifacts descriptions,transcripts --json
-tinycloud probe "pricing discussion" --in collection:col_123 --scope segment --json
-tinycloud ask "What did customers object to?" --in collection:col_123 --json
+tinycloud search "discount" --in collection:col_123 --json
 
 # Extract timestamped findings → cut them into clips
 tinycloud watch ./talk.mp4 --json \

package/skills/tinycloud/reference/setup.md

@@ -25,7 +25,8 @@ supported — use WSL2. More at https://tinycloud.sh.
 
 ## Credentials
 
-Cloud verbs (`watch extract probe ask publish`) need a Cloudglue API key.
+Cloud verbs (`watch extract probe ask publish face`) need a Cloudglue API key
+(as do `library collections add` and the collection reads).
 Usage is billed to that key per the
 [rate card](https://app.cloudglue.dev/home/billing/rate-card).
 
@@ -95,9 +96,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

@@ -14,7 +14,8 @@ every verb. Regenerate doubts from it instead of trusting prose.
 | `ask` | cloud | yes | Grounded Q&A over one or more videos |
 | `clip` | local | no | Cuts, thumbs, audio, stitch, split, transcode, burn, explore |
 | `grab` | network | no | Download a remote video (YouTube, TikTok, Loom, direct) |
-| `library` | varies | no | Collections, connectors, local mirrors, sync |
+| `face` | cloud | yes | Detect faces in a video, or match/search a query face (0.3.4+) |
+| `library` | varies | no | Collections (incl. create/add/remove/delete), connectors, mirrors, sync |
 | `jobs` | network | yes | Poll/wait/forget tracked async jobs |
 | `workflow` | varies | no | Validate/plan/run workflow recipes |
 | `publish` | cloud | yes | Publish HTML/code artifacts as Cloudglue Sites; share videos |
@@ -23,6 +24,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.
@@ -108,17 +127,84 @@ tinycloud clip cut --from-findings -o clips/        # cut timestamped findings p
 tinycloud grab <url> [-o <file-or-dir>] [--audio-only] [--format <yt-dlp-selector>]
 ```
 
+### face — detect & match faces (cloud, 0.3.4+)
+
+```bash
+tinycloud face detect <source> [--fps <n>] [--start <t>] [--end <t>]
+  [--thumbnails] [--limit <n>] --json
+tinycloud face match <image> <source> [--max-faces <n>] [--min-similarity <0-100>]
+  [--fps <n>] [--start <t>] [--end <t>] [--thumbnails] --json
+tinycloud face list <source> --in collection:col_… [--limit <n>] [--offset <n>] --json
+tinycloud face search <image> --in collection:col_… [col_…]
+  [--min-score <n>] [--group-by file] [--limit <n>] --json
+```
+
+`detect` runs Cloudglue face detection over a video and returns every face as
+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`
+(`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`,
+`--thumbnails` adds per-face frame URLs.
+
+`list` and `search` operate over a **face-analysis collection** (create one with
+`library collections create --type face-analysis` and add videos with
+`library collections add`): `list` reads a video's stored detections; `search`
+finds the query face across one or more collections (`--min-score`,
+`--group-by file`). `total` reports the server-available count across all modes
+(never rewritten by client `--min-*`/`--limit` filters).
+
 ### library — collections and connectors
 
 ```bash
 tinycloud library collections list --json
-tinycloud library collections show <col_id> --json
+tinycloud library collections show <col_id> --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] [--description <text>] [--prompt <text> | --schema <file>] --json
+tinycloud library collections add <source> --to <col_id> [--no-upload] [--no-download] --json
+tinycloud library collections remove <source> --from <col_id> --json
+tinycloud library collections delete <col_id> --json
+tinycloud library collections entities <col_id> <source> [--limit <n>] [--offset <n>] --json   # read a video's entities
 tinycloud library connectors list --json
 tinycloud library connectors files <connector-id> [--limit 25] [--page-token <t>] --json
 tinycloud library connectors sync [<connector-id>] <uri-share-link-or-public-url> --json
 ```
 
+`collections create|add|remove|delete` are the only writes in an otherwise
+read-only `library` (gated by the `library.collections.create.v1` /
+`library.collections.mutate.v1` feature ids). `create` defaults to
+`--type media-descriptions`; an `entities` collection also needs an extraction
+spec — `--prompt <text>` or `--schema <file.json>` — or `create` errors. `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; `remove` (`--from <col>`) takes a Cloudglue file
+id/uri; `delete` removes the whole collection (and cleans the local mirror).
+Collection ids accept a bare uuid, a `col_…` slug, or `collection:<id>` /
+`cloudglue://collections/<id>` forms, consistently across read and write paths.
+
+**Readiness — always poll before querying.** `add` enriches each file
+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.
+
+The collection's `--type` decides which verb reads it (every type follows the
+same `create → add → poll show → query → delete` lifecycle):
+
+| `--type` | read with |
+|---|---|
+| `media-descriptions` (default) | `ask` / `probe` / `search` (`--in collection:<col>`) |
+| `face-analysis` | `face list` / `face search` |
+| `entities` (needs `--prompt`/`--schema`) | `library collections entities <col> <source>` |
+| `rich-transcripts` | `collections sync --artifacts transcripts` |
+
+`collections entities <col> <source>` returns a video's extracted entities
+(video- and segment-level, `--limit`/`--offset`) from an `entities` collection.
+For a one-off per-video pull without standing up a collection, `extract` returns
+entities/facts directly (free-form query or `--schema`).
+
 `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
@@ -257,11 +343,16 @@ Output: `--json` (force JSONL envelopes), `--pretty` (one JSON array),
 `--data raw`, `--raw-output` (raw backend payload; disables pipe protocol),
 `--quiet`, `--verbose`.
 
-Cache/spend — on `watch`, `extract`, `caption`, and `workflow` only:
+Cache — on `watch`, `extract`, `caption`, `face`, and `workflow` only:
 `--refresh` (recompute), `--no-cache` (no persistence), `--cached` (reuse
-exact-match history), `--no-upload` (refuse cloud upload → `needs_upload`),
-`--no-download` (refuse local materialization → `needs_download`).
-`ask`/`probe` always call the cloud; use `search` for a free cached lookup.
+exact-match history). `ask`/`probe` always call the cloud; use `search` for a
+free cached lookup.
+
+Upload/download refusal — on every verb that resolves a source:
+`--no-upload` (refuse cloud upload → `needs_upload`) on `watch`/`extract`/
+`caption`/`face`/`workflow`/`publish` and `library collections add`;
+`--no-download` (refuse local materialization → `needs_download`) on the same
+set minus `publish`.
 
 Source reuse (`watch`/`extract`/`caption`): `--source-id <id>`, `--result-id <id>`.
 

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.2"
+MIN_VERSION="0.3.4"
 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 library.sync.url.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 face.v1 jobs.v1 library.collections.v1 library.collections.create.v1 library.collections.mutate.v1 library.collections.entities.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.3.0",
+  "skill_version": "0.3.4",
   "tinycloud": {
-    "min_version": "0.3.2",
-    "supported_range": ">=0.3.2 <0.4.0",
+    "min_version": "0.3.4",
+    "supported_range": ">=0.3.4 <0.4.0",
     "required_features": [
       "envelope.v1",
       "watch.v1",
@@ -13,8 +13,12 @@
       "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.sync.url.v1",
       "workflow.v1",
       "publish.v1",

package/skills/tinycloud-init/SKILL.md

@@ -22,14 +22,16 @@ in order, skipping any that already pass.
 command -v tinycloud && tinycloud --version --json </dev/null
 ```
 
-If installed and the JSON reports `"version"` ≥ 0.3.0, go to step 2. If
-missing (or no machine-readable version), install it — ask the user which
-they prefer:
+If installed and the JSON reports `"version"` ≥ 0.3.4 (the floor the tinycloud
+skill requires), go to step 2. If missing, older than 0.3.4, or no
+machine-readable version, install or upgrade it — ask the user which they
+prefer:
 
 ```bash
-npm install -g @cloudglue/tinycloud          # canonical (Node >= 18)
+npm install -g @cloudglue/tinycloud          # canonical (Node >= 18); reinstall to upgrade
 # or
 curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+tinycloud update                             # already installed but older → move to latest stable
 ```
 
 The first run downloads the platform distribution (~90 MB, one time). More
@@ -75,6 +77,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