@cloudglue/tinycloud 0.3.2 → 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.2",
+  "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

@@ -110,6 +110,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 +177,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

@@ -88,3 +88,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/setup.md

@@ -95,9 +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.

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