@mutagent/cli 0.1.379 → 0.1.381

package/dist/bin/cli.js

@@ -268,7 +268,7 @@ function handleError(error, isJson) {
       }
       if (error instanceof WorkspaceContextError) {
         jsonOutput.remediation = {
-          setWorkspace: "mutagent config set workspace <workspace-id>",
+          setWorkspace: "mutagent workspaces use <name>",
           listWorkspaces: "mutagent workspaces list"
         };
       }
@@ -290,7 +290,7 @@ function handleError(error, isJson) {
       console.log(JSON.stringify(scrubKnownDeep(jsonOutput), null, 2));
     } else {
       console.error(`Error: ${scrubKnown(error.message)}`);
-      if (error instanceof AuthenticationError) {
+      if (error.name === "TenancyError") {} else if (error instanceof AuthenticationError) {
         console.error("");
         console.error(AUTH_REMEDIATION_MESSAGE);
       } else if (error instanceof WorkspaceContextError) {
@@ -393,14 +393,14 @@ var init_errors = __esm(() => {
     }
   };
   WORKSPACE_REMEDIATION_MESSAGE = [
-    "Workspace context missing. To fix:",
-    "  mutagent config set workspace <workspace-id>   # Set default workspace",
-    "  mutagent workspaces list                        # List available workspaces"
+    "No workspace selected. To fix:",
+    "  mutagent workspaces use <name>    # Select the workspace every later command works in",
+    "  mutagent workspaces list          # Your workspaces"
   ].join(`
 `);
   WorkspaceContextError = class WorkspaceContextError extends MutagentError {
     constructor(message) {
-      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
+      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent workspaces use <name>", 3);
     }
   };
   ValidationError = class ValidationError extends MutagentError {
@@ -16519,6 +16519,448 @@ function writeSecureFile(path, contents) {
 var SECURE_FILE_MODE = 384;
 var init_secure_file = () => {};
 
+// src/lib/config.ts
+import { cosmiconfigSync } from "cosmiconfig";
+import { z } from "zod";
+import { homedir as homedir2 } from "os";
+import { join as join7 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync2, mkdirSync } from "fs";
+function parseJsonSafe(content, schema4) {
+  try {
+    const parsed = JSON.parse(content);
+    return schema4.parse(parsed);
+  } catch {
+    return null;
+  }
+}
+function loadConfig() {
+  const explorer = cosmiconfigSync("mutagent");
+  const result = explorer.search();
+  const rcConfig = result?.config;
+  let credentials = null;
+  if (existsSync2(CREDENTIALS_FILE)) {
+    credentials = parseJsonSafe(readFileSync2(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  }
+  const envKey = process.env.MUTAGENT_API_KEY;
+  const fileDescribesKey = envKey === undefined || envKey === credentials?.apiKey;
+  const envWorkspace = process.env.MUTAGENT_WORKSPACE_ID?.trim() ?? "";
+  const fileSelection = fileDescribesKey ? credentials?.defaultWorkspace : undefined;
+  const selected = fileSelection ?? rcConfig?.defaultWorkspace;
+  const defaultWorkspace = envWorkspace !== "" ? envWorkspace : selected;
+  const merged = {
+    providers: {},
+    environment: "production",
+    ...rcConfig,
+    ...credentials,
+    apiKey: envKey ?? credentials?.apiKey ?? rcConfig?.apiKey,
+    endpoint: process.env.MUTAGENT_ENDPOINT ?? credentials?.endpoint ?? rcConfig?.endpoint,
+    defaultWorkspace,
+    workspaceOrigin: envWorkspace !== "" ? "override" : selected ? "selection" : undefined,
+    workspaceName: envWorkspace === "" && fileSelection !== undefined && fileSelection === selected ? credentials?.workspaceName : undefined,
+    defaultOrganization: fileDescribesKey ? credentials?.defaultOrganization ?? rcConfig?.defaultOrganization : undefined,
+    organizationName: fileDescribesKey ? credentials?.organizationName : undefined,
+    organizationSlug: fileDescribesKey ? credentials?.organizationSlug : undefined,
+    keyScope: fileDescribesKey ? credentials?.keyScope : undefined
+  };
+  return configSchema.parse(merged);
+}
+function readCredentialsFile() {
+  if (!existsSync2(CREDENTIALS_FILE))
+    return {};
+  try {
+    return JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function updateCredentials(patch) {
+  if (!existsSync2(CREDENTIALS_DIR)) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  const updated = Object.fromEntries(Object.entries({ ...readCredentialsFile(), ...patch }).filter(([key, value2]) => value2 !== undefined && key !== "defaultWorkspaceSource"));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
+}
+function saveCredentials(apiKey, endpoint) {
+  if (!existsSync2(CREDENTIALS_DIR)) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  const config = loadConfig();
+  const credentials = {
+    apiKey,
+    endpoint: endpoint ?? config.endpoint
+  };
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
+}
+function saveFullCredentials(creds) {
+  const existing = readCredentialsFile();
+  updateCredentials({
+    apiKey: creds.apiKey,
+    endpoint: creds.endpoint ?? existing.endpoint ?? "https://api.mutagent.io",
+    defaultWorkspace: creds.workspaceId,
+    workspaceName: creds.workspaceName,
+    defaultOrganization: creds.organizationId,
+    organizationName: creds.organizationName,
+    organizationSlug: creds.organizationSlug,
+    keyScope: creds.keyScope,
+    expiresAt: creds.expiresAt
+  });
+}
+function clearCredentials() {
+  if (existsSync2(CREDENTIALS_FILE)) {
+    writeSecureFile(CREDENTIALS_FILE, JSON.stringify({}));
+  }
+}
+function hasCredentials() {
+  if (process.env.MUTAGENT_API_KEY)
+    return true;
+  if (!existsSync2(CREDENTIALS_FILE))
+    return false;
+  const credentials = parseJsonSafe(readFileSync2(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  return credentials?.apiKey !== undefined && credentials.apiKey !== "";
+}
+function envKeyReplacesFile() {
+  const envKey = process.env.MUTAGENT_API_KEY;
+  if (envKey === undefined)
+    return false;
+  if (!existsSync2(CREDENTIALS_FILE))
+    return true;
+  const credentials = parseJsonSafe(readFileSync2(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  return envKey !== credentials?.apiKey;
+}
+function getApiKey() {
+  const apiKey = process.env.MUTAGENT_API_KEY ?? loadConfig().apiKey;
+  registerSecret(apiKey);
+  return apiKey;
+}
+function setWorkspaceSelection(workspaceId, workspaceName) {
+  updateCredentials({ defaultWorkspace: workspaceId, workspaceName });
+}
+function recordKeyScope(self) {
+  updateCredentials({
+    keyScope: self.scope,
+    defaultOrganization: self.organization?.id,
+    organizationName: self.organization?.name,
+    organizationSlug: self.organization?.slug,
+    ...self.scope === "workspace" && self.workspace ? { defaultWorkspace: self.workspace.id, workspaceName: self.workspace.name } : {}
+  });
+}
+var keyScopeSchema, configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
+var init_config = __esm(() => {
+  init_secure_file();
+  init_known_secrets();
+  keyScopeSchema = z.enum(["organization", "workspace", "user"]);
+  configSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().default("https://api.mutagent.io"),
+    format: z.enum(["table", "json"]).default("table"),
+    timeout: z.number().default(30000),
+    defaultWorkspace: z.string().optional(),
+    workspaceOrigin: z.enum(["override", "selection"]).optional(),
+    workspaceName: z.string().optional(),
+    defaultOrganization: z.string().optional(),
+    organizationName: z.string().optional(),
+    organizationSlug: z.string().optional(),
+    keyScope: keyScopeSchema.optional()
+  });
+  credentialsSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().optional(),
+    defaultWorkspace: z.string().optional(),
+    workspaceName: z.string().optional(),
+    defaultOrganization: z.string().optional(),
+    organizationName: z.string().optional(),
+    organizationSlug: z.string().optional(),
+    keyScope: keyScopeSchema.optional(),
+    expiresAt: z.string().optional()
+  }).loose();
+  CREDENTIALS_DIR = join7(homedir2(), ".config", "mutagent");
+  CREDENTIALS_FILE = join7(CREDENTIALS_DIR, "credentials.json");
+});
+
+// src/lib/organization-scope.ts
+var exports_organization_scope = {};
+__export(exports_organization_scope, {
+  unreachableServerError: () => unreachableServerError,
+  tenancyHeaders: () => tenancyHeaders,
+  tenancyFailure: () => tenancyFailure,
+  setWorkspaceFlag: () => setWorkspaceFlag,
+  setOrgAssertion: () => setOrgAssertion,
+  resolveKeyTenancy: () => resolveKeyTenancy,
+  otherOrganizationHint: () => otherOrganizationHint,
+  orgMismatch: () => orgMismatch,
+  noWorkspaceSelected: () => noWorkspaceSelected,
+  matchesOrganization: () => matchesOrganization,
+  looksLikeWorkspaceId: () => looksLikeWorkspaceId,
+  listKeyWorkspaces: () => listKeyWorkspaces,
+  findWorkspace: () => findWorkspace,
+  fetchOrganizations: () => fetchOrganizations,
+  fetchKeySelf: () => fetchKeySelf,
+  envKeyHasNoSelection: () => envKeyHasNoSelection,
+  deadKeyError: () => deadKeyError,
+  configTenancyHeaders: () => configTenancyHeaders,
+  TenancyError: () => TenancyError,
+  TENANCY_DENIED: () => TENANCY_DENIED
+});
+function looksLikeWorkspaceId(value2) {
+  return UUID_PATTERN.test(value2);
+}
+function tenancyHeaders(t) {
+  const headers = {};
+  if (!t.workspaceId)
+    return headers;
+  if (t.keyScope === "workspace") {
+    if (t.workspaceOrigin === "override")
+      headers["x-workspace-id"] = t.workspaceId;
+    return headers;
+  }
+  headers["x-workspace-id"] = t.workspaceId;
+  if (t.keyScope === "user" && t.organizationId)
+    headers["x-organization-id"] = t.organizationId;
+  return headers;
+}
+function configTenancyHeaders(config) {
+  return tenancyHeaders({
+    keyScope: config.keyScope,
+    workspaceId: config.defaultWorkspace,
+    workspaceOrigin: config.workspaceOrigin,
+    organizationId: config.defaultOrganization
+  });
+}
+function parseBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object")
+      return parsed;
+  } catch {}
+  return {};
+}
+function deadKeyError() {
+  return new TenancyError("AUTH_EXPIRED", "Your CLI key expired or was revoked.", "Run: mutagent login", 2);
+}
+function tenancyFailure(status, body, ctx) {
+  const parsed = parseBody(body);
+  if (status === 401)
+    return deadKeyError();
+  if (status === 403 && parsed.code === TENANCY_DENIED) {
+    const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
+    if (ctx.workspaceOrigin === "selection") {
+      return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
+    }
+    const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
+    return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
+  }
+  if (status === 403 && ctx.keyScope === "workspace" && ctx.workspaceOrigin === "override") {
+    return new TenancyError("WORKSPACE_KEY_MISMATCH", "This API key only works in its own workspace.", "Run: mutagent login (for a key that can switch workspaces)");
+  }
+  if (status === 400 && (parsed.message ?? body).toLowerCase().includes("x-workspace-id")) {
+    return noWorkspaceSelected();
+  }
+  return;
+}
+function noWorkspaceSelected() {
+  const fix = envKeyReplacesFile() ? ENV_KEY_WORKSPACE_FIX : "Run: mutagent workspaces use <name>";
+  return new TenancyError("WORKSPACE_REQUIRED", "No workspace selected.", fix, 3);
+}
+function envKeyHasNoSelection() {
+  return new TenancyError("WORKSPACE_FROM_ENV", "With MUTAGENT_API_KEY set, the workspace comes from --workspace or MUTAGENT_WORKSPACE_ID.", ENV_KEY_WORKSPACE_FIX);
+}
+async function tenancyFetch(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch {
+    throw unreachableServerError(url);
+  }
+}
+function unreachableServerError(url) {
+  let origin = url;
+  try {
+    origin = new URL(url).origin;
+  } catch {}
+  return new MutagentError("REQUEST_FAILED", `Unable to connect to the Mutagent server at ${origin}.`, "Check your connection and the endpoint: mutagent config get endpoint");
+}
+async function fetchKeySelf(apiKey, endpoint, opts = {}) {
+  const response = await tenancyFetch(`${endpoint}/api/api-keys/self`, {
+    headers: { "x-api-key": apiKey, ...opts.headers }
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw tenancyFailure(response.status, body, opts.ctx ?? {}) ?? new MutagentError("KEY_SCOPE_UNAVAILABLE", `Could not read this API key's scope (${String(response.status)}).`, "Check the endpoint with: mutagent config get endpoint");
+  }
+  return await response.json();
+}
+async function fetchOrganizations(apiKey, endpoint) {
+  try {
+    const response = await fetch(`${endpoint}/api/organizations`, {
+      headers: { "x-api-key": apiKey }
+    });
+    if (!response.ok)
+      return [];
+    const data = await response.json();
+    return data.data ?? [];
+  } catch {
+    return [];
+  }
+}
+function matchesOrganization(value2, org) {
+  if (!org)
+    return false;
+  if (value2 === org.id || org.slug !== undefined && value2 === org.slug)
+    return true;
+  return org.name !== undefined && value2.toLowerCase() === org.name.toLowerCase();
+}
+function orgMismatch(value2, org) {
+  const shown = org.slug ? `${org.name} (${org.slug})` : org.name;
+  return new TenancyError("ORG_MISMATCH", `Your key is for ${shown}.`, `Run: mutagent login --org ${value2}`);
+}
+function otherOrganizationHint(wanted, keyOrg, orgs) {
+  const others = orgs.filter((o) => o.id !== keyOrg?.id);
+  const where = keyOrg ? ` in ${keyOrg.name}` : "";
+  const what = `No workspace "${wanted}"${where}.`;
+  const named = others.map((o) => `${o.name} (${o.slug ?? o.id})`).join(", ");
+  if (others.length === 1 && others[0]) {
+    const only = others[0];
+    return new TenancyError("WORKSPACE_NOT_FOUND", `${what} Your other organization: ${named}.`, `To switch: mutagent login --org ${only.slug ?? only.id}`);
+  }
+  if (others.length > 1) {
+    return new TenancyError("WORKSPACE_NOT_FOUND", `${what} Your other organizations: ${named}.`, "To switch: mutagent login --org <slug>");
+  }
+  return new TenancyError("WORKSPACE_NOT_FOUND", what, "See: mutagent workspaces list");
+}
+function setOrgAssertion(value2) {
+  const trimmed = value2?.trim();
+  orgAssertion = trimmed === "" ? undefined : trimmed;
+}
+function setWorkspaceFlag(value2) {
+  const trimmed = value2?.trim();
+  workspaceFlag = trimmed === "" ? undefined : trimmed;
+}
+function endpointOf(configured) {
+  const trimmed = configured?.trim();
+  return (trimmed === undefined || trimmed === "" ? "https://api.mutagent.io" : trimmed).replace(/\/+$/, "");
+}
+async function probeKeyScope(apiKey, endpoint, workspaceNamed) {
+  const fromFile = !envKeyReplacesFile();
+  if (!fromFile && workspaceNamed && orgAssertion === undefined)
+    return;
+  try {
+    const self = await fetchKeySelf(apiKey, endpoint);
+    if (fromFile)
+      recordKeyScope(self);
+    return self;
+  } catch (error3) {
+    if (error3 instanceof MutagentError && (error3.code === "AUTH_EXPIRED" || error3.code === "REQUEST_FAILED"))
+      throw error3;
+    return;
+  }
+}
+function enforceOrgAssertion(org) {
+  if (orgAssertion === undefined)
+    return;
+  if (org === undefined) {
+    throw new TenancyError("ORG_UNKNOWN", "This key's organization is unknown, so --org cannot be checked.", "Run: mutagent workspaces current");
+  }
+  if (!matchesOrganization(orgAssertion, org)) {
+    throw orgMismatch(orgAssertion, org);
+  }
+}
+async function resolveKeyTenancy(apiKey, opts = {}) {
+  const config = loadConfig();
+  const endpoint = endpointOf(config.endpoint);
+  let keyScope = config.keyScope;
+  let organization = config.defaultOrganization ? { id: config.defaultOrganization, name: config.organizationName ?? config.defaultOrganization, slug: config.organizationSlug } : undefined;
+  let workspaceId = config.defaultWorkspace;
+  let workspaceName = config.workspaceName;
+  const workspaceOrigin = config.workspaceOrigin;
+  if (keyScope === undefined && (opts.probe !== false || orgAssertion !== undefined)) {
+    const self = await probeKeyScope(apiKey, endpoint, workspaceId !== undefined);
+    if (self) {
+      keyScope = self.scope;
+      organization = self.organization ?? undefined;
+      if (self.scope === "workspace" && self.workspace && workspaceOrigin !== "override") {
+        workspaceId = self.workspace.id;
+        workspaceName = self.workspace.name;
+      }
+    }
+  }
+  enforceOrgAssertion(organization);
+  if (opts.resolveOverride !== false && workspaceFlag !== undefined && workspaceId === workspaceFlag && !looksLikeWorkspaceId(workspaceId)) {
+    const found = await findWorkspace(workspaceId, { apiKey, endpoint, keyScope, organization, workspaceId: config.defaultWorkspace, workspaceName });
+    workspaceId = found.id;
+    workspaceName = found.name;
+    process.env.MUTAGENT_WORKSPACE_ID = found.id;
+  }
+  return { endpoint, keyScope, organization, workspaceId, workspaceName, workspaceOrigin };
+}
+async function listKeyWorkspaces(apiKey, endpoint, t) {
+  const headers = { "x-api-key": apiKey };
+  if (t.keyScope === "user" && t.organization)
+    headers["x-organization-id"] = t.organization.id;
+  const response = await tenancyFetch(`${endpoint}/api/workspaces`, { headers });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw tenancyFailure(response.status, body, { keyScope: t.keyScope, organizationName: t.organization?.name }) ?? new MutagentError("REQUEST_FAILED", `Could not list workspaces (${String(response.status)}).`, "Run: mutagent workspaces current");
+  }
+  const data = await response.json();
+  return data.workspaces ?? [];
+}
+async function findWorkspace(wanted, t) {
+  if (t.keyScope === "workspace") {
+    if (t.workspaceId && (wanted === t.workspaceId || wanted === t.workspaceName)) {
+      return { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId };
+    }
+    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${t.workspaceName ?? t.workspaceId ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
+  }
+  const rows = await listKeyWorkspaces(t.apiKey, t.endpoint, t);
+  const byId = rows.find((w) => w.id === wanted);
+  if (byId)
+    return { id: byId.id, name: byId.name };
+  let matches = rows.filter((w) => w.name === wanted || w.slug === wanted);
+  if (matches.length === 0)
+    matches = rows.filter((w) => w.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1 && matches[0])
+    return { id: matches[0].id, name: matches[0].name };
+  if (matches.length > 1) {
+    throw new TenancyError("WORKSPACE_AMBIGUOUS", `Several workspaces are named "${wanted}": ${matches.map((w) => `${w.name} (${w.id})`).join(", ")}.`, "Run: mutagent workspaces use <id>");
+  }
+  const orgs = await fetchOrganizations(t.apiKey, t.endpoint);
+  throw otherOrganizationHint(wanted, t.organization, orgs);
+}
+var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag;
+var init_organization_scope = __esm(() => {
+  init_errors();
+  init_config();
+  UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  TenancyError = class TenancyError extends MutagentError {
+    constructor(code, what, fix, exitCode = 1) {
+      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""), exitCode);
+      this.name = "TenancyError";
+    }
+  };
+});
+
+// src/lib/provider-request.ts
+function buildCreateProviderBody(data) {
+  const body = {
+    name: data.name,
+    provider: data.provider,
+    isDefault: data.isDefault ?? false
+  };
+  if (data.apiKey)
+    body.apiKey = data.apiKey;
+  if (data.baseUrl)
+    body.baseUrl = data.baseUrl;
+  if (data.hostedFamily)
+    body.hostedFamily = data.hostedFamily;
+  if (data.credentialFields && Object.keys(data.credentialFields).length > 0) {
+    body.credentialFields = data.credentialFields;
+  }
+  if (data.metadata && Object.keys(data.metadata).length > 0)
+    body.metadata = data.metadata;
+  if (data.supportedModels !== undefined)
+    body.supportedModels = data.supportedModels;
+  return body;
+}
+
 // src/lib/sdk-debug.ts
 function isDebugEnabled(env = process.env) {
   return TRUTHY.has((env.MUTAGENT_DEBUG ?? "").trim().toLowerCase());
@@ -16613,315 +17055,39 @@ var init_sdk_debug = __esm(() => {
   };
 });
 
-// src/lib/organization-scope.ts
-function isWellFormedOrganizationId(id) {
-  return ORGANIZATION_ID_PATTERN.test(id);
+// src/lib/sdk-mappers.ts
+import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
+function isProviderType(value2) {
+  return PROVIDER_TYPES.includes(value2);
 }
-function isOrganizationScopeMismatch(status, body) {
-  if (status !== 403)
-    return false;
-  return body.toLowerCase().includes("organization scope mismatch");
+function narrowProviderType(value2) {
+  return isProviderType(value2) ? value2 : value2;
 }
-async function lookupOrganizations(apiKey, endpoint) {
-  try {
-    const response = await fetch(`${endpoint}/api/organizations`, {
-      headers: { "x-api-key": apiKey }
-    });
-    if (!response.ok)
-      return [];
-    const data = await response.json();
-    return data.data ?? [];
-  } catch {
-    return [];
-  }
+function toIsoString(value2) {
+  if (value2 === null || value2 === undefined)
+    return null;
+  return value2 instanceof Date ? value2.toISOString() : value2;
 }
-async function fetchOrganizations(apiKey, endpoint) {
-  return lookupOrganizations(apiKey, endpoint);
-}
-async function assertUsableOrganizationId(id, lookup) {
-  const orgs = lookup.apiKey ? await lookup.fetchOrganizations(lookup.apiKey, lookup.endpoint).catch(() => []) : [];
-  if (orgs.length === 0) {
-    if (isWellFormedOrganizationId(id))
-      return;
-    throw new MutagentError("INVALID_ORGANIZATION_ID", `"${id}" is not an organization id.`, `Organization ids look like org_xxxxxxxxxxxxxxxxxxxxx.
-` + "Log in so the id can be checked against your account: mutagent auth login --browser");
-  }
-  if (orgs.some((org) => org.id === id))
-    return;
-  throw new MutagentError("UNKNOWN_ORGANIZATION", `"${id}" is not an organization this API key can access.`, `Available: ${orgs.map((org) => org.id).join(", ")}
-` + "A stored organization that does not match the key makes every request fail with 403.");
-}
-function createOrgScopeRecoveringFetcher(hooks) {
-  let recoveryUsed = false;
-  async function recover() {
-    if (recoveryUsed)
-      return;
-    recoveryUsed = true;
-    const stale = hooks.currentOrganization();
-    if (!stale)
-      return;
-    hooks.adoptOrganization(undefined);
-    hooks.forgetStoredOrganization?.();
-    const orgs = await lookupOrganizations(hooks.apiKey, hooks.endpoint);
-    const resolved = orgs[0]?.id;
-    if (!resolved || resolved === stale)
-      return;
-    hooks.adoptOrganization(resolved);
-    if (isDebugEnabled()) {
-      process.stderr.write(`[mutagent] Stored organization was rejected by the API; re-resolved and retried once.
-`);
-    }
-    return resolved;
-  }
-  return async function fetchWithOrgRecovery(input, init) {
-    const retryTemplate = input instanceof Request ? input.clone() : undefined;
-    const response = init == null ? await fetch(input) : await fetch(input, init);
-    if (response.status !== 403)
-      return response;
-    const body = await response.clone().text().catch(() => "");
-    if (!isOrganizationScopeMismatch(response.status, body))
-      return response;
-    const resolved = await recover();
-    if (!resolved)
-      return response;
-    if (retryTemplate) {
-      retryTemplate.headers.set("x-organization-id", resolved);
-      return fetch(retryTemplate);
-    }
-    const headers = new Headers(init?.headers);
-    headers.set("x-organization-id", resolved);
-    return fetch(input, { ...init, headers });
-  };
-}
-var ORGANIZATION_ID_PATTERN;
-var init_organization_scope = __esm(() => {
-  init_errors();
-  init_sdk_debug();
-  ORGANIZATION_ID_PATTERN = /^org_[A-Za-z0-9_-]{8,}$/;
-});
-
-// src/lib/config.ts
-import { cosmiconfigSync } from "cosmiconfig";
-import { z } from "zod";
-import { homedir as homedir2 } from "os";
-import { join as join7 } from "path";
-import { existsSync as existsSync2, readFileSync as readFileSync2, mkdirSync } from "fs";
-function parseJsonSafe(content, schema4) {
-  try {
-    const parsed = JSON.parse(content);
-    return schema4.parse(parsed);
-  } catch {
-    return null;
-  }
-}
-function loadConfig() {
-  const explorer = cosmiconfigSync("mutagent");
-  const result = explorer.search();
-  const rcConfig = result?.config;
-  let credentials = null;
-  if (existsSync2(CREDENTIALS_FILE)) {
-    credentials = parseJsonSafe(readFileSync2(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
-  }
-  const merged = {
-    providers: {},
-    environment: "production",
-    ...rcConfig,
-    ...credentials,
-    apiKey: process.env.MUTAGENT_API_KEY ?? credentials?.apiKey ?? rcConfig?.apiKey,
-    endpoint: process.env.MUTAGENT_ENDPOINT ?? credentials?.endpoint ?? rcConfig?.endpoint,
-    defaultWorkspace: process.env.MUTAGENT_WORKSPACE_ID ?? credentials?.defaultWorkspace ?? rcConfig?.defaultWorkspace,
-    defaultWorkspaceSource: process.env.MUTAGENT_WORKSPACE_ID ? "user" : credentials?.defaultWorkspace ? credentials.defaultWorkspaceSource ?? "login-inferred" : rcConfig?.defaultWorkspace ? "login-inferred" : undefined,
-    defaultOrganization: credentials?.defaultOrganization ?? rcConfig?.defaultOrganization
-  };
-  return configSchema.parse(merged);
-}
-function saveCredentials(apiKey, endpoint) {
-  if (!existsSync2(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  const config = loadConfig();
-  const credentials = {
-    apiKey,
-    endpoint: endpoint ?? config.endpoint
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
-}
-function saveFullCredentials(creds) {
-  if (!existsSync2(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync2(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const existingSource = existingCredentials.defaultWorkspaceSource;
-  const workspaceChanged = creds.workspaceId !== undefined && creds.workspaceId !== existingCredentials.defaultWorkspace;
-  const source2 = creds.workspaceId === undefined ? existingSource : workspaceChanged ? "login-inferred" : existingSource ?? "login-inferred";
-  const credentials = {
-    ...existingCredentials,
-    apiKey: creds.apiKey,
-    endpoint: creds.endpoint ?? existingCredentials.endpoint ?? "https://api.mutagent.io",
-    defaultWorkspace: creds.workspaceId ?? existingCredentials.defaultWorkspace,
-    defaultWorkspaceSource: source2,
-    defaultOrganization: creds.organizationId ?? existingCredentials.defaultOrganization,
-    expiresAt: creds.expiresAt
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
-}
-function clearCredentials() {
-  if (existsSync2(CREDENTIALS_FILE)) {
-    writeSecureFile(CREDENTIALS_FILE, JSON.stringify({}));
-  }
-}
-function hasCredentials() {
-  if (process.env.MUTAGENT_API_KEY)
-    return true;
-  if (!existsSync2(CREDENTIALS_FILE))
-    return false;
-  const credentials = parseJsonSafe(readFileSync2(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
-  return credentials?.apiKey !== undefined && credentials.apiKey !== "";
-}
-function getApiKey() {
-  const apiKey = process.env.MUTAGENT_API_KEY ?? loadConfig().apiKey;
-  registerSecret(apiKey);
-  return apiKey;
-}
-function setDefaultWorkspace(workspaceId, source2 = "user") {
-  if (!existsSync2(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync2(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const updated = {
-    ...existingCredentials,
-    defaultWorkspace: workspaceId,
-    defaultWorkspaceSource: source2
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
-}
-function setDefaultOrganization(organizationId) {
-  if (!isWellFormedOrganizationId(organizationId)) {
-    throw new MutagentError("INVALID_ORGANIZATION_ID", `"${organizationId}" is not an organization id.`, `Organization ids look like org_xxxxxxxxxxxxxxxxxxxxx.
-` + "List the ones you can use with: mutagent auth status");
-  }
-  if (!existsSync2(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync2(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const updated = {
-    ...existingCredentials,
-    defaultOrganization: organizationId
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
-}
-function clearDefaultOrganization() {
-  if (!existsSync2(CREDENTIALS_FILE))
-    return;
-  let existingCredentials;
-  try {
-    existingCredentials = JSON.parse(readFileSync2(CREDENTIALS_FILE, "utf-8"));
-  } catch {
-    return;
-  }
-  if (!("defaultOrganization" in existingCredentials))
-    return;
-  delete existingCredentials.defaultOrganization;
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(existingCredentials, null, 2));
-}
-var configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
-var init_config = __esm(() => {
-  init_secure_file();
-  init_known_secrets();
-  init_organization_scope();
-  init_errors();
-  configSchema = z.object({
-    apiKey: z.string().optional(),
-    endpoint: z.string().default("https://api.mutagent.io"),
-    format: z.enum(["table", "json"]).default("table"),
-    timeout: z.number().default(30000),
-    defaultWorkspace: z.string().optional(),
-    defaultWorkspaceSource: z.enum(["user", "login-inferred"]).optional(),
-    defaultOrganization: z.string().optional()
-  });
-  credentialsSchema = z.object({
-    apiKey: z.string().optional(),
-    endpoint: z.string().optional(),
-    defaultWorkspace: z.string().optional(),
-    defaultWorkspaceSource: z.enum(["user", "login-inferred"]).optional(),
-    defaultOrganization: z.string().optional(),
-    expiresAt: z.string().optional()
-  }).loose();
-  CREDENTIALS_DIR = join7(homedir2(), ".config", "mutagent");
-  CREDENTIALS_FILE = join7(CREDENTIALS_DIR, "credentials.json");
-});
-
-// src/lib/provider-request.ts
-function buildCreateProviderBody(data) {
-  const body = {
-    name: data.name,
-    provider: data.provider,
-    isDefault: data.isDefault ?? false
-  };
-  if (data.apiKey)
-    body.apiKey = data.apiKey;
-  if (data.baseUrl)
-    body.baseUrl = data.baseUrl;
-  if (data.hostedFamily)
-    body.hostedFamily = data.hostedFamily;
-  if (data.credentialFields && Object.keys(data.credentialFields).length > 0) {
-    body.credentialFields = data.credentialFields;
-  }
-  if (data.metadata && Object.keys(data.metadata).length > 0)
-    body.metadata = data.metadata;
-  if (data.supportedModels !== undefined)
-    body.supportedModels = data.supportedModels;
-  return body;
-}
-
-// src/lib/sdk-mappers.ts
-import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
-function isProviderType(value2) {
-  return PROVIDER_TYPES.includes(value2);
-}
-function narrowProviderType(value2) {
-  return isProviderType(value2) ? value2 : value2;
-}
-function toIsoString(value2) {
-  if (value2 === null || value2 === undefined)
-    return null;
-  return value2 instanceof Date ? value2.toISOString() : value2;
-}
-function toAgent(sdk) {
-  return {
-    id: sdk.id,
-    name: sdk.name,
-    slug: sdk.slug,
-    description: sdk.description,
-    systemPrompt: sdk.systemPrompt,
-    model: sdk.model,
-    maxTurns: sdk.maxTurns,
-    permissionMode: sdk.permissionMode,
-    allowedTools: sdk.allowedTools,
-    disallowedTools: sdk.disallowedTools,
-    status: sdk.status,
-    isPublic: sdk.isPublic,
-    metadata: sdk.metadata,
-    tags: sdk.tags,
-    createdBy: sdk.createdBy,
-    createdAt: toIsoString(sdk.createdAt),
-    updatedAt: toIsoString(sdk.updatedAt)
-  };
+function toAgent(sdk) {
+  return {
+    id: sdk.id,
+    name: sdk.name,
+    slug: sdk.slug,
+    description: sdk.description,
+    systemPrompt: sdk.systemPrompt,
+    model: sdk.model,
+    maxTurns: sdk.maxTurns,
+    permissionMode: sdk.permissionMode,
+    allowedTools: sdk.allowedTools,
+    disallowedTools: sdk.disallowedTools,
+    status: sdk.status,
+    isPublic: sdk.isPublic,
+    metadata: sdk.metadata,
+    tags: sdk.tags,
+    createdBy: sdk.createdBy,
+    createdAt: toIsoString(sdk.createdAt),
+    updatedAt: toIsoString(sdk.updatedAt)
+  };
 }
 function toAgentList(sdk) {
   return sdk.map(toAgent);
@@ -16977,15 +17143,6 @@ var init_sdk_mappers = __esm(() => {
 });
 
 // src/lib/sdk-client.ts
-var exports_sdk_client = {};
-__export(exports_sdk_client, {
-  validateApiKey: () => validateApiKey,
-  resetSDKClient: () => resetSDKClient,
-  getSDKClient: () => getSDKClient,
-  fetchWorkspaces: () => fetchWorkspaces,
-  fetchOrganizations: () => fetchOrganizations,
-  MutagentSDK: () => SDKClientWrapper
-});
 import { Mutagent, HTTPClient } from "@mutagent/sdk";
 
 class SDKClientWrapper {
@@ -16994,32 +17151,24 @@ class SDKClientWrapper {
   endpoint;
   workspaceId;
   organizationId;
-  workspaceResolution = "none";
+  tenancy;
   debugSecrets = new Set;
-  recoveringFetch;
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.endpoint = opts.serverURL ?? "http://localhost:3003";
     this.workspaceId = opts.workspaceId;
     this.organizationId = opts.organizationId;
-    if (opts.workspaceId && opts.workspaceSource === "user") {
-      this.workspaceResolution = "configured";
-    }
-    this.recoveringFetch = createOrgScopeRecoveringFetcher({
-      apiKey: this.apiKey,
-      endpoint: this.endpoint,
-      currentOrganization: () => this.organizationId,
-      adoptOrganization: (id) => {
-        this.organizationId = id;
-      },
-      forgetStoredOrganization: opts.clearStoredOrganization
-    });
-    const httpClient = new HTTPClient({ fetcher: this.recoveringFetch });
+    this.tenancy = {
+      keyScope: opts.keyScope,
+      workspaceId: opts.workspaceId,
+      workspaceName: opts.workspaceName,
+      workspaceOrigin: opts.workspaceOrigin ?? (opts.workspaceId ? "selection" : undefined),
+      organizationName: opts.organizationName
+    };
+    const httpClient = new HTTPClient;
     httpClient.addHook("beforeRequest", (req) => {
-      if (this.workspaceId)
-        req.headers.set("x-workspace-id", this.workspaceId);
-      if (this.organizationId)
-        req.headers.set("x-organization-id", this.organizationId);
+      for (const [name, value2] of Object.entries(this.tenancyHeaders()))
+        req.headers.set(name, value2);
       return req;
     });
     this.debugSecrets.add(this.apiKey);
@@ -17034,8 +17183,16 @@ class SDKClientWrapper {
     });
   }
   handleError(error3) {
+    if (error3 instanceof Error && SDK_TRANSPORT_ERRORS.has(error3.name)) {
+      throw unreachableServerError(this.endpoint);
+    }
     if (error3 && typeof error3 === "object") {
       const err = error3;
+      if (err.statusCode) {
+        const tenancy = tenancyFailure(err.statusCode, err.body ?? "", this.tenancy);
+        if (tenancy)
+          throw tenancy;
+      }
       if (err.statusCode === 401) {
         throw new AuthenticationError;
       }
@@ -17056,7 +17213,7 @@ class SDKClientWrapper {
     }
     if (error3 instanceof TypeError && typeof error3.message === "string") {
       if (error3.message.includes("fetch") || error3.message.includes("network") || error3.message.includes("ECONNREFUSED")) {
-        throw new MutagentError("NETWORK_ERROR", "Unable to connect to the Mutagent server", "Check your internet connection and verify the server URL with: mutagent config list");
+        throw unreachableServerError(this.endpoint);
       }
     }
     if (error3 instanceof Error) {
@@ -17074,28 +17231,31 @@ class SDKClientWrapper {
     } else if (optHeaders) {
       extraHeaders = optHeaders;
     }
-    const tenancyHeaders = {};
-    if (this.workspaceId)
-      tenancyHeaders["x-workspace-id"] = this.workspaceId;
-    if (this.organizationId)
-      tenancyHeaders["x-organization-id"] = this.organizationId;
-    const response = await this.recoveringFetch(`${this.endpoint}${path}`, {
-      ...options,
-      headers: {
-        "x-api-key": this.apiKey,
-        "Content-Type": "application/json",
-        ...tenancyHeaders,
-        ...extraHeaders
-      }
-    });
+    let response;
+    try {
+      response = await fetch(`${this.endpoint}${path}`, {
+        ...options,
+        headers: {
+          "x-api-key": this.apiKey,
+          "Content-Type": "application/json",
+          ...this.tenancyHeaders(),
+          ...extraHeaders
+        }
+      });
+    } catch {
+      throw unreachableServerError(this.endpoint);
+    }
     if (!response.ok) {
+      const error3 = await response.text();
+      const tenancy = tenancyFailure(response.status, error3, this.tenancy);
+      if (tenancy)
+        throw tenancy;
       if (response.status === 401) {
         throw new AuthenticationError;
       }
       if (response.status === 403) {
-        throw new ApiError(403, await response.text() || "Access denied");
+        throw new ApiError(403, error3 || "Access denied");
       }
-      const error3 = await response.text();
       const errorLower = error3.toLowerCase();
       if (errorLower.includes("workspace") && (errorLower.includes("missing") || errorLower.includes("required")) || errorLower.includes("x-workspace-id")) {
         throw new WorkspaceContextError(error3);
@@ -17241,11 +17401,9 @@ class SDKClientWrapper {
   }
   async getModelsCatalog() {
     try {
-      const wsId = this.workspaceId;
-      if (!wsId)
+      if (!this.workspaceId)
         return { models: [] };
-      const qs = `?workspaceId=${encodeURIComponent(wsId)}`;
-      return await this.request(`/api/providers/catalog${qs}`);
+      return await this.request("/api/providers/catalog");
     } catch {
       return { models: [] };
     }
@@ -17253,56 +17411,17 @@ class SDKClientWrapper {
   getCurrentWorkspaceId() {
     return this.workspaceId;
   }
-  getCurrentOrgId() {
-    return this.organizationId;
-  }
-  async ensureContext() {
-    const needsWorkspaceClassification = !this.workspaceId || this.workspaceResolution === "none";
-    if (this.organizationId && !needsWorkspaceClassification)
-      return;
-    if (!this.organizationId) {
-      let orgs = await fetchOrganizations(this.apiKey, this.endpoint).catch(() => []);
-      if (orgs.length === 0) {
-        await new Promise((r) => setTimeout(r, 1000));
-        orgs = await fetchOrganizations(this.apiKey, this.endpoint).catch(() => []);
-      }
-      if (orgs.length > 0 && orgs[0]) {
-        this.organizationId = orgs[0].id;
-      }
-    }
-    if (this.workspaceResolution === "none" && this.organizationId) {
-      try {
-        const response = await this.sdk.workspaces.listWorkspaces({ includeInactive: false });
-        const workspaces = toWorkspaceList(response.workspaces);
-        if (workspaces.length === 1 && workspaces[0]) {
-          this.workspaceId = workspaces[0].id;
-          this.workspaceResolution = "sole";
-        } else if (workspaces.length > 1) {
-          const defaultWs = workspaces.find((ws) => ws.isDefault);
-          if (defaultWs) {
-            this.workspaceId = defaultWs.id;
-            this.workspaceResolution = "configured";
-          } else {
-            const first = workspaces[0] ?? undefined;
-            if (first) {
-              this.workspaceId = this.workspaceId ?? first.id;
-              this.workspaceResolution = "ambiguous";
-            }
-          }
-        }
-      } catch {}
-    }
-  }
-  getWorkspaceResolution() {
-    return this.workspaceResolution;
+  tenancyHeaders() {
+    return tenancyHeaders({
+      keyScope: this.tenancy.keyScope,
+      workspaceId: this.workspaceId,
+      workspaceOrigin: this.tenancy.workspaceOrigin,
+      organizationId: this.organizationId
+    });
   }
-  requireUnambiguousWorkspace() {
-    if (!this.workspaceId || this.workspaceResolution === "none") {
-      throw new MutagentError("WORKSPACE_REQUIRED", "No workspace configured.", "Set one with: mutagent config set workspace <workspace-id>  (list them with: mutagent workspaces list)");
-    }
-    if (this.workspaceResolution === "ambiguous") {
-      throw new MutagentError("WORKSPACE_AMBIGUOUS", "Several workspaces are available and none is marked default, so the target for this write is ambiguous.", "Choose one explicitly: mutagent config set workspace <workspace-id>  (list them with: mutagent workspaces list)");
-    }
+  requireSelectedWorkspace() {
+    if (!this.workspaceId)
+      throw noWorkspaceSelected();
     return this.workspaceId;
   }
   async testProvider(id) {
@@ -17316,7 +17435,7 @@ class SDKClientWrapper {
     }
   }
   async createProvider(data) {
-    this.requireUnambiguousWorkspace();
+    this.requireSelectedWorkspace();
     registerSecret(data.apiKey);
     registerSecretFields(data.credentialFields);
     const body = buildCreateProviderBody(data);
@@ -17331,7 +17450,7 @@ class SDKClientWrapper {
     }
   }
   async updateProvider(id, data) {
-    const workspaceId = this.requireUnambiguousWorkspace();
+    const workspaceId = this.requireSelectedWorkspace();
     if (data.apiKey)
       this.debugSecrets.add(data.apiKey);
     registerSecret(data.apiKey);
@@ -17370,7 +17489,7 @@ class SDKClientWrapper {
     }
   }
   async deleteProvider(id) {
-    const workspaceId = this.requireUnambiguousWorkspace();
+    const workspaceId = this.requireSelectedWorkspace();
     try {
       await this.sdk.llmProviders.deleteProviderConfig({ id });
       return { workspaceId };
@@ -17385,21 +17504,18 @@ async function getSDKClient() {
     if (!apiKey) {
       throw new AuthenticationError;
     }
-    const config = loadConfig();
+    const tenancy = await resolveKeyTenancy(apiKey);
+    if (tenancy.keyScope === "organization" && !tenancy.workspaceId)
+      throw noWorkspaceSelected();
     sdkClient = new SDKClientWrapper({
       apiKey,
-      serverURL: config.endpoint,
-      workspaceId: config.defaultWorkspace,
-      organizationId: config.defaultOrganization,
-      workspaceSource: config.defaultWorkspaceSource,
-      clearStoredOrganization: clearDefaultOrganization
-    });
-    await sdkClient.ensureContext().catch((err) => {
-      if (isDebugEnabled()) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[mutagent] Context resolution failed: ${message}
-`);
-      }
+      serverURL: tenancy.endpoint,
+      workspaceId: tenancy.workspaceId,
+      workspaceName: tenancy.workspaceName,
+      workspaceOrigin: tenancy.workspaceOrigin,
+      organizationId: tenancy.organization?.id,
+      organizationName: tenancy.organization?.name,
+      keyScope: tenancy.keyScope
     });
   }
   return sdkClient;
@@ -17417,20 +17533,7 @@ async function validateApiKey(apiKey, endpoint) {
     return false;
   }
 }
-async function fetchWorkspaces(apiKey, endpoint, orgId) {
-  try {
-    const response = await fetch(`${endpoint}/api/workspaces`, {
-      headers: { "x-api-key": apiKey, "x-organization-id": orgId }
-    });
-    if (!response.ok)
-      return [];
-    const data = await response.json();
-    return data.workspaces ?? [];
-  } catch {
-    return [];
-  }
-}
-var sdkClient = null;
+var SDK_TRANSPORT_ERRORS, sdkClient = null;
 var init_sdk_client = __esm(() => {
   init_errors();
   init_config();
@@ -17439,6 +17542,7 @@ var init_sdk_client = __esm(() => {
   init_known_secrets();
   init_sdk_mappers();
   init_organization_scope();
+  SDK_TRANSPORT_ERRORS = new Set(["ConnectionError", "RequestTimeoutError", "RequestAbortedError", "UnexpectedClientError"]);
 });
 
 // src/lib/agent/sdk.ts
@@ -17558,7 +17662,7 @@ async function createAgentDeploymentAPI() {
   const context = await getSDKClient();
   let workspaceId;
   try {
-    workspaceId = context.requireUnambiguousWorkspace();
+    workspaceId = context.requireSelectedWorkspace();
   } catch (error3) {
     if (error3 instanceof MutagentError)
       error3.exitCode = 3;
@@ -18496,17 +18600,13 @@ async function installHelix(options, deps = {}) {
 
 // src/lib/install-telemetry.ts
 init_config();
+init_organization_scope();
 var TELEMETRY_TIMEOUT_MS = 1500;
 function resolveApiAuth() {
   const apiKey = getApiKey();
   const config = loadConfig();
   const apiBase = config.endpoint ?? "https://api.mutagent.io";
-  const headers = {};
-  if (config.defaultWorkspace)
-    headers["x-workspace-id"] = config.defaultWorkspace;
-  if (config.defaultOrganization)
-    headers["x-organization-id"] = config.defaultOrganization;
-  return { apiBase, apiKey, headers };
+  return { apiBase, apiKey, headers: configTenancyHeaders(config) };
 }
 async function reportInstall(event, deps = {}) {
   try {
@@ -18619,6 +18719,7 @@ async function runPostOnboarding(deps = {}) {
 // src/lib/auth-flow.ts
 init_config();
 init_sdk_client();
+init_organization_scope();
 init_errors();
 import { input, password, select } from "@inquirer/prompts";
 import chalk3 from "chalk";
@@ -18667,6 +18768,17 @@ async function openBrowser(url) {
     throw new BrowserAuthError("BROWSER_OPEN_FAILED", `Could not open browser automatically. Please visit: ${url}`);
   }
 }
+function withOrgPreselect(authUrl, org) {
+  if (!org)
+    return authUrl;
+  try {
+    const url = new URL(authUrl);
+    url.searchParams.set("org", org);
+    return url.toString();
+  } catch {
+    return `${authUrl}${authUrl.includes("?") ? "&" : "?"}org=${encodeURIComponent(org)}`;
+  }
+}
 function sleep(ms) {
   return new Promise((resolve6) => setTimeout(resolve6, ms));
 }
@@ -18680,7 +18792,7 @@ async function performBrowserAuth(options, onStatusUpdate) {
   const cliToken = generateCliToken();
   onStatusUpdate?.("Initializing browser authentication...");
   const initResponse = await initBrowserAuth(endpoint, cliToken);
-  const { authUrl } = initResponse;
+  const authUrl = withOrgPreselect(initResponse.authUrl, options.org);
   if (!skipBrowserOpen) {
     onStatusUpdate?.("Opening browser for authentication...");
     try {
@@ -18797,7 +18909,7 @@ async function performLoginAction(opts) {
     useBrowserAuth = method === "browser";
   }
   if (useBrowserAuth) {
-    return loginWithBrowser(endpoint, output, wasFirstLogin);
+    return loginWithBrowser(endpoint, output, wasFirstLogin, opts.org);
   }
   return loginWithPastedKey(endpoint, output, wasFirstLogin);
 }
@@ -18814,55 +18926,76 @@ function buildLoginJsonResponse(result) {
     }
   };
 }
-async function loginWithExistingKey(apiKey, endpoint, output, wasFirstLogin) {
-  output.info("Validating API key...");
-  const isValid = await validateApiKey(apiKey, endpoint);
-  if (!isValid) {
-    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+async function describeKey(apiKey, endpoint, pick3) {
+  let self;
+  try {
+    self = await fetchKeySelf(apiKey, endpoint);
+  } catch {
+    return {};
   }
-  const orgs = await fetchOrganizations(apiKey, endpoint);
-  let orgId;
-  let orgName;
-  let wsId;
-  let wsName;
-  if (orgs.length >= 1 && orgs[0]) {
-    orgId = orgs[0].id;
-    orgName = orgs[0].name;
-    const workspaces = await fetchWorkspaces(apiKey, endpoint, orgId);
-    const defaultWs = workspaces.find((w) => w.isDefault) ?? workspaces[0];
-    if (defaultWs) {
-      wsId = defaultWs.id;
-      wsName = defaultWs.name;
-    }
-  }
-  saveFullCredentials({
-    apiKey,
-    endpoint,
-    workspaceId: wsId,
-    organizationId: orgId
-  });
+  const organization = self.organization ?? undefined;
+  const scope = {
+    keyScope: self.scope,
+    organizationId: organization?.id,
+    organizationName: organization?.name,
+    organizationSlug: organization?.slug
+  };
+  if (self.workspace) {
+    return { ...scope, workspaceId: self.workspace.id, workspaceName: self.workspace.name };
+  }
+  const envWorkspace = process.env.MUTAGENT_WORKSPACE_ID?.trim();
+  const rows = await listKeyWorkspaces(apiKey, endpoint, { keyScope: self.scope, organization }).catch(() => []);
+  let chosen;
+  if (envWorkspace)
+    chosen = rows.find((w) => w.id === envWorkspace);
+  else if (rows.length === 1)
+    chosen = rows[0];
+  else if (pick3 && rows.length > 1) {
+    const id = await pick3(rows);
+    chosen = rows.find((w) => w.id === id);
+  }
+  return chosen ? { ...scope, workspaceId: chosen.id, workspaceName: chosen.name } : scope;
+}
+function loginResult(apiKey, endpoint, described, wasFirstLogin) {
   return {
     authenticated: true,
     apiKey,
     endpoint,
-    workspace: wsId ? { id: wsId, name: wsName } : null,
-    organization: orgId ? { id: orgId, name: orgName } : null,
+    workspace: described.workspaceId ? { id: described.workspaceId, name: described.workspaceName } : null,
+    organization: described.organizationId ? { id: described.organizationId, name: described.organizationName } : null,
     wasFirstLogin
   };
 }
-async function loginWithBrowser(endpoint, output, wasFirstLogin) {
+async function loginWithExistingKey(apiKey, endpoint, output, wasFirstLogin) {
+  output.info("Validating API key...");
+  const isValid = await validateApiKey(apiKey, endpoint);
+  if (!isValid) {
+    throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
+  }
+  const described = await describeKey(apiKey, endpoint);
+  saveFullCredentials({ apiKey, endpoint, ...described });
+  return loginResult(apiKey, endpoint, described, wasFirstLogin);
+}
+async function loginWithBrowser(endpoint, output, wasFirstLogin, org) {
   const spinner = ora2({ text: "Opening browser for authentication...", spinner: "dots" });
   try {
     spinner.start();
-    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000 }, (message) => {
+    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000, org }, (message) => {
       spinner.text = message;
     });
     spinner.succeed("Authenticated successfully!");
+    const self = await fetchKeySelf(result.apiKey, endpoint).catch(() => {
+      return;
+    });
     saveFullCredentials({
       apiKey: result.apiKey,
       endpoint,
       workspaceId: result.workspaceId,
+      workspaceName: result.workspaceName,
       organizationId: result.organizationId,
+      organizationName: result.organizationName,
+      organizationSlug: self?.organization?.slug,
+      keyScope: self?.scope,
       expiresAt: result.expiresAt
     });
     if (result.workspaceName)
@@ -18900,55 +19033,12 @@ async function loginWithPastedKey(initialEndpoint, output, wasFirstLogin) {
   if (!isValid) {
     throw new MutagentError("INVALID_API_KEY", "Invalid API key or endpoint", "Check your API key and try again");
   }
-  let selectedOrgId;
-  let selectedOrgName;
-  let selectedWsId;
-  let selectedWsName;
-  const orgs = await fetchOrganizations(apiKey, endpoint);
-  if (orgs.length === 1 && orgs[0]) {
-    selectedOrgId = orgs[0].id;
-    selectedOrgName = orgs[0].name;
-  } else if (orgs.length > 1) {
-    selectedOrgId = await select({
-      message: "Select organization:",
-      choices: orgs.map((o) => ({ name: o.name, value: o.id }))
-    });
-    selectedOrgName = orgs.find((o) => o.id === selectedOrgId)?.name;
-  }
-  if (selectedOrgId) {
-    const workspaces = await fetchWorkspaces(apiKey, endpoint, selectedOrgId);
-    const defaultWs = workspaces.find((w) => w.isDefault);
-    if (workspaces.length === 1 && workspaces[0]) {
-      selectedWsId = workspaces[0].id;
-      selectedWsName = workspaces[0].name;
-    } else if (defaultWs) {
-      selectedWsId = defaultWs.id;
-      selectedWsName = defaultWs.name;
-    } else if (workspaces.length > 1) {
-      selectedWsId = await select({
-        message: "Select workspace:",
-        choices: workspaces.map((w) => ({
-          name: w.name + (w.isDefault ? " (default)" : ""),
-          value: w.id
-        }))
-      });
-      selectedWsName = workspaces.find((w) => w.id === selectedWsId)?.name;
-    }
-  }
-  saveFullCredentials({
-    apiKey,
-    endpoint,
-    workspaceId: selectedWsId,
-    organizationId: selectedOrgId
-  });
-  return {
-    authenticated: true,
-    apiKey,
-    endpoint,
-    workspace: selectedWsId ? { id: selectedWsId, name: selectedWsName } : null,
-    organization: selectedOrgId ? { id: selectedOrgId, name: selectedOrgName } : null,
-    wasFirstLogin
-  };
+  const described = await describeKey(apiKey, endpoint, async (rows) => rows.find((w) => w.isDefault)?.id ?? select({
+    message: "Select workspace:",
+    choices: rows.map((w) => ({ name: w.name, value: w.id }))
+  }));
+  saveFullCredentials({ apiKey, endpoint, ...described });
+  return loginResult(apiKey, endpoint, described, wasFirstLogin);
 }
 
 // src/commands/auth.ts
@@ -18978,6 +19068,7 @@ See mutagent login --help for the full description.
         endpoint: options.endpoint,
         browser: options.browser,
         nonInteractive: options.nonInteractive,
+        org: auth.optsWithGlobals().org,
         isJson,
         output
       });
@@ -18990,7 +19081,7 @@ See mutagent login --help for the full description.
         if (result.workspace?.name)
           output.info(`Workspace: ${result.workspace.name}`);
         output.info(`Endpoint: ${result.endpoint}`);
-        output.info("Next: mutagent workspaces list --json");
+        output.info(result.workspace ? "Next: mutagent workspaces current" : "Next: mutagent workspaces use <name>");
       }
       if (result.wasFirstLogin && process.stdin.isTTY && !isJson) {
         await runPostOnboarding();
@@ -19094,10 +19185,13 @@ Examples:
   ${chalk5.dim("$")} mutagent login                          ${chalk5.dim("# In a terminal, choose browser or API key")}
   ${chalk5.dim("$")} mutagent login --browser                ${chalk5.dim("# Sign in with the browser")}
   ${chalk5.dim("$")} mutagent login --non-interactive        ${chalk5.dim("# Browser sign-in without the method prompt (a person approves in the browser)")}
+  ${chalk5.dim("$")} mutagent login --org <slug>              ${chalk5.dim("# Sign in for another organization (preselected on the approval page)")}
   ${chalk5.dim("$")} MUTAGENT_API_KEY=mt_... mutagent login --json   ${chalk5.dim("# Sign in with a key (CI)")}
 
 Browser sign-in opens app.mutagent.io, where you sign in or sign up, finish onboarding
 and approve this CLI. The CLI waits up to 5 minutes and saves the credentials.
+The key works in every workspace you are a member of in the approved organization, for
+30 days. The approved workspace is selected; switch with mutagent workspaces use <name>.
 
 When MUTAGENT_API_KEY is set, login skips the browser and validates the key.
 
@@ -19108,8 +19202,8 @@ Environment:
   CI=true                        Same as --non-interactive
 
 Then:
-  ${chalk5.dim("$")} mutagent auth status
-  ${chalk5.dim("$")} mutagent workspaces list --json
+  ${chalk5.dim("$")} mutagent workspaces current
+  ${chalk5.dim("$")} mutagent workspaces use <name>
 
 mutagent auth login runs the same sign-in.
     `).action(async (options) => {
@@ -19120,6 +19214,7 @@ mutagent auth login runs the same sign-in.
         endpoint: options.endpoint,
         browser: options.browser,
         nonInteractive: options.nonInteractive,
+        org: login.optsWithGlobals().org,
         isJson,
         output
       });
@@ -19132,7 +19227,7 @@ mutagent auth login runs the same sign-in.
         if (result.workspace?.name)
           output.info(`Workspace: ${result.workspace.name}`);
         output.info(`Endpoint: ${result.endpoint}`);
-        output.info("Next: mutagent workspaces list --json");
+        output.info(result.workspace ? "Next: mutagent workspaces current" : "Next: mutagent workspaces use <name>");
       }
       if (result.wasFirstLogin && process.stdin.isTTY && !isJson) {
         await runPostOnboarding();
@@ -19150,163 +19245,163 @@ mutagent auth login runs the same sign-in.
 
 // src/commands/config.ts
 init_config();
+import { Command as Command5 } from "commander";
+import chalk7 from "chalk";
+init_errors();
+init_organization_scope();
+
+// src/commands/workspaces.ts
+init_sdk_client();
 import { Command as Command4 } from "commander";
 import chalk6 from "chalk";
 init_errors();
-init_sdk_client();
+init_config();
 init_organization_scope();
-var VALID_CONFIG_KEYS = ["apiKey", "endpoint", "format", "timeout", "defaultWorkspace", "defaultOrganization"];
-function createConfigCommand() {
-  const config = new Command4("config").description("Manage CLI configuration").addHelpText("after", `
+async function useWorkspace(value2) {
+  const apiKey = getApiKey();
+  if (!apiKey)
+    throw new AuthenticationError;
+  if (envKeyReplacesFile())
+    throw envKeyHasNoSelection();
+  const tenancy = await resolveKeyTenancy(apiKey, { resolveOverride: false });
+  const config = loadConfig();
+  const workspace = await findWorkspace(value2, {
+    apiKey,
+    endpoint: tenancy.endpoint,
+    keyScope: tenancy.keyScope,
+    organization: tenancy.organization,
+    workspaceId: config.workspaceOrigin === "selection" ? tenancy.workspaceId : undefined,
+    workspaceName: config.workspaceOrigin === "selection" ? tenancy.workspaceName : undefined
+  });
+  setWorkspaceSelection(workspace.id, workspace.name);
+  resetSDKClient();
+  const org = tenancy.organization;
+  return { workspace, organization: org ? { id: org.id, name: org.name } : null };
+}
+function createWorkspacesCommand() {
+  const workspaces = new Command4("workspaces").alias("workspace").description("List, select and inspect workspaces").addHelpText("after", `
 Examples:
-  ${chalk6.dim("$")} mutagent config list
-  ${chalk6.dim("$")} mutagent config get endpoint
-  ${chalk6.dim("$")} mutagent config set workspace <workspace-id>
-  ${chalk6.dim("$")} mutagent config set org <org-id>
+  ${chalk6.dim("$")} mutagent workspaces list
+  ${chalk6.dim("$")} mutagent workspaces use <name|id>       ${chalk6.dim("# Every later command works in this workspace")}
+  ${chalk6.dim("$")} mutagent workspaces current --json
+  ${chalk6.dim("$")} mutagent providers list --workspace <name|id>   ${chalk6.dim("# One command in another workspace")}
+
+The CLI key from \`mutagent login\` works in every workspace you are a member of in its
+organization. Workspace precedence: --workspace, then MUTAGENT_WORKSPACE_ID, then the
+workspace chosen with \`workspaces use\`.
+To work in another organization: mutagent login --org <slug>
+Create or change workspaces in the dashboard: ${getAppBaseUrl()}
     `);
-  config.command("list").description("List all configuration").addHelpText("after", `
+  workspaces.command("list").description("List your workspaces in the key's organization (* = selected)").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").addHelpText("after", `
 Examples:
-  ${chalk6.dim("$")} mutagent config list
-  ${chalk6.dim("$")} mutagent config list --json
-    `).action(() => {
-    const isJson = getJsonFlag(config);
-    const output = new OutputFormatter(isJson ? "json" : "table");
-    const cfg = loadConfig();
-    const display = {
-      ...cfg,
-      apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : undefined
-    };
-    output.output(display);
-  });
-  config.command("get").description("Get configuration value").argument("<key>", "Configuration key (apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization)").addHelpText("after", `
-Examples:
-  ${chalk6.dim("$")} mutagent config get endpoint
-  ${chalk6.dim("$")} mutagent config get defaultWorkspace
-  ${chalk6.dim("$")} mutagent config get apiKey --json
+  ${chalk6.dim("$")} mutagent workspaces list
+  ${chalk6.dim("$")} mutagent workspaces list --limit 10 --json
 
-${chalk6.dim("Keys: apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization")}
-${chalk6.dim("A key with no value set is reported as unknown.")}
-    `).action((key) => {
-    const isJson = getJsonFlag(config);
+Lists only workspaces you are a member of. Works even when the selected workspace is no
+longer available, so you can pick another with: mutagent workspaces use <name>
+    `).action(async (options) => {
+    const isJson = getJsonFlag(workspaces);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
-      const cfg = loadConfig();
-      if (!(key in cfg)) {
-        throw new MutagentError("INVALID_ARGUMENTS", `Unknown config key: "${key}"`, `Valid keys: ${VALID_CONFIG_KEYS.join(", ")}
-` + "Example: mutagent config get endpoint");
-      }
-      const value2 = cfg[key];
-      const stringValue = typeof value2 === "object" ? JSON.stringify(value2) : String(value2 ?? "");
-      const displayValue = key === "apiKey" && value2 ? `${stringValue.slice(0, 8)}...` : stringValue;
+      const apiKey = getApiKey();
+      if (!apiKey)
+        throw new AuthenticationError;
+      const tenancy = await resolveKeyTenancy(apiKey, { resolveOverride: false });
+      const rows = await listKeyWorkspaces(apiKey, tenancy.endpoint, tenancy);
+      const offset = options.offset ? parseInt(options.offset, 10) : 0;
+      const limit = parseInt(options.limit, 10) || 50;
+      const page = rows.slice(offset, offset + limit);
+      const selected = tenancy.workspaceId;
       if (isJson) {
-        output.output({ [key]: displayValue });
+        output.output({
+          data: page.map((w) => ({
+            id: w.id,
+            name: w.name,
+            slug: w.slug,
+            isDefault: w.isDefault,
+            selected: w.id === selected,
+            _links: workspaceLinks(w.id)
+          })),
+          total: rows.length
+        });
       } else {
-        output.info(displayValue);
+        output.output(page.map((w) => ({
+          selected: w.id === selected ? "*" : "",
+          id: w.id,
+          name: w.name,
+          slug: w.slug,
+          url: workspaceLink(w.id)
+        })));
       }
     } catch (error3) {
       handleError(error3, isJson);
     }
   });
-  const set2 = new Command4("set").description("Set configuration value").action(() => {
-    set2.help();
-  });
-  set2.command("workspace").description("Set default workspace ID").argument("<id>", "Workspace ID to set as default").addHelpText("after", `
+  workspaces.command("use").description("Select the workspace every later command works in").argument("<name|id>", "Workspace name or id").addHelpText("after", `
 Examples:
-  ${chalk6.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk6.dim("$")} mutagent workspaces use staging
+  ${chalk6.dim("$")} mutagent workspaces use <workspace-id> --json
 
-${chalk6.dim("Commands use this workspace until you change it.")}
-    `).action((id) => {
-    const isJson = getJsonFlag(config);
-    const output = new OutputFormatter(isJson ? "json" : "table");
-    setDefaultWorkspace(id);
-    resetSDKClient();
-    if (isJson) {
-      output.output({ success: true, defaultWorkspace: id });
-    } else {
-      output.success(`Default workspace set to ${id}`);
-    }
-  });
-  set2.command("org").description("Set default organization ID").argument("<id>", "Organization ID to set as default").addHelpText("after", `
-Examples:
-  ${chalk6.dim("$")} mutagent config set org <org-id>
-
-${chalk6.dim("Persists organization ID for org-scoped API keys.")}
-${chalk6.dim("The ID is checked against your account first — a stored organization the")}
-${chalk6.dim("API key does not own makes every later command fail with 403.")}
-    `).action(async (id) => {
-    const isJson = getJsonFlag(config);
+Resolves against your workspaces in the key's organization and saves the choice. No
+browser and no prompt. A workspace in another organization needs a key for that
+organization: mutagent login --org <slug>. Two workspaces with the same name: pass the id.
+    `).action(async (value2) => {
+    const isJson = getJsonFlag(workspaces);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
-      await assertUsableOrganizationId(id, {
-        apiKey: getApiKey(),
-        endpoint: loadConfig().endpoint ?? "https://api.mutagent.io",
-        fetchOrganizations
-      });
-      setDefaultOrganization(id);
-      resetSDKClient();
+      const result = await useWorkspace(value2);
       if (isJson) {
-        output.output({ success: true, defaultOrganization: id });
+        output.output({ success: true, ...result, _links: workspaceLinks(result.workspace.id) });
       } else {
-        output.success(`Default organization set to ${id}`);
+        output.success(`Workspace: ${result.workspace.name} (${result.workspace.id})`);
       }
     } catch (error3) {
       handleError(error3, isJson);
     }
   });
-  config.addCommand(set2);
-  return config;
-}
-
-// src/commands/workspaces.ts
-init_sdk_client();
-import { Command as Command5 } from "commander";
-import chalk7 from "chalk";
-init_errors();
-function createWorkspacesCommand() {
-  const workspaces = new Command5("workspaces").description("View workspaces (read-only)").addHelpText("after", `
+  workspaces.command("current").description("Show the key's scope, organization and the verified workspace").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent workspaces list
-  ${chalk7.dim("$")} mutagent workspaces get <workspace-id>
+  ${chalk6.dim("$")} mutagent workspaces current
+  ${chalk6.dim("$")} mutagent workspaces current --json
 
-Choose the active workspace with: mutagent config set workspace <workspace-id>
-Create or change workspaces in the dashboard: https://app.mutagent.io
-    `);
-  workspaces.command("list").description("List all workspaces").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").addHelpText("after", `
-Examples:
-  ${chalk7.dim("$")} mutagent workspaces list
-  ${chalk7.dim("$")} mutagent workspaces list --limit 10 --json
-    `).action(async (options) => {
+Asks the server (GET /api/api-keys/self) with the workspace this command would use, so
+the answer is verified, not read from local config.
+    `).action(async () => {
     const isJson = getJsonFlag(workspaces);
     const output = new OutputFormatter(isJson ? "json" : "table");
     try {
-      const client = await getSDKClient();
-      const filters = {
-        limit: parseInt(options.limit, 10) || 50
-      };
-      if (options.offset) {
-        filters.offset = parseInt(options.offset, 10);
-      }
-      const result = await client.listWorkspaces(filters);
+      const apiKey = getApiKey();
+      if (!apiKey)
+        throw new AuthenticationError;
+      const tenancy = await resolveKeyTenancy(apiKey);
+      if (tenancy.keyScope === "organization" && !tenancy.workspaceId)
+        throw noWorkspaceSelected();
+      const headers = tenancyHeaders({
+        keyScope: tenancy.keyScope,
+        workspaceId: tenancy.workspaceId,
+        workspaceOrigin: tenancy.workspaceOrigin,
+        organizationId: tenancy.organization?.id
+      });
+      const self = await fetchKeySelf(apiKey, tenancy.endpoint, { headers, ctx: tenancy });
+      if (!envKeyReplacesFile())
+        recordKeyScope(self);
+      if (!self.workspace && self.scope === "organization")
+        throw noWorkspaceSelected();
       if (isJson) {
-        const withLinks = result.data.map((w) => ({
-          id: w.id,
-          name: w.name,
-          slug: w.slug,
-          isDefault: w.isDefault,
-          updatedAt: w.updatedAt,
-          _links: workspaceLinks(w.id)
-        }));
-        output.output({ ...result, data: withLinks });
+        output.output({
+          scope: self.scope,
+          organization: self.organization,
+          workspace: self.workspace,
+          expiresAt: self.expiresAt ?? null
+        });
       } else {
-        const formatted = result.data.map((w) => ({
-          id: w.id,
-          name: w.name,
-          slug: w.slug,
-          isDefault: w.isDefault ? "Yes" : "No",
-          updated: w.updatedAt ? new Date(w.updatedAt).toLocaleDateString() : "N/A",
-          url: workspaceLink(w.id)
-        }));
-        output.output(formatted);
+        output.info(`Key scope: ${self.scope}`);
+        if (self.organization)
+          output.info(`Organization: ${self.organization.name} (${self.organization.id})`);
+        if (self.workspace)
+          output.info(`Workspace: ${self.workspace.name} (${self.workspace.id})`);
+        if (self.expiresAt)
+          output.info(`Key expires: ${self.expiresAt}`);
       }
     } catch (error3) {
       handleError(error3, isJson);
@@ -19314,8 +19409,8 @@ Examples:
   });
   workspaces.command("get").description("Get workspace details").argument("<id>", "Workspace ID").addHelpText("after", `
 Examples:
-  ${chalk7.dim("$")} mutagent workspaces get <workspace-id>
-  ${chalk7.dim("$")} mutagent workspaces get <workspace-id> --json
+  ${chalk6.dim("$")} mutagent workspaces get <workspace-id>
+  ${chalk6.dim("$")} mutagent workspaces get <workspace-id> --json
     `).action(async (id) => {
     const isJson = getJsonFlag(workspaces);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -19345,6 +19440,115 @@ Examples:
   return workspaces;
 }
 
+// src/commands/config.ts
+var VALID_CONFIG_KEYS = ["apiKey", "endpoint", "format", "timeout", "defaultWorkspace", "workspaceName", "defaultOrganization", "organizationName", "keyScope"];
+function createConfigCommand() {
+  const config = new Command5("config").description("Manage CLI configuration").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent config list
+  ${chalk7.dim("$")} mutagent config get endpoint
+  ${chalk7.dim("$")} mutagent config set workspace <name|id>   ${chalk7.dim("# Same as: mutagent workspaces use")}
+    `);
+  config.command("list").description("List all configuration").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent config list
+  ${chalk7.dim("$")} mutagent config list --json
+    `).action(() => {
+    const isJson = getJsonFlag(config);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    const cfg = loadConfig();
+    const display = {
+      ...cfg,
+      apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : undefined
+    };
+    output.output(display);
+  });
+  config.command("get").description("Get configuration value").argument("<key>", `Configuration key (${VALID_CONFIG_KEYS.join(", ")})`).addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent config get endpoint
+  ${chalk7.dim("$")} mutagent config get defaultWorkspace
+  ${chalk7.dim("$")} mutagent config get apiKey --json
+
+${chalk7.dim(`Keys: ${VALID_CONFIG_KEYS.join(", ")}`)}
+${chalk7.dim("A key with no value set is reported as unknown.")}
+    `).action((key) => {
+    const isJson = getJsonFlag(config);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const cfg = loadConfig();
+      if (!(key in cfg)) {
+        throw new MutagentError("INVALID_ARGUMENTS", `Unknown config key: "${key}"`, `Valid keys: ${VALID_CONFIG_KEYS.join(", ")}
+` + "Example: mutagent config get endpoint");
+      }
+      const value2 = cfg[key];
+      const stringValue = typeof value2 === "object" ? JSON.stringify(value2) : String(value2 ?? "");
+      const displayValue = key === "apiKey" && value2 ? `${stringValue.slice(0, 8)}...` : stringValue;
+      if (isJson) {
+        output.output({ [key]: displayValue });
+      } else {
+        output.info(displayValue);
+      }
+    } catch (error3) {
+      handleError(error3, isJson);
+    }
+  });
+  const set2 = new Command5("set").description("Set configuration value").action(() => {
+    set2.help();
+  });
+  set2.command("workspace").description("Select the workspace every later command works in (same as: workspaces use)").argument("<name|id>", "Workspace name or id").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent config set workspace staging
+  ${chalk7.dim("$")} mutagent config set workspace <workspace-id>
+
+${chalk7.dim("Runs mutagent workspaces use: resolves the name among your workspaces and saves it.")}
+    `).action(async (value2) => {
+    const isJson = getJsonFlag(config);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const result = await useWorkspace(value2);
+      if (isJson) {
+        output.output({ success: true, defaultWorkspace: result.workspace.id, ...result });
+      } else {
+        output.success(`Workspace: ${result.workspace.name} (${result.workspace.id})`);
+      }
+    } catch (error3) {
+      handleError(error3, isJson);
+    }
+  });
+  set2.command("org").description("Confirm the key's organization (it comes from the key; nothing is stored)").argument("<id|slug>", "Organization id or slug").addHelpText("after", `
+Examples:
+  ${chalk7.dim("$")} mutagent config set org <org-id|slug>
+
+${chalk7.dim("The CLI key belongs to one organization. The same organization: nothing to do.")}
+${chalk7.dim("Another organization: sign in for it with mutagent login --org <id|slug>.")}
+    `).action(async (value2) => {
+    const isJson = getJsonFlag(config);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const apiKey = getApiKey();
+      if (!apiKey)
+        throw new AuthenticationError;
+      setOrgAssertion(value2);
+      const { organization } = await resolveKeyTenancy(apiKey, { resolveOverride: false });
+      if (!organization) {
+        throw new MutagentError("ORG_UNKNOWN", "This key's organization is unknown.", "Run: mutagent workspaces current");
+      }
+      if (!matchesOrganization(value2, organization)) {
+        throw orgMismatch(value2, organization);
+      }
+      if (isJson) {
+        output.output({ success: true, organization });
+      } else {
+        output.success(`Organization: ${organization.name} (${organization.id}), from the key`);
+      }
+    } catch (error3) {
+      handleError(error3, isJson);
+    }
+  });
+  config.addCommand(set2);
+  return config;
+}
+
 // src/commands/providers/index.ts
 init_sdk_client();
 import { Command as Command6 } from "commander";
@@ -19837,7 +20041,7 @@ anthropic for an endpoint that speaks the Anthropic API; unset, the server defau
 The base URL must be a public address: hosts ending in .internal, .local, .localhost or
 .home.arpa are refused.
 
-Adds the LLM provider to the configured workspace (mutagent config set workspace <id>).
+Adds the LLM provider to the configured workspace (mutagent workspaces use <name>, or --workspace for one command).
 The key is encrypted and never returned.
 Workspace default model: when the workspace has none, adding a keyed LLM provider sets
 one on the server. An existing workspace default model is never changed.
@@ -19875,7 +20079,7 @@ AI Agent Directive:
         validateApiFormat(providerType, options.apiFormat);
       }
       const client = await getSDKClient();
-      const workspaceId = client.requireUnambiguousWorkspace();
+      const workspaceId = client.requireSelectedWorkspace();
       const credentialFields = collectCredentialFields(options);
       if (secretWireName !== "apiKey")
         credentialFields[secretWireName] = secret;
@@ -20787,7 +20991,7 @@ function statusGlyph(result) {
   }
 }
 function registerMirrorCommand(parent) {
-  parent.command("mirror").description("Copy the API keys from your local Helix login store into the workspace as LLM providers").option("-y, --yes", "Consent without prompting (required when non-interactive)").option("--no-overwrite", "Leave LLM providers the workspace already has untouched").option("--workspace <id>", "Target workspace for this run (default: the configured one)").option("--channel <channel>", `Helix channel whose store is read: ${HELIX_CHANNELS2.join(" | ")}`, "stable").option("--provider <id>", "Only this local LLM provider id (repeatable)", (value2, prev = []) => [...prev, value2]).addHelpText("after", `
+  parent.command("mirror").description("Copy the API keys from your local Helix login store into the workspace as LLM providers").option("-y, --yes", "Consent without prompting (required when non-interactive)").option("--no-overwrite", "Leave LLM providers the workspace already has untouched").option("--channel <channel>", `Helix channel whose store is read: ${HELIX_CHANNELS2.join(" | ")}`, "stable").option("--provider <id>", "Only this local LLM provider id (repeatable)", (value2, prev = []) => [...prev, value2]).addHelpText("after", `
 Examples:
   ${chalk11.dim("$")} mutagent providers mirror
   ${chalk11.dim("$")} mutagent providers mirror --json                 ${chalk11.dim("Show the plan without sending anything")}
@@ -20816,6 +21020,9 @@ default model is never changed. Change it with
 
 Mirroring does not test the keys: check \`mutagent helix models\`, then run a model.
 
+--workspace <name|id> still works here: it is the global flag and targets this run only
+(mutagent workspaces use <name> changes the default).
+
 Requires \`mutagent login\` and a workspace. Keys are sent only to the configured
 endpoint and are never printed. Consent is asked once per run; without a terminal,
 --yes is required. Without it the run exits 2 (with --json it returns the plan).
@@ -20835,12 +21042,9 @@ AI Agent Directive:
     try {
       const apiKey = getApiKey();
       const config = loadConfig();
-      const workspaceId = options.workspace ?? config.defaultWorkspace;
+      const workspaceId = config.defaultWorkspace;
       if (!apiKey || !workspaceId) {
-        throw new MutagentError("AUTH_REQUIRED", "No platform identity for this machine — run `mutagent auth login` first.", "mutagent auth login  (then, if needed: mutagent config set workspace <workspace-id>)", MIRROR_EXIT_NO_IDENTITY);
-      }
-      if (options.workspace) {
-        process.env.MUTAGENT_WORKSPACE_ID = options.workspace;
+        throw new MutagentError("AUTH_REQUIRED", "No platform identity for this machine — run `mutagent auth login` first.", "mutagent login  (then, if needed: mutagent workspaces use <name>)", MIRROR_EXIT_NO_IDENTITY);
       }
       if (!HELIX_CHANNELS2.includes(options.channel)) {
         throw new MutagentError("INVALID_OPTION", `Unknown channel '${options.channel}'.`, `Use --channel ${HELIX_CHANNELS2.join(" or ")}`);
@@ -20851,7 +21055,7 @@ AI Agent Directive:
       for (const secret of localCredentialSecrets(store.entries))
         registerSecret(secret);
       const client = await getSDKClient();
-      const target = client.requireUnambiguousWorkspace();
+      const target = client.requireSelectedWorkspace();
       const rows = (await client.listProviders({ limit: 1000 })).data.map((row) => ({
         id: row.id,
         name: row.name,
@@ -21782,22 +21986,28 @@ exits — run \`mutagent login\` first, then re-run \`mutagent init\`.
 
 \`\`\`bash
 mutagent config list --json                 # show all config
-mutagent config get <key> --json            # keys: apiKey, endpoint, format, timeout,
-                                             #       defaultWorkspace, defaultOrganization
-mutagent config set workspace <id> --json   # set default workspace
-mutagent config set org <id> --json         # set default organization
+mutagent config get <key> --json            # keys: apiKey, endpoint, format, timeout, defaultWorkspace,
+                                             #       workspaceName, defaultOrganization, organizationName, keyScope
+mutagent config set workspace <name|id> --json   # same as: mutagent workspaces use
+mutagent config set org <id|slug> --json    # confirms the key's organization; another org exits 1
 \`\`\`
 
 ---
 
-## 4. workspaces (read-only)
+## 4. workspaces
 
 \`\`\`bash
-mutagent workspaces list --json          # list workspaces
+mutagent workspaces list --json          # your workspaces in the key's organization (selected: true)
+mutagent workspaces use <name|id> --json # select the workspace later commands work in (no browser, no prompt)
+mutagent workspaces current --json       # key scope, organization, verified workspace, key expiry
 mutagent workspaces get <id> --json      # workspace details
 \`\`\`
 
-To make a workspace the default, use \`mutagent config set workspace <id>\`.
+The login key works in every workspace the user is a member of in its organization.
+For one command in another workspace, pass \`--workspace <name|id>\` (it beats
+\`MUTAGENT_WORKSPACE_ID\`, which beats the selection). For another organization:
+\`mutagent login --org <slug>\`. A tenancy error is one line ending in the fix command:
+run that command, never retry the same request.
 
 ---
 
@@ -22008,51 +22218,33 @@ It never prompts. Without a sign-in it prints what to run and exits.
       } else {
         const config = (deps.loadConfig ?? loadConfig)();
         const endpoint = config.endpoint ?? "https://api.mutagent.io";
-        let workspace = config.defaultWorkspace;
+        const workspace = config.defaultWorkspace;
         let workspaceValidation;
-        let resolvedOrgId;
         try {
           const apiKey = (deps.getApiKey ?? getApiKey)();
-          if (apiKey) {
-            const sdk = await Promise.resolve().then(() => (init_sdk_client(), exports_sdk_client));
-            const fetchOrgs = deps.fetchOrganizations ?? sdk.fetchOrganizations;
-            const fetchWs = deps.fetchWorkspaces ?? sdk.fetchWorkspaces;
-            let orgId = config.defaultOrganization;
-            if (!orgId) {
-              const orgs = await fetchOrgs(apiKey, endpoint);
-              orgId = orgs[0]?.id;
-            }
-            if (orgId) {
-              resolvedOrgId = orgId;
-              const workspaces = await fetchWs(apiKey, endpoint, orgId);
-              if (workspaces.length > 0) {
-                const found = workspace ? workspaces.find((w) => w.id === workspace) : undefined;
-                if (found) {
-                  workspaceValidation = { id: found.id, name: found.name, validated: true, corrected: false };
-                } else if (workspaces[0]) {
-                  const first = workspaces[0];
-                  (deps.setDefaultWorkspace ?? setDefaultWorkspace)(first.id, "login-inferred");
-                  workspace = first.id;
-                  workspaceValidation = { id: first.id, name: first.name, validated: true, corrected: true };
-                }
-              }
-            }
+          if (apiKey && workspace) {
+            const list = deps.listWorkspaces ?? (async (key) => {
+              const { listKeyWorkspaces: listKeyWorkspaces2, resolveKeyTenancy: resolveKeyTenancy2 } = await Promise.resolve().then(() => (init_organization_scope(), exports_organization_scope));
+              const tenancy = await resolveKeyTenancy2(key, { resolveOverride: false });
+              return listKeyWorkspaces2(key, tenancy.endpoint, tenancy);
+            });
+            const found = (await list(apiKey)).find((w) => w.id === workspace);
+            workspaceValidation = { id: workspace, name: found?.name, found: found !== undefined };
           }
         } catch {}
         rcConfig = {
           endpoint,
-          ...workspace ? { defaultWorkspace: workspace } : {},
-          ...resolvedOrgId ? { defaultOrganization: resolvedOrgId } : {}
+          ...workspace ? { defaultWorkspace: workspace } : {}
         };
         writeRcConfig(rcConfig, cwd);
         if (!isJson) {
           output.success("Created .mutagentrc.json");
-          if (workspaceValidation) {
-            if (workspaceValidation.corrected) {
-              output.warn(`Workspace auto-corrected to: ${workspaceValidation.name} (${workspaceValidation.id})`);
-            } else {
-              output.info(`Workspace: ${workspaceValidation.name} (${workspaceValidation.id})`);
-            }
+          if (workspaceValidation?.found) {
+            output.info(`Workspace: ${workspaceValidation.name ?? workspaceValidation.id} (${workspaceValidation.id})`);
+          } else if (workspaceValidation) {
+            output.warn(`Your saved workspace ${workspaceValidation.id} is not among your workspaces. Run: mutagent workspaces use <name>`);
+          } else if (!workspace) {
+            output.warn("No workspace selected. Run: mutagent workspaces use <name>");
           }
         }
       }
@@ -22236,22 +22428,8 @@ function parseTranscript(raw) {
 // src/commands/hooks/api.ts
 init_config();
 init_known_secrets();
+init_organization_scope();
 var API_TIMEOUT_MS = 5000;
-function resolveTenancyHeaders(config) {
-  if (config.defaultWorkspace && !config.defaultOrganization) {
-    return {
-      ok: false,
-      warning: "[mutagent hooks] Warning: a default workspace is set but no default organization, " + "so the server will reject every trace batch. " + `Fix with: mutagent config set organization <org-id>
-`
-    };
-  }
-  const headers = {};
-  if (config.defaultWorkspace)
-    headers["x-workspace-id"] = config.defaultWorkspace;
-  if (config.defaultOrganization)
-    headers["x-organization-id"] = config.defaultOrganization;
-  return { ok: true, headers };
-}
 async function sendBatchTrace(traces) {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -22265,12 +22443,7 @@ async function sendBatchTrace(traces) {
     "x-api-key": apiKey,
     "Content-Type": "application/json"
   };
-  const tenancy = resolveTenancyHeaders(config);
-  if (!tenancy.ok) {
-    process.stderr.write(tenancy.warning);
-    return;
-  }
-  Object.assign(headers, tenancy.headers);
+  Object.assign(headers, configTenancyHeaders(config));
   const controller = new AbortController;
   const timeout = setTimeout(() => {
     controller.abort();
@@ -23282,6 +23455,7 @@ import { join as join18, dirname as dirname5 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 init_errors();
 init_config();
+init_organization_scope();
 
 // src/lib/transcript.ts
 init_errors();
@@ -23691,15 +23865,12 @@ function buildAutoContext(harness) {
     nodeVersion: process.version
   };
 }
-async function postToServer(payload, endpoint, apiKey, workspaceId, organizationId) {
+async function postToServer(payload, endpoint, apiKey, tenancy) {
   const headers = {
     "Content-Type": "application/json",
-    "x-api-key": apiKey
+    "x-api-key": apiKey,
+    ...tenancy
   };
-  if (workspaceId)
-    headers["x-workspace-id"] = workspaceId;
-  if (organizationId)
-    headers["x-organization-id"] = organizationId;
   let response;
   try {
     response = await fetch(`${endpoint}/api/feedback`, {
@@ -23823,7 +23994,7 @@ Or set an API key: mutagent config set apiKey <key>`);
       const payload = buildPayload(feedbackBody, category, options.title, options.session, transcript);
       const config = loadConfig();
       const endpoint = config.endpoint ?? "https://api.mutagent.io";
-      const result = await postToServer(payload, endpoint, apiKey, config.defaultWorkspace, config.defaultOrganization);
+      const result = await postToServer(payload, endpoint, apiKey, configTenancyHeaders(config));
       if (isJson) {
         output.output({
           success: true,
@@ -24657,12 +24828,14 @@ init_errors();
 
 // src/lib/sandbox-api.ts
 init_config();
+init_organization_scope();
 init_errors();
 
 // src/lib/sandbox-token.ts
 init_secure_file();
 init_errors();
 init_known_secrets();
+init_organization_scope();
 import { existsSync as existsSync12, readFileSync as readFileSync12, mkdirSync as mkdirSync5, rmSync as rmSync2 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join20, dirname as dirname6 } from "path";
@@ -24743,12 +24916,11 @@ async function exchangeToken(input2, deps = {}) {
     const detail = error3 instanceof Error ? error3.message : String(error3);
     throw new MutagentError("SANDBOX_UNREACHABLE", `Could not reach the MutagenT API at ${input2.endpoint}: ${detail}`, "Check your connection, then verify the endpoint with: mutagent config list", 5);
   }
-  if (response.status === 401) {
-    throw new AuthenticationError("Your MutagenT API key was rejected. It may have been revoked or expired.", { suggestions: ["mutagent auth login --browser", "mutagent auth status"] });
-  }
+  if (response.status === 401)
+    throw deadKeyError();
   if (response.status === 403) {
     const detail = scrubKnown(messageFrom(await response.text().catch(() => "")));
-    throw new MutagentError("SANDBOX_WORKSPACE_FORBIDDEN", detail !== "" ? detail : `Your API key is valid, but this account cannot use workspace "${input2.workspaceId}".`, `Pick a workspace you belong to: mutagent workspaces list, then mutagent config set workspace <id>`, 3);
+    throw new MutagentError("SANDBOX_WORKSPACE_FORBIDDEN", detail !== "" ? detail : `Your API key is valid, but this account cannot use workspace "${input2.workspaceId}".`, `Pick a workspace you belong to: mutagent workspaces list, then mutagent workspaces use <name>`, 3);
   }
   if (!response.ok) {
     const detail = scrubKnown(messageFrom(await response.text().catch(() => "")));
@@ -24821,22 +24993,25 @@ async function withStoppingRetry(send, sleep2 = (ms) => new Promise((resolve9) =
 
 // src/lib/sandbox-api.ts
 init_known_secrets();
-function resolveConnection() {
+async function resolveConnection() {
   const apiKey = getApiKey();
   if (!apiKey)
     throw new AuthenticationError;
-  const config = loadConfig();
-  const configured = config.endpoint?.trim();
-  const endpoint = (configured === undefined || configured === "" ? "https://api.mutagent.io" : configured).replace(/\/+$/, "");
-  const workspaceId = requireWorkspace(config.defaultWorkspace);
-  const headers = { "x-workspace-id": workspaceId };
-  if (config.defaultOrganization)
-    headers["x-organization-id"] = config.defaultOrganization;
-  return { endpoint, apiKey, workspaceId, headers };
+  const tenancy = await resolveKeyTenancy(apiKey, { probe: envKeyReplacesFile() });
+  if (tenancy.keyScope === "organization" && !tenancy.workspaceId)
+    throw noWorkspaceSelected();
+  const workspaceId = requireWorkspace(tenancy.workspaceId);
+  const headers = tenancyHeaders({
+    keyScope: tenancy.keyScope,
+    workspaceId,
+    workspaceOrigin: tenancy.workspaceOrigin,
+    organizationId: tenancy.organization?.id
+  });
+  return { endpoint: tenancy.endpoint, apiKey, workspaceId, headers };
 }
 function requireWorkspace(workspaceId) {
   if (workspaceId === undefined || workspaceId.trim() === "") {
-    throw new WorkspaceContextError("A workspace is required: sandbox access is minted per workspace, not per account.");
+    throw new WorkspaceContextError("No workspace selected: sandbox access is minted per workspace, not per account.");
   }
   return workspaceId.trim();
 }
@@ -24852,7 +25027,7 @@ async function fetchWithTokenRetry(url, init, baseHeaders, transport) {
   return attempt(true);
 }
 async function sandboxFetch(path, init, deps = {}) {
-  const connection = resolveConnection();
+  const connection = await resolveConnection();
   const { endpoint } = connection;
   try {
     const response = await fetchWithTokenRetry(`${endpoint}${path}`, init, { ...connection.headers, ...toHeaderRecord(init.headers) }, {
@@ -28091,7 +28266,7 @@ Examples:
   ${chalk34.dim("$")} mutagent sandbox ls --json
 
 Lists the sandboxes in the configured workspace
-(mutagent config set workspace <workspace-id>).
+(mutagent workspaces use <name>).
 An empty list means none are running.
 
 AI Agent Directive:
@@ -28323,7 +28498,7 @@ AI Agent Directive:
   spawned sandbox runs until it is removed or stopped by the idle policy: confirm
   with the user before 'spawn' and before 'rm', and tell them the sandbox ID.
 
-Requires a workspace: mutagent config set workspace <workspace-id>
+Requires a workspace: mutagent workspaces use <name> (or --workspace for one command)
       `);
   registerSpawnCommand(sandbox);
   registerLsCommand(sandbox);
@@ -28459,7 +28634,7 @@ Values are write-only. \`show\` prints each entry's name and a sha256[:8] finger
 Names: Environments use letters, digits, '.', '_' and '-' (up to 64); variables use
 A-Z, 0-9 and _, not starting with a digit. An Environment holds up to 64 KiB.
 
-Requires a workspace: mutagent config set workspace <workspace-id>
+Requires a workspace: mutagent workspaces use <name> (or --workspace for one command)
 
 AI Agent Directive:
   Use 'set' to create or update — it creates the Environment when absent and
@@ -28694,6 +28869,7 @@ function printEntries(environment) {
 
 // src/bin/cli.ts
 init_config();
+init_organization_scope();
 
 // src/lib/brand.ts
 var BRAND = {
@@ -28762,7 +28938,7 @@ ${lines.join(`
 }
 
 // src/lib/global-version-flag.ts
-var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint"]);
+var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint", "--workspace", "--org"]);
 function findSubcommandIndex(rawArgs) {
   for (let i = 0;i < rawArgs.length; i++) {
     const arg = rawArgs[i];
@@ -28862,7 +29038,7 @@ To pass the Mutagent platform key instead, put it before the command (mutagent -
 function rootValueOptionRefusal(option, label) {
   const command = label.replace(/^mutagent /, "");
   const what = option === "--endpoint" ? "its own server endpoint, and would send the Mutagent platform key there" : "its own option";
-  const env = option === "--endpoint" ? " or export MUTAGENT_ENDPOINT" : "";
+  const env = option === "--endpoint" ? " or export MUTAGENT_ENDPOINT" : option === "--workspace" ? " or export MUTAGENT_WORKSPACE_ID" : "";
   return new MutagentError("NOT_SUPPORTED", `${option} after '${label}' and before a -- is refused: the mutagent CLI would read it as ${what}, and the command it forwards would never see it.`, `For the mutagent CLI, put it before the command (mutagent ${option} <value> ${command} …)${env}.
 For the forwarded command, put it after --: ${label} … -- … ${option} <value>.`, 2);
 }
@@ -29254,7 +29430,7 @@ var program = new Command18;
 program.name("mutagent").description(`Mutagent CLI - command-line client for the Mutagent platform
 
   Documentation: https://docs.mutagent.io/cli
-  Dashboard:     https://app.mutagent.io`).option("--json", "Output results as JSON (for AI agents)").option("--api-key <key>", "Mutagent API key").option("--endpoint <url>", "Mutagent server endpoint").option("--non-interactive", "Disable interactive prompts (for CI/AI agents)").configureHelp({
+  Dashboard:     https://app.mutagent.io`).option("--json", "Output results as JSON (for AI agents)").option("--api-key <key>", "Mutagent API key").option("--endpoint <url>", "Mutagent server endpoint").option("--workspace <name|id>", "Workspace for this command only (beats MUTAGENT_WORKSPACE_ID and the selection)").option("--org <id|slug>", "Check that the key belongs to this organization (its id, slug or name); a mismatch exits 1 and sends nothing (with login: the organization to sign in to)").option("--non-interactive", "Disable interactive prompts (for CI/AI agents)").configureHelp({
   sortSubcommands: true,
   showGlobalOptions: true
 });
@@ -29272,9 +29448,11 @@ ${chalk37.yellow("Managed agents:")}
   mutagent agent --help                   ${chalk37.dim("check, pack, run, deploy, activate, list, inspect, retire")}
 
 ${chalk37.yellow("Workspace:")}
-  mutagent auth status                    ${chalk37.dim("Sign-in state and the active workspace")}
-  mutagent workspaces list                ${chalk37.dim("Workspaces you can see")}
-  mutagent config set workspace <id>      ${chalk37.dim("Choose the active workspace")}
+  mutagent workspaces use <name>          ${chalk37.dim("Choose the workspace every later command works in")}
+  mutagent workspaces current             ${chalk37.dim("The key's scope, organization and the verified workspace")}
+  mutagent workspaces list                ${chalk37.dim("Your workspaces in the key's organization")}
+  --workspace <name|id>                   ${chalk37.dim("One command in another workspace (then MUTAGENT_WORKSPACE_ID, then the selection)")}
+  mutagent login --org <slug>             ${chalk37.dim("Sign in for another organization")}
   mutagent providers list                 ${chalk37.dim("LLM providers in the workspace")}
   mutagent helix models                   ${chalk37.dim("Models Helix can use in the cloud, and the workspace default model")}
   mutagent env ls                         ${chalk37.dim("Environments: variables and secrets for tools")}
@@ -29337,7 +29515,7 @@ var rootOptionError = forwardedRootOptionRefusal(rawArgs);
 if (rootOptionError !== undefined) {
   handleError(rootOptionError, rawArgs.includes("--json"));
 }
-program.hook("preAction", (thisCommand) => {
+program.hook("preAction", (thisCommand, actionCommand) => {
   const globalOpts = thisCommand.optsWithGlobals();
   if (globalOpts.apiKey && !process.env.MUTAGENT_API_KEY) {
     process.env.MUTAGENT_API_KEY = globalOpts.apiKey;
@@ -29345,6 +29523,13 @@ program.hook("preAction", (thisCommand) => {
   if (globalOpts.endpoint && !process.env.MUTAGENT_ENDPOINT) {
     process.env.MUTAGENT_ENDPOINT = globalOpts.endpoint;
   }
+  if (globalOpts.workspace) {
+    process.env.MUTAGENT_WORKSPACE_ID = globalOpts.workspace;
+    setWorkspaceFlag(globalOpts.workspace);
+  }
+  if (actionCommand.name() !== "login") {
+    setOrgAssertion(globalOpts.org);
+  }
   if (globalOpts.nonInteractive || process.env.CI === "true" || !process.stdin.isTTY) {
     process.env.MUTAGENT_NON_INTERACTIVE = "true";
   }
@@ -29388,4 +29573,4 @@ if (isAgentInvocation(rawArgs)) {
   program.parse(argvForCommander, { from: "user" });
 }
 
-//# debugId=DD369C05E2A6AE2D64756E2164756E21
+//# debugId=22EA0CB4BCE602F064756E2164756E21