@gamecrate/cli 1.2.0 → 1.4.0

package/dist/gamecrate.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { existsSync as existsSync10 } from "node:fs";
-import { chown, cp, mkdir as mkdir6, readdir as readdir10, readFile as readFile10, rm as rm4, rmdir, stat as stat5, writeFile as writeFile7 } from "node:fs/promises";
+import { existsSync as existsSync12 } from "node:fs";
+import { chown, cp, mkdir as mkdir6, readdir as readdir11, readFile as readFile12, rm as rm5, rmdir, stat as stat6, writeFile as writeFile7 } from "node:fs/promises";
 import { homedir as homedir5 } from "node:os";
-import { basename as basename10, dirname as dirname8, join as join19 } from "node:path";
-import { setTimeout as sleep6 } from "node:timers/promises";
+import { basename as basename11, dirname as dirname10, join as join22 } from "node:path";
+import { setTimeout as sleep7 } from "node:timers/promises";
 
 // src/cli/args.ts
 import { Command, CommanderError, Option } from "commander";
@@ -150,7 +150,7 @@ var SUBCOMMANDS = [
     summary: "tiered wipe of a profile",
     usage: "<game> [profile]",
     positionals: ["game", "profile"],
-    flags: ["--staging", "--logs", "--all", "--yes", "--instance", "--worktree", "--no-worktree"]
+    flags: ["--staging", "--logs", "--all", "--downloads", "--yes", "--instance", "--worktree", "--no-worktree"]
   },
   {
     name: "clone",
@@ -291,7 +291,7 @@ function enumOption(flags, summary, values) {
 }
 function buildProgram() {
   const program = new Command;
-  program.name("gamecrate").exitOverride().helpOption(false).allowExcessArguments(true).showSuggestionAfterError(false).configureOutput({ writeOut: () => {}, writeErr: () => {} }).argument("[args...]").option("--mod <id>", "add a mod to the profile set", collect, []).option("--without <id>", "drop a mod from the resolved set", collect, []).option("--only <id>", "restrict the resolved set to these mods", collect, []).option("--worktree <path>", "promote mods from this git worktree, in its own instance ($GAMECRATE_WORKTREE)", collect, []).option("--use <packageId>=<path>", "force one mod to load from this directory, whatever the profile pins", collect, []).option("--no-worktree", "ignore the current worktree and $GAMECRATE_WORKTREE").option("--instance <name>", "run under a named sub-profile with its own saves, logs and container").addOption(enumOption(`--mode <${MODES.join("|")}>`, "how the game is displayed", MODES)).option("--marker <str>", "exit 0 as soon as this string appears in the log").option("--timeout <seconds>", "bound a marker run, or a headless run with no marker", (v) => seconds("--timeout", v)).option("--render-wait <seconds>", "settle time before a screenshot is taken", (v) => seconds("--render-wait", v)).option("--resolution <width>x<height>", "override the game resolution", parseResolution).addOption(enumOption(`--network <${NETWORK_POLICIES.join("|")}>`, "the container's network mode", NETWORK_POLICIES)).option("--log <path>", "route launch stdout and stderr to one file").addOption(enumOption(`--pull <${PULL_POLICIES.join("|")}>`, "when to pull the runtime image", PULL_POLICIES)).option("--build", "build local C# mods before launching").option("--no-build", "never build, even when an assembly is stale").option("--no-stale-check", "do not warn when a mod's sources are newer than its assemblies").option("--replace", "stop whatever is holding this profile and instance, then launch").option("--no-replace", "refuse when this profile and instance are already running").option("--detach", "start the run in the background and return the prompt").option("--no-detach", "stay in the foreground, whatever the profile or project config asks for").addOption(new Option("--supervised <instanceDir>").hideHelp()).addOption(enumOption(`--sort <${SORTS.join("|")}>`, "load order: the profile order, or a topological sort", SORTS)).option("--docker-arg <arg>", "one extra argv element for docker run", collect, []).option("--dry-run", "resolve and validate fully, write nothing").option("--print-plan", "print the resolved launch plan instead of launching").option("--json", "machine-readable output").option("--root", "run as root instead of mapping the host uid").option("--staging", "clean: wipe .stage only (the default)").option("--logs", "clean: wipe the captured run logs").option("--all", "clean: wipe the whole profile, saves included (needs --yes)").option("-f, --follow", "keep printing as the run writes").option("-y, --yes", "skip destructive-action confirmation").option("--path <dir>", "mods add: take the mod from this directory").option("--workshop <id>", "mods add: take the mod from this steam workshop item", workshopId).option("--git <url>", "mods add: clone the mod from this repository").option("--branch <name>", "mods add: track this git branch").option("--tag <name>", "mods add: pin this git tag").option("--commit <sha>", "mods add: pin this git commit").option("--subdir <path>", "mods add: the mod folder inside the repository").option("--global", "write to the global config").option("--project", "write to the project config").option("--force", "overwrite an entry that is already there").option("-h, --help", "this help");
+  program.name("gamecrate").exitOverride().helpOption(false).allowExcessArguments(true).showSuggestionAfterError(false).configureOutput({ writeOut: () => {}, writeErr: () => {} }).argument("[args...]").option("--mod <id>", "add a mod to the profile set", collect, []).option("--without <id>", "drop a mod from the resolved set", collect, []).option("--only <id>", "restrict the resolved set to these mods", collect, []).option("--worktree <path>", "promote mods from this git worktree, in its own instance ($GAMECRATE_WORKTREE)", collect, []).option("--use <packageId>=<path>", "force one mod to load from this directory, whatever the profile pins", collect, []).option("--no-worktree", "ignore the current worktree and $GAMECRATE_WORKTREE").option("--instance <name>", "run under a named sub-profile with its own saves, logs and container").addOption(enumOption(`--mode <${MODES.join("|")}>`, "how the game is displayed", MODES)).option("--marker <str>", "exit 0 as soon as this string appears in the log").option("--timeout <seconds>", "bound a marker run, or a headless run with no marker", (v) => seconds("--timeout", v)).option("--render-wait <seconds>", "settle time before a screenshot is taken", (v) => seconds("--render-wait", v)).option("--resolution <width>x<height>", "override the game resolution", parseResolution).addOption(enumOption(`--network <${NETWORK_POLICIES.join("|")}>`, "the container's network mode", NETWORK_POLICIES)).option("--log <path>", "route launch stdout and stderr to one file").addOption(enumOption(`--pull <${PULL_POLICIES.join("|")}>`, "when to pull the runtime image", PULL_POLICIES)).option("--build", "build local C# mods before launching").option("--no-build", "never build, even when an assembly is stale").option("--no-stale-check", "do not warn when a mod's sources are newer than its assemblies").option("--replace", "stop whatever is holding this profile and instance, then launch").option("--no-replace", "refuse when this profile and instance are already running").option("--detach", "start the run in the background and return the prompt").option("--no-detach", "stay in the foreground, whatever the profile or project config asks for").addOption(new Option("--supervised <instanceDir>").hideHelp()).addOption(enumOption(`--sort <${SORTS.join("|")}>`, "load order: the profile order, or a topological sort", SORTS)).option("--docker-arg <arg>", "one extra argv element for docker run", collect, []).option("--dry-run", "resolve and validate fully, write nothing").option("--print-plan", "print the resolved launch plan instead of launching").option("--json", "machine-readable output").option("--root", "run as root instead of mapping the host uid").option("--staging", "clean: wipe .stage only (the default)").option("--logs", "clean: wipe the captured run logs").option("--all", "clean: wipe the whole profile and the game downloads (needs --yes)").option("--downloads", "clean: wipe this game's workshop downloads, keeping steamcmd").option("-f, --follow", "keep printing as the run writes").option("-y, --yes", "skip destructive-action confirmation").option("--path <dir>", "mods add: take the mod from this directory").option("--workshop <id>", "mods add: take the mod from this steam workshop item", workshopId).option("--git <url>", "mods add: clone the mod from this repository").option("--branch <name>", "mods add: track this git branch").option("--tag <name>", "mods add: pin this git tag").option("--commit <sha>", "mods add: pin this git commit").option("--subdir <path>", "mods add: the mod folder inside the repository").option("--global", "write to the global config").option("--project", "write to the project config").option("--force", "overwrite an entry that is already there").option("-h, --help", "this help");
   return program;
 }
 function checkValueTokens(program, head) {
@@ -336,7 +336,7 @@ function parseArgs(argv, opts = {}) {
       counts.set(long, (counts.get(long) ?? 0) + 1);
       if (long === "--worktree" && value !== undefined)
         worktree.push(value);
-      if (long === "--staging" || long === "--logs" || long === "--all") {
+      if (long === "--staging" || long === "--logs" || long === "--all" || long === "--downloads") {
         cleanTier = long.slice(2);
       }
     });
@@ -796,9 +796,9 @@ function list(args, config, defaults) {
 }
 
 // src/cli/mods.ts
-import { existsSync as existsSync5 } from "node:fs";
-import { mkdir as mkdir2, readFile as readFile6, readdir as readdir5, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname5, join as join10, relative as relative2, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
+import { mkdir as mkdir2, readFile as readFile7, readdir as readdir6, writeFile as writeFile3 } from "node:fs/promises";
+import { dirname as dirname7, join as join12, relative as relative2, resolve as resolve4 } from "node:path";
 
 // src/config/load.ts
 import { z as z2 } from "zod";
@@ -1188,6 +1188,7 @@ var root = obj({
   plugins: strArray.optional(),
   dataRoot: str,
   defaults: obj({ settings: settings.optional() }).optional(),
+  steamcmd: obj({ path: str.optional() }).optional(),
   games: z.unknown()
 });
 function validateConfig(cfg) {
@@ -1739,6 +1740,8 @@ function deepMerge(base, over, concatArrays = false) {
 }
 function expandPaths(config) {
   config.dataRoot = expandHome(config.dataRoot);
+  if (config.steamcmd?.path !== undefined)
+    config.steamcmd.path = expandHome(config.steamcmd.path);
   for (const game of Object.values(config.games)) {
     if (game.gameFiles.host !== undefined)
       game.gameFiles.host = expandHome(game.gameFiles.host);
@@ -2307,24 +2310,28 @@ async function scanBuildTimes(dir) {
   await walk(dir, false);
   return times;
 }
+var SKEW_MS = 1000;
+function newerThan(source, assembly) {
+  return source - assembly > SKEW_MS;
+}
 function decideStale(times) {
   const { newestSource, newestAssembly } = times;
   if (newestSource === undefined)
     return false;
-  return newestAssembly === undefined || newestSource.mtimeMs > newestAssembly.mtimeMs;
+  return newestAssembly === undefined || newerThan(newestSource.mtimeMs, newestAssembly.mtimeMs);
 }
 function staleReport(times) {
   const { newestSource, newestAssembly } = times;
   if (newestSource === undefined || newestAssembly === undefined)
     return null;
-  if (newestSource.mtimeMs <= newestAssembly.mtimeMs)
+  if (!newerThan(newestSource.mtimeMs, newestAssembly.mtimeMs))
     return null;
   return {
     newestSource: newestSource.path,
     newestSourceMs: newestSource.mtimeMs,
     assembly: newestAssembly.path,
     assemblyMs: newestAssembly.mtimeMs,
-    newerCount: times.sourceTimes.filter((t) => t > newestAssembly.mtimeMs).length
+    newerCount: times.sourceTimes.filter((t) => newerThan(t, newestAssembly.mtimeMs)).length
   };
 }
 var INDENT = " ".repeat("warning: ".length);
@@ -2972,7 +2979,7 @@ function staleWarning2(dir, url, step) {
     return `${what}, using the clone already on disk`;
   return `${what}, using ${sha} from ${ago(Number(seconds) * 1000)}`;
 }
-async function lockClone(dir) {
+async function lockDir(dir) {
   const path = `${dir}.lock`;
   await mkdir(dirname4(path), { recursive: true });
   const deadline = Date.now() + LOCK_TIMEOUT_MS;
@@ -3032,31 +3039,35 @@ function releaser(path) {
     await unlink2(path).catch(() => {});
   };
 }
+function reachedEntries(game, profile, args) {
+  const out = [...game.preCore ?? [], game.core, ...game.dlc];
+  if (profile.includeBase !== false)
+    out.push(...game.base ?? []);
+  const only = args.only ?? [];
+  out.push(...only.length > 0 ? only : profile.mods ?? []);
+  out.push(...args.mods ?? []);
+  const dropped = [...profile.exclude ?? [], ...args.without ?? []].map(globToRegExp);
+  return out.filter((entry) => {
+    if (typeof entry !== "string" && "match" in entry)
+      return true;
+    const id = typeof entry === "string" ? entry : entry.id;
+    return !dropped.some((pattern) => pattern.test(id));
+  });
+}
 function pinnableIds(game, profile, args) {
   const out = [];
-  const push = (entry) => {
+  for (const entry of reachedEntries(game, profile, args)) {
     if (typeof entry === "string") {
       if (!entry.includes(":"))
         out.push(entry);
-      return;
+      continue;
     }
     if ("match" in entry)
-      return;
+      continue;
     if (entry.path === undefined && entry.workshop === undefined && !entry.id.includes(":"))
       out.push(entry.id);
-  };
-  for (const id of [...game.preCore ?? [], game.core, ...game.dlc])
-    push(id);
-  if (profile.includeBase !== false)
-    for (const id of game.base ?? [])
-      push(id);
-  const only = args.only ?? [];
-  for (const entry of only.length > 0 ? only : profile.mods ?? [])
-    push(entry);
-  for (const id of args.mods ?? [])
-    push(id);
-  const dropped = [...profile.exclude ?? [], ...args.without ?? []].map(globToRegExp);
-  return out.filter((id) => !dropped.some((pattern) => pattern.test(id)));
+  }
+  return out;
 }
 function cachedSources(game, profileName, args, dataRoot) {
   const dirs = new Map;
@@ -3117,7 +3128,7 @@ async function prepareSources(game, profileName, args, dataRoot, allowFetch) {
   try {
     for (const dir of [...jobs.keys()].sort()) {
       const job = jobs.get(dir);
-      locks.push(await lockClone(dir));
+      locks.push(await lockDir(dir));
       const result = await ensureClone(dataRoot, job.pin, job.ref, allowFetch ? "fetch" : "use");
       fetched.push(result.dir);
       if (result.warning !== undefined)
@@ -3130,9 +3141,404 @@ async function prepareSources(game, profileName, args, dataRoot, allowFetch) {
   return { dirs, warnings, fetched, release };
 }
 
+// src/mods/steamcmd.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { accessSync, constants, existsSync as existsSync5, mkdirSync as mkdirSync3, statSync as statSync2 } from "node:fs";
+import { readdir as readdir5, rm as rm2 } from "node:fs/promises";
+import { delimiter, dirname as dirname5, join as join10 } from "node:path";
+import { setTimeout as sleep4 } from "node:timers/promises";
+var STEAMCMD_IMAGE = "steamcmd/steamcmd";
+function steamHome(dataRoot) {
+  return join10(dataRoot, "steam");
+}
+function downloadRoot(dataRoot, game) {
+  return join10(steamHome(dataRoot), "steamapps", "workshop", "content", String(game.steamAppId));
+}
+async function removeDownloads(root, steamAppId) {
+  if (!existsSync5(root))
+    return `no workshop downloads at ${root}`;
+  const items = (await readdir5(root).catch(() => [])).length;
+  await rm2(root, { recursive: true, force: true });
+  await rm2(join10(dirname5(dirname5(root)), `appworkshop_${steamAppId}.acf`), { force: true });
+  return `removed ${root} (${items} item(s))`;
+}
+function resolveSteamcmd(config) {
+  const home = steamHome(config.dataRoot);
+  const configured = config.steamcmd?.path === undefined ? undefined : expandHome(config.steamcmd.path);
+  if (configured !== undefined) {
+    if (!executable(configured)) {
+      throw new GamecrateError(`steamcmd.path is not an executable file: ${configured}`, Exit.Environment, "point steamcmd.path at the steamcmd binary, or remove it to use PATH or docker");
+    }
+    return { kind: "host", argv: [configured], env: { HOME: home } };
+  }
+  const found = onPath("steamcmd");
+  if (found !== undefined)
+    return { kind: "host", argv: [found], env: { HOME: home } };
+  if (onPath("docker") !== undefined) {
+    return {
+      kind: "docker",
+      argv: [
+        "docker",
+        "run",
+        "--rm",
+        "--user",
+        `${process.getuid?.() ?? 0}:${process.getgid?.() ?? 0}`,
+        "-v",
+        `${home}:${home}`,
+        "-e",
+        `HOME=${home}`,
+        STEAMCMD_IMAGE
+      ],
+      env: {}
+    };
+  }
+  throw new GamecrateError("steamcmd is not available", Exit.Environment, `steamcmd.path is unset, steamcmd is not on PATH, and docker is not there to run ${STEAMCMD_IMAGE}`);
+}
+function executable(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return statSync2(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function onPath(name) {
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (dir.length === 0)
+      continue;
+    const candidate = join10(dir, name);
+    if (executable(candidate))
+      return candidate;
+  }
+  return;
+}
+function workshopUrlId(url) {
+  if (url === undefined)
+    return;
+  const client = /^steam:\/\/url\/CommunityFilePage\/(\d+)$/i.exec(url.trim());
+  if (client !== null)
+    return client[1];
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+  if (!/(^|\.)steamcommunity\.com$/.test(parsed.hostname.toLowerCase()))
+    return;
+  const id = parsed.searchParams.get("id");
+  return id !== null && /^\d+$/.test(id) ? id : undefined;
+}
+var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]`, "g");
+var SUCCESS = /Success\. Downloaded item (\d+) to "([^"]+)" \((\d+) bytes\)/g;
+var FAILED = /ERROR! Download item (\d+) failed \(([^)]+)\)/g;
+var ATTEMPTS = 2;
+var RETRY_DELAY_MS = 1000;
+async function downloadItems(config, game, dataRoot, ids) {
+  const items = new Map;
+  const warnings = [];
+  if (ids.length === 0)
+    return { items, warnings };
+  const runner = resolveSteamcmd(config);
+  mkdirSync3(steamHome(dataRoot), { recursive: true });
+  const reasons = new Map;
+  const release = await lockDir(steamHome(dataRoot));
+  try {
+    let pending = ids;
+    for (let attempt = 0;attempt < ATTEMPTS && pending.length > 0; attempt++) {
+      const output = run(runner, game, dataRoot, pending);
+      for (const m of output.matchAll(SUCCESS)) {
+        items.set(m[1], { ok: true, dir: m[2], bytes: Number(m[3]) });
+      }
+      for (const m of output.matchAll(FAILED))
+        reasons.set(m[1], m[2]);
+      pending = pending.filter((id) => !items.has(id));
+      if (pending.length > 0 && attempt + 1 < ATTEMPTS)
+        await sleep4(RETRY_DELAY_MS);
+    }
+  } finally {
+    await release();
+  }
+  for (const id of ids) {
+    if (items.has(id))
+      continue;
+    const reason = reasons.get(id) ?? "steamcmd reported nothing for it";
+    items.set(id, { ok: false, reason });
+    warnings.push(`could not download workshop item ${id}: ${reason}`);
+  }
+  return { items, warnings };
+}
+function run(runner, game, dataRoot, ids) {
+  const argv = [
+    ...runner.argv,
+    "+force_install_dir",
+    steamHome(dataRoot),
+    "+login",
+    "anonymous",
+    ...ids.flatMap((id) => ["+workshop_download_item", String(game.steamAppId), id]),
+    "+quit"
+  ];
+  const r = spawnSync2(argv[0], argv.slice(1), {
+    encoding: "utf8",
+    env: { ...process.env, ...runner.env },
+    maxBuffer: 64 * 1024 * 1024
+  });
+  if (r.error) {
+    throw new GamecrateError(`could not run steamcmd: ${argv[0]}`, Exit.Environment, r.error.message);
+  }
+  return `${r.stdout ?? ""}
+${r.stderr ?? ""}`.replace(ANSI, "");
+}
+
+// src/mods/workshopapi.ts
+import { readFile as readFile6, stat as stat4 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname6, join as join11 } from "node:path";
+
+// src/mods/acf.ts
+var MAX_DEPTH = 100;
+function isSpace(c) {
+  return c === " " || c === "\t" || c === "\r" || c === `
+`;
+}
+function skip(text, start) {
+  let i = start;
+  for (;; ) {
+    while (i < text.length && isSpace(text[i]))
+      i += 1;
+    if (!text.startsWith("//", i))
+      return i;
+    const nl = text.indexOf(`
+`, i);
+    if (nl === -1)
+      return text.length;
+    i = nl + 1;
+  }
+}
+function quoted(text, start) {
+  let out = "";
+  let i = start + 1;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === "\\") {
+      if (i + 1 >= text.length)
+        return null;
+      out += text[i + 1];
+      i += 2;
+      continue;
+    }
+    if (c === '"')
+      return { value: out, next: i + 1 };
+    out += c;
+    i += 1;
+  }
+  return null;
+}
+function root2(text) {
+  const node = {};
+  let i = skip(text, 0);
+  while (i < text.length) {
+    if (text[i] !== '"')
+      return null;
+    const next = readEntry(text, i, 0, node);
+    if (next === null)
+      return null;
+    i = skip(text, next);
+  }
+  return node;
+}
+function block(text, start, depth) {
+  if (depth > MAX_DEPTH)
+    return null;
+  const node = {};
+  let i = skip(text, start);
+  while (i < text.length) {
+    if (text[i] === "}")
+      return { node, next: i + 1 };
+    if (text[i] !== '"')
+      return null;
+    const next = readEntry(text, i, depth, node);
+    if (next === null)
+      return null;
+    i = skip(text, next);
+  }
+  return null;
+}
+function readEntry(text, start, depth, node) {
+  const key = quoted(text, start);
+  if (key === null)
+    return null;
+  const i = skip(text, key.next);
+  if (i >= text.length)
+    return null;
+  if (text[i] === "{") {
+    const child = block(text, i + 1, depth + 1);
+    if (child === null)
+      return null;
+    node[key.value] = child.node;
+    return child.next;
+  }
+  if (text[i] !== '"')
+    return null;
+  const value = quoted(text, i);
+  if (value === null)
+    return null;
+  node[key.value] = value.value;
+  return value.next;
+}
+function parseAcf(text) {
+  return root2(text) ?? {};
+}
+function section(node, name) {
+  const direct = node[name];
+  if (typeof direct === "object")
+    return direct;
+  for (const child of Object.values(node)) {
+    if (typeof child === "object" && typeof child[name] === "object")
+      return child[name];
+  }
+  return;
+}
+function installedItems(text) {
+  const out = new Map;
+  const items = section(parseAcf(text), "WorkshopItemsInstalled");
+  if (items === undefined)
+    return out;
+  for (const [id, entry] of Object.entries(items)) {
+    if (typeof entry !== "object")
+      continue;
+    const manifest = entry["manifest"];
+    if (typeof manifest !== "string" || manifest === "")
+      continue;
+    out.set(id, { manifest, timeupdated: Number(entry["timeupdated"]) || 0 });
+  }
+  return out;
+}
+
+// src/mods/workshopapi.ts
+var ENDPOINT = "https://api.steampowered.com/ISteamRemoteStorage/GetPublishedFileDetails/v1/";
+var CHUNK = 100;
+var TIMEOUT_MS = 5000;
+async function checkDrift(ids, roots, fetchImpl = fetch) {
+  const wanted = [...new Set(ids)];
+  const { loaded, listed } = await installs(wanted, roots);
+  const missing = [];
+  for (const id of wanted) {
+    if (!listed.has(id) || !await onDisk(roots, id))
+      missing.push(id);
+  }
+  let details;
+  try {
+    details = await published(wanted, fetchImpl);
+  } catch (error) {
+    return {
+      needed: missing,
+      unavailable: [],
+      warnings: [`could not ask steam which items changed (${reason(error)}); only missing items will download`]
+    };
+  }
+  const needed = new Set(missing);
+  const unavailable = [];
+  const warnings = [];
+  for (const id of wanted) {
+    const detail = details.get(id);
+    if (detail === undefined)
+      continue;
+    if (detail.result !== 1) {
+      warnings.push(`workshop item ${id} is not available (result ${detail.result}); skipping it`);
+      needed.delete(id);
+      unavailable.push(id);
+      continue;
+    }
+    const local = loaded.get(id);
+    if (local !== undefined && detail.timeUpdated > local)
+      needed.add(id);
+  }
+  return { needed: [...needed], unavailable, warnings };
+}
+async function installs(ids, roots) {
+  const loaded = new Map;
+  const listed = new Set;
+  for (const root of roots) {
+    const items = installedItems(await readText(acfPath(root)));
+    for (const id of ids) {
+      const item = items.get(id);
+      if (item === undefined)
+        continue;
+      listed.add(id);
+      if (!loaded.has(id) && await exists(join11(root, id)))
+        loaded.set(id, item.timeupdated);
+    }
+  }
+  return { loaded, listed };
+}
+async function onDisk(roots, id) {
+  for (const root of roots) {
+    if (await exists(join11(root, id)))
+      return true;
+  }
+  return false;
+}
+async function published(ids, fetchImpl) {
+  const out = new Map;
+  if (ids.length === 0)
+    return out;
+  const abort = new AbortController;
+  const timer = setTimeout(() => abort.abort(new Error(`no answer in ${TIMEOUT_MS}ms`)), TIMEOUT_MS);
+  try {
+    for (let i = 0;i < ids.length; i += CHUNK) {
+      const chunk = ids.slice(i, i + CHUNK);
+      const body = new URLSearchParams({ itemcount: String(chunk.length) });
+      chunk.forEach((id, n) => body.set(`publishedfileids[${n}]`, id));
+      const response = await fetchImpl(ENDPOINT, { method: "POST", body, signal: abort.signal });
+      if (!response.ok)
+        throw new Error(`steam answered ${response.status}`);
+      for (const [id, detail] of readDetails(await response.json()))
+        out.set(id, detail);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+  return out;
+}
+function readDetails(payload) {
+  const list = payload?.response?.publishedfiledetails;
+  if (!Array.isArray(list))
+    throw new Error("steam returned a body this does not understand");
+  const out = new Map;
+  for (const entry of list) {
+    const id = entry["publishedfileid"];
+    const result = entry["result"];
+    if (typeof id !== "string" || typeof result !== "number") {
+      throw new Error("steam returned a body this does not understand");
+    }
+    out.set(id, { result, timeUpdated: Number(entry["time_updated"]) || 0 });
+  }
+  return out;
+}
+function acfPath(root) {
+  return join11(dirname6(dirname6(root)), `appworkshop_${basename5(root)}.acf`);
+}
+async function exists(dir) {
+  try {
+    return (await stat4(dir)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function readText(path) {
+  try {
+    return await readFile6(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function reason(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/cli/mods.ts
 async function globalConfigPath() {
-  return await findGlobalConfig() ?? join10(globalConfigDir(), "profiles.yml");
+  return await findGlobalConfig() ?? join12(globalConfigDir(), "profiles.yml");
 }
 async function modsAdd(args, ctx) {
   const game = requireGame(args, ctx.config);
@@ -3141,9 +3547,6 @@ async function modsAdd(args, ctx) {
   if (source === undefined) {
     throw new GamecrateError("mods add needs one of --path, --workshop or --git", Exit.Usage);
   }
-  if (source.kind === "workshop" && gameConfig.workshopRoot === null) {
-    throw new GamecrateError(`games.${game}.workshopRoot is null, so workshop item ${source.value} cannot resolve`, Exit.Config, `set games.${game}.workshopRoot to the workshop directory for app ${gameConfig.steamAppId}`);
-  }
   const target = await resolveTarget(args, ctx, game);
   const pins = await discover(source, gameConfig, requirePlugin(ctx.plugins, game), ctx);
   if (pins.length === 0) {
@@ -3175,8 +3578,8 @@ overwrite them with --force`);
       edits.push({ path: [...target.prefix, old], value: undefined });
     edits.push({ path: [...target.prefix, pin.id], value: pin.entry });
   }
-  if (!existsSync5(target.file)) {
-    await mkdir2(dirname5(target.file), { recursive: true });
+  if (!existsSync6(target.file)) {
+    await mkdir2(dirname7(target.file), { recursive: true });
     await writeFile3(target.file, "");
   }
   await writeConfig(target.file, edits);
@@ -3205,21 +3608,27 @@ async function modsSync(args, ctx) {
   const only = args.rest.map((id) => id.toLowerCase());
   const games = args.game === undefined ? Object.keys(ctx.config.games) : [requireGame(args, ctx.config)];
   const wanted = [];
+  const subscribed = [];
   for (const name of games) {
+    const pins = [];
     for (const [id, entry] of Object.entries(ctx.config.games[name]?.library ?? {})) {
-      if (entry.git === undefined)
-        continue;
       if (only.length > 0 && !only.includes(id.toLowerCase()))
         continue;
-      wanted.push({ id, git: entry.git, entry });
+      if (entry.git !== undefined)
+        wanted.push({ id, git: entry.git, entry });
+      else if (entry.workshop !== undefined)
+        pins.push({ id, item: String(entry.workshop) });
     }
+    if (pins.length > 0)
+      subscribed.push({ game: name, pins });
   }
-  const missing = only.filter((id) => !wanted.some((pin) => pin.id.toLowerCase() === id));
+  const named = [...wanted.map((pin) => pin.id), ...subscribed.flatMap((one) => one.pins.map((pin) => pin.id))];
+  const missing = only.filter((id) => !named.some((pinned) => pinned.toLowerCase() === id));
   if (missing.length > 0) {
-    throw new GamecrateError(`${missing.length} mod id(s) are not git-pinned in the library`, Exit.Resolution, missing.map((id) => `  ${id}`).join(`
+    throw new GamecrateError(`${missing.length} mod id(s) are not git- or workshop-pinned in the library`, Exit.Resolution, missing.map((id) => `  ${id}`).join(`
 `));
   }
-  if (wanted.length === 0) {
+  if (wanted.length === 0 && subscribed.length === 0) {
     status("nothing to sync");
     return Exit.Ok;
   }
@@ -3235,7 +3644,7 @@ async function modsSync(args, ctx) {
     const dir = cloneDir(ctx.config.dataRoot, pin.git, ref);
     if (!fetched.has(dir)) {
       fetched.add(dir);
-      const unlock = await lockClone(dir);
+      const unlock = await lockDir(dir);
       try {
         const result = await ensureClone(ctx.config.dataRoot, gitPin(pin.git, pin.entry), ref, "force");
         if (result.warning !== undefined)
@@ -3246,8 +3655,29 @@ async function modsSync(args, ctx) {
     }
     status(`synced ${pin.id} at ${ref.kind} ${ref.value}`);
   }
+  for (const one of subscribed)
+    await syncWorkshop(ctx, one.game, one.pins);
   return Exit.Ok;
 }
+async function syncWorkshop(ctx, name, pins) {
+  const game = ctx.config.games[name];
+  const drift = await checkDrift(pins.map((pin) => pin.item), [downloadRoot(ctx.config.dataRoot, game)], ctx.fetch);
+  for (const line of drift.warnings)
+    warn(line);
+  const report = drift.needed.length === 0 ? undefined : await downloadItems(ctx.config, game, ctx.config.dataRoot, drift.needed);
+  for (const line of report?.warnings ?? [])
+    warn(line);
+  const unavailable = new Set(drift.unavailable);
+  for (const pin of pins) {
+    const outcome = report?.items.get(pin.item);
+    if (unavailable.has(pin.item))
+      status(`${pin.id} is unavailable at workshop item ${pin.item}`);
+    else if (outcome === undefined)
+      status(`${pin.id} is up to date at workshop item ${pin.item}`);
+    else if (outcome.ok)
+      status(`synced ${pin.id} at workshop item ${pin.item}`);
+  }
+}
 function gitPin(url, entry) {
   return { url, ...entry.subdir === undefined ? {} : { subdir: entry.subdir } };
 }
@@ -3326,13 +3756,18 @@ async function discover(source, game, plugin, ctx) {
     return id === undefined ? [] : [{ id, entry: { path: dir } }];
   }
   if (source.kind === "workshop") {
-    const dir = join10(game.workshopRoot, String(source.value));
-    const id = await readId(dir, game.manifest.file, plugin);
+    const item = String(source.value);
+    const report = await downloadItems(ctx.config, game, ctx.config.dataRoot, [item]);
+    const outcome = report.items.get(item);
+    if (outcome?.ok !== true) {
+      throw new GamecrateError(`could not download workshop item ${item}: ${outcome?.reason ?? "steamcmd reported nothing for it"}`, Exit.Resolution, `check that ${item} is still published and public at https://steamcommunity.com/sharedfiles/filedetails/?id=${item}`);
+    }
+    const id = await readId(outcome.dir, game.manifest.file, plugin);
     return id === undefined ? [] : [{ id, entry: { workshop: source.value } }];
   }
   const ref = source.ref ?? defaultBranch(source.url);
   const dir = cloneDir(ctx.config.dataRoot, source.url, ref);
-  const unlock = await lockClone(dir);
+  const unlock = await lockDir(dir);
   let root;
   try {
     const result = await ensureClone(ctx.config.dataRoot, { url: source.url }, ref, "fetch");
@@ -3342,7 +3777,7 @@ async function discover(source, game, plugin, ctx) {
   } finally {
     await unlock();
   }
-  const start = source.subdir === undefined ? root : join10(root, source.subdir);
+  const start = source.subdir === undefined ? root : join12(root, source.subdir);
   const found = await walk(start, game.manifest.file, plugin);
   return found.map(({ id, dir: at }) => {
     const entry = { git: source.url };
@@ -3367,17 +3802,17 @@ async function walk(root, manifestFile, plugin) {
       out.push({ id, dir });
       return;
     }
-    const entries = await readdir5(dir, { withFileTypes: true }).catch(() => []);
+    const entries = await readdir6(dir, { withFileTypes: true }).catch(() => []);
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       if (entry.isDirectory() && !entry.name.startsWith("."))
-        await descend(join10(dir, entry.name));
+        await descend(join12(dir, entry.name));
     }
   };
   await descend(root);
   return out;
 }
 async function readId(dir, manifestFile, plugin) {
-  const text = await readFile6(join10(dir, manifestFile), "utf8").catch(() => {
+  const text = await readFile7(join12(dir, manifestFile), "utf8").catch(() => {
     return;
   });
   if (text === undefined)
@@ -3462,8 +3897,8 @@ function gameHelp(name, game) {
       notes.push(`alias for ${config.alias}`);
     if (config.extends)
       notes.push(`extends ${config.extends}`);
-    if (config.autoDependencies)
-      notes.push("auto dependencies");
+    if (config.autoDependencies === false)
+      notes.push("no auto dependencies");
     const count = config.mods?.length ?? 0;
     if (!config.alias)
       notes.push(count === 1 ? "1 entry" : `${count} entries`);
@@ -3585,9 +4020,9 @@ function hostUserName(uid) {
 }
 
 // src/docker/preflight.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync3 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
-import { basename as basename5, join as join11 } from "node:path";
+import { basename as basename6, join as join13 } from "node:path";
 var CDI_SPEC = "/etc/cdi/nvidia.yaml";
 async function preflight(plan) {
   const problems = [];
@@ -3687,7 +4122,7 @@ function checkDisplay(plan, problems) {
   });
 }
 function checkCdi(problems) {
-  if (!existsSync6(CDI_SPEC)) {
+  if (!existsSync7(CDI_SPEC)) {
     problems.push({
       where: CDI_SPEC,
       message: "no CDI spec, so --device nvidia.com/gpu=all cannot resolve",
@@ -3719,15 +4154,15 @@ function checkGameDir(plan, problems) {
     problems.push({ where, message: 'gameFiles.source is "mount" but no host path is set' });
     return;
   }
-  if (!existsSync6(files.host)) {
+  if (!existsSync7(files.host)) {
     problems.push({ where, message: `game directory does not exist: ${files.host}` });
     return;
   }
-  const executable = join11(files.host, basename5(plan.gameConfig.executable));
-  if (!existsSync6(executable)) {
+  const executable = join13(files.host, basename6(plan.gameConfig.executable));
+  if (!existsSync7(executable)) {
     problems.push({
       where,
-      message: `${files.host} does not contain ${basename5(plan.gameConfig.executable)}`,
+      message: `${files.host} does not contain ${basename6(plan.gameConfig.executable)}`,
       suggestion: "point gameFiles.host at the install directory, not its parent"
     });
   }
@@ -3747,7 +4182,7 @@ function checkBindSources(plan, problems) {
   for (const mount of mounts) {
     if (mount.type !== "bind" || !mount.source)
       continue;
-    if (existsSync6(mount.source))
+    if (existsSync7(mount.source))
       continue;
     if (mount.source.startsWith(plan.profileDir))
       continue;
@@ -3769,7 +4204,7 @@ function needsLogin(stderr) {
   return /unauthorized|authentication required|denied|forbidden/i.test(stderr);
 }
 function hasStoredAuth(host) {
-  const path = join11(process.env.DOCKER_CONFIG ?? join11(homedir3(), ".docker"), "config.json");
+  const path = join13(process.env.DOCKER_CONFIG ?? join13(homedir3(), ".docker"), "config.json");
   try {
     const config = JSON.parse(readFileSync3(path, "utf8"));
     if (config.credsStore || config.credHelpers?.[host])
@@ -3789,12 +4224,12 @@ function message(error) {
 
 // src/docker/window.ts
 import { readFileSync as readFileSync4 } from "node:fs";
-import { basename as basename6 } from "node:path";
-import { setTimeout as sleep4 } from "node:timers/promises";
+import { basename as basename7 } from "node:path";
+import { setTimeout as sleep5 } from "node:timers/promises";
 var WAIT_MS = 180000;
 var POLL_MS = 500;
 function newMatches(now, seen, executable) {
-  const wanted = basename6(executable).toLowerCase();
+  const wanted = basename7(executable).toLowerCase();
   return now.filter((w) => !seen.has(w.id) && w.wmClass.toLowerCase().includes(wanted));
 }
 function parseWindowPid(stdout) {
@@ -3807,7 +4242,7 @@ function isPeerClaim(pid, self) {
     return false;
   try {
     const argv = readFileSync4(`/proc/${pid}/cmdline`, "utf8").split("\x00");
-    return argv.some((arg) => basename6(arg).startsWith("gamecrate"));
+    return argv.some((arg) => basename7(arg).startsWith("gamecrate"));
   } catch {
     return false;
   }
@@ -3841,7 +4276,7 @@ async function adoptNewWindow(opts) {
   (async () => {
     const deadline = Date.now() + WAIT_MS;
     while (!stopped && Date.now() < deadline) {
-      await sleep4(POLL_MS);
+      await sleep5(POLL_MS);
       if (stopped)
         return;
       for (const match of newMatches(await toplevels() ?? [], seen, opts.executable)) {
@@ -3863,7 +4298,7 @@ async function adoptNewWindow(opts) {
 async function watchForClose(id, stopped, onClosed) {
   let misses = 0;
   while (!stopped()) {
-    await sleep4(POLL_MS);
+    await sleep5(POLL_MS);
     if (stopped())
       return;
     const now = await toplevels();
@@ -3921,15 +4356,15 @@ function parseAtoms(stdout) {
 }
 
 // src/launch/generate.ts
-import { mkdir as mkdir3, readdir as readdir6, readFile as readFile7, writeFile as writeFile4 } from "node:fs/promises";
-import { dirname as dirname6, join as join12 } from "node:path";
+import { mkdir as mkdir3, readdir as readdir7, readFile as readFile8, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname8, join as join14 } from "node:path";
 async function readInstallVersion(game, plugin) {
   const host = game.gameFiles.host;
   if (game.gameFiles.source !== "mount" || host === undefined)
     return null;
   let raw;
   try {
-    raw = await readFile7(join12(expandHome(host), "Version.txt"), "utf8");
+    raw = await readFile8(join14(expandHome(host), "Version.txt"), "utf8");
   } catch {
     return null;
   }
@@ -3941,10 +4376,10 @@ async function readKnownExpansions(game, plugin, warnings) {
   const host = game.gameFiles.host;
   if (game.gameFiles.source !== "mount" || host === undefined)
     return [...game.dlc];
-  const dataDir = join12(expandHome(host), "Data");
+  const dataDir = join14(expandHome(host), "Data");
   let entries;
   try {
-    entries = await readdir6(dataDir, { withFileTypes: true });
+    entries = await readdir7(dataDir, { withFileTypes: true });
   } catch {
     warnings.push(`could not read ${dataDir}; falling back to the configured dlc list`);
     return [...game.dlc];
@@ -3955,7 +4390,7 @@ async function readKnownExpansions(game, plugin, warnings) {
       continue;
     let id = null;
     try {
-      id = plugin.parseManifest(await readFile7(join12(dataDir, entry.name, game.manifest.file), "utf8"))?.packageId ?? null;
+      id = plugin.parseManifest(await readFile8(join14(dataDir, entry.name, game.manifest.file), "utf8"))?.packageId ?? null;
     } catch {
       continue;
     }
@@ -3971,8 +4406,8 @@ async function readKnownExpansions(game, plugin, warnings) {
 }
 async function generateModsConfig(plan) {
   const game = plan.gameConfig;
-  const target = join12(plan.dataDirHost, game.modsConfig.file);
-  await mkdir3(dirname6(target), { recursive: true });
+  const target = join14(plan.dataDirHost, game.modsConfig.file);
+  await mkdir3(dirname8(target), { recursive: true });
   const installed = await readInstallVersion(game, plan.plugin);
   if (installed === null) {
     plan.warnings.push(`could not read Version.txt for ${plan.game}; ModsConfig version may be rejected`);
@@ -4022,11 +4457,11 @@ function ownedPrefs(plan) {
   return owned;
 }
 async function mergePrefs(plan) {
-  const target = join12(plan.dataDirHost, plan.gameConfig.prefs.file);
-  await mkdir3(dirname6(target), { recursive: true });
+  const target = join14(plan.dataDirHost, plan.gameConfig.prefs.file);
+  await mkdir3(dirname8(target), { recursive: true });
   let existing = null;
   try {
-    existing = await readFile7(target, "utf8");
+    existing = await readFile8(target, "utf8");
   } catch (error) {
     if (error.code !== "ENOENT")
       throw error;
@@ -4036,10 +4471,10 @@ async function mergePrefs(plan) {
 }
 
 // src/launch/supervisor.ts
-import { existsSync as existsSync7 } from "node:fs";
-import { readFile as readFile8, readlink, rm as rm2, writeFile as writeFile5 } from "node:fs/promises";
-import { basename as basename7, join as join13 } from "node:path";
-import { setTimeout as sleep5 } from "node:timers/promises";
+import { existsSync as existsSync8 } from "node:fs";
+import { readFile as readFile9, readlink, rm as rm3, writeFile as writeFile5 } from "node:fs/promises";
+import { basename as basename8, join as join15 } from "node:path";
+import { setTimeout as sleep6 } from "node:timers/promises";
 async function forkSupervisor(plan, argv) {
   await clearLock(plan);
   const name = containerName(plan);
@@ -4096,15 +4531,15 @@ async function supervisorFailed(dir, code) {
   const record = { at: new Date().toISOString(), code, reason: "failed" };
   const wrote = await writeExit(dir, record).then(() => true, () => false);
   if (wrote)
-    await rm2(join13(dir, ".gamecrate", "lock"), { force: true }).catch(() => {});
+    await rm3(join15(dir, ".gamecrate", "lock"), { force: true }).catch(() => {});
   return code;
 }
 async function writeExit(instanceDir, record) {
-  await writeFile5(join13(instanceDir, ".gamecrate", "last-exit.json"), `${JSON.stringify(record)}
+  await writeFile5(join15(instanceDir, ".gamecrate", "last-exit.json"), `${JSON.stringify(record)}
 `);
 }
 async function lastExit(instanceDir) {
-  const text = await readFile8(join13(instanceDir, ".gamecrate", "last-exit.json"), "utf8").catch(() => {
+  const text = await readFile9(join15(instanceDir, ".gamecrate", "last-exit.json"), "utf8").catch(() => {
     return;
   });
   if (text === undefined)
@@ -4127,7 +4562,7 @@ function endedAfter(record, notBefore) {
   return !Number.isNaN(at) && at >= began;
 }
 async function awaitExit(instanceDir, poll = WAIT_POLL_MS) {
-  const file = join13(instanceDir, ".gamecrate", "lock");
+  const file = join15(instanceDir, ".gamecrate", "lock");
   let watching;
   for (;; ) {
     const lock = await readLock(file) ?? watching;
@@ -4139,12 +4574,12 @@ async function awaitExit(instanceDir, poll = WAIT_POLL_MS) {
     if (!isRunning(lock.pid, lock.startedAt))
       return "orphaned";
     watching = lock;
-    await sleep5(poll);
+    await sleep6(poll);
   }
 }
 var RUN_LOG_POLL_MS = 250;
 async function awaitRunLog(instanceDir, lock, poll = RUN_LOG_POLL_MS, notice = WAIT_NOTICE) {
-  const link = join13(instanceDir, "logs", "current");
+  const link = join15(instanceDir, "logs", "current");
   const written = Date.parse(lock.startedAt);
   const since = Date.now();
   let lastNotice = 0;
@@ -4152,9 +4587,9 @@ async function awaitRunLog(instanceDir, lock, poll = RUN_LOG_POLL_MS, notice = W
     const target = await readlink(link).catch(() => {
       return;
     });
-    const began = target === undefined ? undefined : runStartedAt(basename7(target));
+    const began = target === undefined ? undefined : runStartedAt(basename8(target));
     const current = began !== undefined && (Number.isNaN(written) || began >= written);
-    if (current && existsSync7(currentLog(instanceDir)))
+    if (current && existsSync8(currentLog(instanceDir)))
       return true;
     if (!isRunning(lock.pid, lock.startedAt))
       return false;
@@ -4164,20 +4599,20 @@ async function awaitRunLog(instanceDir, lock, poll = RUN_LOG_POLL_MS, notice = W
       status(`waiting for ${lock.game} ${lock.profile} to open its log (${label})`);
       lastNotice = waited;
     }
-    await sleep5(poll);
+    await sleep6(poll);
   }
 }
 
 // src/launch/instance.ts
 import { createHash as createHash2 } from "node:crypto";
-import { basename as basename8, join as join14 } from "node:path";
+import { basename as basename9, join as join16 } from "node:path";
 
 // src/mods/worktree.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync8, realpathSync as realpathSync2 } from "node:fs";
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync9, realpathSync as realpathSync2 } from "node:fs";
 import { isAbsolute as isAbsolute2, resolve as resolve5, sep } from "node:path";
 function inspect(dir) {
-  const r = spawnSync2("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+  const r = spawnSync3("git", ["-C", dir, "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
   if (r.status !== 0 || typeof r.stdout !== "string")
     return null;
   const lines = r.stdout.trim().split(`
@@ -4197,7 +4632,7 @@ function canonical(p) {
 function resolveWorktree(dir, source, order) {
   const raw = expandHome(dir);
   const abs = isAbsolute2(raw) ? raw : resolve5(process.cwd(), raw);
-  if (!existsSync8(abs)) {
+  if (!existsSync9(abs)) {
     return { where: abs, message: `--worktree path does not exist`, suggestion: "check the path, or drop the flag" };
   }
   const info = inspect(abs);
@@ -4252,7 +4687,7 @@ function resolveInstance(options) {
   const name = args.instance === undefined ? derive(requests) : named(args.instance);
   return {
     ...name === undefined ? {} : { name },
-    dir: name === undefined ? profileDir : join14(profileDir, "instances", name),
+    dir: name === undefined ? profileDir : join16(profileDir, "instances", name),
     requests,
     problems,
     ...configured?.settings === undefined ? {} : { settings: configured.settings }
@@ -4283,21 +4718,22 @@ function derive(requests) {
   return `${slug2(first.root)}-${digest.slice(0, 6)}`;
 }
 function slug2(root) {
-  const body = basename8(root).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").slice(0, SLUG_LIMIT2).replace(/[-._]+$/, "");
+  const body = basename9(root).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+/, "").slice(0, SLUG_LIMIT2).replace(/[-._]+$/, "");
   return body === "" ? "wt" : body;
 }
 
 // src/launch/resolve.ts
-import { join as join16 } from "node:path";
+import { join as join18 } from "node:path";
 
 // src/mods/modindex.ts
-import { existsSync as existsSync9, readFileSync as readFileSync5, statSync as statSync2 } from "node:fs";
-import { mkdir as mkdir4, readdir as readdir7, readFile as readFile9, writeFile as writeFile6 } from "node:fs/promises";
+import { createHash as createHash3 } from "node:crypto";
+import { existsSync as existsSync10, readFileSync as readFileSync5, statSync as statSync3 } from "node:fs";
+import { mkdir as mkdir4, readdir as readdir8, readFile as readFile10, writeFile as writeFile6 } from "node:fs/promises";
 import { homedir as homedir4 } from "node:os";
-import { dirname as dirname7, join as join15, relative as relative3, sep as sep2, resolve as resolvePath } from "node:path";
+import { dirname as dirname9, join as join17, relative as relative3, sep as sep2, resolve as resolvePath } from "node:path";
 import picomatch from "picomatch";
 function cacheDir() {
-  return join15(process.env["XDG_CACHE_HOME"] ?? join15(homedir4(), ".cache"), "gamecrate");
+  return join17(process.env["XDG_CACHE_HOME"] ?? join17(homedir4(), ".cache"), "gamecrate");
 }
 function globMatch(pattern, path) {
   return picomatch.isMatch(path, pattern.replace(/[[\]{}()!,@+|^$.\\]/g, "\\$&"), { dot: true });
@@ -4309,10 +4745,10 @@ var ALWAYS_EXCLUDE = ["**/.worktrees/**", "**/.claude/worktrees/**"];
 function inLinkedWorktree(dir, stopAt) {
   let current = dir;
   for (;; ) {
-    const git = join15(current, ".git");
-    if (existsSync9(git)) {
+    const git = join17(current, ".git");
+    if (existsSync10(git)) {
       try {
-        if (statSync2(git).isFile())
+        if (statSync3(git).isFile())
           return true;
       } catch {
         return false;
@@ -4321,7 +4757,7 @@ function inLinkedWorktree(dir, stopAt) {
     }
     if (current === stopAt)
       return false;
-    const parent = dirname7(current);
+    const parent = dirname9(current);
     if (parent === current)
       return false;
     current = parent;
@@ -4331,8 +4767,8 @@ async function scanLocalRoot(root, rootIndex, manifestFile, found) {
   const base = resolvePath(expandHome(root.path));
   const exclude = [...root.exclude ?? [], ...rootIndex === -1 ? [] : ALWAYS_EXCLUDE];
   const walk = async (dir, depth) => {
-    const manifest = join15(dir, manifestFile);
-    if (existsSync9(manifest)) {
+    const manifest = join17(dir, manifestFile);
+    if (existsSync10(manifest)) {
       found.push({
         dir,
         kind: "local",
@@ -4345,20 +4781,20 @@ async function scanLocalRoot(root, rootIndex, manifestFile, found) {
       return;
     let entries;
     try {
-      entries = await readdir7(dir, { withFileTypes: true });
+      entries = await readdir8(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name.startsWith(".git"))
         continue;
-      const child = join15(dir, entry.name);
+      const child = join17(dir, entry.name);
       if (excluded(exclude, relative3(base, child)))
         continue;
       await walk(child, depth + 1);
     }
   };
-  if (!existsSync9(base))
+  if (!existsSync10(base))
     return;
   await walk(base, 0);
 }
@@ -4366,15 +4802,15 @@ async function scanWorkshopRoot(workshopRoot, rootIndex, manifestFile, found) {
   const base = resolvePath(expandHome(workshopRoot));
   let entries;
   try {
-    entries = await readdir7(base, { withFileTypes: true });
+    entries = await readdir8(base, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (!entry.isDirectory() || !/^\d+$/.test(entry.name))
       continue;
-    const dir = join15(base, entry.name);
-    if (!existsSync9(join15(dir, manifestFile)))
+    const dir = join17(base, entry.name);
+    if (!existsSync10(join17(dir, manifestFile)))
       continue;
     found.push({ dir, kind: "workshop", rootIndex, linkedWorktree: false, workshopId: Number(entry.name) });
   }
@@ -4383,37 +4819,62 @@ async function scanGameData(game, rootIndex, found) {
   const host = game.gameFiles.host;
   if (game.gameFiles.source !== "mount" || host === undefined)
     return;
-  const data = join15(resolvePath(expandHome(host)), "Data");
+  const data = join17(resolvePath(expandHome(host)), "Data");
   let entries;
   try {
-    entries = await readdir7(data, { withFileTypes: true });
+    entries = await readdir8(data, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (!entry.isDirectory())
       continue;
-    const dir = join15(data, entry.name);
-    if (!existsSync9(join15(dir, game.manifest.file)))
+    const dir = join17(data, entry.name);
+    if (!existsSync10(join17(dir, game.manifest.file)))
       continue;
     found.push({ dir, kind: "official", rootIndex, linkedWorktree: false });
   }
 }
-var CACHE_VERSION = 3;
-function workshopStamp(game) {
-  if (game.workshopRoot === null)
+var CACHE_VERSION = 4;
+function acfPath2(root, steamAppId) {
+  return join17(dirname9(dirname9(resolvePath(expandHome(root)))), `appworkshop_${steamAppId}.acf`);
+}
+function contentPairs(acf) {
+  let text;
+  try {
+    text = readFileSync5(acf, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    return null;
+  }
+  const pairs = [...installedItems(text)].map(([id, item]) => `${id}:${item.manifest}`).sort();
+  if (pairs.length === 0 && text.trim() !== "" && Object.keys(parseAcf(text)).length === 0)
     return null;
-  const acf = join15(dirname7(dirname7(resolvePath(expandHome(game.workshopRoot)))), `appworkshop_${game.steamAppId}.acf`);
+  return pairs;
+}
+function workshopStamp(game, dataRoot) {
+  const pairs = [];
+  for (const root of dataRoot === undefined ? [] : [downloadRoot(dataRoot, game)]) {
+    const found = contentPairs(acfPath2(root, game.steamAppId));
+    if (found === null)
+      return null;
+    pairs.push(...found);
+  }
+  const download = createHash3("sha256").update(pairs.toSorted().join(`
+`)).digest("hex");
+  if (game.workshopRoot === null)
+    return download;
   try {
-    const info = statSync2(acf);
-    return `${info.mtimeMs}:${info.size}`;
+    const info = statSync3(acfPath2(game.workshopRoot, game.steamAppId));
+    return `${download}|${info.mtimeMs}:${info.size}`;
   } catch {
     return null;
   }
 }
 async function readWorkshopCache(game, stamp) {
   try {
-    const raw = JSON.parse(await readFile9(join15(cacheDir(), `${game}.workshop.json`), "utf8"));
+    const raw = JSON.parse(await readFile10(join17(cacheDir(), `${game}.workshop.json`), "utf8"));
     if (raw.version !== CACHE_VERSION || raw.stamp !== stamp)
       return null;
     return raw.records;
@@ -4425,7 +4886,7 @@ async function writeWorkshopCache(game, stamp, records) {
   const payload = { version: CACHE_VERSION, stamp, records };
   try {
     await mkdir4(cacheDir(), { recursive: true });
-    await writeFile6(join15(cacheDir(), `${game}.workshop.json`), JSON.stringify(payload));
+    await writeFile6(join17(cacheDir(), `${game}.workshop.json`), JSON.stringify(payload));
   } catch {}
 }
 function toRecord(candidate, manifest, game) {
@@ -4513,8 +4974,8 @@ async function applySourceOverrides(index, overrides, config) {
     }
     const wanted = spec.slice(0, eq);
     const dir = resolvePath(expandHome(spec.slice(eq + 1)));
-    const file = join15(dir, config.manifest.file);
-    if (!existsSync9(file)) {
+    const file = join17(dir, config.manifest.file);
+    if (!existsSync10(file)) {
       problems.push({
         where: spec,
         message: `no ${config.manifest.file} under ${dir}`,
@@ -4575,7 +5036,7 @@ function insert(index, record) {
     }
   }
 }
-async function buildIndex(game, config, plugin, sourcesDir) {
+async function buildIndex(game, config, plugin, sourcesDir, dataRoot) {
   const index = {
     game,
     plugin,
@@ -4598,15 +5059,22 @@ async function buildIndex(game, config, plugin, sourcesDir) {
   }
   for (const record of parsed)
     insert(index, record);
-  if (config.workshopRoot !== null) {
-    const stamp = workshopStamp(config);
+  const workshopRoots = [];
+  if (dataRoot !== undefined)
+    workshopRoots.push(downloadRoot(dataRoot, config));
+  if (config.workshopRoot !== null)
+    workshopRoots.push(config.workshopRoot);
+  if (workshopRoots.length > 0) {
+    const stamp = workshopStamp(config, dataRoot);
     const cached = stamp === null ? null : await readWorkshopCache(game, stamp);
     if (cached) {
       for (const record of cached)
         insert(index, record);
     } else {
       const items = [];
-      await scanWorkshopRoot(config.workshopRoot, cacheIndex + 1, config.manifest.file, items);
+      for (const [i, root] of workshopRoots.entries()) {
+        await scanWorkshopRoot(root, cacheIndex + 1 + i, config.manifest.file, items);
+      }
       const records = await parseAll(items, config, plugin, index.problems);
       for (const record of records)
         insert(index, record);
@@ -4623,10 +5091,10 @@ function oneModPerClone(records, sourcesDir) {
   const stamps = new Map;
   for (const record of [...records].sort((a, b) => a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0)) {
     const clone = relative3(sourcesDir, record.dir).split(sep2).slice(0, 2).join(sep2);
-    const at = join15(sourcesDir, clone);
+    const at = join17(sourcesDir, clone);
     let stamp = stamps.get(at);
     if (stamp === undefined) {
-      stamp = statSync2(at).mtimeMs;
+      stamp = statSync3(at).mtimeMs;
       stamps.set(at, stamp);
     }
     record.clonedAt = stamp;
@@ -4638,9 +5106,9 @@ function oneModPerClone(records, sourcesDir) {
 }
 async function parseAll(candidates, config, plugin, problems) {
   const records = await Promise.all(candidates.map(async (candidate) => {
-    const file = join15(candidate.dir, config.manifest.file);
+    const file = join17(candidate.dir, config.manifest.file);
     try {
-      const manifest = plugin.parseManifest(await readFile9(file, "utf8"));
+      const manifest = plugin.parseManifest(await readFile10(file, "utf8"));
       return manifest === null ? null : toRecord(candidate, manifest, config);
     } catch (error) {
       problems.push({
@@ -4711,8 +5179,8 @@ function byPath(index, raw, game) {
     if (hit)
       return hit;
   }
-  const file = join15(dir, game.manifest.file);
-  if (!existsSync9(file))
+  const file = join17(dir, game.manifest.file);
+  if (!existsSync10(file))
     return null;
   try {
     const manifest = index.plugin.parseManifest(readFileSync5(file, "utf8"));
@@ -4730,35 +5198,8 @@ var DEFAULT_RENDER_WAIT_SECONDS = 25;
 function isDynamic(entry) {
   return typeof entry !== "string" && "match" in entry;
 }
-function noWorkshopRoot(gameName, what) {
-  return `${gameName} has no workshopRoot, so ${what} cannot resolve`;
-}
-function workshopRootProblem(gameName, game) {
-  if (game.workshopRoot !== null)
-    return null;
-  const ids = new Set;
-  for (const entry of Object.values(game.library ?? {})) {
-    if (entry.workshop !== undefined)
-      ids.add(String(entry.workshop));
-  }
-  for (const profile of Object.values(game.profiles)) {
-    for (const entry of profile.mods ?? []) {
-      if (typeof entry === "string") {
-        if (entry.startsWith("workshop:"))
-          ids.add(entry.slice(9));
-      } else if ("workshop" in entry && entry.workshop !== undefined)
-        ids.add(String(entry.workshop));
-    }
-  }
-  if (ids.size === 0)
-    return null;
-  const shown = [...ids].slice(0, 3).join(", ");
-  const tail = `${ids.size} workshop reference(s)`;
-  return {
-    where: `/games/${gameName}/workshopRoot`,
-    message: `${noWorkshopRoot(gameName, tail)}: ${shown}${ids.size > 3 ? ", ..." : ""}`,
-    suggestion: `set games.${gameName}.workshopRoot, or pin those mods with path: or git:`
-  };
+function notFetched(id) {
+  return `workshop item ${id} is not fetched, and fetching is off for this command; a real launch would fetch it`;
 }
 function refFor(entry, game, sources) {
   const object = typeof entry === "string" ? { id: entry } : entry;
@@ -4776,7 +5217,7 @@ function refFor(entry, game, sources) {
   if (pin?.git !== undefined) {
     const dir = sources.get(object.id.toLowerCase());
     if (dir !== undefined)
-      return `path:${pin.subdir === undefined ? dir : join16(dir, pin.subdir)}`;
+      return `path:${pin.subdir === undefined ? dir : join18(dir, pin.subdir)}`;
   }
   return object.id;
 }
@@ -4941,6 +5382,7 @@ async function resolvePlan(options) {
   const { game: gameName, profile: requestedProfile, root } = options;
   const args = options.args ?? {};
   const sources = options.sources ?? new Map;
+  const unfetched = new Set(options.unfetched ?? []);
   const problems = [];
   const warnings = [];
   const game = own(root.games, gameName);
@@ -4968,7 +5410,7 @@ async function resolvePlan(options) {
   if (args.dockerArgs?.length)
     settings.dockerArgs = [...settings.dockerArgs ?? [], ...args.dockerArgs];
   const plugin = requirePlugin(options.plugins, gameName);
-  const index = options.index ?? await buildIndex(gameName, game, plugin, sourcesRoot(root.dataRoot));
+  const index = options.index ?? await buildIndex(gameName, game, plugin, sourcesRoot(root.dataRoot), root.dataRoot);
   await applyWorktreeRequests(index, instance.requests, game);
   problems.push(...await applySourceOverrides(index, args.use ?? [], game));
   const excluded = [...profile.exclude ?? [], ...args.without ?? []].map(globToRegExp);
@@ -4985,11 +5427,8 @@ async function resolvePlan(options) {
           continue;
         if (optional)
           warnings.push(`optional mod ${ref} is not installed; skipped`);
-        else if (ref.startsWith("workshop:") && game.workshopRoot === null) {
-          problems.push({
-            where: slot.where,
-            message: noWorkshopRoot(gameName, ref)
-          });
+        else if (ref.startsWith("workshop:") && unfetched.has(ref.slice(9))) {
+          problems.push({ where: slot.where, message: notFetched(ref.slice(9)) });
         } else
           problems.push({ where: slot.where, message: `no mod matches "${ref}"` });
         continue;
@@ -5001,8 +5440,15 @@ async function resolvePlan(options) {
       staged.push({ record, explicit: true });
     }
   }
-  if (profile.autoDependencies === true)
+  if (profile.autoDependencies !== false)
     insertDependencies(staged, present, index, game, problems);
+  if (unfetched.size > 0) {
+    for (const problem of problems) {
+      const id = workshopUrlId(problem.suggestion);
+      if (id !== undefined && unfetched.has(id))
+        problem.message = notFetched(id);
+    }
+  }
   const ordered = args.sort === "none" ? staged : topoSort(staged, problems, game.core);
   warnings.push(...incompatibilityWarnings(ordered));
   const mods = [];
@@ -5043,6 +5489,9 @@ async function resolvePlan(options) {
   if (!game.modes.includes(mode)) {
     problems.push({ where: "flag --mode", message: `${gameName} does not support mode "${mode}"` });
   }
+  if (unfetched.size > 0) {
+    warnings.unshift(`this plan is provisional: ${unfetched.size} workshop item(s) are not fetched, and a real launch would fetch them first`);
+  }
   const plan = {
     game: gameName,
     gameConfig: game,
@@ -5053,11 +5502,11 @@ async function resolvePlan(options) {
     profileDir,
     ...instance.name === undefined ? {} : { instance: instance.name },
     instanceDir: instance.dir,
-    dataDirHost: join16(instance.dir, "game"),
-    configDirHost: join16(profileDir, "config"),
-    stageDirHost: join16(instance.dir, ".stage"),
-    logsDirHost: join16(instance.dir, "logs"),
-    runDirHost: join16(instance.dir, "logs"),
+    dataDirHost: join18(instance.dir, "game"),
+    configDirHost: join18(profileDir, "config"),
+    stageDirHost: join18(instance.dir, ".stage"),
+    logsDirHost: join18(instance.dir, "logs"),
+    runDirHost: join18(instance.dir, "logs"),
     mode,
     ...args.marker === undefined ? {} : { marker: args.marker },
     timeoutSeconds: args.timeout ?? DEFAULT_TIMEOUT_SECONDS,
@@ -5069,8 +5518,8 @@ async function resolvePlan(options) {
 }
 
 // src/run/registry.ts
-import { readdir as readdir8 } from "node:fs/promises";
-import { join as join17 } from "node:path";
+import { readdir as readdir9 } from "node:fs/promises";
+import { join as join19 } from "node:path";
 var FORMAT = '{{.Names}}\t{{.Label "gamecrate.game"}}\t{{.Label "gamecrate.profile"}}\t{{.Label "gamecrate.instance"}}\t{{.Status}}';
 function parseDockerRuns(stdout) {
   const out = [];
@@ -5095,20 +5544,20 @@ function parseDockerRuns(stdout) {
 async function walkLocks(dataRoot) {
   const out = [];
   for (const game of await entries(dataRoot)) {
-    const gameDir = join17(dataRoot, game);
+    const gameDir = join19(dataRoot, game);
     for (const profile of await entries(gameDir)) {
-      const profileDir = join17(gameDir, profile);
-      await push(out, join17(profileDir, ".gamecrate", "lock"));
-      const instancesDir = join17(profileDir, "instances");
+      const profileDir = join19(gameDir, profile);
+      await push(out, join19(profileDir, ".gamecrate", "lock"));
+      const instancesDir = join19(profileDir, "instances");
       for (const instance of await entries(instancesDir)) {
-        await push(out, join17(instancesDir, instance, ".gamecrate", "lock"));
+        await push(out, join19(instancesDir, instance, ".gamecrate", "lock"));
       }
     }
   }
   return out;
 }
 async function entries(dir) {
-  const found = await readdir8(dir, { withFileTypes: true }).catch(() => []);
+  const found = await readdir9(dir, { withFileTypes: true }).catch(() => []);
   return found.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
 async function push(out, path) {
@@ -5158,10 +5607,10 @@ async function listRuns(dataRoot, docker = dockerPs) {
 }
 
 // src/launch/stage.ts
-import { lstat, mkdir as mkdir5, readdir as readdir9, realpath as realpath2, rm as rm3, stat as stat4 } from "node:fs/promises";
-import { basename as basename9, join as join18 } from "node:path";
+import { lstat, mkdir as mkdir5, readdir as readdir10, realpath as realpath2, rm as rm4, stat as stat5 } from "node:fs/promises";
+import { basename as basename10, join as join20 } from "node:path";
 async function stageMods(plan) {
-  await rm3(plan.stageDirHost, { recursive: true, force: true });
+  await rm4(plan.stageDirHost, { recursive: true, force: true });
   await mkdir5(plan.stageDirHost, { recursive: true });
   const mounts = [];
   for (const mod of plan.mods) {
@@ -5173,10 +5622,10 @@ async function stageMods(plan) {
     } catch {
       throw new GamecrateError(`mod directory for ${mod.packageId} is missing`, Exit.Environment, mod.hostDir);
     }
-    if (!(await stat4(source)).isDirectory()) {
+    if (!(await stat5(source)).isDirectory()) {
       throw new GamecrateError(`${mod.packageId} does not resolve to a directory`, Exit.Environment, source);
     }
-    await mkdir5(join18(plan.stageDirHost, basename9(mod.containerDir)), { recursive: true });
+    await mkdir5(join20(plan.stageDirHost, basename10(mod.containerDir)), { recursive: true });
     mounts.push({ type: "bind", source, target: mod.containerDir, readonly: true });
   }
   return mounts;
@@ -5186,12 +5635,12 @@ async function ensureProfileTree(plan) {
     plan.profileDir,
     plan.instanceDir,
     plan.dataDirHost,
-    join18(plan.configDirHost, "config"),
-    join18(plan.configDirHost, "data"),
-    join18(plan.configDirHost, "cache"),
-    join18(plan.logsDirHost, "runs"),
+    join20(plan.configDirHost, "config"),
+    join20(plan.configDirHost, "data"),
+    join20(plan.configDirHost, "cache"),
+    join20(plan.logsDirHost, "runs"),
     plan.stageDirHost,
-    join18(plan.instanceDir, ".gamecrate"),
+    join20(plan.instanceDir, ".gamecrate"),
     ...engineDirs(plan)
   ]) {
     await mkdir5(dir, { recursive: true });
@@ -5201,7 +5650,7 @@ function engineDirs(plan) {
   const { dataDir, modsDir } = plan.gameConfig;
   if (!modsDir.container.startsWith(`${dataDir.container}/`))
     return [];
-  return [join18(plan.dataDirHost, modsDir.container.slice(dataDir.container.length + 1))];
+  return [join20(plan.dataDirHost, modsDir.container.slice(dataDir.container.length + 1))];
 }
 async function detectForeignOwnership(dir, uid, limit = 100) {
   const foreign = [];
@@ -5222,8 +5671,8 @@ async function detectForeignOwnership(dir, uid, limit = 100) {
     if (!info.isDirectory())
       continue;
     try {
-      for (const entry of await readdir9(current))
-        queue.push(join18(current, entry));
+      for (const entry of await readdir10(current))
+        queue.push(join20(current, entry));
     } catch {
       continue;
     }
@@ -5231,8 +5680,144 @@ async function detectForeignOwnership(dir, uid, limit = 100) {
   return foreign;
 }
 
+// src/mods/workshop.ts
+import { existsSync as existsSync11 } from "node:fs";
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join21, resolve as resolvePath2 } from "node:path";
+var ROUNDS = 5;
+async function prepareWorkshop(game, profileName, args, config, allowFetch, plugin, sources) {
+  const roots = mountedRoots(config.dataRoot, game);
+  const ids = new Set;
+  const warnings = [];
+  const problems = [];
+  const profile = resolveProfile(game, profileName);
+  const seeded = await localSeeds(game, profile, args, sources, plugin, problems);
+  let frontier = [...new Set([...wantedIds(game, profile, args), ...seeded])];
+  for (let round = 0;round < ROUNDS && frontier.length > 0; round++) {
+    for (const id of frontier)
+      ids.add(id);
+    if (allowFetch)
+      warnings.push(...await fetchRound(config, game, roots, frontier));
+    frontier = await dependenciesOf(frontier, ids, roots, game, plugin, problems);
+  }
+  if (frontier.length > 0) {
+    problems.push({
+      where: `profile ${profileName}`,
+      message: `workshop dependencies are still unresolved after ${ROUNDS} rounds: ${frontier.join(", ")}`,
+      suggestion: "name them in the profile so they download in the first round"
+    });
+  }
+  return { ids, warnings, problems, unfetched: [...ids].filter((id) => itemDir(roots, id) === undefined) };
+}
+async function fetchRound(config, game, roots, frontier) {
+  try {
+    const drift = await checkDrift(frontier, roots);
+    const downloaded = await downloadItems(config, game, config.dataRoot, drift.needed);
+    return [...drift.warnings, ...downloaded.warnings];
+  } catch (error) {
+    return [`could not download workshop items: ${error instanceof Error ? error.message : String(error)}`];
+  }
+}
+async function dependenciesOf(frontier, seen, roots, game, plugin, problems) {
+  const next = new Set;
+  for (const id of frontier) {
+    const manifest = await manifestOf(roots, id, game, plugin, problems);
+    for (const dep of manifest?.modDependencies ?? []) {
+      const depId = workshopUrlId(dep.steamWorkshopUrl);
+      if (depId !== undefined && !seen.has(depId))
+        next.add(depId);
+    }
+  }
+  return [...next];
+}
+function mountedRoots(dataRoot, game) {
+  return [downloadRoot(dataRoot, game), ...game.workshopRoot === null ? [] : [game.workshopRoot]];
+}
+function itemDir(roots, id) {
+  return roots.map((root) => join21(root, id)).find((dir) => existsSync11(dir));
+}
+async function manifestOf(roots, id, game, plugin, problems) {
+  const dir = itemDir(roots, id);
+  return dir === undefined ? null : await manifestAt(dir, game, plugin, problems);
+}
+async function manifestAt(dir, game, plugin, problems) {
+  const file = join21(dir, game.manifest.file);
+  if (!existsSync11(file))
+    return null;
+  try {
+    return plugin.parseManifest(await readFile11(file, "utf8"));
+  } catch (error) {
+    problems.push({ where: file, message: error instanceof Error ? error.message : String(error) });
+    return null;
+  }
+}
+async function localSeeds(game, profile, args, sources, plugin, problems) {
+  const out = new Set;
+  for (const dir of localDirs(game, profile, args, sources)) {
+    const manifest = await manifestAt(dir, game, plugin, problems);
+    for (const dep of manifest?.modDependencies ?? []) {
+      const id = workshopUrlId(dep.steamWorkshopUrl);
+      if (id !== undefined)
+        out.add(id);
+    }
+  }
+  return [...out];
+}
+function localDirs(game, profile, args, sources) {
+  const out = new Set;
+  for (const entry of reachedEntries(game, profile, args)) {
+    const dir = localDirOf(entry, game, sources);
+    if (dir !== undefined)
+      out.add(dir);
+  }
+  return [...out];
+}
+function localDirOf(entry, game, sources) {
+  if (typeof entry !== "string" && "match" in entry)
+    return;
+  const object = typeof entry === "string" ? { id: entry } : entry;
+  if (object.path !== undefined)
+    return resolvePath2(expandHome(object.path));
+  if (object.id.includes(":"))
+    return;
+  const pin = libraryPin(game, object.id);
+  const clone = sources.get(object.id.toLowerCase());
+  if (clone !== undefined)
+    return pin?.subdir === undefined ? clone : join21(clone, pin.subdir);
+  return pin?.path === undefined ? undefined : resolvePath2(expandHome(pin.path));
+}
+function wantedIds(game, profile, args) {
+  const out = new Set;
+  for (const entry of reachedEntries(game, profile, args)) {
+    const id = workshopIdOf(entry, game);
+    if (id !== undefined)
+      out.add(id);
+  }
+  return [...out];
+}
+function workshopIdOf(entry, game) {
+  if (typeof entry !== "string" && "match" in entry)
+    return;
+  const object = typeof entry === "string" ? { id: entry } : entry;
+  if (object.path !== undefined)
+    return;
+  if (object.workshop !== undefined)
+    return published2(String(object.workshop));
+  if (object.id.startsWith("workshop:"))
+    return published2(object.id.slice("workshop:".length));
+  if (object.id.includes(":"))
+    return;
+  const pin = libraryPin(game, object.id);
+  if (pin?.path !== undefined)
+    return;
+  return pin?.workshop === undefined ? undefined : published2(String(pin.workshop));
+}
+function published2(value) {
+  return /^\d+$/.test(value) ? value : undefined;
+}
+
 // src/index.ts
-var VERSION = "1.2.0";
+var VERSION = "1.4.0";
 async function main(argv) {
   const supervised = supervisedDir(argv);
   try {
@@ -5304,13 +5889,13 @@ async function dispatch(argv, args, config, plugins, defaults) {
     case "wait":
       return waitFor(args, config, defaults);
     case "shell":
-      return run(argv, args, config, plugins, defaults, true);
+      return run2(argv, args, config, plugins, defaults, true);
     case "config":
       return configEdit(args);
     case "fix-perms":
       return fixPerms(args, config);
     case "run":
-      return run(argv, args, config, plugins, defaults, false);
+      return run2(argv, args, config, plugins, defaults, false);
     default:
       throw new GamecrateError(`no such subcommand ${args.subcommand}`, Exit.Usage);
   }
@@ -5356,25 +5941,38 @@ function reportEnvironment(problems) {
   throw new GamecrateError(`${problems.length} environment problem(s)`, Exit.Environment, out.join(`
 `));
 }
-async function run(argv, args, config, plugins, defaults, asShell) {
+async function run2(argv, args, config, plugins, defaults, asShell) {
   const game = requireGame(args, config);
   const profile = profileOf(args, defaults);
   const gameConfig = config.games[game];
   const allowFetch = !args.dryRun && !args.printPlan;
   const sources = await prepareSources(gameConfig, profile, args, config.dataRoot, allowFetch);
   try {
-    return await resolved(argv, args, config, plugins, asShell, game, profile, sources);
+    const workshop = await prepareWorkshop(gameConfig, profile, args, config, allowFetch, requirePlugin(plugins, game), sources.dirs);
+    return await resolved(argv, args, config, plugins, asShell, game, profile, sources, workshop, allowFetch);
   } finally {
     await sources.release();
   }
 }
-async function resolved(argv, args, config, plugins, asShell, game, profile, sources) {
-  for (const warning of sources.warnings)
+function warnUnfetched(problems, unfetched) {
+  const provisional = new Set(unfetched.map(notFetched));
+  const fatal = [];
+  for (const problem of problems) {
+    if (provisional.has(problem.message))
+      warn(`${problem.where}: ${problem.message}`);
+    else
+      fatal.push(problem);
+  }
+  return fatal;
+}
+async function resolved(argv, args, config, plugins, asShell, game, profile, sources, workshop, allowFetch) {
+  for (const warning of [...sources.warnings, ...workshop.warnings])
     warn(warning);
-  const index = await buildIndex(game, config.games[game], requirePlugin(plugins, game), sourcesRoot(config.dataRoot));
-  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index, sources: sources.dirs });
-  if (problems.length > 0)
-    reportProblems(problems);
+  const index = await buildIndex(game, config.games[game], requirePlugin(plugins, game), sourcesRoot(config.dataRoot), config.dataRoot);
+  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index, sources: sources.dirs, unfetched: allowFetch ? undefined : workshop.unfetched });
+  const fatal = warnUnfetched([...workshop.problems, ...problems], allowFetch ? [] : workshop.unfetched);
+  if (fatal.length > 0)
+    reportProblems(fatal);
   const identity = resolveIdentity(args.root);
   if (args.printPlan || args.dryRun) {
     const environment = await preflight(plan);
@@ -5421,7 +6019,7 @@ run: gamecrate fix-perms ${game} ${profile}`);
   }
   const runDir = openRunLog(plan.logsDirHost);
   plan.runDirHost = runDir;
-  const supervisorLog = args.supervised && args.log === undefined ? redirectOutput(join19(runDir, "supervisor.log")) : undefined;
+  const supervisorLog = args.supervised && args.log === undefined ? redirectOutput(join22(runDir, "supervisor.log")) : undefined;
   try {
     return await execute(plan, args, config, identity, asShell, profileSpec, runDir, releaseSources);
   } finally {
@@ -5479,19 +6077,19 @@ async function execute(plan, args, config, identity, asShell, profileSpec, runDi
   }
 }
 function markerSources(plan, logDir) {
-  const sources = [join19(logDir, STDOUT_LOG)];
+  const sources = [join22(logDir, STDOUT_LOG)];
   const { logFile } = plan.gameConfig;
   if (logFile.mode === "arg")
-    sources.push(join19(logDir, "Player.log"));
+    sources.push(join22(logDir, "Player.log"));
   else
-    sources.push(join19(plan.dataDirHost, logFile.from));
+    sources.push(join22(plan.dataDirHost, logFile.from));
   return sources;
 }
 async function runBounded(spec, plan, logDir) {
   const container = runContainer(spec, { logDir, stopTimeoutSeconds: STOP_TIMEOUT_SECONDS });
   const winner = await Promise.race([
     container.then((code) => ({ kind: "exit", code })),
-    sleep6(plan.timeoutSeconds * 1000).then(() => ({ kind: "timeout" }))
+    sleep7(plan.timeoutSeconds * 1000).then(() => ({ kind: "timeout" }))
   ]);
   if (winner.kind === "exit")
     return { code: normalize(winner.code), reason: reasonFor(winner.code) };
@@ -5502,7 +6100,7 @@ async function runBounded(spec, plan, logDir) {
 }
 async function runWithScreenshot(spec, plan, logDir) {
   const container = runContainer(spec, { logDir, stopTimeoutSeconds: STOP_TIMEOUT_SECONDS });
-  const settled = sleep6(plan.renderWaitSeconds * 1000).then(() => "ready");
+  const settled = sleep7(plan.renderWaitSeconds * 1000).then(() => "ready");
   const winner = await Promise.race([
     container.then((code) => ({ kind: "exit", code })),
     settled.then(() => ({ kind: "ready" }))
@@ -5552,10 +6150,10 @@ async function copyOutLogs(plan) {
   const spec = plan.gameConfig.logFile;
   if (spec.mode !== "copy-out")
     return;
-  const source = join19(plan.dataDirHost, spec.from);
-  if (!existsSync10(source))
+  const source = join22(plan.dataDirHost, spec.from);
+  if (!existsSync12(source))
     return;
-  const target = join19(plan.runDirHost, basename10(spec.from.replace(/\/+$/, "")));
+  const target = join22(plan.runDirHost, basename11(spec.from.replace(/\/+$/, "")));
   try {
     await cp(source, target, { recursive: true, force: true });
   } catch (error) {
@@ -5565,21 +6163,65 @@ async function copyOutLogs(plan) {
 async function mods(args, config, plugins, defaults) {
   const game = requireGame(args, config);
   const profile = profileOf(args, defaults);
-  const index = await buildIndex(game, config.games[game], requirePlugin(plugins, game), sourcesRoot(config.dataRoot));
   const sources = cachedSources(config.games[game], profile, args, config.dataRoot);
-  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index, sources });
-  if (problems.length > 0)
-    reportProblems(problems);
+  const workshop = await prepareWorkshop(config.games[game], profile, args, config, false, requirePlugin(plugins, game), sources);
+  for (const warning of workshop.warnings)
+    warn(warning);
+  const index = await buildIndex(game, config.games[game], requirePlugin(plugins, game), sourcesRoot(config.dataRoot), config.dataRoot);
+  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index, sources, unfetched: workshop.unfetched });
+  const fatal = warnUnfetched([...workshop.problems, ...problems], workshop.unfetched);
+  if (fatal.length > 0)
+    reportProblems(fatal);
   printPlan(plan, args.json);
   return Exit.Ok;
 }
+function usesWorkshop(game) {
+  for (const entry of Object.values(game.library ?? {})) {
+    if (entry.workshop !== undefined)
+      return true;
+  }
+  for (const ref of [...game.preCore ?? [], game.core, ...game.dlc, ...game.base ?? []]) {
+    if (ref.startsWith("workshop:"))
+      return true;
+  }
+  for (const profile of Object.values(game.profiles)) {
+    for (const entry of profile.mods ?? []) {
+      if (typeof entry === "string") {
+        if (entry.startsWith("workshop:"))
+          return true;
+      } else if ("workshop" in entry && entry.workshop !== undefined)
+        return true;
+    }
+  }
+  return false;
+}
+function steamcmdSource(runner, config) {
+  if (runner.kind === "docker")
+    return `docker image ${STEAMCMD_IMAGE}`;
+  const where = config.steamcmd?.path === undefined ? "on PATH" : "steamcmd.path";
+  return `${runner.argv[0]} (${where})`;
+}
 async function doctor(config, plugins) {
   let failed = false;
   for (const game of Object.keys(config.games)) {
-    const sources = cachedSources(config.games[game], "modless", {}, config.dataRoot);
+    const gameConfig = config.games[game];
+    const sources = cachedSources(gameConfig, "modless", {}, config.dataRoot);
     const { plan, problems } = await resolvePlan({ game, profile: "modless", root: config, plugins, sources });
-    const workshop = workshopRootProblem(game, config.games[game]);
-    const all = [...problems, ...await preflight(plan), ...workshop === null ? [] : [workshop]];
+    const steamcmd = [];
+    if (usesWorkshop(gameConfig)) {
+      try {
+        status(`${game}: steamcmd ${steamcmdSource(resolveSteamcmd(config), config)}`);
+      } catch (error) {
+        steamcmd.push({
+          where: "steamcmd",
+          message: error instanceof Error ? error.message : String(error),
+          ...error instanceof GamecrateError && error.detail !== undefined ? { suggestion: error.detail } : {}
+        });
+      }
+      const root = downloadRoot(config.dataRoot, gameConfig);
+      status(`${game}: workshop downloads ${root}${existsSync12(root) ? "" : " (not created yet)"}`);
+    }
+    const all = [...problems, ...await preflight(plan), ...steamcmd];
     if (all.length === 0) {
       status(`${game}: ok`);
       continue;
@@ -5603,13 +6245,13 @@ async function logs(args, config, defaults) {
   const dir = instanceDir(args, config, game, profile);
   if (args.follow)
     return await follow(dir, false, `${game} ${profile}`);
-  const runs = join19(dir, "logs", "runs");
-  const latest = (await readdir10(runs, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().at(-1);
+  const runs = join22(dir, "logs", "runs");
+  const latest = (await readdir11(runs, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().at(-1);
   if (latest === undefined) {
     throw new GamecrateError(`no runs recorded for ${game} ${profile}`, Exit.Usage, runs);
   }
-  const runDir = join19(runs, latest);
-  const files = (await readdir10(runDir, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+  const runDir = join22(runs, latest);
+  const files = (await readdir11(runDir, { withFileTypes: true })).filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
   if (args.json) {
     process.stdout.write(`${JSON.stringify({ run: latest, dir: runDir, files }, null, 2)}
 `);
@@ -5617,7 +6259,7 @@ async function logs(args, config, defaults) {
   }
   status(runDir);
   for (const name of files) {
-    const text = await readFile10(join19(runDir, name), "utf8").catch(() => "");
+    const text = await readFile12(join22(runDir, name), "utf8").catch(() => "");
     for (const line of text.split(`
 `)) {
       if (line.length > 0)
@@ -5744,18 +6386,24 @@ async function clean(args, config, defaults) {
   const dir = profileDataDir(config, game, profile);
   const tier = args.cleanTier ?? "staging";
   const saveSuffixes = config.games[game].saveExtensions.map((ext) => `.${ext.replace(/^\./, "")}`.toLowerCase());
+  const downloads = downloadRoot(config.dataRoot, config.games[game]);
+  if (tier === "downloads") {
+    status(await removeDownloads(downloads, config.games[game].steamAppId));
+    return Exit.Ok;
+  }
   if (tier !== "all") {
-    const target = join19(instanceDir(args, config, game, profile), tier === "logs" ? "logs" : ".stage");
-    await rm4(target, { recursive: true, force: true });
+    const target = join22(instanceDir(args, config, game, profile), tier === "logs" ? "logs" : ".stage");
+    await rm5(target, { recursive: true, force: true });
     status(`removed ${target}`);
     return Exit.Ok;
   }
   const saves = await countSaves(dir, saveSuffixes);
   if (!args.yes) {
-    throw new GamecrateError(`clean --all would delete ${dir}, including ${saves} save file(s)`, Exit.Usage, "add --yes to confirm");
+    throw new GamecrateError(`clean --all would delete ${dir}, including ${saves} save file(s), and ${game}'s workshop downloads`, Exit.Usage, "add --yes to confirm, or --downloads to drop only the downloads");
   }
-  await rm4(dir, { recursive: true, force: true });
+  await rm5(dir, { recursive: true, force: true });
   status(`removed ${dir} (${saves} save file(s))`);
+  status(await removeDownloads(downloads, config.games[game].steamAppId));
   return Exit.Ok;
 }
 async function countSaves(dir, suffixes) {
@@ -5765,13 +6413,13 @@ async function countSaves(dir, suffixes) {
     const current = queue.shift();
     let entries;
     try {
-      entries = await readdir10(current, { withFileTypes: true });
+      entries = await readdir11(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
       if (entry.isDirectory())
-        queue.push(join19(current, entry.name));
+        queue.push(join22(current, entry.name));
       else if (suffixes.some((s) => entry.name.toLowerCase().endsWith(s)))
         count++;
     }
@@ -5784,11 +6432,11 @@ async function clone(args, config) {
   if (src === undefined || dst === undefined) {
     throw new GamecrateError("clone needs a source and a destination profile", Exit.Usage);
   }
-  const from = join19(profileDataDir(config, game, src), "game");
-  const to = join19(profileDataDir(config, game, dst), "game");
-  if (!existsSync10(from))
+  const from = join22(profileDataDir(config, game, src), "game");
+  const to = join22(profileDataDir(config, game, dst), "game");
+  if (!existsSync12(from))
     throw new GamecrateError(`${from} does not exist`, Exit.Usage);
-  if (existsSync10(to) && !args.yes) {
+  if (existsSync12(to) && !args.yes) {
     throw new GamecrateError(`${to} already exists`, Exit.Usage, "add --yes to overwrite");
   }
   await mkdir6(to, { recursive: true });
@@ -5830,7 +6478,7 @@ async function ps(args, config) {
 async function stop(args, config, defaults) {
   const game = requireGame(args, config);
   const profile = profileOf(args, defaults);
-  const file = join19(instanceDir(args, config, game, profile), ".gamecrate", "lock");
+  const file = join22(instanceDir(args, config, game, profile), ".gamecrate", "lock");
   const record = await readLock(file);
   if (record === undefined) {
     status(`${game} ${profile} is not running`);
@@ -5850,11 +6498,11 @@ async function attach(args, config, defaults) {
   return await follow(instanceDir(args, config, game, profile), true, `${game} ${profile}`);
 }
 async function follow(dir, fromStart, what) {
-  const lock = await readLock(join19(dir, ".gamecrate", "lock"));
+  const lock = await readLock(join22(dir, ".gamecrate", "lock"));
   const held = lock !== undefined && isRunning(lock.pid, lock.startedAt);
   const live = held && await awaitRunLog(dir, lock);
   const file = currentLog(dir);
-  if (!existsSync10(file)) {
+  if (!existsSync12(file)) {
     throw new GamecrateError(`no captured output for ${what}`, Exit.Usage, file);
   }
   return await spawnStatus(tailArgv(file, fromStart, live ? lock.pid : undefined), true);
@@ -5887,9 +6535,9 @@ async function configEdit(args) {
   if (args.rest[0] !== "edit")
     throw new GamecrateError("config takes one word: edit", Exit.Usage);
   const existing = await findGlobalConfig();
-  const path = existing ?? join19(globalConfigDir(), "profiles.yml");
-  await mkdir6(dirname8(path), { recursive: true });
-  if (!existsSync10(path)) {
+  const path = existing ?? join22(globalConfigDir(), "profiles.yml");
+  await mkdir6(dirname10(path), { recursive: true });
+  if (!existsSync12(path)) {
     await writeFile7(path, `# gamecrate config. see https://github.com/RimWorks/gamecrate
 ` + `plugins: []
 ` + `games: {}
@@ -5909,7 +6557,7 @@ async function fixPerms(args, config) {
   const identity = resolveIdentity(false);
   const found = [];
   for (const dir of await profileDirs(config, game, args.profile)) {
-    if (!existsSync10(dir))
+    if (!existsSync12(dir))
       continue;
     found.push(...await detectForeignOwnership(dir, identity.uid, 1e4));
   }
@@ -5949,10 +6597,10 @@ async function fixPerms(args, config) {
   return Exit.Ok;
 }
 async function removeIfEmptyDir(path) {
-  const info = await stat5(path).catch(() => null);
+  const info = await stat6(path).catch(() => null);
   if (info === null || !info.isDirectory())
     return false;
-  const entries = await readdir10(path).catch(() => null);
+  const entries = await readdir11(path).catch(() => null);
   if (entries === null || entries.length > 0)
     return false;
   return rmdir(path).then(() => true, () => false);