@groundfloorcloud/cli 0.1.12 → 0.2.0

package/dist/index.js

@@ -56,6 +56,7 @@ async function writeConfig(config) {
 `, {
     mode: 384
   });
+  await fs.chmod(CONFIG_FILE, 384);
 }
 async function updateConfig(patch) {
   const current = await readConfig();
@@ -394,7 +395,7 @@ var EXPIRY_SKEW_MS = 3e4;
 var NotLoggedInError = class extends Error {
   constructor() {
     super(
-      "Not logged in. Set GROUNDFLOOR_TOKEN, or run `gf login` first."
+      "Not logged in. Set GROUNDFLOOR_TOKEN to a Groundfloor access token (e.g. from `gf m2m token`), or run `gf login` first."
     );
     this.name = "NotLoggedInError";
   }
@@ -425,11 +426,26 @@ function sessionFromTokens(tokens, ctx) {
 function isFresh(session) {
   return Date.now() < session.expiresAt - EXPIRY_SKEW_MS;
 }
+function isExpiredJwt(token) {
+  const exp = decodeJwt(token)?.exp;
+  return typeof exp === "number" && Date.now() >= exp * 1e3 - EXPIRY_SKEW_MS;
+}
 async function getValidAccessToken() {
   if (accessTokenProvider) {
     return accessTokenProvider();
   }
+  const envToken = process.env.GROUNDFLOOR_TOKEN?.trim();
+  let envTokenExpired = false;
+  if (envToken) {
+    if (!isExpiredJwt(envToken)) return envToken;
+    envTokenExpired = true;
+  }
   const session = await readAuth();
+  if (envTokenExpired && (!session || !session.accessToken)) {
+    throw new Error(
+      "GROUNDFLOOR_TOKEN has expired and there is no saved `gf login` session. Mint a fresh token (e.g. `gf m2m token`) or run `gf login`."
+    );
+  }
   if (!session || !session.accessToken) {
     throw new NotLoggedInError();
   }
@@ -781,36 +797,29 @@ function getProcessLogs(apiUrl, workspaceId, query = {}) {
     `/v1/workspaces/${encodeURIComponent(workspaceId)}/logs${qs ? `?${qs}` : ""}`
   );
 }
-function domainsBase(workspaceId, coderunnerId) {
+function domainsBase(workspaceId, appId) {
   return `/v1/workspaces/${encodeURIComponent(
     workspaceId
-  )}/coderunners/${encodeURIComponent(coderunnerId)}/domains`;
+  )}/apps/${encodeURIComponent(appId)}/coderunner/domains`;
 }
-function listDomains(apiUrl, workspaceId, coderunnerId) {
-  return cpGet(
-    apiUrl,
-    domainsBase(workspaceId, coderunnerId)
-  );
+function listDomains(apiUrl, workspaceId, appId) {
+  return cpGet(apiUrl, domainsBase(workspaceId, appId));
 }
-function addDomain(apiUrl, workspaceId, coderunnerId, domain) {
-  return cpPostJson(
-    apiUrl,
-    domainsBase(workspaceId, coderunnerId),
-    { domain }
-  );
+function addDomain(apiUrl, workspaceId, appId, domain) {
+  return cpPostJson(apiUrl, domainsBase(workspaceId, appId), {
+    domain
+  });
 }
-function removeDomain(apiUrl, workspaceId, coderunnerId, domain) {
+function removeDomain(apiUrl, workspaceId, appId, domain) {
   return cpDelete(
     apiUrl,
-    `${domainsBase(workspaceId, coderunnerId)}/${encodeURIComponent(domain)}`
+    `${domainsBase(workspaceId, appId)}/${encodeURIComponent(domain)}`
   );
 }
-function verifyDomain(apiUrl, workspaceId, coderunnerId, domain) {
+function verifyDomain(apiUrl, workspaceId, appId, domain) {
   return cpPostJson(
     apiUrl,
-    `${domainsBase(workspaceId, coderunnerId)}/${encodeURIComponent(
-      domain
-    )}/verify`,
+    `${domainsBase(workspaceId, appId)}/${encodeURIComponent(domain)}/verify`,
     {}
   );
 }
@@ -1052,6 +1061,20 @@ async function controlPlaneRequest(apiUrl, method, path11, body) {
   if (!text) return void 0;
   return JSON.parse(text);
 }
+function getAccountQuota(apiUrl, accountId) {
+  return cpGet(
+    apiUrl,
+    `/v1/accounts/${encodeURIComponent(accountId)}/quota`
+  );
+}
+function getBillingSummary(apiUrl, accountId, sinceSeconds) {
+  return cpGet(
+    apiUrl,
+    `/v1/accounts/${encodeURIComponent(accountId)}/billing/summary${queryString({
+      since_seconds: sinceSeconds ? String(sinceSeconds) : void 0
+    })}`
+  );
+}
 
 // src/commands/whoami.ts
 async function whoamiCommand() {
@@ -1139,6 +1162,14 @@ Tip: run \`gf workspaces use <id>\` to set a default.
   }
 }
 async function workspacesUseCommand(workspaceId) {
+  const cfg = await resolveConfig();
+  const workspaces2 = await listWorkspaces(cfg.apiUrl);
+  const match = workspaces2.find((ws) => ws.id === workspaceId);
+  if (!match) {
+    throw new Error(
+      `Workspace ${workspaceId} was not found among the workspaces visible to you. Run \`gf workspaces\` to list valid ids.`
+    );
+  }
   await updateConfig({ workspaceId });
   process.stdout.write(`Default workspace set to ${workspaceId}
 `);
@@ -1256,6 +1287,49 @@ async function m2mTokenCommand(opts) {
 `);
 }
 
+// src/prompt.ts
+import readline from "readline";
+function defaultPromptIO() {
+  return {
+    isTTY: Boolean(process.stdin.isTTY && process.stderr.isTTY),
+    ask(question) {
+      return new Promise((resolve2) => {
+        const rl = readline.createInterface({
+          input: process.stdin,
+          output: process.stderr
+        });
+        rl.question(question, (answer) => {
+          rl.close();
+          resolve2(answer);
+        });
+      });
+    }
+  };
+}
+function isYes(answer) {
+  return /^(y|yes)$/i.test(answer.trim());
+}
+var AbortedError = class extends Error {
+  constructor() {
+    super("Aborted. Nothing was changed.");
+    this.name = "AbortedError";
+  }
+};
+async function confirmAction(opts) {
+  const io = opts.io ?? defaultPromptIO();
+  const write = opts.write ?? ((line) => process.stderr.write(`${line}
+`));
+  for (const line of opts.summary) write(line);
+  if (opts.yes) return;
+  if (!io.isTTY) {
+    throw new Error(
+      `Refusing to continue without confirmation (no interactive terminal). Re-run with ${opts.bypassHint ?? "--yes"} to confirm.`
+    );
+  }
+  const answer = await io.ask(`${opts.question ?? "Continue?"} [y/N] `);
+  if (!isYes(answer)) throw new AbortedError();
+}
+
 // src/commands/cancel-deployment.ts
 async function cancelDeploymentCommand(opts) {
   const cfg = await resolveConfig({ workspaceId: opts.workspace });
@@ -1264,14 +1338,26 @@ async function cancelDeploymentCommand(opts) {
       "No workspace selected. Run `gf workspaces use <id>` or pass --workspace <id>."
     );
   }
-  const coderunnerId = await resolveCoderunnerId(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    opts.coderunner
+  const ws = cfg.workspaceId;
+  const all = await listCoderunners(cfg.apiUrl, ws);
+  const target = all.find(
+    (c) => c.id === opts.coderunner || c.slug === opts.coderunner
   );
+  if (!target) {
+    throw new Error(`Coderunner not found: ${opts.coderunner}`);
+  }
+  const coderunnerId = target.id;
+  let workspaceName;
+  try {
+    workspaceName = (await listWorkspaces(cfg.apiUrl)).find(
+      (item) => item.id === ws
+    )?.name;
+  } catch {
+  }
   let deploymentId = opts.deploymentId?.trim();
+  const defaulted = !deploymentId;
   if (!deploymentId) {
-    const current = await getDeployment(cfg.apiUrl, cfg.workspaceId, coderunnerId);
+    const current = await getDeployment(cfg.apiUrl, ws, coderunnerId);
     deploymentId = current?.id?.trim();
   }
   if (!deploymentId) {
@@ -1279,12 +1365,20 @@ async function cancelDeploymentCommand(opts) {
       `No current deployment for coderunner ${coderunnerId}. Pass --deployment-id.`
     );
   }
-  await deleteCoderunnerDeployment(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    coderunnerId,
-    deploymentId
-  );
+  const label = (name, id) => name?.trim() ? `${name.trim()} (${id})` : id;
+  await confirmAction({
+    summary: [
+      "This will DELETE a deployment. If it is the live one, the service goes offline.",
+      `  workspace:   ${label(workspaceName, ws)}`,
+      `  coderunner:  ${label(target.name ?? target.slug, coderunnerId)}`,
+      `  deployment:  ${deploymentId}${defaulted ? "  (the current live deployment)" : ""}`
+    ],
+    yes: opts.yes,
+    bypassHint: "--yes",
+    question: "Delete this deployment?",
+    io: opts.io
+  });
+  await deleteCoderunnerDeployment(cfg.apiUrl, ws, coderunnerId, deploymentId);
   process.stdout.write(
     `Deleted deployment ${deploymentId} for coderunner ${coderunnerId}
 `
@@ -1337,10 +1431,10 @@ function statusLabel(status) {
 function customerPortalOrigin(apiUrl) {
   try {
     const url = new URL(apiUrl);
-    url.host = url.host.replace(/^platform\./, "app.");
+    url.host = url.host.replace(/^platform\./, "console.");
     return url.origin;
   } catch {
-    return "https://app.groundfloor.cloud";
+    return "https://console.groundfloor.cloud";
   }
 }
 function processLogPortalUrl(portalOrigin, workspaceId, runnerId) {
@@ -1433,6 +1527,34 @@ async function diagnoseDeployFailure(opts) {
 }
 
 // src/commands/logs.ts
+var MAX_LOG_LIMIT = 1e3;
+var MAX_LOG_SINCE_SECONDS = 7 * 24 * 60 * 60;
+var DEFAULT_LOG_LIMIT = 50;
+var DEFAULT_LOG_SINCE_SECONDS = 3600;
+function parseWholeNumber(raw) {
+  return /^\d+$/.test(raw.trim()) ? Number(raw) : Number.NaN;
+}
+function parseLogsWindow(opts) {
+  const limit = opts.limit !== void 0 ? parseWholeNumber(opts.limit) : DEFAULT_LOG_LIMIT;
+  const sinceSeconds = opts.sinceSeconds !== void 0 ? parseWholeNumber(opts.sinceSeconds) : DEFAULT_LOG_SINCE_SECONDS;
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error("Invalid --limit (expected a whole number from 1 to 1000).");
+  }
+  if (limit > MAX_LOG_LIMIT) {
+    throw new Error(
+      `--limit ${limit} is above the maximum of ${MAX_LOG_LIMIT} lines per request.`
+    );
+  }
+  if (!Number.isInteger(sinceSeconds) || sinceSeconds < 10) {
+    throw new Error("Invalid --since-seconds (minimum 10).");
+  }
+  if (sinceSeconds > MAX_LOG_SINCE_SECONDS) {
+    throw new Error(
+      `--since-seconds ${sinceSeconds} is above the maximum of ${MAX_LOG_SINCE_SECONDS} (7 days).`
+    );
+  }
+  return { limit, sinceSeconds };
+}
 async function logsCommand(opts) {
   const cfg = await resolveConfig({ workspaceId: opts.workspace });
   if (!cfg.workspaceId) {
@@ -1445,14 +1567,7 @@ async function logsCommand(opts) {
     cfg.workspaceId,
     opts.coderunner
   );
-  const limit = opts.limit ? Number(opts.limit) : 50;
-  const sinceSeconds = opts.sinceSeconds ? Number(opts.sinceSeconds) : 3600;
-  if (!Number.isFinite(limit) || limit < 1) {
-    throw new Error("Invalid --limit (expected a positive number).");
-  }
-  if (!Number.isFinite(sinceSeconds) || sinceSeconds < 10) {
-    throw new Error("Invalid --since-seconds (minimum 10).");
-  }
+  const { limit, sinceSeconds } = parseLogsWindow(opts);
   const page = await getProcessLogs(cfg.apiUrl, cfg.workspaceId, {
     runner_id: coderunnerId,
     limit,
@@ -1795,8 +1910,36 @@ async function readOptional(filePath) {
     return null;
   }
 }
-async function preflightNodePackage(sourceDir) {
+var NODE_HANDLER_MISSING = "Function/Job/Schedule Node projects need a handler.js exporting `handler` at the project root (or a package.json \"main\" pointing at an existing file). The platform runs a generated /app/main.js that does require('./handler'); `npm start` is not run for these workload types. See the runtime docs for the handler signature.";
+async function exists(filePath) {
+  try {
+    return (await fs3.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+async function hasHandlerEntry(sourceDir) {
+  if (await exists(path4.join(sourceDir, "handler.js"))) return true;
+  const raw = await readOptional(path4.join(sourceDir, "package.json"));
+  if (raw == null) return false;
+  let main2;
+  try {
+    main2 = JSON.parse(raw).main;
+  } catch {
+    throw new Error("package.json is not valid JSON.");
+  }
+  if (typeof main2 !== "string" || !main2.trim()) return false;
+  const resolved = path4.resolve(sourceDir, main2);
+  const rel = path4.relative(sourceDir, resolved);
+  if (rel.startsWith("..") || path4.isAbsolute(rel)) return false;
+  return exists(resolved);
+}
+async function preflightNodePackage(sourceDir, workloadType = "service") {
   const dockerfile = await readOptional(path4.join(sourceDir, "Dockerfile"));
+  if (dockerfile == null && workloadType !== "service") {
+    if (!await hasHandlerEntry(sourceDir)) throw new Error(NODE_HANDLER_MISSING);
+    return;
+  }
   const needsStartScript = dockerfile == null || dockerfileRunsNpmStart(dockerfile);
   if (!needsStartScript) return;
   const raw = await readOptional(path4.join(sourceDir, "package.json"));
@@ -1881,6 +2024,45 @@ function credentialEnvKeys(env) {
   return Object.keys(env).filter((key) => isCredentialEnvKey(key)).sort();
 }
 
+// src/deploy/safety.ts
+function workspaceSource(flag, env = process.env) {
+  if (flag) return "flag";
+  if (env.GROUNDFLOOR_WORKSPACE_ID) return "env";
+  return "saved";
+}
+function labelWithId(name, id) {
+  return name?.trim() ? `${name.trim()} (${id})` : id;
+}
+function savedDefaultRefusal(workspaceLabel) {
+  return `Refusing to deploy to the saved default workspace ${workspaceLabel} without confirmation (no interactive terminal). The saved default is machine-wide state that another terminal can change. Pass -w <workspace-id> (or set GROUNDFLOOR_WORKSPACE_ID) to choose the target explicitly.`;
+}
+function priorEnvKeys(coderunner2) {
+  const manifest = coderunner2.manifest;
+  const keys = manifest?.coderunner?.deploy?.env_keys;
+  return Array.isArray(keys) ? keys.map(String) : [];
+}
+function envRedeployWarning(priorKeys, sentKeys) {
+  const sent = new Set(sentKeys);
+  const missing = priorKeys.filter((k) => !sent.has(k)).sort();
+  const base = 'Environment variable VALUES are not stored by Groundfloor: every deploy must resend them with -e KEY=VALUE or groundfloor.json "env".';
+  if (priorKeys.length > 0) {
+    if (missing.length === 0) return [];
+    return [
+      `WARNING: this deploy does not resend ${missing.length} variable(s) from the previous deployment: ${missing.join(", ")}.`,
+      "  The new deployment will run WITHOUT them. " + base
+    ];
+  }
+  if (sentKeys.length === 0) {
+    return [
+      "WARNING: this deploy sends no environment variables. If the running service has any, the new deployment will run WITHOUT them. " + base
+    ];
+  }
+  return [];
+}
+function credentialEnvMessage(keys) {
+  return `Credential-shaped variable names cannot be passed as --env / groundfloor.json "env": ${keys.join(", ")}. Keep secrets out of deploy variables: store them with \`gf secrets set KEY\` and have the service read them at runtime with an M2M client that has the \`secrets:read\` scope (see \`gf m2m token\`). \`gf deploy --secret KEY\` (injection at deploy time) only works on platforms where secret injection is enabled.`;
+}
+
 // src/commands/deploy.ts
 var FALLBACK_RUNTIMES = /* @__PURE__ */ new Set([
   "python",
@@ -1924,7 +2106,9 @@ function reportFiltering(filtered) {
     log(
       `Excluded ${filtered.excluded.length} credential file(s): ${names(filtered.excluded)}`
     );
-    log("  (use `gf secrets` or `--env KEY=VALUE` to pass values to the app)");
+    log(
+      "  (use `--env KEY=VALUE` for non-secret config; read secrets at runtime via an M2M client with `secrets:read`)"
+    );
   }
   if (filtered.dotfilesIncluded.length) {
     log(
@@ -1932,6 +2116,17 @@ function reportFiltering(filtered) {
     );
   }
 }
+async function environmentLabel(apiUrl, workspaceId, environmentId) {
+  if (typeof environmentId !== "string" || !environmentId) {
+    return "(workspace default)";
+  }
+  try {
+    const envs = await listWorkspaceEnvironments(apiUrl, workspaceId);
+    return labelWithId(envs.find((e) => e.id === environmentId)?.name, environmentId);
+  } catch {
+    return environmentId;
+  }
+}
 async function failDeploy(opts) {
   throw new Error(await diagnoseDeployFailure(opts));
 }
@@ -1946,6 +2141,8 @@ async function deployCommand(opts) {
     );
   }
   const ws = cfg.workspaceId;
+  const source = workspaceSource(opts.workspace);
+  const io = opts.io ?? defaultPromptIO();
   let workspaceName;
   try {
     const workspaces2 = await listWorkspaces(cfg.apiUrl);
@@ -1960,6 +2157,19 @@ async function deployCommand(opts) {
       apiUrl: cfg.apiUrl
     })
   );
+  if (source === "saved") {
+    const target = labelWithId(workspaceName, ws);
+    if (!io.isTTY) {
+      throw new Error(savedDefaultRefusal(target));
+    }
+    await confirmAction({
+      summary: [
+        `No -w/--workspace or GROUNDFLOOR_WORKSPACE_ID given: using the saved default workspace ${target}.`
+      ],
+      question: `Deploy to ${target}?`,
+      io
+    });
+  }
   log(
     opts.git ? `Cloning ${opts.git}${opts.ref ? ` (${opts.ref})` : ""}...` : `Packaging ${path5.resolve(opts.path ?? process.cwd())}...`
   );
@@ -2005,20 +2215,84 @@ async function deployCommand(opts) {
       }
     }
     if (runtime === "node") {
-      await preflightNodePackage(pkg.sourceDir);
+      await preflightNodePackage(pkg.sourceDir, workloadType);
     }
     const schedule = resolveDeploySchedule({
       workloadType,
       flag: opts.schedule,
       manifestSchedule: manifest.schedule
     });
+    const envVariable = {
+      ...manifest.env ?? {},
+      ...parseEnvPairs(opts.env)
+    };
+    if (!opts.skipDeploy) {
+      const plaintextSecrets = credentialEnvKeys(envVariable);
+      if (plaintextSecrets.length) {
+        throw new Error(credentialEnvMessage(plaintextSecrets));
+      }
+    }
+    const injectSecretKeys = (opts.secret ?? []).map((key) => key.trim()).filter(Boolean);
     let coderunnerId = opts.coderunner;
+    if (coderunnerId && !opts.skipDeploy) {
+      try {
+        const known = (await listCoderunners(cfg.apiUrl, ws)).find(
+          (c) => c.id === coderunnerId
+        );
+        if (known) {
+          for (const line of envRedeployWarning(
+            priorEnvKeys(known),
+            Object.keys(envVariable)
+          )) {
+            log(line);
+          }
+        }
+      } catch {
+      }
+    }
+    if (opts.appId && coderunnerId) {
+      log(
+        `WARNING: --app-id ${opts.appId} is IGNORED with --coderunner: it only applies when a new coderunner is created.`
+      );
+    }
     if (!coderunnerId) {
       const name = opts.name ?? manifest.name ?? (opts.git ? nameFromGitUrl(opts.git) : path5.basename(path5.resolve(opts.path ?? process.cwd())));
       const slug = manifest.slug ?? slugify(name);
       const existing = await listCoderunners(cfg.apiUrl, ws);
       const match = existing.find((c) => c.slug === slug || c.name === name);
       if (match) {
+        const lines = [
+          `A coderunner named "${match.name ?? match.slug ?? name}" already exists and will be UPDATED (a new version replaces the live deployment):`,
+          `  name:         ${match.name ?? match.slug ?? name}`,
+          `  id:           ${match.id}`,
+          `  environment:  ${await environmentLabel(cfg.apiUrl, ws, match.environment_id)}`,
+          `  workspace:    ${labelWithId(workspaceName, ws)}`
+        ];
+        if (opts.appId) {
+          lines.push(
+            `WARNING: --app-id ${opts.appId} is IGNORED: it only applies when a new coderunner is created.`
+          );
+        }
+        if (opts.workloadType && match.workload_type && opts.workloadType !== match.workload_type) {
+          lines.push(
+            `WARNING: --workload-type ${opts.workloadType} is ignored; the existing coderunner is ${match.workload_type}.`
+          );
+        }
+        if (!opts.skipDeploy) {
+          lines.push(
+            ...envRedeployWarning(priorEnvKeys(match), Object.keys(envVariable))
+          );
+        }
+        lines.push(
+          "  (pass -c <id> to target a specific coderunner, or -n <name> to create a different one)"
+        );
+        await confirmAction({
+          summary: lines,
+          yes: opts.yes,
+          bypassHint: "--yes",
+          question: "Update this coderunner?",
+          io
+        });
         coderunnerId = match.id;
         log(`Using existing coderunner ${slug} (${coderunnerId})`);
       } else {
@@ -2105,26 +2379,26 @@ async function deployCommand(opts) {
       );
       return;
     }
-    const envVariable = {
-      ...manifest.env ?? {},
-      ...parseEnvPairs(opts.env)
-    };
-    const plaintextSecrets = credentialEnvKeys(envVariable);
-    if (plaintextSecrets.length) {
-      throw new Error(
-        `Do not pass secrets as --env: ${plaintextSecrets.join(", ")}. Store them with \`gf secrets set KEY\` and deploy with \`--secret KEY\`.`
-      );
-    }
-    const injectSecretKeys = (opts.secret ?? []).map((key) => key.trim()).filter(Boolean);
     log("Deploying...");
-    const result = await deployCoderunner(cfg.apiUrl, ws, coderunnerId, {
-      version_id: uploaded.version_id,
-      cpu: opts.cpu ?? manifest.cpu,
-      memory: opts.memory ?? manifest.memory,
-      envVariable: Object.keys(envVariable).length ? envVariable : void 0,
-      schedule,
-      inject_secret_keys: injectSecretKeys.length ? injectSecretKeys : void 0
-    });
+    let result;
+    try {
+      result = await deployCoderunner(cfg.apiUrl, ws, coderunnerId, {
+        version_id: uploaded.version_id,
+        cpu: opts.cpu ?? manifest.cpu,
+        memory: opts.memory ?? manifest.memory,
+        envVariable: Object.keys(envVariable).length ? envVariable : void 0,
+        schedule,
+        inject_secret_keys: injectSecretKeys.length ? injectSecretKeys : void 0
+      });
+    } catch (err) {
+      if (err instanceof CpError && err.status === 422 && injectSecretKeys.length) {
+        throw new Error(
+          `${err.message}
+--secret only works where the platform has secret injection enabled. Otherwise read the secret at runtime with an M2M client that has the \`secrets:read\` scope (see \`gf m2m token\`).`
+        );
+      }
+      throw err;
+    }
     log("Waiting for deployment...");
     const deployDeadline = Date.now() + DEPLOY_POLL_TIMEOUT_MS;
     let deployOk = false;
@@ -2221,11 +2495,6 @@ async function runCommand(opts) {
     coderunnerId,
     payload
   );
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
-    return;
-  }
   process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
 }
@@ -2269,903 +2538,887 @@ async function statusCommand(opts) {
     process.stdout.write(`deployment:  ${deployment.id ?? "\u2014"} [${deployment.status}]
 `);
   }
-  process.stdout.write(`
-${JSON.stringify(out, null, 2)}
-`);
 }
 
-// src/commands/domains.ts
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function resolve(opts) {
-  const cfg = await resolveConfig({ workspaceId: opts.workspace });
-  if (!cfg.workspaceId) {
-    throw new Error(
-      "No workspace selected. Run `gf workspaces use <id>` or pass --workspace <id>."
-    );
-  }
-  const ref = opts.coderunner;
-  if (!ref) {
-    throw new Error(
-      "Specify the coderunner with --coderunner <id|slug>."
-    );
-  }
-  let coderunnerId = ref;
-  if (!UUID_RE.test(ref)) {
-    const all = await listCoderunners(cfg.apiUrl, cfg.workspaceId);
-    const match = all.find((c) => c.slug === ref || c.name === ref);
-    if (!match) {
-      throw new Error(`No coderunner matching "${ref}" in this workspace.`);
-    }
-    coderunnerId = match.id;
-  }
-  return {
-    apiUrl: cfg.apiUrl,
-    workspaceId: cfg.workspaceId,
-    coderunnerId
-  };
+// src/commands/apps.ts
+import { promises as fs5 } from "fs";
+import path6 from "path";
+
+// src/release-zip.ts
+import AdmZip2 from "adm-zip";
+var REMOTE_ENTRY = "remoteEntry.js";
+var FLATTEN_SUFFIXES = [".js", ".mjs", ".cjs", ".css", ".map", ".wasm"];
+var IMPORT_ASSETS = /(__federation_import|import)\((['"])\.\/assets\//g;
+function rewriteRemoteEntryAssetPrefix(source) {
+  return source.replace(IMPORT_ASSETS, "$1($2./");
 }
-function printInstructions(item) {
-  const out = process.stdout;
-  out.write(`
-Added ${item.domain} (status: ${item.status})
-`);
-  out.write("\nCreate these DNS records at your registrar:\n");
-  if (item.cname_target) {
-    out.write(`  CNAME  ${item.domain}  \u2192  ${item.cname_target}
-`);
-  }
-  if (item.verification_record) {
-    const r = item.verification_record;
-    out.write(`  ${r.type}    ${r.name}  =  ${r.value}
-`);
-  }
-  out.write(`
-Then run:  gf domains verify ${item.domain} --coderunner <id|slug>
-`);
+function normalizeZipEntryName(filename) {
+  return filename.replace(/\\/g, "/").replace(/^\/+/, "");
 }
-async function domainsAddCommand(domain, opts) {
-  const { apiUrl, workspaceId, coderunnerId } = await resolve(opts);
-  const item = await addDomain(apiUrl, workspaceId, coderunnerId, domain);
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(item, null, 2)}
-`);
-    return;
-  }
-  printInstructions(item);
+function parentDir(rel) {
+  const i = rel.lastIndexOf("/");
+  return i === -1 ? "" : rel.slice(0, i);
 }
-async function domainsListCommand(opts) {
-  const { apiUrl, workspaceId, coderunnerId } = await resolve(opts);
-  const result = await listDomains(apiUrl, workspaceId, coderunnerId);
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(result.domains, null, 2)}
-`);
-    return;
-  }
-  if (result.domains.length === 0) {
-    process.stdout.write("No custom domains.\n");
-    return;
-  }
-  for (const d of result.domains) {
-    const target = d.cname_target ? ` \u2192 ${d.cname_target}` : "";
-    process.stdout.write(`${d.domain}  [${d.status}]${target}
-`);
-  }
+function basename(rel) {
+  const i = rel.lastIndexOf("/");
+  return i === -1 ? rel : rel.slice(i + 1);
 }
-async function domainsRemoveCommand(domain, opts) {
-  const { apiUrl, workspaceId, coderunnerId } = await resolve(opts);
-  await removeDomain(apiUrl, workspaceId, coderunnerId, domain);
-  process.stdout.write(`Removed ${domain}
-`);
+function chooseRemoteEntry(relpaths) {
+  const entries = relpaths.filter(
+    (p) => p === REMOTE_ENTRY || p.endsWith(`/${REMOTE_ENTRY}`)
+  );
+  if (entries.length === 0) return void 0;
+  if (entries.includes(REMOTE_ENTRY)) return REMOTE_ENTRY;
+  return [...entries].sort((a, b) => {
+    const score = (p) => {
+      const parts = p.split("/");
+      const inAssets = parts.length >= 2 && parts[parts.length - 2] === "assets";
+      return `${inAssets ? 0 : 1}:${parts.length}:${p}`;
+    };
+    return score(a).localeCompare(score(b));
+  })[0];
 }
-async function domainsVerifyCommand(domain, opts) {
-  const { apiUrl, workspaceId, coderunnerId } = await resolve(opts);
-  const result = await verifyDomain(apiUrl, workspaceId, coderunnerId, domain);
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
-`);
-    return;
+function flattenFederatedBundlePlan(relpaths) {
+  const paths2 = relpaths.map(normalizeZipEntryName).filter((name) => name && !name.endsWith("/") && !name.split("/").includes(".."));
+  const pathset = new Set(paths2);
+  const entry = chooseRemoteEntry([...pathset]);
+  if (!entry) return {};
+  const promoteDirs = /* @__PURE__ */ new Set();
+  const entryDir = parentDir(entry);
+  if (entryDir) promoteDirs.add(entryDir);
+  for (const path11 of pathset) {
+    const parent = parentDir(path11);
+    if (parent === "assets" || parent.endsWith("/assets") && parent.split("/").length - 1 < 2) {
+      promoteDirs.add(parent);
+    }
   }
-  const mark = result.verified ? "verified" : "not verified";
-  process.stdout.write(`${result.domain}: ${mark} [${result.status}]
-`);
-  process.stdout.write(`${result.detail}
-`);
-  if (!result.verified) {
-    process.exitCode = 1;
+  const destToSrc = {};
+  for (const src of paths2) {
+    const parent = parentDir(src);
+    if (!promoteDirs.has(parent)) continue;
+    const dest = basename(src);
+    if (dest === "release.zip") continue;
+    const lower = dest.toLowerCase();
+    if (dest !== REMOTE_ENTRY && !FLATTEN_SUFFIXES.some((ext) => lower.endsWith(ext))) {
+      continue;
+    }
+    if (pathset.has(dest)) continue;
+    const prev = destToSrc[dest];
+    if (prev === void 0 || src.split("/").length < prev.split("/").length) {
+      destToSrc[dest] = src;
+    }
+  }
+  return destToSrc;
+}
+function flattenFederatedReleaseZip(bytes) {
+  const zip = new AdmZip2(bytes);
+  const rels = [];
+  const byNorm = /* @__PURE__ */ new Map();
+  for (const entry of zip.getEntries()) {
+    if (entry.isDirectory) continue;
+    const name = normalizeZipEntryName(entry.entryName);
+    rels.push(name);
+    byNorm.set(name, entry);
+  }
+  const plan = flattenFederatedBundlePlan(rels);
+  const keys = Object.keys(plan);
+  if (keys.length > 0) {
+    for (const dest of keys) {
+      const src = plan[dest];
+      const source = byNorm.get(src);
+      if (!source) continue;
+      zip.addFile(dest, source.getData());
+    }
+  }
+  rewriteRemoteEntryInZip(zip);
+  return zip.toBuffer();
+}
+function rewriteRemoteEntryInZip(zip) {
+  const names2 = zip.getEntries().filter((entry) => !entry.isDirectory).map((entry) => normalizeZipEntryName(entry.entryName));
+  const entryRel = chooseRemoteEntry(names2);
+  if (!entryRel) return;
+  const zipEntry = zip.getEntries().find((item) => {
+    if (item.isDirectory) return false;
+    return normalizeZipEntryName(item.entryName) === entryRel;
+  });
+  if (!zipEntry) return;
+  const before = zipEntry.getData().toString("utf8");
+  const after = rewriteRemoteEntryAssetPrefix(before);
+  if (after === before) return;
+  zip.updateFile(zipEntry.entryName, Buffer.from(after, "utf8"));
+}
+function federatedReleaseZipHint(slug) {
+  return `Run \`npm run release\` in a kit from \`gf apps init\`, then publish that zip (do not zip Vite dist/ or upload only remoteEntry.js). ${initThenPublishHint(slug)}`;
+}
+function federationRemoteName(appId) {
+  const sanitized = appId.replace(/[^a-zA-Z0-9_$]/g, "_");
+  return sanitized.length > 0 ? sanitized : "federatedApp";
+}
+function initThenPublishHint(slug) {
+  const s = (slug ?? "").trim() || "<portal-slug>";
+  return `gf apps init --slug ${s} && cd ${s} && npm install && npm run release && gf apps publish --path release.zip`;
+}
+function extractReferencedSiblings(remoteEntrySource) {
+  const names2 = /* @__PURE__ */ new Set();
+  for (const match of remoteEntrySource.matchAll(
+    /["']\.\/(?:assets\/)?([^"'/]+\.(?:js|mjs|cjs|css))["']/g
+  )) {
+    if (match[1] !== REMOTE_ENTRY) names2.add(match[1]);
+  }
+  for (const match of remoteEntrySource.matchAll(
+    /["']([A-Za-z0-9._-]+\.css)["']/g
+  )) {
+    names2.add(match[1]);
+  }
+  return [...names2];
+}
+function extractFederationScope(remoteEntrySource) {
+  return remoteEntrySource.match(/css__([A-Za-z0-9_-]+)__/)?.[1];
+}
+function zipRootNames(bytes) {
+  const zip = new AdmZip2(bytes);
+  return zip.getEntries().filter((entry) => !entry.isDirectory).map((entry) => normalizeZipEntryName(entry.entryName));
+}
+function readZipFile(bytes, rel) {
+  const zip = new AdmZip2(bytes);
+  const entry = zip.getEntries().find((item) => {
+    if (item.isDirectory) return false;
+    return normalizeZipEntryName(item.entryName) === rel;
+  });
+  return entry ? entry.getData().toString("utf8") : void 0;
+}
+function assertFederatedReleaseZip(bytes, slug) {
+  const hint = initThenPublishHint(slug);
+  const names2 = zipRootNames(bytes);
+  const present = new Set(names2.map((name) => basename(name)));
+  const entryRel = chooseRemoteEntry(names2);
+  if (!entryRel) {
+    throw new Error(`Zip has no remoteEntry.js. ${hint}`);
+  }
+  const source = readZipFile(bytes, entryRel);
+  if (!source) {
+    throw new Error(`Zip has no remoteEntry.js. ${hint}`);
+  }
+  const siblings = extractReferencedSiblings(source);
+  const missing = siblings.filter((name) => !present.has(name));
+  const jsOrCssAtRoot = names2.filter((name) => {
+    if (name.includes("/")) return false;
+    const lower = name.toLowerCase();
+    return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".css");
+  });
+  if (missing.length > 0 || siblings.length === 0 && jsOrCssAtRoot.length < 2) {
+    const detail = missing.length > 0 ? `Missing next to remoteEntry.js: ${missing.join(", ")}.` : "Zip is only remoteEntry.js (Vite chunks were never packed).";
+    throw new Error(
+      `${detail} Do not zip dist/ or upload a lone remoteEntry.js. ${hint}`
+    );
+  }
+  const scope = extractFederationScope(source);
+  if (slug && scope) {
+    const expected = federationRemoteName(slug);
+    if (scope !== expected) {
+      throw new Error(
+        `Federation name is "${scope}" but Shell looks up "${expected}" (from slug ${slug}). Use the starter-kit vite.config (federationRemoteName). ${hint}`
+      );
+    }
   }
 }
 
-// src/commands/secrets.ts
-async function readValue(value) {
-  if (value === void 0) {
-    throw new Error("Pass a value, or `-` to read from stdin.");
+// src/commands/apps.ts
+import AdmZip3 from "adm-zip";
+var MAX_RELEASE_BYTES = 32 * 1024 * 1024;
+function slugify2(input) {
+  const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "app";
+}
+function formatApp(app) {
+  return `${app.id}  ${app.name ?? app.slug ?? ""}  ${app.app_kind ?? ""}  [${app.status ?? ""}]`;
+}
+async function readJsonObject(filePath) {
+  const raw = await fs5.readFile(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`${filePath} must contain a JSON object`);
   }
-  if (value === "-") {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(Buffer.from(chunk));
+  return parsed;
+}
+async function maybeReadManifest(filePath) {
+  if (!filePath) return void 0;
+  return readJsonObject(path6.resolve(filePath));
+}
+async function findSiblingManifest(bundlePath) {
+  const dir = await isDirectory(bundlePath) ? bundlePath : path6.dirname(bundlePath);
+  const candidate = path6.join(dir, "groundfloor.manifest.json");
+  try {
+    await fs5.access(candidate);
+  } catch {
+    return void 0;
+  }
+  return { path: candidate, manifest: await readJsonObject(candidate) };
+}
+function zipHasRemoteEntry(bytes) {
+  const zip = new AdmZip3(bytes);
+  return zip.getEntries().some((entry) => {
+    if (entry.isDirectory) return false;
+    const name = normalizeZipEntryName(entry.entryName);
+    return name === REMOTE_ENTRY || name.endsWith(`/${REMOTE_ENTRY}`);
+  });
+}
+function prepareReleaseZip(bytes, slug) {
+  if (!zipHasRemoteEntry(bytes)) {
+    throw new Error(
+      `Zip has no remoteEntry.js. ${initThenPublishHint(slug)}`
+    );
+  }
+  const flattened = flattenFederatedReleaseZip(bytes);
+  const plan = flattenFederatedBundlePlan(
+    new AdmZip3(bytes).getEntries().filter((e) => !e.isDirectory).map((e) => normalizeZipEntryName(e.entryName))
+  );
+  if (Object.keys(plan).length > 0) {
+    process.stderr.write(
+      `Note: flattened Vite dist/assets layout so chunks sit next to remoteEntry.js.
+Prefer: ${federatedReleaseZipHint(slug)}
+`
+    );
+  }
+  assertFederatedReleaseZip(flattened, slug);
+  return flattened;
+}
+async function isDirectory(filePath) {
+  try {
+    return (await fs5.stat(filePath)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function resolveAppId(apiUrl, workspaceId, idOrSlug) {
+  const listed = await listApps(apiUrl, workspaceId);
+  const match = listed.apps.find(
+    (app) => app.id === idOrSlug || app.slug === idOrSlug
+  );
+  if (match) return match;
+  try {
+    return await getApp(apiUrl, workspaceId, idOrSlug);
+  } catch (err) {
+    if (err instanceof CpError && err.status === 404) {
+      throw new Error(
+        `App not found: ${idOrSlug}. Run \`gf apps ls\` or \`gf apps create\`.`
+      );
     }
-    return Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
+    throw err;
   }
-  return value;
 }
-async function secretsListCommand(opts) {
+async function appsListCommand(opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const data = await listSecrets(cfg.apiUrl, cfg.workspaceId, opts.environment);
+  const data = await listApps(cfg.apiUrl, cfg.workspaceId);
   if (opts.json) {
     process.stdout.write(`${JSON.stringify(data, null, 2)}
 `);
     return;
   }
-  if (data.secrets.length === 0) {
-    process.stdout.write("No secrets in this workspace.\n");
+  if (data.apps.length === 0) {
+    process.stdout.write("No apps in this workspace.\n");
     return;
   }
-  for (const secret of data.secrets) {
-    process.stdout.write(`${secret.key}
+  for (const app of data.apps) {
+    process.stdout.write(`${formatApp(app)}
 `);
   }
 }
-async function secretsGetCommand(key, opts) {
+async function appsGetCommand(appId, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const secret = await getSecret(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    key,
-    opts.environment
-  );
+  const app = await resolveAppId(cfg.apiUrl, cfg.workspaceId, appId);
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(secret, null, 2)}
+    process.stdout.write(`${JSON.stringify(app, null, 2)}
 `);
     return;
   }
-  process.stdout.write(`${secret.value}
+  process.stdout.write(`${formatApp(app)}
 `);
 }
-async function secretsSetCommand(key, value, opts) {
+async function appsCreateCommand(opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const resolved = await readValue(value);
-  const saved = await putSecret(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    key,
-    { value: resolved, description: opts.description },
-    opts.environment
-  );
-  process.stdout.write(`Saved secret ${saved.key}
-`);
-}
-async function secretsRmCommand(key, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  await deleteSecret(cfg.apiUrl, cfg.workspaceId, key, opts.environment);
-  process.stdout.write(`Deleted secret ${key}
-`);
-}
-
-// src/commands/flags.ts
-var VALUE_TYPES = [
-  "boolean",
-  "string",
-  "number",
-  "json"
-];
-var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-function matchEnvironment(environments2, idOrName) {
-  const wanted = idOrName.trim();
-  const byId = environments2.find((env) => env.id === wanted);
-  if (byId) return byId.id;
-  const byName = environments2.filter(
-    (env) => env.name.toLowerCase() === wanted.toLowerCase()
-  );
-  if (byName.length === 1) return byName[0].id;
-  const names2 = environments2.map((env) => env.name).join(", ") || "none";
-  throw new Error(
-    `Environment "${wanted}" not found in this workspace (have: ${names2}). Run \`gf environments ls\`.`
-  );
-}
-async function resolveEnvironment(apiUrl, workspaceId, idOrName) {
-  if (!idOrName) return void 0;
-  if (UUID_RE2.test(idOrName.trim())) return idOrName.trim();
-  const environments2 = await listWorkspaceEnvironments(apiUrl, workspaceId);
-  return matchEnvironment(environments2, idOrName);
-}
-function parseFlagValue(raw, type) {
-  if (type !== void 0 && !VALUE_TYPES.includes(type)) {
-    throw new Error(`--type must be one of: ${VALUE_TYPES.join(", ")}`);
+  const kindRaw = (opts.kind ?? "shell_federated").trim();
+  if (kindRaw === "coderunner") {
+    throw new Error(
+      "Do not create app_kind=coderunner. Deploy workloads with `gf deploy`. Use --kind shell_federated or --kind standalone."
+    );
   }
-  const lower = raw.trim().toLowerCase();
-  const valueType = type ?? (lower === "true" || lower === "false" ? "boolean" : raw.trim() !== "" && Number.isFinite(Number(raw)) ? "number" : "string");
-  switch (valueType) {
-    case "boolean":
-      if (lower !== "true" && lower !== "false") {
-        throw new Error("boolean flags take true or false");
-      }
-      return { value: lower === "true", value_type: "boolean" };
-    case "number": {
-      const n = Number(raw);
-      if (raw.trim() === "" || !Number.isFinite(n)) {
-        throw new Error(`"${raw}" is not a number`);
-      }
-      return { value: n, value_type: "number" };
+  if (kindRaw !== "shell_federated" && kindRaw !== "standalone") {
+    throw new Error(
+      `--kind must be shell_federated or standalone (got ${kindRaw})`
+    );
+  }
+  const kind = kindRaw;
+  const localManifest = await maybeReadManifest(opts.manifest);
+  const name = opts.name?.trim() || (typeof localManifest?.name === "string" ? localManifest.name : "");
+  const slug = opts.slug?.trim() || (typeof localManifest?.appId === "string" ? localManifest.appId : name ? slugify2(name) : "");
+  if (!name) {
+    throw new Error("Pass --name, or a manifest with a name field.");
+  }
+  if (!slug) {
+    throw new Error("Pass --slug, or a manifest with appId.");
+  }
+  if (kind === "standalone" && !opts.primaryCoderunner?.trim()) {
+    throw new Error(
+      "Standalone apps require --primary-coderunner <id> (an existing service coderunner)."
+    );
+  }
+  const body = {
+    name,
+    slug,
+    app_kind: kind
+  };
+  if (opts.environment) body.environment_id = opts.environment;
+  if (opts.primaryCoderunner) {
+    body.primary_coderunner_id = opts.primaryCoderunner;
+  }
+  if (localManifest) body.manifest = localManifest;
+  let app;
+  try {
+    app = await createApp(cfg.apiUrl, cfg.workspaceId, body);
+  } catch (err) {
+    if (err instanceof CpError && err.status === 409) {
+      throw new Error(
+        `App slug ${slug} already exists. Init the kit if you do not have it, then publish:
+  ${initThenPublishHint(slug)}`
+      );
     }
-    case "json":
-      try {
-        return { value: JSON.parse(raw), value_type: "json" };
-      } catch {
-        throw new Error("--type json needs a valid JSON value");
-      }
-    default:
-      return { value: raw, value_type: "string" };
+    throw err;
   }
-}
-function formatValue(value) {
-  return typeof value === "string" ? value : JSON.stringify(value);
-}
-async function flagsListCommand(opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const env = await resolveEnvironment(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    opts.environment
-  );
-  const data = await listFlags(cfg.apiUrl, cfg.workspaceId, env);
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(data, null, 2)}
+    process.stdout.write(`${JSON.stringify(app, null, 2)}
 `);
     return;
   }
-  process.stderr.write(`environment ${data.environment_id}
+  process.stdout.write(`Created ${formatApp(app)}
 `);
-  if (data.flags.length === 0) {
-    process.stdout.write("No flags in this environment.\n");
-    return;
-  }
-  for (const flag of data.flags) {
+  if (kind === "shell_federated") {
     process.stdout.write(
-      `${flag.key}	${flag.value_type}	${formatValue(flag.value)}
+      `Next:
+  gf apps init --slug ${slug}
+  cd ${slug} && npm install && npm run release
+  gf apps publish --path release.zip
+Do not scaffold src/App.tsx from scratch \u2014 BrowserRouter in App.tsx crashes the Shell.
 `
     );
   }
 }
-async function flagsGetCommand(key, opts) {
+async function appsPublishCommand(appRef, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const env = await resolveEnvironment(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    opts.environment
-  );
-  const flag = await getFlag(cfg.apiUrl, cfg.workspaceId, key, env);
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(flag, null, 2)}
-`);
-    return;
+  const inputPath = path6.resolve(opts.path ?? "release.zip");
+  const bundlePath = await isDirectory(inputPath) ? path6.join(inputPath, "release.zip") : inputPath;
+  let bytes;
+  try {
+    bytes = await fs5.readFile(bundlePath);
+  } catch {
+    throw new Error(
+      `No bundle at ${bundlePath}. ${initThenPublishHint()}`
+    );
   }
-  process.stdout.write(`${formatValue(flag.value)}
-`);
-}
-async function flagsSetCommand(key, value, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const env = await resolveEnvironment(
+  if (bytes.byteLength === 0) {
+    throw new Error(`Bundle is empty: ${bundlePath}`);
+  }
+  if (bytes.byteLength > MAX_RELEASE_BYTES) {
+    throw new Error(
+      `Bundle exceeds ${MAX_RELEASE_BYTES} bytes (${bytes.byteLength}).`
+    );
+  }
+  const sibling = await findSiblingManifest(bundlePath);
+  const ref = appRef?.trim() || opts.app?.trim() || (typeof sibling?.manifest.appId === "string" ? sibling.manifest.appId : "");
+  if (!ref) {
+    throw new Error(
+      "Pass an app id or slug, or set appId in groundfloor.manifest.json next to the bundle."
+    );
+  }
+  const app = await resolveAppId(cfg.apiUrl, cfg.workspaceId, ref);
+  if (app.app_kind && app.app_kind !== "shell_federated") {
+    throw new Error(
+      `Releases are only for shell_federated apps (this app is ${app.app_kind}). Use \`gf deploy\` for coderunner workloads.`
+    );
+  }
+  const ext = path6.extname(bundlePath).toLowerCase();
+  const isZip = ext === ".zip";
+  if (!isZip) {
+    throw new Error(
+      `Publish release.zip from \`npm run release\`, not a lone ${path6.basename(bundlePath)}. ` + initThenPublishHint(app.slug)
+    );
+  }
+  bytes = prepareReleaseZip(bytes, app.slug);
+  const bundle = "zip";
+  const contentType = "application/zip";
+  if (opts.syncManifest !== false && sibling) {
+    await patchApp(cfg.apiUrl, cfg.workspaceId, app.id, {
+      manifest: sibling.manifest
+    });
+  }
+  const init = await initAppReleaseUpload(cfg.apiUrl, cfg.workspaceId, app.id, {
+    bundle,
+    label: opts.label,
+    // Required since wave 5: the server pins this into the presigned PUT and
+    // checks it against the quota before minting a URL. Omitting it is a 422.
+    size_bytes: bytes.byteLength
+  });
+  await uploadAppReleaseContent(
     cfg.apiUrl,
     cfg.workspaceId,
-    opts.environment
+    app.id,
+    init.release.id,
+    bytes,
+    contentType
   );
-  const parsed = parseFlagValue(value, opts.type);
-  const saved = await putFlag(
+  const release = await finalizeAppRelease(
     cfg.apiUrl,
     cfg.workspaceId,
-    key,
-    { ...parsed, description: opts.description },
-    env
+    app.id,
+    init.release.id
   );
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(saved, null, 2)}
+    process.stdout.write(`${JSON.stringify({ app, release }, null, 2)}
 `);
     return;
   }
   process.stdout.write(
-    `Set ${saved.key} = ${formatValue(saved.value)} (${saved.value_type}) in environment ${saved.environment_id}
-`
-  );
-}
-async function flagsRmCommand(key, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const env = await resolveEnvironment(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    opts.environment
+    `Published ${app.slug ?? app.id}  build ${release.build_number}` + (release.remote_url ? `  ${release.remote_url}` : "") + "\n"
   );
-  await deleteFlag(cfg.apiUrl, cfg.workspaceId, key, env);
-  process.stdout.write(`Deleted flag ${key}
-`);
 }
-async function flagsCompareCommand(source, target, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const [src, tgt] = await Promise.all([
-    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
-    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
-  ]);
-  const data = await compareFlags(cfg.apiUrl, cfg.workspaceId, src, tgt);
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(data, null, 2)}
-`);
-    return;
-  }
-  if (data.keys.length === 0) {
-    process.stdout.write("No flags in either environment.\n");
-    return;
+
+// src/commands/domains.ts
+var DOMAINS_APPS_ONLY = "Custom domains are available on Apps (standalone / service apps), not on standalone coderunners. Wrap the service coderunner with `gf apps create --kind standalone --primary-coderunner <id>`, then use `gf domains ... --app <id|slug>`.";
+async function resolve(opts) {
+  const cfg = await resolveConfig({ workspaceId: opts.workspace });
+  if (!cfg.workspaceId) {
+    throw new Error(
+      "No workspace selected. Run `gf workspaces use <id>` or pass --workspace <id>."
+    );
   }
-  for (const row of data.keys) {
-    process.stdout.write(
-      `${row.key}	${row.status}	${formatValue(row.source_value ?? null)} \u2192 ${formatValue(row.target_value ?? null)}
-`
+  if (!opts.app) {
+    throw new Error(
+      opts.coderunner ? `--coderunner is no longer supported for domains. ${DOMAINS_APPS_ONLY}` : "Specify the app with --app <id|slug>. " + DOMAINS_APPS_ONLY
     );
   }
+  const app = await resolveAppId(cfg.apiUrl, cfg.workspaceId, opts.app);
+  return { apiUrl: cfg.apiUrl, workspaceId: cfg.workspaceId, appId: app.id };
 }
-async function flagsPromoteCommand(source, target, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const [src, tgt] = await Promise.all([
-    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
-    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
-  ]);
-  const keys = opts.keys?.split(",").map((k) => k.trim()).filter(Boolean);
-  const result = await promoteFlags(cfg.apiUrl, cfg.workspaceId, {
-    source_environment_id: src,
-    target_environment_id: tgt,
-    keys: keys && keys.length > 0 ? keys : void 0,
-    mode: opts.overwrite ? "overwrite" : "skip_existing",
-    dry_run: Boolean(opts.dryRun)
-  });
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify(result, null, 2)}
+function printInstructions(item) {
+  const out = process.stdout;
+  out.write(`
+Added ${item.domain} (status: ${item.status})
 `);
-    return;
-  }
-  const prefix = result.dry_run ? "[dry run] " : "";
-  process.stdout.write(
-    `${prefix}copied: ${result.copied.join(", ") || "none"}
-${prefix}skipped (already set; use --overwrite): ${result.skipped.join(", ") || "none"}
-`
-  );
-  for (const failure of result.failed) {
-    process.stdout.write(`${prefix}failed: ${failure.key} \u2014 ${failure.error}
+  out.write("\nCreate these DNS records at your registrar:\n");
+  if (item.cname_target) {
+    out.write(`  CNAME  ${item.domain}  \u2192  ${item.cname_target}
 `);
   }
-  if (result.failed.length > 0) {
-    process.exitCode = 1;
+  if (item.verification_record) {
+    const r = item.verification_record;
+    out.write(`  ${r.type}    ${r.name}  =  ${r.value}
+`);
   }
+  out.write(`
+Then run:  gf domains verify ${item.domain} --app <id|slug>
+`);
 }
-
-// src/commands/files.ts
-import { promises as fs5 } from "fs";
-import path6 from "path";
-function guessContentType(filename) {
-  const ext = path6.extname(filename).toLowerCase();
-  const types = {
-    ".json": "application/json",
-    ".txt": "text/plain",
-    ".csv": "text/csv",
-    ".pdf": "application/pdf",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".zip": "application/zip"
-  };
-  return types[ext] ?? "application/octet-stream";
+async function domainsAddCommand(domain, opts) {
+  const { apiUrl, workspaceId, appId } = await resolve(opts);
+  const item = await addDomain(apiUrl, workspaceId, appId, domain);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(item, null, 2)}
+`);
+    return;
+  }
+  printInstructions(item);
 }
-async function filesListCommand(opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const data = await listFiles(cfg.apiUrl, cfg.workspaceId);
+async function domainsListCommand(opts) {
+  const { apiUrl, workspaceId, appId } = await resolve(opts);
+  const result = await listDomains(apiUrl, workspaceId, appId);
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(data, null, 2)}
+    process.stdout.write(`${JSON.stringify(result.domains, null, 2)}
 `);
     return;
   }
-  if (data.files.length === 0) {
-    process.stdout.write("No files in this workspace.\n");
+  if (result.domains.length === 0) {
+    process.stdout.write("No custom domains.\n");
     return;
   }
-  for (const file of data.files) {
-    const size = file.size_bytes != null ? `${file.size_bytes}B` : "";
-    process.stdout.write(
-      `${file.id}  ${file.name ?? ""}  ${size}  [${file.status ?? ""}]
-`
-    );
+  for (const d of result.domains) {
+    const target = d.cname_target ? ` \u2192 ${d.cname_target}` : "";
+    process.stdout.write(`${d.domain}  [${d.status}]${target}
+`);
   }
 }
-async function filesUploadCommand(filePath, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const resolved = path6.resolve(filePath);
-  const buf = await fs5.readFile(resolved);
-  const name = opts.name ?? path6.basename(resolved);
-  const contentType = guessContentType(name);
-  const init = await initFileUpload(cfg.apiUrl, cfg.workspaceId, {
-    name,
-    content_type: contentType,
-    size_bytes: buf.byteLength
-  });
-  const put = await fetch(init.upload_url, {
-    method: "PUT",
-    headers: { "Content-Type": contentType },
-    body: buf
-  });
-  if (!put.ok) {
-    throw new Error(
-      `Upload to object storage failed: ${put.status} ${put.statusText}`
-    );
-  }
-  const file = await finalizeFileUpload(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    init.file.id
-  );
-  process.stdout.write(`Uploaded ${file.id}  ${file.name ?? name}
+async function domainsRemoveCommand(domain, opts) {
+  const { apiUrl, workspaceId, appId } = await resolve(opts);
+  await removeDomain(apiUrl, workspaceId, appId, domain);
+  process.stdout.write(`Removed ${domain}
 `);
 }
-async function filesDownloadCommand(fileId, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const { download_url: url } = await getFileDownloadUrl(
-    cfg.apiUrl,
-    cfg.workspaceId,
-    fileId
-  );
-  const res = await fetch(url);
-  if (!res.ok) {
-    throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+async function domainsVerifyCommand(domain, opts) {
+  const { apiUrl, workspaceId, appId } = await resolve(opts);
+  const result = await verifyDomain(apiUrl, workspaceId, appId, domain);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    return;
   }
-  const buf = Buffer.from(await res.arrayBuffer());
-  const dest = path6.resolve(opts.out ?? fileId);
-  await fs5.writeFile(dest, buf);
-  process.stdout.write(`Wrote ${dest}
+  const mark = result.verified ? "verified" : "not verified";
+  process.stdout.write(`${result.domain}: ${mark} [${result.status}]
 `);
-}
-async function filesRmCommand(fileId, opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  await deleteFile(cfg.apiUrl, cfg.workspaceId, fileId);
-  process.stdout.write(`Deleted file ${fileId}
+  process.stdout.write(`${result.detail}
 `);
-}
-
-// src/commands/apps.ts
-import { promises as fs6 } from "fs";
-import path7 from "path";
-
-// src/release-zip.ts
-import AdmZip2 from "adm-zip";
-var REMOTE_ENTRY = "remoteEntry.js";
-var FLATTEN_SUFFIXES = [".js", ".mjs", ".cjs", ".css", ".map", ".wasm"];
-var IMPORT_ASSETS = /(__federation_import|import)\((['"])\.\/assets\//g;
-function rewriteRemoteEntryAssetPrefix(source) {
-  return source.replace(IMPORT_ASSETS, "$1($2./");
-}
-function normalizeZipEntryName(filename) {
-  return filename.replace(/\\/g, "/").replace(/^\/+/, "");
-}
-function parentDir(rel) {
-  const i = rel.lastIndexOf("/");
-  return i === -1 ? "" : rel.slice(0, i);
-}
-function basename(rel) {
-  const i = rel.lastIndexOf("/");
-  return i === -1 ? rel : rel.slice(i + 1);
-}
-function chooseRemoteEntry(relpaths) {
-  const entries = relpaths.filter(
-    (p) => p === REMOTE_ENTRY || p.endsWith(`/${REMOTE_ENTRY}`)
-  );
-  if (entries.length === 0) return void 0;
-  if (entries.includes(REMOTE_ENTRY)) return REMOTE_ENTRY;
-  return [...entries].sort((a, b) => {
-    const score = (p) => {
-      const parts = p.split("/");
-      const inAssets = parts.length >= 2 && parts[parts.length - 2] === "assets";
-      return `${inAssets ? 0 : 1}:${parts.length}:${p}`;
-    };
-    return score(a).localeCompare(score(b));
-  })[0];
-}
-function flattenFederatedBundlePlan(relpaths) {
-  const paths2 = relpaths.map(normalizeZipEntryName).filter((name) => name && !name.endsWith("/") && !name.split("/").includes(".."));
-  const pathset = new Set(paths2);
-  const entry = chooseRemoteEntry([...pathset]);
-  if (!entry) return {};
-  const promoteDirs = /* @__PURE__ */ new Set();
-  const entryDir = parentDir(entry);
-  if (entryDir) promoteDirs.add(entryDir);
-  for (const path11 of pathset) {
-    const parent = parentDir(path11);
-    if (parent === "assets" || parent.endsWith("/assets") && parent.split("/").length - 1 < 2) {
-      promoteDirs.add(parent);
-    }
-  }
-  const destToSrc = {};
-  for (const src of paths2) {
-    const parent = parentDir(src);
-    if (!promoteDirs.has(parent)) continue;
-    const dest = basename(src);
-    if (dest === "release.zip") continue;
-    const lower = dest.toLowerCase();
-    if (dest !== REMOTE_ENTRY && !FLATTEN_SUFFIXES.some((ext) => lower.endsWith(ext))) {
-      continue;
-    }
-    if (pathset.has(dest)) continue;
-    const prev = destToSrc[dest];
-    if (prev === void 0 || src.split("/").length < prev.split("/").length) {
-      destToSrc[dest] = src;
-    }
+  if (!result.verified) {
+    process.exitCode = 1;
   }
-  return destToSrc;
 }
-function flattenFederatedReleaseZip(bytes) {
-  const zip = new AdmZip2(bytes);
-  const rels = [];
-  const byNorm = /* @__PURE__ */ new Map();
-  for (const entry of zip.getEntries()) {
-    if (entry.isDirectory) continue;
-    const name = normalizeZipEntryName(entry.entryName);
-    rels.push(name);
-    byNorm.set(name, entry);
+
+// src/commands/secrets.ts
+async function readValue(value) {
+  if (value === void 0) {
+    throw new Error("Pass a value, or `-` to read from stdin.");
   }
-  const plan = flattenFederatedBundlePlan(rels);
-  const keys = Object.keys(plan);
-  if (keys.length > 0) {
-    for (const dest of keys) {
-      const src = plan[dest];
-      const source = byNorm.get(src);
-      if (!source) continue;
-      zip.addFile(dest, source.getData());
+  if (value === "-") {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.from(chunk));
     }
+    return Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
   }
-  rewriteRemoteEntryInZip(zip);
-  return zip.toBuffer();
-}
-function rewriteRemoteEntryInZip(zip) {
-  const names2 = zip.getEntries().filter((entry) => !entry.isDirectory).map((entry) => normalizeZipEntryName(entry.entryName));
-  const entryRel = chooseRemoteEntry(names2);
-  if (!entryRel) return;
-  const zipEntry = zip.getEntries().find((item) => {
-    if (item.isDirectory) return false;
-    return normalizeZipEntryName(item.entryName) === entryRel;
-  });
-  if (!zipEntry) return;
-  const before = zipEntry.getData().toString("utf8");
-  const after = rewriteRemoteEntryAssetPrefix(before);
-  if (after === before) return;
-  zip.updateFile(zipEntry.entryName, Buffer.from(after, "utf8"));
-}
-function federatedReleaseZipHint(slug) {
-  return `Run \`npm run release\` in a kit from \`gf apps init\`, then publish that zip (do not zip Vite dist/ or upload only remoteEntry.js). ${initThenPublishHint(slug)}`;
-}
-function federationRemoteName(appId) {
-  const sanitized = appId.replace(/[^a-zA-Z0-9_$]/g, "_");
-  return sanitized.length > 0 ? sanitized : "federatedApp";
-}
-function initThenPublishHint(slug) {
-  const s = (slug ?? "").trim() || "<portal-slug>";
-  return `gf apps init --slug ${s} && cd ${s} && npm install && npm run release && gf apps publish --path release.zip`;
-}
-function extractReferencedSiblings(remoteEntrySource) {
-  const names2 = /* @__PURE__ */ new Set();
-  for (const match of remoteEntrySource.matchAll(
-    /["']\.\/(?:assets\/)?([^"'/]+\.(?:js|mjs|cjs|css))["']/g
-  )) {
-    if (match[1] !== REMOTE_ENTRY) names2.add(match[1]);
-  }
-  for (const match of remoteEntrySource.matchAll(
-    /["']([A-Za-z0-9._-]+\.css)["']/g
-  )) {
-    names2.add(match[1]);
-  }
-  return [...names2];
-}
-function extractFederationScope(remoteEntrySource) {
-  return remoteEntrySource.match(/css__([A-Za-z0-9_-]+)__/)?.[1];
-}
-function zipRootNames(bytes) {
-  const zip = new AdmZip2(bytes);
-  return zip.getEntries().filter((entry) => !entry.isDirectory).map((entry) => normalizeZipEntryName(entry.entryName));
-}
-function readZipFile(bytes, rel) {
-  const zip = new AdmZip2(bytes);
-  const entry = zip.getEntries().find((item) => {
-    if (item.isDirectory) return false;
-    return normalizeZipEntryName(item.entryName) === rel;
-  });
-  return entry ? entry.getData().toString("utf8") : void 0;
+  return value;
 }
-function assertFederatedReleaseZip(bytes, slug) {
-  const hint = initThenPublishHint(slug);
-  const names2 = zipRootNames(bytes);
-  const present = new Set(names2.map((name) => basename(name)));
-  const entryRel = chooseRemoteEntry(names2);
-  if (!entryRel) {
-    throw new Error(`Zip has no remoteEntry.js. ${hint}`);
-  }
-  const source = readZipFile(bytes, entryRel);
-  if (!source) {
-    throw new Error(`Zip has no remoteEntry.js. ${hint}`);
+async function secretsListCommand(opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const data = await listSecrets(cfg.apiUrl, cfg.workspaceId, opts.environment);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
   }
-  const siblings = extractReferencedSiblings(source);
-  const missing = siblings.filter((name) => !present.has(name));
-  const jsOrCssAtRoot = names2.filter((name) => {
-    if (name.includes("/")) return false;
-    const lower = name.toLowerCase();
-    return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".css");
-  });
-  if (missing.length > 0 || siblings.length === 0 && jsOrCssAtRoot.length < 2) {
-    const detail = missing.length > 0 ? `Missing next to remoteEntry.js: ${missing.join(", ")}.` : "Zip is only remoteEntry.js (Vite chunks were never packed).";
-    throw new Error(
-      `${detail} Do not zip dist/ or upload a lone remoteEntry.js. ${hint}`
-    );
+  if (data.secrets.length === 0) {
+    process.stdout.write("No secrets in this workspace.\n");
+    return;
   }
-  const scope = extractFederationScope(source);
-  if (slug && scope) {
-    const expected = federationRemoteName(slug);
-    if (scope !== expected) {
-      throw new Error(
-        `Federation name is "${scope}" but Shell looks up "${expected}" (from slug ${slug}). Use the starter-kit vite.config (federationRemoteName). ${hint}`
-      );
-    }
+  for (const secret of data.secrets) {
+    process.stdout.write(`${secret.key}
+`);
   }
 }
-
-// src/commands/apps.ts
-import AdmZip3 from "adm-zip";
-var MAX_RELEASE_BYTES = 32 * 1024 * 1024;
-function slugify2(input) {
-  const slug = input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug || "app";
+async function secretsGetCommand(key, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const secret = await getSecret(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    key,
+    opts.environment
+  );
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(secret, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${secret.value}
+`);
 }
-function formatApp(app) {
-  return `${app.id}  ${app.name ?? app.slug ?? ""}  ${app.app_kind ?? ""}  [${app.status ?? ""}]`;
+async function secretsSetCommand(key, value, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const resolved = await readValue(value);
+  const saved = await putSecret(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    key,
+    { value: resolved, description: opts.description },
+    opts.environment
+  );
+  process.stdout.write(`Saved secret ${saved.key}
+`);
 }
-async function readJsonObject(filePath) {
-  const raw = await fs6.readFile(filePath, "utf8");
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${filePath} must contain a JSON object`);
-  }
-  return parsed;
+async function secretsRmCommand(key, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  await deleteSecret(cfg.apiUrl, cfg.workspaceId, key, opts.environment);
+  process.stdout.write(`Deleted secret ${key}
+`);
 }
-async function maybeReadManifest(filePath) {
-  if (!filePath) return void 0;
-  return readJsonObject(path7.resolve(filePath));
+
+// src/commands/flags.ts
+var VALUE_TYPES = [
+  "boolean",
+  "string",
+  "number",
+  "json"
+];
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function matchEnvironment(environments2, idOrName) {
+  const wanted = idOrName.trim();
+  const byId = environments2.find((env) => env.id === wanted);
+  if (byId) return byId.id;
+  const byName = environments2.filter(
+    (env) => env.name.toLowerCase() === wanted.toLowerCase()
+  );
+  if (byName.length === 1) return byName[0].id;
+  const names2 = environments2.map((env) => env.name).join(", ") || "none";
+  throw new Error(
+    `Environment "${wanted}" not found in this workspace (have: ${names2}). Run \`gf environments ls\`.`
+  );
 }
-async function findSiblingManifest(bundlePath) {
-  const dir = await isDirectory(bundlePath) ? bundlePath : path7.dirname(bundlePath);
-  const candidate = path7.join(dir, "groundfloor.manifest.json");
-  try {
-    await fs6.access(candidate);
-  } catch {
-    return void 0;
+async function resolveEnvironment(apiUrl, workspaceId, idOrName) {
+  if (!idOrName) return void 0;
+  if (UUID_RE.test(idOrName.trim())) return idOrName.trim();
+  const environments2 = await listWorkspaceEnvironments(apiUrl, workspaceId);
+  return matchEnvironment(environments2, idOrName);
+}
+function parseFlagValue(raw, type) {
+  if (type !== void 0 && !VALUE_TYPES.includes(type)) {
+    throw new Error(`--type must be one of: ${VALUE_TYPES.join(", ")}`);
+  }
+  const lower = raw.trim().toLowerCase();
+  const valueType = type ?? (lower === "true" || lower === "false" ? "boolean" : raw.trim() !== "" && Number.isFinite(Number(raw)) ? "number" : "string");
+  switch (valueType) {
+    case "boolean":
+      if (lower !== "true" && lower !== "false") {
+        throw new Error("boolean flags take true or false");
+      }
+      return { value: lower === "true", value_type: "boolean" };
+    case "number": {
+      const n = Number(raw);
+      if (raw.trim() === "" || !Number.isFinite(n)) {
+        throw new Error(`"${raw}" is not a number`);
+      }
+      return { value: n, value_type: "number" };
+    }
+    case "json":
+      try {
+        return { value: JSON.parse(raw), value_type: "json" };
+      } catch {
+        throw new Error("--type json needs a valid JSON value");
+      }
+    default:
+      return { value: raw, value_type: "string" };
   }
-  return { path: candidate, manifest: await readJsonObject(candidate) };
 }
-function zipHasRemoteEntry(bytes) {
-  const zip = new AdmZip3(bytes);
-  return zip.getEntries().some((entry) => {
-    if (entry.isDirectory) return false;
-    const name = normalizeZipEntryName(entry.entryName);
-    return name === REMOTE_ENTRY || name.endsWith(`/${REMOTE_ENTRY}`);
-  });
+function formatValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
 }
-function prepareReleaseZip(bytes, slug) {
-  if (!zipHasRemoteEntry(bytes)) {
-    throw new Error(
-      `Zip has no remoteEntry.js. ${initThenPublishHint(slug)}`
-    );
-  }
-  const flattened = flattenFederatedReleaseZip(bytes);
-  const plan = flattenFederatedBundlePlan(
-    new AdmZip3(bytes).getEntries().filter((e) => !e.isDirectory).map((e) => normalizeZipEntryName(e.entryName))
+async function flagsListCommand(opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
   );
-  if (Object.keys(plan).length > 0) {
-    process.stderr.write(
-      `Note: flattened Vite dist/assets layout so chunks sit next to remoteEntry.js.
-Prefer: ${federatedReleaseZipHint(slug)}
+  const data = await listFlags(cfg.apiUrl, cfg.workspaceId, env);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  process.stderr.write(`environment ${data.environment_id}
+`);
+  if (data.flags.length === 0) {
+    process.stdout.write("No flags in this environment.\n");
+    return;
+  }
+  for (const flag of data.flags) {
+    process.stdout.write(
+      `${flag.key}	${flag.value_type}	${formatValue(flag.value)}
 `
     );
   }
-  assertFederatedReleaseZip(flattened, slug);
-  return flattened;
 }
-async function isDirectory(filePath) {
-  try {
-    return (await fs6.stat(filePath)).isDirectory();
-  } catch {
-    return false;
+async function flagsGetCommand(key, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  const flag = await getFlag(cfg.apiUrl, cfg.workspaceId, key, env);
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(flag, null, 2)}
+`);
+    return;
   }
+  process.stdout.write(`${formatValue(flag.value)}
+`);
 }
-async function resolveAppId(apiUrl, workspaceId, idOrSlug) {
-  const listed = await listApps(apiUrl, workspaceId);
-  const match = listed.apps.find(
-    (app) => app.id === idOrSlug || app.slug === idOrSlug
+async function flagsSetCommand(key, value, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
   );
-  if (match) return match;
-  try {
-    return await getApp(apiUrl, workspaceId, idOrSlug);
-  } catch (err) {
-    if (err instanceof CpError && err.status === 404) {
-      throw new Error(
-        `App not found: ${idOrSlug}. Run \`gf apps ls\` or \`gf apps create\`.`
-      );
-    }
-    throw err;
+  const parsed = parseFlagValue(value, opts.type);
+  const saved = await putFlag(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    key,
+    { ...parsed, description: opts.description },
+    env
+  );
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(saved, null, 2)}
+`);
+    return;
   }
+  process.stdout.write(
+    `Set ${saved.key} = ${formatValue(saved.value)} (${saved.value_type}) in environment ${saved.environment_id}
+`
+  );
 }
-async function appsListCommand(opts) {
+async function flagsRmCommand(key, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const data = await listApps(cfg.apiUrl, cfg.workspaceId);
+  const env = await resolveEnvironment(
+    cfg.apiUrl,
+    cfg.workspaceId,
+    opts.environment
+  );
+  await deleteFlag(cfg.apiUrl, cfg.workspaceId, key, env);
+  process.stdout.write(`Deleted flag ${key}
+`);
+}
+async function flagsCompareCommand(source, target, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const [src, tgt] = await Promise.all([
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
+  ]);
+  const data = await compareFlags(cfg.apiUrl, cfg.workspaceId, src, tgt);
   if (opts.json) {
     process.stdout.write(`${JSON.stringify(data, null, 2)}
 `);
     return;
   }
-  if (data.apps.length === 0) {
-    process.stdout.write("No apps in this workspace.\n");
+  if (data.keys.length === 0) {
+    process.stdout.write("No flags in either environment.\n");
     return;
   }
-  for (const app of data.apps) {
-    process.stdout.write(`${formatApp(app)}
-`);
+  for (const row of data.keys) {
+    process.stdout.write(
+      `${row.key}	${row.status}	${formatValue(row.source_value ?? null)} \u2192 ${formatValue(row.target_value ?? null)}
+`
+    );
   }
 }
-async function appsGetCommand(appId, opts) {
+async function flagsPromoteCommand(source, target, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const app = await resolveAppId(cfg.apiUrl, cfg.workspaceId, appId);
+  const [src, tgt] = await Promise.all([
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, source),
+    resolveEnvironment(cfg.apiUrl, cfg.workspaceId, target)
+  ]);
+  const keys = opts.keys?.split(",").map((k) => k.trim()).filter(Boolean);
+  const result = await promoteFlags(cfg.apiUrl, cfg.workspaceId, {
+    source_environment_id: src,
+    target_environment_id: tgt,
+    keys: keys && keys.length > 0 ? keys : void 0,
+    mode: opts.overwrite ? "overwrite" : "skip_existing",
+    dry_run: Boolean(opts.dryRun)
+  });
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(app, null, 2)}
+    process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
     return;
   }
-  process.stdout.write(`${formatApp(app)}
+  const prefix = result.dry_run ? "[dry run] " : "";
+  process.stdout.write(
+    `${prefix}copied: ${result.copied.join(", ") || "none"}
+${prefix}skipped (already set; use --overwrite): ${result.skipped.join(", ") || "none"}
+`
+  );
+  for (const failure of result.failed) {
+    process.stdout.write(`${prefix}failed: ${failure.key} \u2014 ${failure.error}
 `);
-}
-async function appsCreateCommand(opts) {
-  const cfg = await requireWorkspace(opts.workspace);
-  const kindRaw = (opts.kind ?? "shell_federated").trim();
-  if (kindRaw === "coderunner") {
-    throw new Error(
-      "Do not create app_kind=coderunner. Deploy workloads with `gf deploy`. Use --kind shell_federated or --kind standalone."
-    );
-  }
-  if (kindRaw !== "shell_federated" && kindRaw !== "standalone") {
-    throw new Error(
-      `--kind must be shell_federated or standalone (got ${kindRaw})`
-    );
-  }
-  const kind = kindRaw;
-  const localManifest = await maybeReadManifest(opts.manifest);
-  const name = opts.name?.trim() || (typeof localManifest?.name === "string" ? localManifest.name : "");
-  const slug = opts.slug?.trim() || (typeof localManifest?.appId === "string" ? localManifest.appId : name ? slugify2(name) : "");
-  if (!name) {
-    throw new Error("Pass --name, or a manifest with a name field.");
-  }
-  if (!slug) {
-    throw new Error("Pass --slug, or a manifest with appId.");
   }
-  if (kind === "standalone" && !opts.primaryCoderunner?.trim()) {
-    throw new Error(
-      "Standalone apps require --primary-coderunner <id> (an existing service coderunner)."
-    );
+  if (result.failed.length > 0) {
+    process.exitCode = 1;
   }
-  const body = {
-    name,
-    slug,
-    app_kind: kind
+}
+
+// src/commands/files.ts
+import { promises as fs6 } from "fs";
+import path7 from "path";
+function guessContentType(filename) {
+  const ext = path7.extname(filename).toLowerCase();
+  const types = {
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".csv": "text/csv",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".zip": "application/zip"
   };
-  if (opts.environment) body.environment_id = opts.environment;
-  if (opts.primaryCoderunner) {
-    body.primary_coderunner_id = opts.primaryCoderunner;
-  }
-  if (localManifest) body.manifest = localManifest;
-  let app;
-  try {
-    app = await createApp(cfg.apiUrl, cfg.workspaceId, body);
-  } catch (err) {
-    if (err instanceof CpError && err.status === 409) {
-      throw new Error(
-        `App slug ${slug} already exists. Init the kit if you do not have it, then publish:
-  ${initThenPublishHint(slug)}`
-      );
-    }
-    throw err;
-  }
+  return types[ext] ?? "application/octet-stream";
+}
+async function filesListCommand(opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const data = await listFiles(cfg.apiUrl, cfg.workspaceId);
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(app, null, 2)}
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
 `);
     return;
   }
-  process.stdout.write(`Created ${formatApp(app)}
-`);
-  if (kind === "shell_federated") {
+  if (data.files.length === 0) {
+    process.stdout.write("No files in this workspace.\n");
+    return;
+  }
+  for (const file of data.files) {
+    const size = file.size_bytes != null ? `${file.size_bytes}B` : "";
     process.stdout.write(
-      `Next:
-  gf apps init --slug ${slug}
-  cd ${slug} && npm install && npm run release
-  gf apps publish --path release.zip
-Do not scaffold src/App.tsx from scratch \u2014 BrowserRouter in App.tsx crashes the Shell.
+      `${file.id}  ${file.name ?? ""}  ${size}  [${file.status ?? ""}]
 `
     );
   }
 }
-async function appsPublishCommand(appRef, opts) {
+async function filesUploadCommand(filePath, opts) {
   const cfg = await requireWorkspace(opts.workspace);
-  const inputPath = path7.resolve(opts.path ?? "release.zip");
-  const bundlePath = await isDirectory(inputPath) ? path7.join(inputPath, "release.zip") : inputPath;
-  let bytes;
-  try {
-    bytes = await fs6.readFile(bundlePath);
-  } catch {
-    throw new Error(
-      `No bundle at ${bundlePath}. ${initThenPublishHint()}`
-    );
-  }
-  if (bytes.byteLength === 0) {
-    throw new Error(`Bundle is empty: ${bundlePath}`);
-  }
-  if (bytes.byteLength > MAX_RELEASE_BYTES) {
-    throw new Error(
-      `Bundle exceeds ${MAX_RELEASE_BYTES} bytes (${bytes.byteLength}).`
-    );
-  }
-  const sibling = await findSiblingManifest(bundlePath);
-  const ref = appRef?.trim() || opts.app?.trim() || (typeof sibling?.manifest.appId === "string" ? sibling.manifest.appId : "");
-  if (!ref) {
-    throw new Error(
-      "Pass an app id or slug, or set appId in groundfloor.manifest.json next to the bundle."
-    );
-  }
-  const app = await resolveAppId(cfg.apiUrl, cfg.workspaceId, ref);
-  if (app.app_kind && app.app_kind !== "shell_federated") {
-    throw new Error(
-      `Releases are only for shell_federated apps (this app is ${app.app_kind}). Use \`gf deploy\` for coderunner workloads.`
-    );
-  }
-  const ext = path7.extname(bundlePath).toLowerCase();
-  const isZip = ext === ".zip";
-  if (!isZip) {
+  const resolved = path7.resolve(filePath);
+  const buf = await fs6.readFile(resolved);
+  const name = opts.name ?? path7.basename(resolved);
+  const contentType = guessContentType(name);
+  const init = await initFileUpload(cfg.apiUrl, cfg.workspaceId, {
+    name,
+    content_type: contentType,
+    size_bytes: buf.byteLength
+  });
+  const put = await fetch(init.upload_url, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: buf
+  });
+  if (!put.ok) {
     throw new Error(
-      `Publish release.zip from \`npm run release\`, not a lone ${path7.basename(bundlePath)}. ` + initThenPublishHint(app.slug)
+      `Upload to object storage failed: ${put.status} ${put.statusText}`
     );
   }
-  bytes = prepareReleaseZip(bytes, app.slug);
-  const bundle = "zip";
-  const contentType = "application/zip";
-  if (opts.syncManifest !== false && sibling) {
-    await patchApp(cfg.apiUrl, cfg.workspaceId, app.id, {
-      manifest: sibling.manifest
-    });
-  }
-  const init = await initAppReleaseUpload(cfg.apiUrl, cfg.workspaceId, app.id, {
-    bundle,
-    label: opts.label,
-    // Required since wave 5: the server pins this into the presigned PUT and
-    // checks it against the quota before minting a URL. Omitting it is a 422.
-    size_bytes: bytes.byteLength
-  });
-  await uploadAppReleaseContent(
+  const file = await finalizeFileUpload(
     cfg.apiUrl,
     cfg.workspaceId,
-    app.id,
-    init.release.id,
-    bytes,
-    contentType
+    init.file.id
   );
-  const release = await finalizeAppRelease(
+  process.stdout.write(`Uploaded ${file.id}  ${file.name ?? name}
+`);
+}
+async function filesDownloadCommand(fileId, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  const { download_url: url } = await getFileDownloadUrl(
     cfg.apiUrl,
     cfg.workspaceId,
-    app.id,
-    init.release.id
+    fileId
   );
-  if (opts.json) {
-    process.stdout.write(`${JSON.stringify({ app, release }, null, 2)}
-`);
-    return;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Download failed: ${res.status} ${res.statusText}`);
   }
-  process.stdout.write(
-    `Published ${app.slug ?? app.id}  build ${release.build_number}` + (release.remote_url ? `  ${release.remote_url}` : "") + "\n"
-  );
+  const buf = Buffer.from(await res.arrayBuffer());
+  const dest = path7.resolve(opts.out ?? fileId);
+  await fs6.writeFile(dest, buf);
+  process.stdout.write(`Wrote ${dest}
+`);
+}
+async function filesRmCommand(fileId, opts) {
+  const cfg = await requireWorkspace(opts.workspace);
+  await deleteFile(cfg.apiUrl, cfg.workspaceId, fileId);
+  process.stdout.write(`Deleted file ${fileId}
+`);
 }
 
 // src/commands/apps-init.ts
@@ -3525,6 +3778,107 @@ async function apiCommand(opts) {
 `);
 }
 
+// src/commands/usage.ts
+var DAY_S = 86400;
+async function usageCommand(opts) {
+  const cfg = await resolveConfig({ workspaceId: opts.workspace });
+  let sinceSeconds;
+  if (opts.sinceDays !== void 0) {
+    const days = Number(opts.sinceDays);
+    if (!Number.isFinite(days) || days < 1 / 24 || days > 400) {
+      throw new Error("--since-days must be a number between 0.05 and 400.");
+    }
+    sinceSeconds = Math.round(days * DAY_S);
+  }
+  let accountId = opts.account?.trim();
+  if (!accountId) {
+    if (!cfg.workspaceId) {
+      throw new Error(
+        "No workspace selected. Pass --account <account-id>, --workspace <id>, or run `gf workspaces use <id>`."
+      );
+    }
+    const workspaces2 = await listWorkspaces(cfg.apiUrl);
+    const ws = workspaces2.find((item) => item.id === cfg.workspaceId);
+    const resolved = ws?.account_id ?? ws?.organization_id;
+    if (!resolved) {
+      throw new Error(
+        `Could not find the account for workspace ${cfg.workspaceId}. Pass --account <account-id>.`
+      );
+    }
+    accountId = resolved;
+  }
+  const [quota, billing] = await Promise.allSettled([
+    getAccountQuota(cfg.apiUrl, accountId),
+    getBillingSummary(cfg.apiUrl, accountId, sinceSeconds)
+  ]);
+  if (opts.json) {
+    const part = (r) => r.status === "fulfilled" ? r.value : { error: errorText(r.reason) };
+    process.stdout.write(
+      `${JSON.stringify({ account_id: accountId, quota: part(quota), billing: part(billing) }, null, 2)}
+`
+    );
+    if (quota.status === "rejected" && billing.status === "rejected") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  process.stdout.write(`Account: ${accountId}
+`);
+  if (quota.status === "fulfilled") {
+    printQuota(quota.value);
+  } else {
+    process.stdout.write(`
+Quota: unavailable (${errorText(quota.reason)})
+`);
+  }
+  if (billing.status === "fulfilled") {
+    printBilling(billing.value);
+  } else {
+    process.stdout.write(`
+Billing: unavailable (${errorText(billing.reason)})
+`);
+  }
+  if (quota.status === "rejected" && billing.status === "rejected") {
+    process.exitCode = 1;
+  }
+}
+function errorText(reason) {
+  if (reason instanceof CpError && reason.status === 403) {
+    return `${reason.message}; your user lacks permission on this account`;
+  }
+  return reason instanceof Error ? reason.message : String(reason);
+}
+function printQuota(q) {
+  const out = process.stdout;
+  out.write(`
+Quota (plan: ${q.plan_tier})
+`);
+  for (const l of q.limits) {
+    const limit = l.limit == null ? "unlimited" : String(l.limit);
+    out.write(`  ${l.label}: ${l.current} / ${limit} ${l.unit}
+`);
+  }
+  if (q.note) out.write(`  note: ${q.note}
+`);
+}
+function printBilling(b) {
+  const out = process.stdout;
+  const label = b.is_estimate === false ? "Billing" : "Billing ESTIMATE (not a final bill)";
+  out.write(`
+${label}: ${b.period_start} to ${b.period_end}
+`);
+  out.write(
+    `  CU: compute ${b.breakdown.compute}, storage ${b.breakdown.storage}, network ${b.breakdown.network}, ai ${b.breakdown.ai} (adjusted ${b.adjusted_cu})
+`
+  );
+  out.write(`  indicative amount: $${b.final_bill_usd.toFixed(2)} USD
+`);
+  if (b.pricing_final === false) out.write("  pricing is not final (placeholder rates)\n");
+  if (b.ai_usage_truncated) out.write("  AI usage may be understated (log window truncated)\n");
+  if (b.note) out.write(`  note: ${b.note}
+`);
+}
+
 // src/commands/identities.ts
 async function identitiesListCommand(opts) {
   const cfg = await resolveConfig({ workspaceId: opts.workspace });
@@ -3620,7 +3974,7 @@ m2m.command("token").description(
   "Exchange GROUNDFLOOR_M2M_CLIENT_ID + SECRET for a short CP JWT (not gf token)"
 ).option("-w, --workspace <id>", "Workspace id override").option("--client-id <id>", "M2M client_id (else GROUNDFLOOR_M2M_CLIENT_ID)").option(
   "--client-secret <secret>",
-  "M2M secret (else GROUNDFLOOR_M2M_CLIENT_SECRET)"
+  "M2M secret (prefer GROUNDFLOOR_M2M_CLIENT_SECRET: argv is visible in `ps` and shell history)"
 ).option("--json", "Output the full token response as JSON").action(
   (opts) => run(
     () => m2mTokenCommand({
@@ -3641,17 +3995,23 @@ workspaces.command("use <workspaceId>").description("Set the default workspace")
 );
 var coderunner = program.command("coderunner").alias("cr").description("Coderunner commands");
 coderunner.command("ls").alias("list").description("List coderunners in the default (or --workspace) workspace").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => coderunnerListCommand(opts)));
-coderunner.command("status").description("Show coderunner status + current deployment JSON").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => statusCommand(opts)));
-coderunner.command("cancel-deployment").description("Delete the current (or --deployment-id) deployment").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--deployment-id <id>", "Deployment id (default: current deployment)").action(
+coderunner.command("status").description("Show coderunner status and current deployment (use --json for the full payload)").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => statusCommand(opts)));
+coderunner.command("cancel-deployment").alias("delete-deployment").description(
+  "DELETE the current (or --deployment-id) deployment. This is not an in-flight cancel: it takes the live service down"
+).requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--deployment-id <id>", "Deployment id (default: the current live deployment)").option(
+  "-y, --yes",
+  "Skip the confirmation (required when there is no interactive terminal)"
+).action(
   (opts) => run(
     () => cancelDeploymentCommand({
       workspace: opts.workspace,
       coderunner: opts.coderunner,
-      deploymentId: opts.deploymentId
+      deploymentId: opts.deploymentId,
+      yes: opts.yes
     })
   )
 );
-coderunner.command("logs").description("Show Process Log lines for a coderunner (stdout/stderr)").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--limit <n>", "Max lines (default 50)").option("--since-seconds <n>", "Lookback window in seconds (default 3600)").option("--search <text>", "Substring filter").option("--json", "Output raw JSON").action(
+coderunner.command("logs").description("Show Process Log lines for a coderunner (stdout/stderr)").requiredOption("-c, --coderunner <id|slug>", "Coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--limit <n>", "Max lines (default 50, max 1000)").option("--since-seconds <n>", "Lookback window in seconds (default 3600, max 604800 = 7 days)").option("--search <text>", "Substring filter").option("--json", "Output raw JSON").action(
   (opts) => run(
     () => logsCommand({
       workspace: opts.workspace,
@@ -3684,13 +4044,15 @@ coderunner.command("vault-token").description(
     })
   )
 );
-var domains = program.command("domains").description("Manage custom domains (CNAME) for a coderunner service");
-domains.command("add <domain>").description("Add a custom domain and print the DNS records to create").requiredOption("-c, --coderunner <id|slug>", "Target coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((domain, opts) => run(() => domainsAddCommand(domain, opts)));
-domains.command("ls").alias("list").description("List custom domains for a coderunner service").requiredOption("-c, --coderunner <id|slug>", "Target coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => domainsListCommand(opts)));
-domains.command("rm <domain>").alias("remove").description("Remove a custom domain from a coderunner service").requiredOption("-c, --coderunner <id|slug>", "Target coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").action(
+var domains = program.command("domains").description(
+  "Manage custom domains (CNAME) for an App (standalone / service apps). Not available on standalone coderunners"
+);
+domains.command("add <domain>").description("Add a custom domain and print the DNS records to create").option("--app <id|slug>", "Target App id or slug (standalone / service app)").option("-c, --coderunner <id|slug>", "Removed: custom domains are not available on standalone coderunners").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((domain, opts) => run(() => domainsAddCommand(domain, opts)));
+domains.command("ls").alias("list").description("List custom domains for an App").option("--app <id|slug>", "Target App id or slug (standalone / service app)").option("-c, --coderunner <id|slug>", "Removed: custom domains are not available on standalone coderunners").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => domainsListCommand(opts)));
+domains.command("rm <domain>").alias("remove").description("Remove a custom domain from an App").option("--app <id|slug>", "Target App id or slug (standalone / service app)").option("-c, --coderunner <id|slug>", "Removed: custom domains are not available on standalone coderunners").option("-w, --workspace <id>", "Workspace id override").action(
   (domain, opts) => run(() => domainsRemoveCommand(domain, opts))
 );
-domains.command("verify <domain>").description("Re-check the DNS records for a custom domain").requiredOption("-c, --coderunner <id|slug>", "Target coderunner id or slug").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action(
+domains.command("verify <domain>").description("Re-check the DNS records for a custom domain").option("--app <id|slug>", "Target App id or slug (standalone / service app)").option("-c, --coderunner <id|slug>", "Removed: custom domains are not available on standalone coderunners").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action(
   (domain, opts) => run(() => domainsVerifyCommand(domain, opts))
 );
 var secrets = program.command("secrets").description("Manage workspace secrets");
@@ -3779,8 +4141,11 @@ var dataplane = program.command("dataplane").description("Workspace Dataplane se
 dataplane.command("status").description("Show Dataplane setup status").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => dataplaneStatusCommand(opts)));
 dataplane.command("provision").description("Provision Dataplane for this workspace (idempotent)").option("-w, --workspace <id>", "Workspace id override").option("--json", "Output raw JSON").action((opts) => run(() => dataplaneProvisionCommand(opts)));
 program.command("deploy").description(
-  "Package code and deploy as a coderunner (not an App)"
-).option("-w, --workspace <id>", "Workspace id override").option("--api-url <url>", "Control Plane base URL").option(
+  "Package code and deploy as a coderunner (not an App). Env var VALUES are not stored: resend them with -e on every deploy"
+).option(
+  "-w, --workspace <id>",
+  "Target workspace id. Required with no interactive terminal unless GROUNDFLOOR_WORKSPACE_ID is set; the saved `gf workspaces use` default is only used after an interactive confirm"
+).option("--api-url <url>", "Control Plane base URL").option(
   "-c, --coderunner <id>",
   "Deploy into an existing coderunner id (skip find/create)"
 ).option("-n, --name <name>", "Coderunner name (default: folder or repo name)").option("-p, --path <dir>", "Local directory to package (default: cwd)").option("--git <url>", "Clone and deploy a remote git/bitbucket repo").option("--ref <ref>", "Branch/tag/commit for --git").option("--subdir <dir>", "Subdirectory within the source to package").option("--runtime <runtime>", "Language slug from Code Runner (node, python, go, \u2026)").option(
@@ -3791,13 +4156,19 @@ program.command("deploy").description(
   'Cron for --workload-type schedule (or groundfloor.json "schedule")'
 ).option(
   "--app-id <id>",
-  "Bind newly created coderunner as a helper of this App (optional)"
+  "Bind a NEWLY CREATED coderunner as a helper of this App (ignored, with a warning, when an existing coderunner is reused)"
 ).option("--cpu <cpu>", "CPU request, e.g. 250m").option("--memory <memory>", "Memory request, e.g. 256Mi").option("-e, --env <KEY=VALUE>", "Environment variable (repeatable)", collect, []).option(
   "--secret <KEY>",
-  "Inject this workspace secret by reference (repeatable). Use for *_SECRET keys.",
+  "Inject this workspace secret by reference (repeatable). Only works where the platform has secret injection enabled (off by default); otherwise read secrets at runtime via an M2M client with secrets:read",
   collect,
   []
+).option(
+  "-y, --yes",
+  "Confirm updating an existing same-named coderunner (required with no interactive terminal). Does not bypass the saved-default-workspace check: pass -w"
 ).option("-m, --message <text>", "Version description").option("--skip-deploy", "Upload a new version but do not deploy it").action((opts) => run(() => deployCommand(opts)));
+program.command("usage").description(
+  "Show account quota/usage and the billing estimate (read-only). The account is the billing parent of the workspace, not the workspace itself"
+).option("-w, --workspace <id>", "Workspace whose account to show").option("--account <id>", "Account id (overrides the workspace's account)").option("--since-days <n>", "Billing lookback in days (default 30, max 400)").option("--json", "Output raw JSON").action((opts) => run(() => usageCommand(opts)));
 program.command("api").description("Call a Control Plane path (passthrough for gaps in gf commands)").argument("<path>", "Path beginning with /v1/\u2026  Use {workspace_id} for the current workspace").option("-X, --method <method>", "HTTP method", "GET").option("--body <json>", "JSON body for POST/PUT/PATCH").option("-w, --workspace <id>", "Workspace id override").action(
   (path11, opts) => run(
     () => apiCommand({