@cloudglue/tinycloud 0.3.0

package/lib/manifest.js

@@ -0,0 +1,181 @@
+"use strict";
+
+const { execFileSync } = require("node:child_process");
+
+const DEFAULT_BASE = "https://media.cloudglue.dev/tinycloud-dist";
+
+// Node's fetch ignores proxy env vars; shell out to curl when one is set so
+// the manifest/sidecar fetches behave like the tarball download (and like
+// install.sh, which always uses curl).
+function useCurl() {
+  return !!(process.env.HTTPS_PROXY || process.env.https_proxy || process.env.TINYCLOUD_USE_CURL === "1");
+}
+
+/** GET url → {status, text}. status 0 = network failure. Proxy-aware. */
+async function httpGetText(url) {
+  if (useCurl()) {
+    try {
+      const out = execFileSync("curl", ["-sSL", "-w", "\n%{http_code}", url], { encoding: "utf8" });
+      const i = out.lastIndexOf("\n");
+      return { status: Number(out.slice(i + 1).trim()) || 0, text: out.slice(0, i) };
+    } catch {
+      return { status: 0, text: "" };
+    }
+  }
+  try {
+    const res = await fetch(url);
+    return { status: res.status, text: res.ok ? await res.text() : "" };
+  } catch {
+    return { status: 0, text: "" };
+  }
+}
+
+/** HEAD url → ETag header value or null. Proxy-aware. */
+async function httpHeadEtag(url) {
+  if (useCurl()) {
+    try {
+      const out = execFileSync("curl", ["-sSIL", url], { encoding: "utf8" });
+      const m = out.match(/^etag:\s*(.+)$/im);
+      return m ? m[1].trim() : null;
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const res = await fetch(url, { method: "HEAD" });
+    return res.ok ? res.headers.get("etag") : null;
+  } catch {
+    return null;
+  }
+}
+
+function baseUrl() {
+  return (process.env.TINYCLOUD_DIST_URL || DEFAULT_BASE).replace(/\/+$/, "");
+}
+
+function requireManifest() {
+  return process.env.TINYCLOUD_REQUIRE_MANIFEST === "1";
+}
+
+// Pinned tarballs on the CDN are v-prefixed (tinycloud-<platform>-v0.3.0.tar.gz);
+// version strings stay bare everywhere else.
+function tarballName(target, version) {
+  return version ? `tinycloud-${target}-v${version}.tar.gz` : `tinycloud-${target}.tar.gz`;
+}
+
+/**
+ * The manifest is an optimization, never a requirement (unless strict mode):
+ * a missing, erroring, or unusable manifest (CloudFront 403-for-missing,
+ * 5xx, captive-portal HTML, future schema) degrades to null so commands
+ * that don't need it keep working. Checksum MISMATCHES still always fail.
+ */
+async function fetchManifest() {
+  const url = `${baseUrl()}/manifest.json`;
+  const degrade = (reason) => {
+    if (requireManifest()) {
+      throw new Error(`TINYCLOUD_REQUIRE_MANIFEST=1 but the release manifest is unavailable: ${reason}`);
+    }
+    return null;
+  };
+  const { status, text } = await httpGetText(url);
+  if (status === 0 || status === 403 || status === 404) {
+    return degrade(`${url} is missing (HTTP ${status || "network error"})`);
+  }
+  if (status !== 200) {
+    process.stderr.write(`tinycloud: fetching ${url} failed (HTTP ${status}); proceeding without it\n`);
+    return degrade(`HTTP ${status}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch {
+    process.stderr.write(`tinycloud: ${url} is not valid JSON; proceeding without it\n`);
+    return degrade("invalid JSON");
+  }
+  if (manifest.schema !== 1) {
+    process.stderr.write(
+      `tinycloud: unsupported manifest schema ${manifest.schema} at ${url}; proceeding without it (upgrade @cloudglue/tinycloud)\n`
+    );
+    return degrade(`unsupported schema ${manifest.schema}`);
+  }
+  return manifest;
+}
+
+/** Try the <tarball>.sha256 sidecar; returns the hex hash or null. */
+async function fetchSidecarSha256(tarballUrl) {
+  const { status, text } = await httpGetText(`${tarballUrl}.sha256`);
+  if (status !== 200) return null;
+  const match = text.trim().match(/^[0-9a-f]{64}/i);
+  return match ? match[0].toLowerCase() : null;
+}
+
+/**
+ * Resolve a version request to a concrete download.
+ * @param {string} versionOrLatest exact semver, or "latest"
+ * @param {string} channel "stable" | "beta"
+ * @param {string} target platform key like "darwin-arm64"
+ * @returns {{version: string|null, url: string, sha256: string|null, size: number|null, verified: boolean}}
+ */
+async function resolveDownload(versionOrLatest, channel, target, prefetchedManifest) {
+  // Callers that already fetched the manifest (update / install --latest)
+  // pass it in to avoid a second network round-trip for the same JSON.
+  const manifest = prefetchedManifest !== undefined ? prefetchedManifest : await fetchManifest();
+  const base = baseUrl();
+
+  if (manifest) {
+    let version = versionOrLatest;
+    const userPinned = versionOrLatest !== "latest";
+    if (versionOrLatest === "latest") {
+      version = manifest.channels && manifest.channels[channel];
+      if (!version) throw new Error(`Channel "${channel}" has no released version in the manifest`);
+      // Manifest-resolved versions get the same leading-v normalization as
+      // user input (install.sh does the same with ${VERSION#v})
+      version = String(version).replace(/^v/, "");
+    }
+    const entry = manifest.versions && manifest.versions[version];
+    const plat = entry && entry.platforms && entry.platforms[target];
+    if (plat) {
+      // An explicit distribution base (mirror, fixture) wins over the
+      // manifest's absolute URLs — otherwise the override only redirects
+      // the manifest fetch while tarballs still hit the canonical CDN.
+      const url = process.env.TINYCLOUD_DIST_URL ? `${base}/${plat.url.split("/").pop()}` : plat.url;
+      return { version, url, sha256: plat.sha256 || null, size: plat.size || null, verified: !!plat.sha256 };
+    }
+    if (!userPinned || requireManifest()) {
+      throw new Error(
+        entry ? `Version ${version} has no build for ${target}` : `Version ${version} not found in the release manifest`
+      );
+    }
+    // A user-pinned version missing from the manifest (e.g. a pre-manifest
+    // release whose tarball is still on the CDN) falls back to the
+    // conventional URL + sidecar instead of hard-failing.
+    process.stderr.write(`tinycloud: version ${version} is not in the release manifest; trying the direct URL\n`);
+    const url = `${base}/${tarballName(target, version)}`;
+    const sha256 = await fetchSidecarSha256(url);
+    return { version, url, sha256, size: null, verified: !!sha256 };
+  }
+
+  // No manifest published: fall back to direct tarball URLs.
+  if (channel !== "stable") {
+    throw new Error(`Channel "${channel}" requires the release manifest, which is not available`);
+  }
+  const version = versionOrLatest === "latest" ? null : versionOrLatest;
+  const url = `${base}/${tarballName(target, version)}`;
+  const sha256 = await fetchSidecarSha256(url);
+  if (!sha256) {
+    process.stderr.write(
+      "tinycloud: release manifest and checksum sidecar not found — proceeding without checksum verification\n"
+    );
+  }
+  return { version, url, sha256, size: null, verified: !!sha256 };
+}
+
+module.exports = {
+  baseUrl,
+  fetchManifest,
+  fetchSidecarSha256,
+  resolveDownload,
+  tarballName,
+  httpHeadEtag,
+  DEFAULT_BASE,
+};

package/lib/platform.js

@@ -0,0 +1,22 @@
+"use strict";
+
+const SUPPORTED = new Set(["darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"]);
+
+class PlatformError extends Error {}
+
+/** Resolve the current platform to a distribution target like "darwin-arm64". */
+function resolveTarget(platform = process.platform, arch = process.arch) {
+  if (platform === "win32") {
+    throw new PlatformError(
+      "Windows is not supported. Use WSL2 (https://learn.microsoft.com/windows/wsl/) and re-run inside your Linux distro."
+    );
+  }
+  const normArch = arch === "x64" || arch === "amd64" ? "x64" : arch === "aarch64" ? "arm64" : arch;
+  const key = `${platform}-${normArch}`;
+  if (!SUPPORTED.has(key)) {
+    throw new PlatformError(`Unsupported platform: ${key}. Supported: ${[...SUPPORTED].join(", ")}`);
+  }
+  return key;
+}
+
+module.exports = { resolveTarget, SUPPORTED, PlatformError };

package/lib/run.js

@@ -0,0 +1,43 @@
+"use strict";
+
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+/**
+ * Exec passthrough to the real binary: inherit stdio, forward signals, and
+ * preserve exit semantics (including 128+n signal death).
+ */
+function run(binPath, args, installDir) {
+  const env = {
+    ...process.env,
+    PATH: `${path.join(installDir, "bin")}${path.delimiter}${process.env.PATH || ""}`,
+  };
+  const child = spawn(binPath, args, { stdio: "inherit", env });
+  const forwarders = new Map();
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    const forward = () => {
+      try {
+        child.kill(sig);
+      } catch {}
+    };
+    forwarders.set(sig, forward);
+    process.on(sig, forward);
+  }
+  child.on("error", (err) => {
+    process.stderr.write(`tinycloud: failed to launch binary: ${err.message}\n`);
+    process.exit(1);
+  });
+  child.on("close", (code, signal) => {
+    if (signal) {
+      // Remove only our forwarder (not listeners owned by parent tooling),
+      // then re-raise so our exit status preserves 128+n semantics.
+      const forward = forwarders.get(signal);
+      if (forward) process.removeListener(signal, forward);
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code == null ? 1 : code);
+  });
+}
+
+module.exports = { run };

package/lib/skills.js

@@ -0,0 +1,126 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+// Agent skills bundled with this package (the npm tarball includes skills/).
+function bundledSkillsDir() {
+  return path.join(__dirname, "..", "skills");
+}
+
+function listBundledSkills() {
+  const dir = bundledSkillsDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((e) => fs.existsSync(path.join(dir, e, "SKILL.md")))
+    .sort();
+}
+
+/**
+ * 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.
+ *   claude-code: <project>/.claude/skills  (global: ~/.claude/skills)
+ *   codex:       <project>/.agents/skills  (agentskills.io layout)
+ */
+function resolveTargets({ global: isGlobal, dir, 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 (targets.length === 0) {
+    // No harness detected: default to claude-code project layout.
+    targets.push({ name: "claude-code", dir: path.join(cwd, ".claude", "skills") });
+  }
+  return targets;
+}
+
+function installSkills({ skills, targets, force }) {
+  const src = bundledSkillsDir();
+  const results = [];
+  for (const target of targets) {
+    fs.mkdirSync(target.dir, { recursive: true });
+    for (const skill of skills) {
+      const from = path.join(src, skill);
+      const to = path.join(target.dir, skill);
+      if (fs.existsSync(to) && !force) {
+        results.push({ target: target.name, skill, dir: to, status: "skipped (exists; use --force)" });
+        continue;
+      }
+      fs.rmSync(to, { recursive: true, force: true });
+      fs.cpSync(from, to, { recursive: true });
+      results.push({ target: target.name, skill, dir: to, status: "installed" });
+    }
+  }
+  return results;
+}
+
+const USAGE = `Usage: tinycloud skills <list|install> [options]
+
+  list                     List the agent skills bundled with this package
+  install                  Copy skills into your agent's skills directory
+
+Install options:
+  --skill <a,b,...>        Only these skills (default: all)
+  --global                 Install to ~/.claude/skills instead of the project
+  --dir <path>             Install to an explicit directory
+  --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.
+`;
+
+async function cmdSkills(args) {
+  const action = args[0];
+  const available = listBundledSkills();
+
+  if (!action || action === "--help" || action === "-h") {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (action === "list") {
+    for (const s of available) console.log(s);
+    return;
+  }
+  if (action !== "install") {
+    throw new Error(`Unknown skills action: ${action}\n${USAGE}`);
+  }
+
+  let wanted = available;
+  let isGlobal = false;
+  let force = false;
+  let dir;
+  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);
+      const unknown = names.filter((n) => !available.includes(n));
+      if (unknown.length) {
+        throw new Error(`Unknown skill(s): ${unknown.join(", ")}. Available: ${available.join(", ")}`);
+      }
+      wanted = names;
+    } else if (args[i] === "--global") isGlobal = true;
+    else if (args[i] === "--force") force = true;
+    else if (args[i] === "--dir" && args[i + 1]) dir = args[++i];
+    else throw new Error(`Unknown install option: ${args[i]}\n${USAGE}`);
+  }
+
+  if (available.length === 0) {
+    throw new Error("No bundled skills found in this package installation");
+  }
+
+  const targets = resolveTargets({ global: isGlobal, dir });
+  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 };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@cloudglue/tinycloud",
+  "version": "0.3.0",
+  "description": "Agent CLI for deep video work, by Cloudglue. Downloads the tinycloud binary on first run.",
+  "bin": {
+    "tinycloud": "bin/tinycloud.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "LICENSE.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudglue/tinycloud.git"
+  },
+  "homepage": "https://tinycloud.sh",
+  "keywords": ["video", "cloudglue", "cli", "agent", "captions", "clips"],
+  "license": "SEE LICENSE IN LICENSE.md"
+}

package/skills/ad-analysis/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: ad-analysis
+description: >-
+  Analyze a video ad into an HTML breakdown with shot timeline, hook
+  classification, pacing, structure, CTA, and takeaways. Use when the user
+  wants ad creative analysis, competitive ad research, or a hook/pacing/CTA
+  breakdown of a commercial or social ad. Takes one source: a local video
+  file, URL, or cloudglue:// file URI (e.g. cloudglue://files/<id>). Runs the built-in tinycloud "ad-analysis"
+  workflow; requires the tinycloud CLI configured with a Cloudglue API key
+  (analysis runs through the user's Cloudglue account).
+argument-hint: "[ad video file, URL, or cloudglue:// file URI]"
+arguments: source
+---
+
+# Video-ad analysis
+
+This skill is a thin wrapper around the `ad-analysis` workflow recipe bundled
+inside the tinycloud binary (`watch → extract → render`).
+
+## Run
+
+1. **Check the CLI.** If the general `tinycloud` skill is installed alongside
+   this one, run its `scripts/preflight.sh`. Otherwise verify directly:
+
+   ```bash
+   tinycloud setup --check --json   # ready when data.ok == true
+   ```
+
+   Missing CLI: `npm install -g @cloudglue/tinycloud` (see https://tinycloud.sh).
+   Missing key: `tinycloud setup cloudglue --api-key <key>`.
+
+2. **Confirm the recipe is available** (free, no cloud calls):
+
+   ```bash
+   tinycloud workflow validate ad-analysis --json
+   ```
+
+3. **Run it** with the user's source. The analysis steps run through the
+   configured Cloudglue API key — if the user has not clearly asked to run
+   it, show the step plan first with
+   `tinycloud workflow plan ad-analysis $source --json` (free).
+
+   ```bash
+   tinycloud workflow ad-analysis $source --json
+   ```
+
+   Useful params: `--param segment=shots` (default; shot-level timeline the
+   breakdown is built around) or `--param segment=uniform:20` for a lighter
+   uniform pass; `--param out=<path>` to control the HTML location.
+
+## Read the result
+
+Parse the single JSON envelope from stdout (machine output; logs are stderr):
+
+- Success: `status == "ready"` and `data.status == "completed"`.
+- The analysis path is `data.outputs.html` (also in `data.artifacts[]`).
+  Default: `./tinycloud-output/runs/<data.run_id>/ad-analysis.html`.
+- Report the HTML path; offer
+  `tinycloud publish <html> --name ad-analysis --visibility private --json`
+  to host it as a shareable page.
+
+Any other `status` (`needs_credentials`, `needs_upload`, `pending`, `paused`,
+`error`) or `data.status` of `partial`/`failed`: stop, report the envelope's
+`error.message`, and follow its `setup` / `resume` / `next` hints. The general
+`tinycloud` skill (if installed) documents full status handling.

package/skills/blog-post/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: blog-post
+description: >-
+  Transform a video into a rich blog post (HTML + embedded markdown) with
+  sections, thumbnails, and key takeaways. Use when the user wants to turn a
+  video, talk, demo, or tutorial into a written article or blog content.
+  Takes one source: a local video file, URL, or cloudglue:// file URI (e.g. cloudglue://files/<id>). Runs the
+  built-in tinycloud "blog-post" workflow; requires the tinycloud CLI
+  configured with a Cloudglue API key (analysis runs through the user's
+  Cloudglue account).
+argument-hint: "[video file, URL, or cloudglue:// file URI]"
+arguments: source
+---
+
+# Video → blog post
+
+This skill is a thin wrapper around the `blog-post` workflow recipe bundled
+inside the tinycloud binary (`watch → extract → render`).
+
+## Run
+
+1. **Check the CLI.** If the general `tinycloud` skill is installed alongside
+   this one, run its `scripts/preflight.sh`. Otherwise verify directly:
+
+   ```bash
+   tinycloud setup --check --json   # ready when data.ok == true
+   ```
+
+   Missing CLI: `npm install -g @cloudglue/tinycloud` (see https://tinycloud.sh).
+   Missing key: `tinycloud setup cloudglue --api-key <key>`.
+
+2. **Confirm the recipe is available** (free, no cloud calls):
+
+   ```bash
+   tinycloud workflow validate blog-post --json
+   ```
+
+3. **Run it** with the user's source. The analysis steps run through the
+   configured Cloudglue API key — if the user has not clearly asked to run
+   it, show the step plan first with
+   `tinycloud workflow plan blog-post $source --json` (free).
+
+   ```bash
+   tinycloud workflow blog-post $source --json
+   ```
+
+   Useful params: `--param segment=chapters` (default; semantic section
+   anchors) or `--param segment=uniform:20` for a lighter pass;
+   `--param out=<path>` to control the HTML location.
+
+## Read the result
+
+Parse the single JSON envelope from stdout (machine output; logs are stderr):
+
+- Success: `status == "ready"` and `data.status == "completed"`.
+- The article path is `data.outputs.html` (also in `data.artifacts[]`).
+  Default: `./tinycloud-output/runs/<data.run_id>/blog-post.html`.
+- Report the HTML path; offer
+  `tinycloud publish <html> --name blog-post --visibility private --json`
+  to host it as a shareable page.
+
+Any other `status` (`needs_credentials`, `needs_upload`, `pending`, `paused`,
+`error`) or `data.status` of `partial`/`failed`: stop, report the envelope's
+`error.message`, and follow its `setup` / `resume` / `next` hints. The general
+`tinycloud` skill (if installed) documents full status handling.

package/skills/meeting-breakdown/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: meeting-breakdown
+description: >-
+  Generate a visual meeting breakdown (HTML) with speaker timeline, topic
+  labels, chapter summaries, and action items from a meeting recording. Use
+  when the user wants meeting notes, a recap, action items, or a who-said-what
+  timeline from a recorded meeting or call. Takes one source: a local video
+  file, URL, or cloudglue:// file URI (e.g. cloudglue://files/<id>). Runs the built-in tinycloud
+  "meeting-breakdown" workflow; requires the tinycloud CLI configured with a
+  Cloudglue API key (analysis runs through the user's Cloudglue account).
+argument-hint: "[meeting recording file, URL, or cloudglue:// file URI]"
+arguments: source
+---
+
+# Meeting breakdown
+
+This skill is a thin wrapper around the `meeting-breakdown` workflow recipe
+bundled inside the tinycloud binary (`watch → extract ×2 → render`).
+
+## Run
+
+1. **Check the CLI.** If the general `tinycloud` skill is installed alongside
+   this one, run its `scripts/preflight.sh`. Otherwise verify directly:
+
+   ```bash
+   tinycloud setup --check --json   # ready when data.ok == true
+   ```
+
+   Missing CLI: `npm install -g @cloudglue/tinycloud` (see https://tinycloud.sh).
+   Missing key: `tinycloud setup cloudglue --api-key <key>`.
+
+2. **Confirm the recipe is available** (free, no cloud calls):
+
+   ```bash
+   tinycloud workflow validate meeting-breakdown --json
+   ```
+
+3. **Run it** with the user's source. The analysis steps (one describe + two
+   extracts) run through the configured Cloudglue API key — if the user has
+   not clearly asked to run it, show the step plan first with
+   `tinycloud workflow plan meeting-breakdown $source --json` (free).
+
+   ```bash
+   tinycloud workflow meeting-breakdown $source --json
+   ```
+
+   Useful params: `--param segment=chapters` (default; semantic meeting
+   narrative) or `--param segment=uniform:20` for dense raw intervals;
+   `--param out=<path>` to control the HTML location.
+
+## Read the result
+
+Parse the single JSON envelope from stdout (machine output; logs are stderr):
+
+- Success: `status == "ready"` and `data.status == "completed"`.
+- The breakdown path is `data.outputs.html` (also in `data.artifacts[]`).
+  Default: `./tinycloud-output/runs/<data.run_id>/meeting-breakdown.html`.
+- Report the HTML path; offer
+  `tinycloud publish <html> --name meeting-breakdown --visibility private --json`
+  to host it as a shareable page.
+
+Any other `status` (`needs_credentials`, `needs_upload`, `pending`, `paused`,
+`error`) or `data.status` of `partial`/`failed`: stop, report the envelope's
+`error.message`, and follow its `setup` / `resume` / `next` hints. The general
+`tinycloud` skill (if installed) documents full status handling.

package/skills/sales-coaching/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: sales-coaching
+description: >-
+  Turn a sales-call recording into a coaching dashboard (HTML) with call
+  scores, speech metrics, objections, and improvement areas. Use when the
+  user wants sales-call analysis, call coaching, or rep feedback from a
+  video/audio recording. Takes one source: a local video file, URL, or
+  cloudglue:// file URI (e.g. cloudglue://files/<id>). Runs the built-in tinycloud "sales-coaching" workflow;
+  requires the tinycloud CLI configured with a Cloudglue API key (analysis
+  runs through the user's Cloudglue account).
+argument-hint: "[sales call video file, URL, or cloudglue:// file URI]"
+arguments: source
+---
+
+# Sales-call coaching dashboard
+
+This skill is a thin wrapper around the `sales-coaching` workflow recipe
+bundled inside the tinycloud binary (`watch → extract ×2 → render`).
+
+## Run
+
+1. **Check the CLI.** If the general `tinycloud` skill is installed alongside
+   this one, run its `scripts/preflight.sh`. Otherwise verify directly:
+
+   ```bash
+   tinycloud setup --check --json   # ready when data.ok == true
+   ```
+
+   Missing CLI: `npm install -g @cloudglue/tinycloud` (see https://tinycloud.sh).
+   Missing key: `tinycloud setup cloudglue --api-key <key>`.
+
+2. **Confirm the recipe is available** (free, no cloud calls):
+
+   ```bash
+   tinycloud workflow validate sales-coaching --json
+   ```
+
+3. **Run it** with the user's source. The analysis steps (one describe + two
+   extracts) run through the configured Cloudglue API key — if the user has
+   not clearly asked to run it, show them the step plan first with
+   `tinycloud workflow plan sales-coaching $source --json` (free).
+
+   ```bash
+   tinycloud workflow sales-coaching $source --json
+   ```
+
+   (The recipe self-permits its local render step — no extra flag needed.)
+   Useful params: `--param segment=chapters` (default; semantic call phases) or
+   `--param segment=uniform:20` for dense fixed intervals;
+   `--param out=<path>` to control the HTML location.
+
+## Read the result
+
+Parse the single JSON envelope from stdout (machine output; logs are stderr):
+
+- Success: `status == "ready"` and `data.status == "completed"`.
+- The dashboard path is `data.outputs.html` (also in `data.artifacts[]`).
+  Default: `./tinycloud-output/runs/<data.run_id>/sales-coaching.html`.
+- Report the HTML path to the user; offer
+  `tinycloud publish <html> --name sales-coaching --visibility private --json`
+  to host it as a shareable page.
+
+Any other `status` (`needs_credentials`, `needs_upload`, `pending`, `paused`,
+`error`) or `data.status` of `partial`/`failed`: stop, report the envelope's
+`error.message`, and follow its `setup` / `resume` / `next` hints. The general
+`tinycloud` skill (if installed) documents full status handling.