@go-labs-sg/gosh 0.11.0 → 0.13.0

package/README.md

@@ -2,6 +2,20 @@
 
 `@go-labs-sg/gosh` provides the `gosh` binary for permission-aware GOSH organizer operations and agent automation. It calls the same tRPC procedures as the web app using the authorizing user's global, organization, and event permissions.
 
+## First step: update before use
+
+Before starting a task, **update to the latest published release first**, including when an AI agent runs this CLI:
+
+```bash
+bun add --global @go-labs-sg/gosh@latest
+gosh version
+gosh --help
+```
+
+Run this sequence once per task, not before every command. Re-read the updated help before choosing commands or flags. If updating fails, stop and report the failure rather than silently using an outdated CLI. If the user explicitly requested a pinned version or a development/staging build, preserve that version instead of replacing it with the public release.
+
+New installation? Follow the runtime and installation instructions below to install Bun first, then return to this step.
+
 ## Runtime and installation
 
 The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer. npm remains the package distribution channel, while the installed `gosh` command runs under Bun.
@@ -83,7 +97,7 @@ Commands use `--input '<json>'` for the exact validated tRPC input object. This
 
 `gosh event list-page` returns `{ items, page, pageSize, pageCount, totalCount }`. It defaults to page 1 with 25 results, accepts page sizes from 1 to 100, and supports server-side `search` and `status` filters. Archived events are excluded unless an explicit status is supplied. Request subsequent pages explicitly; the CLI does not automatically fetch every page. The existing `gosh event list` command and its array response remain unchanged.
 
-The command registry exposes the supported GOSH tRPC procedures across organizer and global-admin operations, organization invitations and membership, player workflows, public results/login procedures, uploads, and realtime subscriptions. Update the registry alongside API changes, then run `bun run generate:commands` to regenerate the manifest, reference, and typed operations.
+The command registry exposes the supported GOSH tRPC procedures across organizer and global-admin operations, organization invitations and membership, player workflows, public results/login procedures, uploads, and realtime subscriptions. Update the registry alongside API changes, then run `bun --filter @go-labs-sg/gosh generate:commands` from the repository root to regenerate the manifest, reference, and typed operations.
 
 ### Templates and organization scope
 
@@ -237,6 +251,37 @@ measures mission work only: travel between stations and staff review time are
 excluded. Existing leaderboard and results commands include the resulting
 timing information.
 
+### Artwork requirements (no login required)
+
+Read the bundled upload policy before preparing station, mission, or branding artwork:
+
+```bash
+gosh assets requirements --type station
+gosh assets requirements --type mission --format text
+gosh assets requirements
+```
+
+The default output is the standard JSON envelope; `--format text` gives a readable brief.
+Omitting `--type` lists every supported artwork type. `gosh commands`,
+`gosh help assets requirements`, and the upload-command help expose this guidance too.
+This command is local and read-only: it does not access credentials, contact the API,
+or upload a file. API URL configuration is not used or validated for this command or
+its help. Its policy comes from the installed CLI version, not a live deployment.
+Update the CLI when newer policy definitions are published.
+
+- Station and mission setup images: JPEG, PNG, WebP; at most **10 MiB (10,485,760 bytes)**.
+- Branding images (logo, sponsor-logo, login-banner, map-marker, player-background):
+  the same formats; at most **5 MiB (5,242,880 bytes)**.
+- Neither artwork upload policy enforces pixel dimensions or aspect ratio.
+- **Recommendations, not requirements:** station artwork 1920 × 1080 (16:9),
+  mission artwork 1600 × 1000 (16:10). Participant cover containers can crop artwork;
+  the standard station card also becomes shorter on completion. Keep essential
+  text in station/mission text fields and important image content away from the edges.
+- Logos, login banners, map markers, and player backgrounds have separate display
+  guidance; no exact canvas is prescribed for them. Preview on the relevant mobile surface.
+
+These policies describe organizer artwork, not participant submission media or profile images.
+
 ### Local file uploads
 
 Upload commands add the local file metadata to the supplied API input, request a permission-scoped signed URL, and upload the bytes directly to storage without sending the GOSH CLI access token to storage:
@@ -313,6 +358,20 @@ Without the allow flags, an interactive terminal prints a workflow preview and r
 
 One-shot commands write one JSON envelope to stdout. Watch commands write newline-delimited JSON envelopes. Failures and opt-in `--debug` diagnostics go to stderr, and known secrets, payloads, join codes, share tokens, and signed URLs are redacted. `--quiet` or `-q` suppresses diagnostics.
 
+## Monorepo development
+
+Follow the [development workflow](../../../docs/development-workflow.md#required-cli-coverage). App/API changes affecting this CLI must update its commands, types/input-output contracts, help/docs and verification in the same change. Use the existing authenticated product API rather than CLI-only business logic. Presentation-only changes do not require CLI edits; record why when no CLI update was needed.
+
+From the repository root after isolated-worktree initialization:
+
+```bash
+bun --filter @go-labs-sg/gosh typecheck
+bun --filter @go-labs-sg/gosh build
+bun run packages/gosh/cli/src/index.ts help
+```
+
+Building is not publication or permission to mutate live data. Use focused temporary business-behavior tests and the final pre-push gate from the shared workflow. Its existing build regenerates command artifacts; review the manifest/reference and typed operations after registry changes.
+
 ## Release verification
 
 The `gosh-cli-v*` release workflow runs

package/command-manifest.json

@@ -2947,5 +2947,17 @@
 			"slug",
 			"name"
 		]
+	},
+	{
+		"path": ["assets", "requirements"],
+		"operation": "local",
+		"input": "none",
+		"requiresAuth": false,
+		"effects": [],
+		"summary": "Show upload limits and separate artwork recommendations without login or network access.",
+		"options": {
+			"--type": "Select station, mission, logo, sponsor-logo, login-banner, map-marker, player-background; omit for all asset types.",
+			"--format": "json (default, standard CLI envelope) or text."
+		}
 	}
 ]

package/command-reference.md

@@ -953,6 +953,7 @@ Upload an event branding asset from a local file.
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
 - Effects: state-change, external-write
+- Artwork guidance: `gosh assets requirements` (bundled policy, no login required).
 
 ## `gosh upload setup-image`
 
@@ -961,6 +962,7 @@ Upload a station or mission setup image from a local file.
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
 - Effects: state-change, external-write
+- Artwork guidance: `gosh assets requirements` (bundled policy, no login required).
 
 ## `gosh upload profile-image`
 
@@ -1153,3 +1155,13 @@ Unban a user.
 - Authentication: browser-authenticated CLI session required
 - Input: `--input '<json>'` required
 - Effects: state-change
+
+## `gosh assets requirements`
+
+Show upload limits and separate artwork recommendations without login or network access.
+
+- Authentication: not required
+- Input: none
+- Effects: read-only
+- --type: Select station, mission, logo, sponsor-logo, login-banner, map-marker, player-background; omit for all asset types.
+- --format: json (default, standard CLI envelope) or text.

package/dist/index.js

@@ -35,16 +35,16 @@ var __toESM = (mod, isNodeMode, target) => {
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = import.meta.require;
 
-// ../../../node_modules/.bun/dotenv@18.0.5/node_modules/dotenv/dist/index.cjs
+// ../../../node_modules/.bun/dotenv@18.0.6/node_modules/dotenv/dist/index.cjs
 var require_dist = __commonJS(function(exports, module) {
-  var I = (e, o) => () => {
+  var S = (e, o) => () => {
     try {
       return o || e((o = { exports: {} }).exports, o), o.exports;
     } catch (t) {
       throw o = 0, t;
     }
   };
-  var S = I((xe, U) => {
+  var j = S((xe, U) => {
     function G(e) {
       return typeof e == "string" ? !["false", "0", "no", "off", ""].includes(e.toLowerCase()) : !!e;
     }
@@ -58,8 +58,8 @@ var require_dist = __commonJS(function(exports, module) {
     }
     U.exports = { parseBoolean: G, optionsFromEnv: X };
   });
-  var N = I((ye, x) => {
-    var Y = __require("fs"), j = __require("path"), z = __require("os"), { URL: Z, fileURLToPath: ee } = __require("url"), { parseBoolean: k, optionsFromEnv: B } = S(), te = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg, b = new Uint8Array(256);
+  var N = S((ye, x) => {
+    var Y = __require("fs"), k = __require("path"), z = __require("os"), { URL: Z, fileURLToPath: ee } = __require("url"), { parseBoolean: $, optionsFromEnv: B } = j(), te = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg, b = new Uint8Array(256);
     for (let e = 48;e <= 57; e++)
       b[e] = 1;
     for (let e = 65;e <= 90; e++)
@@ -185,7 +185,7 @@ var require_dist = __commonJS(function(exports, module) {
       return o;
     }
     function ne(e, o) {
-      return o && k(o.fast) ? oe(e) : re(e);
+      return o && $(o.fast) ? oe(e) : re(e);
     }
     function T(e) {
       console.log(`\u2506 ${e}`);
@@ -194,16 +194,16 @@ var require_dist = __commonJS(function(exports, module) {
       console.error(`\u25C7 ${e}`);
     }
     function V(e) {
-      return e[0] === "~" ? j.join(z.homedir(), e.slice(1)) : e;
+      return e[0] === "~" ? k.join(z.homedir(), e.slice(1)) : e;
     }
     function ie(e = {}) {
       return { ...B(), ...e };
     }
     function ce(e) {
       e = ie(e);
-      let o = j.resolve(process.cwd(), ".env"), t = "utf8", n = process.env;
+      let o = k.resolve(process.cwd(), ".env"), t = "utf8", n = process.env;
       e && e.processEnv != null && (n = e.processEnv);
-      let r = k(e && e.debug);
+      let r = $(e && e.debug);
       e && e.encoding ? t = e.encoding : r && T("no encoding is specified (UTF-8 is used by default)");
       let s = [o];
       if (e && e.path)
@@ -222,12 +222,12 @@ var require_dist = __commonJS(function(exports, module) {
         } catch (a) {
           r && T(`failed to load ${c} ${a.message}`), i = a;
         }
-      let p = A.populate(n, l, e), f = k(Object.prototype.hasOwnProperty.call(e, "quiet") ? e.quiet : B(n).quiet);
+      let p = A.populate(n, l, e), f = $(Object.prototype.hasOwnProperty.call(e, "quiet") ? e.quiet : B(n).quiet);
       if (r || !f) {
         let c = Object.keys(p).length, a = [];
         for (let g of s)
           try {
-            let h = j.relative(process.cwd(), g instanceof Z ? ee(g) : g);
+            let h = k.relative(process.cwd(), g instanceof Z ? ee(g) : g);
             a.push(h);
           } catch (h) {
             r && T(`failed to load ${g} ${h.message}`), i = h;
@@ -240,7 +240,7 @@ var require_dist = __commonJS(function(exports, module) {
       return A.configDotenv(e);
     }
     function le(e, o, t = {}) {
-      let n = !!(t && t.debug), r = !!(t && t.override), s = {};
+      let n = $(t && t.debug), r = $(t && t.override), s = {};
       if (e === null || typeof e != "object" || o === null || typeof o != "object") {
         let i = new Error("OBJECT_REQUIRED: Please check the processEnv argument being passed to populate");
         throw i.code = "OBJECT_REQUIRED", i;
@@ -256,7 +256,7 @@ var require_dist = __commonJS(function(exports, module) {
     x.exports.populate = A.populate;
     x.exports = A;
   });
-  var M = I((Te, W) => {
+  var M = S((Te, W) => {
     var _ = __require("child_process"), fe = __require("fs"), L = __require("path");
     function ue(e) {
       let o = ['"'], t = 0;
@@ -309,9 +309,9 @@ var require_dist = __commonJS(function(exports, module) {
     }
     W.exports = pe;
   });
-  var K = I(($e, F) => {
-    var he = __require("fs"), ge = __require("os"), Q = __require("path"), me = __require("child_process"), ve = M(), R = N(), { optionsFromEnv: Ce } = S();
-    function $() {
+  var K = S(($e, F) => {
+    var he = __require("fs"), ge = __require("os"), Q = __require("path"), me = __require("child_process"), ve = M(), R = N(), { optionsFromEnv: Ce } = j();
+    function D() {
       console.log(["Usage: dotenv run [--help] [-q|--quiet] [--debug] [--override] [--fast] [-f|--file <paths>] [--] <command> [args...]", "", "Run a command with environment variables from a .env file.", "Place dotenv options before the command; all following arguments go to the command.", "", "Options:", "  -f, --file <paths>  .env paths, comma-separated or repeated (default: .env)", "  -q, --quiet suppress the injected env message", "  --debug     enable debug logging", "  --override  override existing environment variables", "  --fast      use the faster character-scanner parser", "", "Environment variables (DOTENV_CONFIG_* names remain as fallbacks):", "  DOTENV_PATH, DOTENV_ENCODING, DOTENV_QUIET,", "  DOTENV_DEBUG, DOTENV_OVERRIDE,", "  DOTENV_FAST"].join(`
 `));
     }
@@ -383,24 +383,24 @@ var require_dist = __commonJS(function(exports, module) {
     function J(e) {
       let o = e[0];
       if (o === "--help" || o === "-h") {
-        $();
+        D();
         return;
       }
       if (o !== "run") {
-        $(), process.exitCode = 1;
+        D(), process.exitCode = 1;
         return;
       }
       let t = we(e.slice(1));
       if (t.help) {
-        $();
+        D();
         return;
       }
       if (t.error) {
-        console.error(`dotenv: ${t.error}`), $(), process.exitCode = 1;
+        console.error(`dotenv: ${t.error}`), D(), process.exitCode = 1;
         return;
       }
       if (t.command.length === 0) {
-        $(), process.exitCode = 1;
+        D(), process.exitCode = 1;
         return;
       }
       let n = Ee(t);
@@ -456,13 +456,13 @@ var require_dist = __commonJS(function(exports, module) {
     F.exports = J;
     F === __require.main && J(process.argv.slice(2));
   });
-  var D = N();
+  var I = N();
   var Oe = K();
-  module.exports = D;
-  module.exports.config = D.config;
-  module.exports.configDotenv = D.configDotenv;
-  module.exports.parse = D.parse;
-  module.exports.populate = D.populate;
+  module.exports = I;
+  module.exports.config = I.config;
+  module.exports.configDotenv = I.configDotenv;
+  module.exports.parse = I.parse;
+  module.exports.populate = I.populate;
 });
 
 // src/load-env.ts
@@ -6716,126 +6716,64 @@ var logoutCliSession = async ({
     return { remoteRevoked };
   });
 };
-// src/api-client.ts
-import {
-  createTRPCProxyClient,
-  httpBatchLink,
-  httpSubscriptionLink,
-  loggerLink,
-  splitLink
-} from "@trpc/client";
-import SuperJSON from "superjson";
-
-// src/features/authenticated-event-source.ts
-class AuthenticatedEventSource {
-  url;
-  init;
-  CLOSED = 2;
-  CONNECTING = 0;
-  OPEN = 1;
-  readyState = this.CONNECTING;
-  abortController = null;
-  closed = false;
-  lastEventId = "";
-  listeners = new Map;
-  retryMilliseconds = 1000;
-  constructor(url, init = {}) {
-    this.url = url;
-    this.init = init;
-    this.connect();
-  }
-  addEventListener(type, listener) {
-    const listeners = this.listeners.get(type) ?? new Set;
-    listeners.add(listener);
-    this.listeners.set(type, listeners);
-  }
-  removeEventListener(type, listener) {
-    this.listeners.get(type)?.delete(listener);
-  }
-  close = () => {
-    this.closed = true;
-    this.readyState = this.CLOSED;
-    this.abortController?.abort();
-  };
-  dispatch(type, event) {
-    for (const listener of this.listeners.get(type) ?? [])
-      listener(event);
-  }
-  async connect() {
-    if (this.closed)
-      return;
-    this.readyState = this.CONNECTING;
-    this.abortController = new AbortController;
-    try {
-      const response = await fetch(this.url, {
-        headers: {
-          Accept: "text/event-stream",
-          ...this.init.headers,
-          ...this.lastEventId ? { "Last-Event-ID": this.lastEventId } : {}
-        },
-        signal: this.abortController.signal
-      });
-      if (!response.ok || !response.body) {
-        throw new Error(`SSE connection failed with HTTP ${response.status}.`);
-      }
-      this.readyState = this.OPEN;
-      this.dispatch("open", new Event("open"));
-      await this.consume(response.body);
-    } catch (error) {
-      if (!this.closed) {
-        this.dispatch("error", new ErrorEvent("error", {
-          error: error instanceof Error ? error : new Error(String(error))
-        }));
-      }
-    }
-    if (!this.closed) {
-      setTimeout(() => void this.connect(), this.retryMilliseconds);
-    }
-  }
-  async consume(body) {
-    const reader = body.getReader();
-    const decoder = new TextDecoder;
-    let pending = "";
-    while (!this.closed) {
-      const { done, value } = await reader.read();
-      pending += decoder.decode(value, { stream: !done });
-      const blocks = pending.split(/\r?\n\r?\n/);
-      pending = blocks.pop() ?? "";
-      for (const block of blocks)
-        this.processBlock(block);
-      if (done)
-        break;
-    }
-  }
-  processBlock(block) {
-    let data = "";
-    let eventType = "message";
-    for (const line of block.split(/\r?\n/)) {
-      if (!line || line.startsWith(":"))
-        continue;
-      const separator = line.indexOf(":");
-      const field = separator === -1 ? line : line.slice(0, separator);
-      const rawValue = separator === -1 ? "" : line.slice(separator + 1);
-      const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
-      if (field === "data")
-        data += `${value}
-`;
-      if (field === "event")
-        eventType = value;
-      if (field === "id")
-        this.lastEventId = value;
-      if (field === "retry" && /^\d+$/.test(value)) {
-        this.retryMilliseconds = Number(value);
-      }
-    }
-    if (!data)
-      return;
-    this.dispatch(eventType, new MessageEvent(eventType, {
-      data: data.slice(0, -1),
-      lastEventId: this.lastEventId
-    }));
+// ../validators/src/asset-requirements.ts
+var goshImageContentTypes = ["image/jpeg", "image/png", "image/webp"];
+var goshImageAccept = goshImageContentTypes.join(",");
+var maxGoshSetupImageBytes = 10 * 1024 * 1024;
+var maxGoshBrandingImageBytes = 5 * 1024 * 1024;
+var goshAssetTypes = [
+  "station",
+  "mission",
+  "logo",
+  "sponsor-logo",
+  "login-banner",
+  "map-marker",
+  "player-background"
+];
+var logoGuidance = {
+  recommendedCanvas: null,
+  display: "Logo containers use contain sizing; available space varies by surface.",
+  artworkAdvice: "Use PNG or WebP for transparency. Keep the logo legible at small sizes; there is no prescribed canvas."
+};
+var guidance2 = {
+  station: {
+    recommendedCanvas: { width: 1920, height: 1080, aspectRatio: "16:9" },
+    display: "The standard event-home station card uses a 16:9 cover crop and a shorter crop when completed. Other station surfaces differ.",
+    artworkAdvice: "Keep important text and logos away from the edges. Prefer putting essential instructions in station text rather than the image."
+  },
+  mission: {
+    recommendedCanvas: { width: 1600, height: 1000, aspectRatio: "16:10" },
+    display: "Participant mission cards and mission artwork use 16:10 cover crops.",
+    artworkAdvice: "Keep important content away from the edges. Use mission text for essential instructions."
+  },
+  logo: logoGuidance,
+  "sponsor-logo": logoGuidance,
+  "login-banner": {
+    recommendedCanvas: null,
+    display: "The login banner uses full container width and automatic height; there is no prescribed upload ratio.",
+    artworkAdvice: "Preview in the mobile login card. No exact canvas is prescribed; do not assume the station's 16:9 recommendation applies."
+  },
+  "map-marker": {
+    recommendedCanvas: null,
+    display: "Custom markers appear in small map-marker containers.",
+    artworkAdvice: "Use a simple, legible icon and PNG or WebP for transparency. Preview on the participant map."
+  },
+  "player-background": {
+    recommendedCanvas: null,
+    display: "Participant backgrounds use centered cover sizing and can crop differently with the viewport.",
+    artworkAdvice: "Use decorative artwork without essential text. Check both portrait and landscape previews."
   }
-}
+};
+var getGoshAssetRequirements = (type) => ({
+  type,
+  requirements: {
+    acceptedContentTypes: goshImageContentTypes,
+    maxBytes: type === "station" || type === "mission" ? maxGoshSetupImageBytes : maxGoshBrandingImageBytes,
+    dimensions: null,
+    aspectRatio: null
+  },
+  recommendations: guidance2[type]
+});
 
 // src/runtime/index.ts
 import { createInterface } from "readline/promises";
@@ -7075,6 +7013,168 @@ var createProcessRuntime = () => ({
   }
 });
 
+// src/features/asset-requirements.ts
+var assetRequirementsCommand = {
+  path: ["assets", "requirements"],
+  operation: "local",
+  input: "none",
+  requiresAuth: false,
+  effects: [],
+  summary: "Show upload limits and separate artwork recommendations without login or network access.",
+  options: {
+    "--type": `Select ${goshAssetTypes.join(", ")}; omit for all asset types.`,
+    "--format": "json (default, standard CLI envelope) or text."
+  }
+};
+var getAssetRequirementsOutput = (type) => {
+  const selectedTypes = type !== undefined ? goshAssetTypes.filter((candidate) => candidate === type) : goshAssetTypes;
+  if (selectedTypes.length === 0) {
+    throw new CliError("USAGE", `Unknown asset type: ${type}. Choose ${goshAssetTypes.join(", ")}.`);
+  }
+  return {
+    provenance: "Bundled CLI policy; not a live-server verification. Update the CLI to obtain newer policy definitions.",
+    assets: selectedTypes.map(getGoshAssetRequirements)
+  };
+};
+var formatAssetRequirementsText = (output) => [
+  output.provenance,
+  ...output.assets.map(({ type, requirements, recommendations }) => {
+    const canvas = recommendations.recommendedCanvas;
+    return [
+      `
+${type}`,
+      `Required: JPEG, PNG, WebP; maximum ${requirements.maxBytes} bytes (${requirements.maxBytes / (1024 * 1024)} MiB).`,
+      "Enforced pixel dimensions / aspect ratio: none.",
+      `Recommended canvas (not required): ${canvas ? `${canvas.width} \xD7 ${canvas.height} px (${canvas.aspectRatio})` : "not prescribed"}.`,
+      `Display: ${recommendations.display}`,
+      `Artwork advice: ${recommendations.artworkAdvice}`
+    ].join(`
+`);
+  })
+].join(`
+`);
+
+// src/api-client.ts
+import {
+  createTRPCProxyClient,
+  httpBatchLink,
+  httpSubscriptionLink,
+  loggerLink,
+  splitLink
+} from "@trpc/client";
+import SuperJSON from "superjson";
+
+// src/features/authenticated-event-source.ts
+class AuthenticatedEventSource {
+  url;
+  init;
+  CLOSED = 2;
+  CONNECTING = 0;
+  OPEN = 1;
+  readyState = this.CONNECTING;
+  abortController = null;
+  closed = false;
+  lastEventId = "";
+  listeners = new Map;
+  retryMilliseconds = 1000;
+  constructor(url, init = {}) {
+    this.url = url;
+    this.init = init;
+    this.connect();
+  }
+  addEventListener(type, listener) {
+    const listeners = this.listeners.get(type) ?? new Set;
+    listeners.add(listener);
+    this.listeners.set(type, listeners);
+  }
+  removeEventListener(type, listener) {
+    this.listeners.get(type)?.delete(listener);
+  }
+  close = () => {
+    this.closed = true;
+    this.readyState = this.CLOSED;
+    this.abortController?.abort();
+  };
+  dispatch(type, event) {
+    for (const listener of this.listeners.get(type) ?? [])
+      listener(event);
+  }
+  async connect() {
+    if (this.closed)
+      return;
+    this.readyState = this.CONNECTING;
+    this.abortController = new AbortController;
+    try {
+      const response = await fetch(this.url, {
+        headers: {
+          Accept: "text/event-stream",
+          ...this.init.headers,
+          ...this.lastEventId ? { "Last-Event-ID": this.lastEventId } : {}
+        },
+        signal: this.abortController.signal
+      });
+      if (!response.ok || !response.body) {
+        throw new Error(`SSE connection failed with HTTP ${response.status}.`);
+      }
+      this.readyState = this.OPEN;
+      this.dispatch("open", new Event("open"));
+      await this.consume(response.body);
+    } catch (error) {
+      if (!this.closed) {
+        this.dispatch("error", new ErrorEvent("error", {
+          error: error instanceof Error ? error : new Error(String(error))
+        }));
+      }
+    }
+    if (!this.closed) {
+      setTimeout(() => void this.connect(), this.retryMilliseconds);
+    }
+  }
+  async consume(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder;
+    let pending = "";
+    while (!this.closed) {
+      const { done, value } = await reader.read();
+      pending += decoder.decode(value, { stream: !done });
+      const blocks = pending.split(/\r?\n\r?\n/);
+      pending = blocks.pop() ?? "";
+      for (const block of blocks)
+        this.processBlock(block);
+      if (done)
+        break;
+    }
+  }
+  processBlock(block) {
+    let data = "";
+    let eventType = "message";
+    for (const line of block.split(/\r?\n/)) {
+      if (!line || line.startsWith(":"))
+        continue;
+      const separator = line.indexOf(":");
+      const field = separator === -1 ? line : line.slice(0, separator);
+      const rawValue = separator === -1 ? "" : line.slice(separator + 1);
+      const value = rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue;
+      if (field === "data")
+        data += `${value}
+`;
+      if (field === "event")
+        eventType = value;
+      if (field === "id")
+        this.lastEventId = value;
+      if (field === "retry" && /^\d+$/.test(value)) {
+        this.retryMilliseconds = Number(value);
+      }
+    }
+    if (!data)
+      return;
+    this.dispatch(eventType, new MessageEvent(eventType, {
+      data: data.slice(0, -1),
+      lastEventId: this.lastEventId
+    }));
+  }
+}
+
 // src/config.ts
 var DEFAULT_GOSH_API_BASE_URL = "https://app.gosh.sg";
 var normalizeApiBaseUrl = (value) => {
@@ -8228,10 +8328,14 @@ var allowedFlags = new Set([
   "input",
   "no-browser",
   "quiet",
-  "target"
+  "target",
+  "type",
+  "format"
 ]);
 var commandName = (command) => command.path.join(" ");
+var updateBeforeUse = "First step before each task: update to the latest published release with 'bun add --global @go-labs-sg/gosh@latest', then run 'gosh version' and 'gosh --help' before using commands. Update once per task. If updating fails, stop and report it. Preserve an explicitly requested pinned or development/staging version.";
 var commandHelp = (command) => ({
+  beforeUse: updateBeforeUse,
   effects: command.effects,
   input: command.input === "json" ? "Pass the exact tRPC input object with --input '<json>'." : "This command does not accept --input.",
   path: command.path,
@@ -8241,9 +8345,14 @@ var commandHelp = (command) => ({
     target: "Pass --target with the exact resource being changed."
   },
   summary: command.summary,
+  ...command.upload === "setup-image" || command.upload === "branding" ? {
+    assetRequirements: goshAssetTypes.filter((type) => command.upload === "setup-image" ? type === "station" || type === "mission" : type !== "station" && type !== "mission").map(getGoshAssetRequirements),
+    assetRequirementsCommand: "gosh assets requirements"
+  } : {},
   usage: `gosh ${commandName(command)}${command.input === "json" ? " --input '<json>'" : ""}`
 });
 var rootHelp = {
+  beforeUse: updateBeforeUse,
   authentication: {
     instructions: "Run 'gosh auth login'. Approve the device in your browser; credentials are stored through Bun.secrets."
   },
@@ -8251,6 +8360,7 @@ var rootHelp = {
     "gosh help [command path]",
     "gosh commands",
     "gosh version",
+    "gosh assets requirements [--type station] [--format text]",
     "gosh <command path> [--input '<json>']"
   ],
   globalOptions: {
@@ -8286,6 +8396,16 @@ var emitHelp = (runtime, apiBaseUrl, positional) => {
       command: "help"
     }, rootHelp);
   }
+  if (positional.join(" ") === "assets requirements") {
+    return emitSuccess(runtime, {
+      apiBaseUrl,
+      cliVersion: GOSH_CLI_VERSION,
+      command: "help assets requirements"
+    }, {
+      ...assetRequirementsCommand,
+      usage: "gosh assets requirements [--type station] [--format json|text]"
+    });
+  }
   const resolved = findCommand(positional);
   if (!resolved || resolved.consumed !== positional.length) {
     throw new CliError("USAGE", `Unknown GOSH command: ${positional.join(" ")}`);
@@ -8302,8 +8422,14 @@ var runGoshCli = async (argv, dependencies) => {
   let apiBaseUrl = DEFAULT_GOSH_API_BASE_URL;
   try {
     validateFlags(flags);
-    apiBaseUrl = resolveApiBaseUrl(dependencies.runtime, flags);
     const [first, ...rest] = positional;
+    const isAssetRequirements = (first === "help" ? rest : positional).join(" ") === "assets requirements";
+    if (!isAssetRequirements) {
+      apiBaseUrl = resolveApiBaseUrl(dependencies.runtime, flags);
+    }
+    if (!isAssetRequirements && (flags.type !== undefined || flags.format !== undefined)) {
+      throw new CliError("USAGE", "--type and --format are only supported by assets requirements.");
+    }
     if (first === undefined || first === "help" || flags.help === true) {
       return emitHelp(dependencies.runtime, apiBaseUrl, first === "help" ? rest : positional);
     }
@@ -8325,7 +8451,32 @@ var runGoshCli = async (argv, dependencies) => {
         apiBaseUrl,
         cliVersion: GOSH_CLI_VERSION,
         command: "commands"
-      }, commandManifest);
+      }, [...commandManifest, assetRequirementsCommand]);
+    }
+    if (isAssetRequirements && first !== "help") {
+      for (const flag of Object.keys(flags)) {
+        if (!["type", "format", "api-url", "debug", "quiet", "help"].includes(flag)) {
+          throw new CliError("USAGE", `assets requirements does not accept --${flag}.`);
+        }
+      }
+      if (flags.type === true || flags.format === true) {
+        throw new CliError("USAGE", "--type and --format require values.");
+      }
+      const format = getStringFlag(flags, "format") ?? "json";
+      if (format !== "json" && format !== "text") {
+        throw new CliError("USAGE", "--format must be json or text.");
+      }
+      const output = getAssetRequirementsOutput(getStringFlag(flags, "type"));
+      if (format === "text") {
+        dependencies.runtime.stdout.write(`${formatAssetRequirementsText(output)}
+`);
+        return 0;
+      }
+      return emitSuccess(dependencies.runtime, {
+        apiBaseUrl,
+        cliVersion: GOSH_CLI_VERSION,
+        command: "assets requirements"
+      }, output);
     }
     const credentialStore = dependencies.credentialStore ?? createBunCredentialStore({
       account: resolveCliCredentialAccount(dependencies.runtime.env),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/gosh",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "GOSH CLI for organizers and AI agents — manage organizations, events, teams, stations, missions, templates, and live operations through the GOSH API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,7 @@
   ],
   "dependencies": {
     "@trpc/client": "^11.19.0",
-    "dotenv": "^18.0.1",
+    "dotenv": "^18.0.6",
     "superjson": "^2.2.6"
   },
   "engines": {