@alter-ai/cli 0.5.0 → 0.6.0

package/dist/cli.js

@@ -28,7 +28,7 @@ import { join } from "path";
 // package.json
 var package_default = {
   name: "@alter-ai/cli",
-  version: "0.5.0",
+  version: "0.6.0",
   description: "Command-line interface for the Alter Vault dev portal \u2014 scripted dashboard automation.",
   type: "module",
   bin: {
@@ -593,9 +593,20 @@ var ReAuthRequiredError = class extends BackendError {
   }
 };
 var GrantExpiredError = class extends ReAuthRequiredError {
-  constructor(message, details) {
+  providerId;
+  agentId;
+  appUserId;
+  // Recovery context appended AFTER `details` — same contract and
+  // rationale as GrantNotFoundError: the delegation-walk 403 carries
+  // provider/agent/app_user recovery fields; the root-path TTL 403
+  // leaves them undefined. Existing `new GrantExpiredError(msg, details)`
+  // callers keep compiling unchanged.
+  constructor(message, details, providerId, agentId, appUserId) {
     super(message, details);
     this.name = "GrantExpiredError";
+    this.providerId = providerId;
+    this.agentId = agentId;
+    this.appUserId = appUserId;
   }
 };
 var GrantRevokedError = class extends ReAuthRequiredError {
@@ -649,6 +660,12 @@ var GrantNotFoundError = class extends BackendError {
     this.appUserId = appUserId;
   }
 };
+var AgentDelegationMissingError = class extends GrantNotFoundError {
+  constructor(message, details, providerId, agentId, appUserId) {
+    super(message, details, providerId, agentId, appUserId);
+    this.name = "AgentDelegationMissingError";
+  }
+};
 var AmbiguousGrantError = class extends BackendError {
   providerId;
   accountIdentifiers;
@@ -711,6 +728,20 @@ var PolicyViolationError = class extends BackendError {
     this.policyError = policyError;
   }
 };
+var StepUpRequiredError = class extends PolicyViolationError {
+  maxSessionAgeSeconds;
+  constructor(message, maxSessionAgeSeconds, details) {
+    super(message, "step_up_required", details);
+    this.name = "StepUpRequiredError";
+    this.maxSessionAgeSeconds = maxSessionAgeSeconds;
+  }
+};
+var RedactDischargeFailedError = class extends PolicyViolationError {
+  constructor(message, details) {
+    super(message, "redact_discharge_failed", details);
+    this.name = "RedactDischargeFailedError";
+  }
+};
 var RestrictedGrantRequiresProxyError = class extends BackendError {
   constructor(message, details) {
     super(message, details);
@@ -805,6 +836,14 @@ var TokenRefreshInProgressError = class extends BackendError {
     this.grantId = grantId;
   }
 };
+var QuotaExceededError = class extends BackendError {
+  retryAfter;
+  constructor(message, retryAfter, details) {
+    super(message, details);
+    this.name = "QuotaExceededError";
+    this.retryAfter = retryAfter;
+  }
+};
 var ConnectFlowError = class extends AlterSDKError {
   constructor(message, details) {
     super(message, details);
@@ -1391,13 +1430,10 @@ var AuthSession = class {
     _assertString(data.session_token, "session_token", "AuthSession");
     _assertString(data.auth_url, "auth_url", "AuthSession");
     _assertString(data.expires_at, "expires_at", "AuthSession");
-    if (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in)) {
-      throw new BackendError(
-        "AuthSession: 'expires_in' must be a finite number",
-        {
-          field: "expires_in"
-        }
-      );
+    if (!Number.isInteger(data.expires_in)) {
+      throw new BackendError("AuthSession: 'expires_in' must be an integer", {
+        field: "expires_in"
+      });
     }
     this.sessionToken = data.session_token;
     this.authUrl = data.auth_url;
@@ -1490,6 +1526,15 @@ var OAuthGrantItem = class {
   // shape and the Python SDK `needs_reconnect`.
   needsReconnect;
   expiresAt;
+  // The grant's OWN TTL-policy expiry (`grant_policy.expires_at`), first-class.
+  // Two DIFFERENT axes: `expiresAt` above is the provider TOKEN's expiry
+  // (auto-refreshed, never a grant terminal); `grantExpiresAt` is when the
+  // PERMISSION itself lapses (the Connect TTL picker). Null = no TTL
+  // (perpetual until revoked). The backend projects `status = "expired"` the
+  // moment this instant passes even if the DB row hasn't lazily flipped yet,
+  // so filtering `status === "active"` never caches a TTL-dead grant id.
+  // Mirrors the backend Pydantic shape and the Python SDK `grant_expires_at`.
+  grantExpiresAt;
   createdAt;
   lastUsedAt;
   // OAuth grants are ``user`` / ``system`` ROOTS, plus ``agent`` DELEGATION
@@ -1538,7 +1583,8 @@ var OAuthGrantItem = class {
     this.status = data.status;
     this.scopeMismatch = data.scope_mismatch ?? false;
     this.needsReconnect = data.needs_reconnect ?? false;
-    this.expiresAt = data.expires_at ?? null;
+    this.expiresAt = typeof data.expires_at === "string" ? data.expires_at : null;
+    this.grantExpiresAt = typeof data.grant_expires_at === "string" ? data.grant_expires_at : null;
     this.createdAt = data.created_at;
     this.lastUsedAt = data.last_used_at ?? null;
     if (data.principal_type !== "user" && data.principal_type !== "system" && data.principal_type !== "agent") {
@@ -1576,6 +1622,7 @@ var OAuthGrantItem = class {
       scope_mismatch: this.scopeMismatch,
       needs_reconnect: this.needsReconnect,
       expires_at: this.expiresAt,
+      grant_expires_at: this.grantExpiresAt,
       created_at: this.createdAt,
       last_used_at: this.lastUsedAt,
       principal_type: this.principalType,
@@ -1604,6 +1651,10 @@ var ManagedSecretGrantItem = class {
   accountIdentifier;
   grantPolicy;
   expiresAt;
+  // The grant's OWN TTL-policy expiry (`grant_policy.expires_at`), first-class —
+  // same semantics as `OAuthGrantItem.grantExpiresAt` (null = perpetual; the
+  // backend projects `status = "expired"` once lapsed).
+  grantExpiresAt;
   createdAt;
   lastUsedAt;
   principalType;
@@ -1630,7 +1681,8 @@ var ManagedSecretGrantItem = class {
     this.status = data.status;
     this.accountIdentifier = data.account_identifier ?? null;
     this.grantPolicy = typeof data.grant_policy === "object" && data.grant_policy !== null && !Array.isArray(data.grant_policy) ? data.grant_policy : null;
-    this.expiresAt = data.expires_at ?? null;
+    this.expiresAt = typeof data.expires_at === "string" ? data.expires_at : null;
+    this.grantExpiresAt = typeof data.grant_expires_at === "string" ? data.grant_expires_at : null;
     this.createdAt = data.created_at;
     this.lastUsedAt = data.last_used_at ?? null;
     this.principalType = data.principal_type;
@@ -1660,6 +1712,7 @@ var ManagedSecretGrantItem = class {
       account_identifier: this.accountIdentifier,
       grant_policy: this.grantPolicy,
       expires_at: this.expiresAt,
+      grant_expires_at: this.grantExpiresAt,
       created_at: this.createdAt,
       last_used_at: this.lastUsedAt,
       parent_grant_id: this.parentGrantId,
@@ -2029,8 +2082,40 @@ function _assertApprovalStatusValue(value, context) {
   }
 }
 var APPROVAL_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["denied", "expired", "executed", "failed"]);
+var ApprovalGate = class {
+  approvalId;
+  expiresAt;
+  expiresIn;
+  approvalUrl;
+  constructor(args) {
+    const ctx = "ApprovalGate";
+    _assertString(args?.approval_id, "approval_id", ctx);
+    if (!Number.isInteger(args?.expires_in)) {
+      throw new BackendError(
+        `${ctx}: 'expires_in' must be an integer, got ${typeof args?.expires_in}`,
+        { field: "expires_in" }
+      );
+    }
+    _assertString(args?.approval_url, "approval_url", ctx);
+    this.approvalId = args.approval_id;
+    this.expiresAt = _parseDateOrThrow(args.expires_at, "expires_at", ctx);
+    this.expiresIn = args.expires_in;
+    this.approvalUrl = args.approval_url;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      approval_id: this.approvalId,
+      expires_at: this.expiresAt.toISOString(),
+      expires_in: this.expiresIn,
+      approval_url: this.approvalUrl
+    };
+  }
+};
 var PendingApproval = class {
   approvalId;
+  /** Shared execution unit for the gate group (N-of-N multi-party). */
+  approvalGroupId;
   // The backend's ``ApprovalPendingResponse`` always reports
   // ``status: "pending"`` on the 202 path. Carrying it on the SDK
   // model preserves the wire contract and matches the Python SDK so
@@ -2047,12 +2132,19 @@ var PendingApproval = class {
    * ``EMAIL_PROVIDER`` configured.
    */
   approvalUrl;
+  /**
+   * Every distinct approver gate (>=1). Each must be approved before execution
+   * proceeds; any denial or expiry kills the whole group. The top-level fields
+   * point at the group's executor gate (the id used for polling).
+   */
+  gates;
   constructor(args) {
     const ctx = "PendingApproval";
     _assertString(args?.approval_id, "approval_id", ctx);
-    if (typeof args?.expires_in !== "number" || !Number.isFinite(args.expires_in)) {
+    _assertString(args?.approval_group_id, "approval_group_id", ctx);
+    if (!Number.isInteger(args?.expires_in)) {
       throw new BackendError(
-        `${ctx}: 'expires_in' must be a finite number, got ${typeof args?.expires_in}`,
+        `${ctx}: 'expires_in' must be an integer, got ${typeof args?.expires_in}`,
         { field: "expires_in" }
       );
     }
@@ -2063,26 +2155,67 @@ var PendingApproval = class {
       );
     }
     _assertString(args?.approval_url, "approval_url", ctx);
+    if (!Array.isArray(args?.gates) || args.gates.length < 1) {
+      throw new BackendError(`${ctx}: 'gates' must be a non-empty array`, {
+        field: "gates"
+      });
+    }
     this.approvalId = args.approval_id;
+    this.approvalGroupId = args.approval_group_id;
     this.status = "pending";
     this.expiresAt = _parseDateOrThrow(args.expires_at, "expires_at", ctx);
     this.expiresIn = args.expires_in;
     this.approvalUrl = args.approval_url;
+    this.gates = Object.freeze(
+      args.gates.map(
+        (g) => new ApprovalGate(g)
+      )
+    );
     Object.freeze(this);
   }
   toJSON() {
     return {
       approval_id: this.approvalId,
+      approval_group_id: this.approvalGroupId,
       status: this.status,
       expires_at: this.expiresAt.toISOString(),
       expires_in: this.expiresIn,
-      approval_url: this.approvalUrl
+      approval_url: this.approvalUrl,
+      gates: this.gates.map((g) => g.toJSON())
+    };
+  }
+};
+var ApprovalGateStatus = class {
+  approvalId;
+  status;
+  expiresAt;
+  decidedAt;
+  constructor(args) {
+    const ctx = "ApprovalGateStatus";
+    _assertString(args?.approval_id, "approval_id", ctx);
+    _assertApprovalStatusValue(args?.status, ctx);
+    this.approvalId = args.approval_id;
+    this.status = args.status;
+    this.expiresAt = _parseDateOrThrow(args.expires_at, "expires_at", ctx);
+    this.decidedAt = _parseOptionalDate(args.decided_at, "decided_at", ctx);
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      approval_id: this.approvalId,
+      status: this.status,
+      expires_at: this.expiresAt.toISOString(),
+      decided_at: this.decidedAt ? this.decidedAt.toISOString() : null
     };
   }
 };
 var ApprovalStatus = class {
   approvalId;
+  /** Shared execution unit; for a multi-party approval `status` is the DERIVED
+   * group status and `gates` carries the per-gate breakdown. */
+  approvalGroupId;
   status;
+  gates;
   expiresAt;
   decidedAt;
   decisionReason;
@@ -2098,7 +2231,13 @@ var ApprovalStatus = class {
   constructor(args) {
     const ctx = "ApprovalStatus";
     _assertString(args?.approval_id, "approval_id", ctx);
+    _assertString(args?.approval_group_id, "approval_group_id", ctx);
     _assertApprovalStatusValue(args?.status, ctx);
+    if (!Array.isArray(args?.gates) || args.gates.length < 1) {
+      throw new BackendError(`${ctx}: 'gates' must be a non-empty array`, {
+        field: "gates"
+      });
+    }
     if (typeof args?.has_result !== "boolean") {
       throw new BackendError(
         `${ctx}: 'has_result' must be a boolean, got ${typeof args?.has_result}`,
@@ -2112,7 +2251,13 @@ var ApprovalStatus = class {
       );
     }
     this.approvalId = args.approval_id;
+    this.approvalGroupId = args.approval_group_id;
     this.status = args.status;
+    this.gates = Object.freeze(
+      args.gates.map(
+        (g) => new ApprovalGateStatus(g)
+      )
+    );
     this.expiresAt = _parseDateOrThrow(args.expires_at, "expires_at", ctx);
     this.decidedAt = _parseOptionalDate(args.decided_at, "decided_at", ctx);
     this.decisionReason = args.decision_reason ?? null;
@@ -2127,7 +2272,9 @@ var ApprovalStatus = class {
   toJSON() {
     return {
       approval_id: this.approvalId,
+      approval_group_id: this.approvalGroupId,
       status: this.status,
+      gates: this.gates.map((g) => g.toJSON()),
       expires_at: this.expiresAt.toISOString(),
       decided_at: this.decidedAt ? this.decidedAt.toISOString() : null,
       decision_reason: this.decisionReason,
@@ -2145,9 +2292,9 @@ var ApprovalResult = class {
   bodyTruncated;
   constructor(args) {
     const ctx = "ApprovalResult";
-    if (typeof args?.status_code !== "number" || !Number.isFinite(args.status_code)) {
+    if (!Number.isInteger(args?.status_code)) {
       throw new BackendError(
-        `${ctx}: 'status_code' must be a finite number, got ${typeof args?.status_code}`,
+        `${ctx}: 'status_code' must be an integer, got ${typeof args?.status_code}`,
         { field: "status_code" }
       );
     }
@@ -2790,6 +2937,271 @@ var IdentityAssertion = class {
     return this.toString();
   }
 };
+var ProviderSpec = class {
+  /** `"oauth"` or `"managed"` (see {@link ProviderSpecKind}). */
+  providerKind;
+  providerId;
+  /** Monotonic ingest version — bumps whenever the stored spec content changes. */
+  version;
+  /** Where the spec came from (e.g. an official published spec vs a curated one). */
+  provenance;
+  sourceUrl;
+  contentHash;
+  operationCount;
+  /**
+   * Parsed to a real `Date` (not a raw string) so callers can compare
+   * freshness against `new Date()` / `Date.now()` without first
+   * remembering to parse. Mirrors Python SDK
+   * ``ProviderSpec.fetched_at: datetime``. Re-serialized to ISO 8601
+   * by `toJSON()`.
+   */
+  fetchedAt;
+  /** When this spec version last changed; unlike fetchedAt, unchanged sweeps do not move it. */
+  changedAt;
+  title;
+  /** The spec document's own declared version string (e.g. an OpenAPI `info.version`). */
+  specVersion;
+  constructor(data) {
+    this.providerKind = _requireNonEmptyString(
+      "ProviderSpec",
+      "provider_kind",
+      data?.provider_kind
+    );
+    this.providerId = _requireNonEmptyString(
+      "ProviderSpec",
+      "provider_id",
+      data.provider_id
+    );
+    this.version = _requireNumber("ProviderSpec", "version", data.version);
+    this.provenance = _requireNonEmptyString(
+      "ProviderSpec",
+      "provenance",
+      data.provenance
+    );
+    this.sourceUrl = _optionalString(
+      "ProviderSpec",
+      "source_url",
+      data.source_url
+    );
+    this.contentHash = _requireNonEmptyString(
+      "ProviderSpec",
+      "content_hash",
+      data.content_hash
+    );
+    this.operationCount = _requireNumber(
+      "ProviderSpec",
+      "operation_count",
+      data.operation_count
+    );
+    this.fetchedAt = _parseDateOrThrow(
+      data.fetched_at,
+      "fetched_at",
+      "ProviderSpec"
+    );
+    this.changedAt = _parseDateOrThrow(
+      data.changed_at,
+      "changed_at",
+      "ProviderSpec"
+    );
+    this.title = _optionalString("ProviderSpec", "title", data.title);
+    this.specVersion = _optionalString(
+      "ProviderSpec",
+      "spec_version",
+      data.spec_version
+    );
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      provider_kind: this.providerKind,
+      provider_id: this.providerId,
+      version: this.version,
+      provenance: this.provenance,
+      source_url: this.sourceUrl,
+      content_hash: this.contentHash,
+      operation_count: this.operationCount,
+      // Serialize Date back to ISO 8601 wire format so toJSON() round-
+      // trips identically to Python ``model_dump(mode="json")``.
+      fetched_at: this.fetchedAt.toISOString(),
+      changed_at: this.changedAt.toISOString(),
+      title: this.title,
+      spec_version: this.specVersion
+    };
+  }
+};
+var SpecOperation = class {
+  /**
+   * Spec-native operation id. May contain slashes (GitHub's
+   * `repos/get`) or dots (Google's `gmail.users.messages.list`).
+   */
+  operationId;
+  method;
+  /** URL path template with `{placeholders}` (e.g. `/repos/{owner}/{repo}`). */
+  pathTemplate;
+  summary;
+  constructor(data) {
+    this.operationId = _requireNonEmptyString(
+      "SpecOperation",
+      "operation_id",
+      data?.operation_id
+    );
+    this.method = _requireNonEmptyString(
+      "SpecOperation",
+      "method",
+      data.method
+    );
+    this.pathTemplate = _requireNonEmptyString(
+      "SpecOperation",
+      "path_template",
+      data.path_template
+    );
+    this.summary = _optionalString("SpecOperation", "summary", data.summary);
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      operation_id: this.operationId,
+      method: this.method,
+      path_template: this.pathTemplate,
+      summary: this.summary
+    };
+  }
+};
+var SpecOperationsPage = class {
+  items;
+  total;
+  limit;
+  offset;
+  hasMore;
+  spec;
+  constructor(data) {
+    if (!Array.isArray(data?.items)) {
+      throw _wireShapeError(
+        "SpecOperationsPage",
+        "items",
+        "array",
+        data?.items
+      );
+    }
+    this.items = Object.freeze(
+      data.items.map(
+        (item) => item instanceof SpecOperation ? item : new SpecOperation(item)
+      )
+    );
+    this.total = _requireNumber("SpecOperationsPage", "total", data.total);
+    this.limit = _requireNumber("SpecOperationsPage", "limit", data.limit);
+    this.offset = _requireNumber("SpecOperationsPage", "offset", data.offset);
+    this.hasMore = _requireBoolean(
+      "SpecOperationsPage",
+      "has_more",
+      data.has_more
+    );
+    this.spec = data.spec instanceof ProviderSpec ? data.spec : new ProviderSpec(data.spec);
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      items: this.items.map((item) => item.toJSON()),
+      total: this.total,
+      limit: this.limit,
+      offset: this.offset,
+      has_more: this.hasMore,
+      spec: this.spec.toJSON()
+    };
+  }
+};
+var SpecOperationDetail = class {
+  operationId;
+  method;
+  pathTemplate;
+  summary;
+  paramsSchema;
+  requestSchema;
+  responseSchema;
+  spec;
+  constructor(data) {
+    this.operationId = _requireNonEmptyString(
+      "SpecOperationDetail",
+      "operation_id",
+      data?.operation_id
+    );
+    this.method = _requireNonEmptyString(
+      "SpecOperationDetail",
+      "method",
+      data.method
+    );
+    this.pathTemplate = _requireNonEmptyString(
+      "SpecOperationDetail",
+      "path_template",
+      data.path_template
+    );
+    this.summary = _optionalString(
+      "SpecOperationDetail",
+      "summary",
+      data.summary
+    );
+    this.paramsSchema = _optionalObjectArray(
+      "SpecOperationDetail",
+      "params_schema",
+      data.params_schema
+    );
+    this.requestSchema = _optionalObject(
+      "SpecOperationDetail",
+      "request_schema",
+      data.request_schema
+    );
+    this.responseSchema = _optionalObject(
+      "SpecOperationDetail",
+      "response_schema",
+      data.response_schema
+    );
+    this.spec = data.spec instanceof ProviderSpec ? data.spec : new ProviderSpec(data.spec);
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      operation_id: this.operationId,
+      method: this.method,
+      path_template: this.pathTemplate,
+      summary: this.summary,
+      params_schema: this.paramsSchema,
+      request_schema: this.requestSchema,
+      response_schema: this.responseSchema,
+      spec: this.spec.toJSON()
+    };
+  }
+};
+function _optionalString(modelName, field, value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "string") {
+    throw _wireShapeError(modelName, field, "string or null", value);
+  }
+  return value;
+}
+function _optionalObject(modelName, field, value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw _wireShapeError(modelName, field, "object or null", value);
+  }
+  return value;
+}
+function _optionalObjectArray(modelName, field, value) {
+  if (value === null || value === void 0) return null;
+  if (!Array.isArray(value)) {
+    throw _wireShapeError(modelName, field, "array of objects or null", value);
+  }
+  for (const entry of value) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      throw _wireShapeError(
+        modelName,
+        field,
+        "array of objects or null",
+        entry
+      );
+    }
+  }
+  return value;
+}
 var ALGORITHM = "AWS4-HMAC-SHA256";
 var AWS_HOST_RE = (
   // eslint-disable-next-line security/detect-unsafe-regex
@@ -3563,7 +3975,7 @@ function _requireStringArray(raw, key, context) {
   }
   return v;
 }
-function _optionalString(raw, key, context) {
+function _optionalString2(raw, key, context) {
   const v = raw[key];
   if (v === null || v === void 0) return null;
   if (typeof v !== "string") {
@@ -3626,11 +4038,11 @@ function rawToInfo(raw) {
   const createdAt = _requireString(raw, "created_at", ctx);
   const cidrAllowlist = _optionalStringArray(raw, "cidr_allowlist", ctx);
   const rateLimitRpm = _optionalNumber(raw, "rate_limit_rpm", ctx);
-  const expiresAt = _optionalString(raw, "expires_at", ctx);
-  const deprecatedAt = _optionalString(raw, "deprecated_at", ctx);
-  const revokedAt = _optionalString(raw, "revoked_at", ctx);
-  const parentKeyId = _optionalString(raw, "parent_key_id", ctx);
-  const lastUsedAt = _optionalString(raw, "last_used_at", ctx);
+  const expiresAt = _optionalString2(raw, "expires_at", ctx);
+  const deprecatedAt = _optionalString2(raw, "deprecated_at", ctx);
+  const revokedAt = _optionalString2(raw, "revoked_at", ctx);
+  const parentKeyId = _optionalString2(raw, "parent_key_id", ctx);
+  const lastUsedAt = _optionalString2(raw, "last_used_at", ctx);
   const status = (() => {
     if (revokedAt !== null) return "revoked";
     if (deprecatedAt !== null) return "rotated";
@@ -3956,6 +4368,216 @@ function requireStringArray(fieldName, value) {
 function catalogContractError(message) {
   return new BackendError(message);
 }
+var LIST_OPERATIONS_LIMIT_MAX = 500;
+var SEARCH_MAX_LENGTH = 200;
+function _requireKind(kind) {
+  if (kind !== "oauth" && kind !== "managed") {
+    throw new AlterValueError(
+      `kind must be "oauth" or "managed", got ${JSON.stringify(kind)}`
+    );
+  }
+  return kind;
+}
+function _requireProviderId(providerId) {
+  if (typeof providerId !== "string" || providerId.trim().length === 0) {
+    throw new AlterValueError("providerId must be a non-empty string");
+  }
+  return providerId;
+}
+function _strictEncodeSegment(segment) {
+  return encodeURIComponent(segment).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+var ProviderSpecsNamespace = class {
+  #vault;
+  constructor(vault) {
+    this.#vault = vault;
+  }
+  /**
+   * Every provider's active spec metadata (freshness + provenance),
+   * optionally filtered to one provider family.
+   *
+   * Requires the `providers:read` key scope.
+   *
+   * @param kind Optional filter: `"oauth"` or `"managed"`.
+   * @throws {AlterValueError} `kind` is not `"oauth"` / `"managed"`.
+   * @throws {InsufficientScopeError} key lacks `providers:read`.
+   * @throws {BackendError} backend reachability or response-shape failure.
+   */
+  async list(kind) {
+    let path = "/sdk/provider-specs";
+    if (kind !== void 0) {
+      const params = new URLSearchParams({ kind: _requireKind(kind) });
+      path += `?${params.toString()}`;
+    }
+    const data = await this.#getJson(path);
+    const obj = _requireResponseObject2("ProviderSpecListResponse", data);
+    const items = obj.items;
+    if (!Array.isArray(items)) {
+      throw new BackendError(
+        "Backend response did not match expected ProviderSpecListResponse shape: missing 'items' array",
+        { model: "ProviderSpecListResponse", received_keys: Object.keys(obj) }
+      );
+    }
+    if (typeof obj.total !== "number") {
+      throw new BackendError(
+        "Backend response did not match expected ProviderSpecListResponse shape: 'total' must be a number",
+        { model: "ProviderSpecListResponse", received_keys: Object.keys(obj) }
+      );
+    }
+    return items.map(
+      (item) => new ProviderSpec(item)
+    );
+  }
+  /**
+   * One provider's active spec metadata.
+   *
+   * @throws {AlterValueError} invalid `kind` / empty `providerId`.
+   * @throws {GrantNotFoundError} no active spec for this provider
+   *   (backend 404, `provider_spec_not_found`).
+   * @throws {InsufficientScopeError} key lacks `providers:read`.
+   * @throws {BackendError} backend reachability or response-shape failure.
+   */
+  async get(kind, providerId) {
+    const path = `/sdk/provider-specs/${_requireKind(kind)}/${_strictEncodeSegment(
+      _requireProviderId(providerId)
+    )}`;
+    const data = await this.#getJson(path);
+    const obj = _requireResponseObject2("ProviderSpec", data);
+    return new ProviderSpec(
+      obj
+    );
+  }
+  /**
+   * Page the provider's operations (in-band discovery). Each row is a
+   * summary ({@link SpecOperation}); fetch the full schemas per
+   * operation via {@link getOperation}.
+   *
+   * @param opts `search` (substring filter, <= 200 chars), `limit`
+   *   (1–500, default 100), `offset` (>= 0, default 0) — all validated
+   *   client-side before any network call, mirroring the backend gates.
+   * @throws {AlterValueError} invalid `kind` / `providerId` / options.
+   * @throws {GrantNotFoundError} no active spec for this provider
+   *   (backend 404, `provider_spec_not_found`).
+   * @throws {InsufficientScopeError} key lacks `providers:read`.
+   * @throws {BackendError} backend reachability or response-shape failure.
+   */
+  async listOperations(kind, providerId, opts = {}) {
+    const basePath = `/sdk/provider-specs/${_requireKind(kind)}/${_strictEncodeSegment(
+      _requireProviderId(providerId)
+    )}/operations`;
+    const limit = opts.limit === void 0 ? 100 : opts.limit;
+    const offset = opts.offset === void 0 ? 0 : opts.offset;
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > LIST_OPERATIONS_LIMIT_MAX) {
+      throw new AlterValueError(
+        `limit must be an integer between 1 and ${LIST_OPERATIONS_LIMIT_MAX}`
+      );
+    }
+    if (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0) {
+      throw new AlterValueError("offset must be an integer >= 0");
+    }
+    if (opts.search !== void 0) {
+      if (typeof opts.search !== "string" || opts.search.length === 0) {
+        throw new AlterValueError("search must be a non-empty string");
+      }
+      if (opts.search.length > SEARCH_MAX_LENGTH) {
+        throw new AlterValueError(
+          `search is capped at ${SEARCH_MAX_LENGTH} characters`
+        );
+      }
+    }
+    const params = new URLSearchParams();
+    params.set("limit", String(limit));
+    params.set("offset", String(offset));
+    if (opts.search !== void 0) {
+      params.set("search", opts.search);
+    }
+    params.sort();
+    const data = await this.#getJson(`${basePath}?${params.toString()}`);
+    const obj = _requireResponseObject2("SpecOperationsPage", data);
+    return new SpecOperationsPage(
+      obj
+    );
+  }
+  /**
+   * One operation with its full parameter/request/response schemas.
+   *
+   * @param operationId Spec-native operation id. May contain slashes
+   *   (GitHub's `repos/get`) — the backend route uses a `:path`
+   *   converter, so slashes are preserved as path structure and every
+   *   other segment character is strictly percent-encoded (RFC 3986,
+   *   byte-identical to the Python SDK's `quote`). Dot-segments (`.` /
+   *   `..`, including pre-encoded `%2e` spellings) and empty segments
+   *   are rejected (path-traversal guard).
+   * @throws {AlterValueError} invalid `kind` / `providerId` / empty
+   *   `operationId` / an `operationId` containing a dot-segment or
+   *   empty path segment.
+   * @throws {GrantNotFoundError} no active spec for this provider OR no
+   *   such operation (backend 404, `provider_spec_not_found` /
+   *   `operation_not_found` — disambiguate via `details.error`).
+   * @throws {InsufficientScopeError} key lacks `providers:read`.
+   * @throws {BackendError} backend reachability or response-shape failure.
+   */
+  async getOperation(kind, providerId, operationId) {
+    if (typeof operationId !== "string" || operationId.trim().length === 0) {
+      throw new AlterValueError("operationId must be a non-empty string");
+    }
+    for (const segment of operationId.split("/")) {
+      if (segment.length === 0) {
+        throw new AlterValueError(
+          "operationId must not contain empty path segments"
+        );
+      }
+      const dotDecoded = segment.replace(/%2e/gi, ".");
+      if (dotDecoded === "." || dotDecoded === "..") {
+        throw new AlterValueError(
+          'operationId must not contain path traversal segments ("." or "..")'
+        );
+      }
+    }
+    const encodedOperationId = operationId.split("/").map(_strictEncodeSegment).join("/");
+    const path = `/sdk/provider-specs/${_requireKind(kind)}/${_strictEncodeSegment(
+      _requireProviderId(providerId)
+    )}/operations/${encodedOperationId}`;
+    const data = await this.#getJson(path);
+    const obj = _requireResponseObject2("SpecOperationDetail", data);
+    return new SpecOperationDetail(
+      obj
+    );
+  }
+  /**
+   * GET `sdkPath`, route non-2xx through the client's canonical typed
+   * exception mapping, and parse the 2xx body as JSON.
+   */
+  async #getJson(sdkPath) {
+    const response = await this.#vault._authedBackendRequest("GET", sdkPath);
+    if (!response.ok) {
+      await this.#vault._handleErrorResponse(response);
+    }
+    try {
+      return await response.json();
+    } catch (e) {
+      throw new BackendError(
+        `${sdkPath.split("?")[0]} returned non-JSON response: ${e instanceof Error ? e.message : String(e)}`,
+        { status_code: response.status }
+      );
+    }
+  }
+};
+function _requireResponseObject2(modelName, data) {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw new BackendError(
+      `Backend response did not match expected ${modelName} shape: response is not a JSON object`,
+      {
+        model: modelName,
+        received_type: data === null ? "null" : Array.isArray(data) ? "array" : typeof data
+      }
+    );
+  }
+  return data;
+}
 var ScopesNamespace = class {
   #vault;
   constructor(vault) {
@@ -4170,6 +4792,136 @@ async function ambientTraceparent(api) {
     return void 0;
   }
 }
+var _alterContextStore = new AsyncLocalStorage();
+var RESERVED_CONTEXT_KEYS = /* @__PURE__ */ new Set([
+  "agent",
+  "parent_agent",
+  "run_id",
+  "thread_id",
+  "tool",
+  "tool_call_id",
+  "framework"
+]);
+var MAX_RUN_METADATA_LENGTH = 4096;
+var MAX_RUN_METADATA_KEYS = 20;
+var MAX_RUN_METADATA_KEY_LENGTH = 64;
+var MAX_RUN_METADATA_VALUE_LENGTH = 512;
+function getCurrentAuditContext() {
+  const value = _alterContextStore.getStore();
+  if (value === void 0) {
+    return null;
+  }
+  return { ...value };
+}
+function _stampAgentIdentity(ctx, agentId, options) {
+  const ambientAgent = ctx.agent;
+  if (!options.isAuthoritative && ambientAgent) {
+    return;
+  }
+  if (ambientAgent && ambientAgent !== agentId) {
+    ctx.parent_agent = ambientAgent;
+  }
+  ctx.agent = agentId;
+}
+function _validateRunMetadata(metadata) {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new AlterValueError(
+      "trace() metadata must be an object of string key/value pairs"
+    );
+  }
+  const keys = Object.keys(metadata);
+  if (keys.length === 0) {
+    return;
+  }
+  if (keys.length > MAX_RUN_METADATA_KEYS) {
+    throw new AlterValueError(
+      `trace() metadata has too many keys (${keys.length}); max is ${MAX_RUN_METADATA_KEYS}`
+    );
+  }
+  const reserved = keys.filter((k) => RESERVED_CONTEXT_KEYS.has(k)).sort();
+  if (reserved.length > 0) {
+    throw new AlterValueError(
+      `trace() metadata contains reserved key(s) ${JSON.stringify(reserved)}; these are owned by the SDK / framework bridges and cannot be set via metadata. Use the explicit \`runId\` / \`threadId\` kwargs for those. Reserved keys: ${JSON.stringify([...RESERVED_CONTEXT_KEYS].sort())}.`
+    );
+  }
+  let totalSize = 0;
+  for (const k of keys) {
+    const keyBytes = Buffer.byteLength(k, "utf8");
+    if (keyBytes > MAX_RUN_METADATA_KEY_LENGTH) {
+      throw new AlterValueError(
+        `trace() metadata key "${k.slice(0, 32)}" exceeds max length (${keyBytes} > ${MAX_RUN_METADATA_KEY_LENGTH} bytes)`
+      );
+    }
+    const v = metadata[k];
+    if (typeof v !== "string") {
+      throw new AlterValueError(
+        `trace() metadata value for key "${k}" must be a string, got ${typeof v}`
+      );
+    }
+    const valueBytes = Buffer.byteLength(v, "utf8");
+    if (valueBytes > MAX_RUN_METADATA_VALUE_LENGTH) {
+      throw new AlterValueError(
+        `trace() metadata value for key "${k}" exceeds max length (${valueBytes} > ${MAX_RUN_METADATA_VALUE_LENGTH} bytes)`
+      );
+    }
+    totalSize += keyBytes + valueBytes;
+  }
+  if (totalSize > MAX_RUN_METADATA_LENGTH) {
+    throw new AlterValueError(
+      `trace() metadata total size ${totalSize} bytes exceeds ${MAX_RUN_METADATA_LENGTH} byte limit`
+    );
+  }
+}
+async function _withRunScope(options, callback) {
+  const { agentId, runId, threadId, parent, metadata } = options;
+  if (metadata !== void 0) {
+    _validateRunMetadata(metadata);
+  }
+  const outer = _alterContextStore.getStore();
+  const newContext = {};
+  if (outer !== void 0) {
+    for (const [k, v] of Object.entries(outer)) {
+      if (!RESERVED_CONTEXT_KEYS.has(k)) {
+        newContext[k] = v;
+      }
+    }
+    if (outer.agent) {
+      newContext.agent = outer.agent;
+      if (outer.parent_agent) {
+        newContext.parent_agent = outer.parent_agent;
+      }
+    }
+  }
+  _stampAgentIdentity(newContext, agentId, { isAuthoritative: true });
+  if (parent === void 0) {
+  } else if (typeof parent === "string" && parent.length > 0) {
+    newContext.parent_agent = parent;
+  } else {
+    delete newContext.parent_agent;
+  }
+  if (runId !== void 0) {
+    if (typeof runId !== "string") {
+      throw new AlterValueError(`runId must be a string, got ${typeof runId}`);
+    }
+    newContext.run_id = runId;
+  } else if (outer !== void 0 && outer.run_id !== void 0) {
+    newContext.run_id = outer.run_id;
+  }
+  if (threadId !== void 0) {
+    if (typeof threadId !== "string") {
+      throw new AlterValueError(
+        `threadId must be a string, got ${typeof threadId}`
+      );
+    }
+    newContext.thread_id = threadId;
+  } else if (outer !== void 0 && outer.thread_id !== void 0) {
+    newContext.thread_id = outer.thread_id;
+  }
+  if (metadata !== void 0) {
+    Object.assign(newContext, metadata);
+  }
+  return _alterContextStore.run(newContext, callback);
+}
 function isRetryErrorInfoPayload(x) {
   if (x == null || typeof x !== "object") {
     return false;
@@ -4198,7 +4950,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.20.0";
+var SDK_VERSION = "0.20.1";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var AUTH_POLL_SERVER_WAIT_MS = 25e3;
 var AUTH_POLL_HTTP_BUFFER_MS = 15e3;
@@ -4213,6 +4965,7 @@ var HTTP_UNAUTHORIZED = 401;
 var HTTP_BAD_GATEWAY = 502;
 var HTTP_INTERNAL_SERVER_ERROR = 500;
 var HTTP_SERVICE_UNAVAILABLE = 503;
+var HTTP_TOO_MANY_REQUESTS = 429;
 var MAX_SCOPE_CONSTRAINT_ATOM_LENGTH = 512;
 var MAX_SCOPE_CONSTRAINT_ATOMS = 100;
 var SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
@@ -4984,7 +5737,10 @@ request-rule:${effectiveRequestRule}`;
       if (errorCode === "grant_expired") {
         throw new GrantExpiredError(
           errorData.message ?? "Grant expired per TTL policy",
-          errorData.details
+          errorData.details,
+          typeof errorData.provider_id === "string" ? errorData.provider_id : void 0,
+          typeof errorData.agent_id === "string" ? errorData.agent_id : void 0,
+          typeof errorData.app_user_id === "string" ? errorData.app_user_id : void 0
         );
       }
       if (errorCode === "grant_revoked") {
@@ -5029,6 +5785,22 @@ request-rule:${effectiveRequestRule}`;
           details
         );
       }
+      if (errorCode === "step_up_required") {
+        const rawAge = errorData.max_session_age_seconds;
+        throw new StepUpRequiredError(
+          errorData.message ?? "This request requires a fresh (stepped-up) session \u2014 re-authenticate the user and retry.",
+          // Number.isInteger mirrors the Python int-only guard
+          // (fractional/bool/absent → undefined).
+          Number.isInteger(rawAge) ? rawAge : void 0,
+          errorData
+        );
+      }
+      if (errorCode === "redact_discharge_failed") {
+        throw new RedactDischargeFailedError(
+          errorData.message ?? "The redact obligation could not be applied to the request body, so the request was denied.",
+          errorData
+        );
+      }
       throw new PolicyViolationError(
         errorData.message ?? "Access denied by policy",
         errorCode,
@@ -5167,6 +5939,20 @@ request-rule:${effectiveRequestRule}`;
         errorData
       );
     }
+    if (response.status === HTTP_TOO_MANY_REQUESTS) {
+      const errorData = await __VaultClient.#safeParseJson(response);
+      if (errorData.error === "quota_exceeded") {
+        const retryAfterRaw = errorData.retry_after;
+        throw new QuotaExceededError(
+          errorData.message ?? "Request quota exceeded for the current window.",
+          // The backend always emits an int; anything else (bool,
+          // fractional number, string) degrades to undefined — parity with
+          // the Python isinstance(int)-and-not-bool guard.
+          Number.isInteger(retryAfterRaw) ? retryAfterRaw : void 0,
+          errorData
+        );
+      }
+    }
     if (response.status === HTTP_INTERNAL_SERVER_ERROR || response.status === HTTP_SERVICE_UNAVAILABLE) {
       const errorData = await __VaultClient.#safeParseJson(response);
       throw new BackendError(
@@ -5536,7 +6322,7 @@ request-rule:${effectiveRequestRule}`;
     }
     const effectiveGrantId = grantId ?? null;
     let currentUrl = url;
-    const context = options?.context;
+    const context = options?.context ?? getCurrentAuditContext() ?? void 0;
     const methodStr = String(method).toUpperCase();
     const urlLower = currentUrl.toLowerCase();
     if (!ALLOWED_URL_SCHEMES.some((scheme) => urlLower.startsWith(scheme))) {
@@ -5989,7 +6775,9 @@ request-rule:${effectiveRequestRule}`;
    */
   async _authedBackendRequest(method, sdkPath, body, extraHeaders) {
     this.#assertNotClosed();
-    const actorHeaders = await this.#getActorRequestHeaders();
+    const actorHeaders = await this.#getActorRequestHeaders(
+      getCurrentAuditContext() ?? void 0
+    );
     const bodyStr = body !== void 0 ? JSON.stringify(body) : void 0;
     const hmac = this.#computeHmacHeaders(
       method.toUpperCase(),
@@ -6099,6 +6887,19 @@ request-rule:${effectiveRequestRule}`;
     return this.#oauthProvidersCache;
   }
   #oauthProvidersCache;
+  /**
+   * Provider API spec discovery: `vault.providerSpecs.list()` /
+   * `.get()` / `.listOperations()` / `.getOperation()`.
+   *
+   * See `provider-specs.ts` for the full API surface.
+   */
+  get providerSpecs() {
+    if (this.#providerSpecsCache === void 0) {
+      this.#providerSpecsCache = new ProviderSpecsNamespace(this);
+    }
+    return this.#providerSpecsCache;
+  }
+  #providerSpecsCache;
   /**
    * Scope catalog discovery: `vault.scopes.list()`.
    */
@@ -6142,13 +6943,11 @@ request-rule:${effectiveRequestRule}`;
    * use the proxy surface, which carries the request method. Endpoints cannot
    * be scoped by a rule (the URL is not a matchable attribute).
    *
-   * HITL caveat: when a request is frozen for human approval (202), the
-   * per-request rule is NOT re-evaluated on the deferred post-approval
-   * execution (it is not snapshotted on the approval). This cannot widen
-   * access — the rule did not match the frozen request at decision time, and
-   * the grant plus every STORED policy rule still bound the execution — but
-   * callers attenuating an approval-required flow should prefer a stored rule
-   * when the constraint must hold at execute time.
+   * HITL behavior: when a request is frozen for human approval (202), the
+   * per-request rule is snapshotted on the approval and RE-APPLIED on the
+   * deferred post-approval execution, so the same attenuation the caller sent
+   * still binds the re-run (a corrupt snapshot fails closed). The rule can
+   * only narrow, never widen.
    *
    * @example
    * ```typescript
@@ -6365,7 +7164,9 @@ request-rule:${effectiveRequestRule}`;
       requestBody.ttl_seconds = ttlSeconds;
     }
     const bodyStr = JSON.stringify(requestBody);
-    const actorHeaders = await this.#getActorRequestHeaders();
+    const actorHeaders = await this.#getActorRequestHeaders(
+      getCurrentAuditContext() ?? void 0
+    );
     const hmacHeaders = this.#computeHmacHeaders("POST", sdkPath, bodyStr);
     let response;
     try {
@@ -6667,6 +7468,14 @@ request-rule:${effectiveRequestRule}`;
     if (options.requiredScopes) {
       sessionBody.required_scopes = options.requiredScopes;
     }
+    if (options.switchAccount !== void 0) {
+      if (typeof options.switchAccount !== "boolean") {
+        throw new AlterValueError("switchAccount must be a boolean");
+      }
+      if (options.switchAccount) {
+        sessionBody.switch_account = true;
+      }
+    }
     if (options.requestedGrant !== void 0) {
       const rg = options.requestedGrant;
       if (rg === null || typeof rg !== "object" || Array.isArray(rg)) {
@@ -7778,7 +8587,7 @@ request-rule:${effectiveRequestRule}`;
       );
     }
     const actorHeaders = await this.#getActorRequestHeaders(
-      args.context,
+      args.context ?? getCurrentAuditContext() ?? void 0,
       args.caller
     );
     const hmacHeaders = this.#computeHmacHeaders("POST", sdkPath, bodyStr);
@@ -8301,129 +9110,6 @@ async function _assertIdentity(client, body) {
     );
   }
 }
-var _alterContextStore = new AsyncLocalStorage();
-var RESERVED_CONTEXT_KEYS = /* @__PURE__ */ new Set([
-  "agent",
-  "parent_agent",
-  "run_id",
-  "thread_id",
-  "tool",
-  "tool_call_id",
-  "framework"
-]);
-var MAX_RUN_METADATA_LENGTH = 4096;
-var MAX_RUN_METADATA_KEYS = 20;
-var MAX_RUN_METADATA_KEY_LENGTH = 64;
-var MAX_RUN_METADATA_VALUE_LENGTH = 512;
-function _stampAgentIdentity(ctx, agentId, options) {
-  const ambientAgent = ctx.agent;
-  if (!options.isAuthoritative && ambientAgent) {
-    return;
-  }
-  if (ambientAgent && ambientAgent !== agentId) {
-    ctx.parent_agent = ambientAgent;
-  }
-  ctx.agent = agentId;
-}
-function _validateRunMetadata(metadata) {
-  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
-    throw new AlterValueError(
-      "trace() metadata must be an object of string key/value pairs"
-    );
-  }
-  const keys = Object.keys(metadata);
-  if (keys.length === 0) {
-    return;
-  }
-  if (keys.length > MAX_RUN_METADATA_KEYS) {
-    throw new AlterValueError(
-      `trace() metadata has too many keys (${keys.length}); max is ${MAX_RUN_METADATA_KEYS}`
-    );
-  }
-  const reserved = keys.filter((k) => RESERVED_CONTEXT_KEYS.has(k)).sort();
-  if (reserved.length > 0) {
-    throw new AlterValueError(
-      `trace() metadata contains reserved key(s) ${JSON.stringify(reserved)}; these are owned by the SDK / framework bridges and cannot be set via metadata. Use the explicit \`runId\` / \`threadId\` kwargs for those. Reserved keys: ${JSON.stringify([...RESERVED_CONTEXT_KEYS].sort())}.`
-    );
-  }
-  let totalSize = 0;
-  for (const k of keys) {
-    const keyBytes = Buffer.byteLength(k, "utf8");
-    if (keyBytes > MAX_RUN_METADATA_KEY_LENGTH) {
-      throw new AlterValueError(
-        `trace() metadata key "${k.slice(0, 32)}" exceeds max length (${keyBytes} > ${MAX_RUN_METADATA_KEY_LENGTH} bytes)`
-      );
-    }
-    const v = metadata[k];
-    if (typeof v !== "string") {
-      throw new AlterValueError(
-        `trace() metadata value for key "${k}" must be a string, got ${typeof v}`
-      );
-    }
-    const valueBytes = Buffer.byteLength(v, "utf8");
-    if (valueBytes > MAX_RUN_METADATA_VALUE_LENGTH) {
-      throw new AlterValueError(
-        `trace() metadata value for key "${k}" exceeds max length (${valueBytes} > ${MAX_RUN_METADATA_VALUE_LENGTH} bytes)`
-      );
-    }
-    totalSize += keyBytes + valueBytes;
-  }
-  if (totalSize > MAX_RUN_METADATA_LENGTH) {
-    throw new AlterValueError(
-      `trace() metadata total size ${totalSize} bytes exceeds ${MAX_RUN_METADATA_LENGTH} byte limit`
-    );
-  }
-}
-async function _withRunScope(options, callback) {
-  const { agentId, runId, threadId, parent, metadata } = options;
-  if (metadata !== void 0) {
-    _validateRunMetadata(metadata);
-  }
-  const outer = _alterContextStore.getStore();
-  const newContext = {};
-  if (outer !== void 0) {
-    for (const [k, v] of Object.entries(outer)) {
-      if (!RESERVED_CONTEXT_KEYS.has(k)) {
-        newContext[k] = v;
-      }
-    }
-    if (outer.agent) {
-      newContext.agent = outer.agent;
-      if (outer.parent_agent) {
-        newContext.parent_agent = outer.parent_agent;
-      }
-    }
-  }
-  _stampAgentIdentity(newContext, agentId, { isAuthoritative: true });
-  if (parent === void 0) {
-  } else if (typeof parent === "string" && parent.length > 0) {
-    newContext.parent_agent = parent;
-  } else {
-    delete newContext.parent_agent;
-  }
-  if (runId !== void 0) {
-    if (typeof runId !== "string") {
-      throw new AlterValueError(`runId must be a string, got ${typeof runId}`);
-    }
-    newContext.run_id = runId;
-  } else if (outer !== void 0 && outer.run_id !== void 0) {
-    newContext.run_id = outer.run_id;
-  }
-  if (threadId !== void 0) {
-    if (typeof threadId !== "string") {
-      throw new AlterValueError(
-        `threadId must be a string, got ${typeof threadId}`
-      );
-    }
-    newContext.thread_id = threadId;
-  } else if (outer !== void 0 && outer.thread_id !== void 0) {
-    newContext.thread_id = outer.thread_id;
-  }
-  if (metadata !== void 0) {
-    Object.assign(newContext, metadata);
-  }
-  return _alterContextStore.run(newContext, callback);
-}
 function _generateLocalRunUuid() {
   const cryptoGlobal = globalThis.crypto;
   if (cryptoGlobal?.randomUUID) {
@@ -8545,6 +9231,14 @@ var Agent = class _Agent {
   get oauthProviders() {
     return this.#client.oauthProviders;
   }
+  /**
+   * Provider API spec discovery (in-band operation discovery):
+   * `agent.providerSpecs.list()` / `.get()` / `.listOperations()` /
+   * `.getOperation()`. Requires the `providers:read` key scope.
+   */
+  get providerSpecs() {
+    return this.#client.providerSpecs;
+  }
   /**
    * User-defined trace spans: `agent.spans.emit()`.
    *
@@ -8604,10 +9298,40 @@ var Agent = class _Agent {
         "App.getAgent(...) is the impersonation surface, NOT delegation-scoped access. request({ grantId }) on this Agent uses the operator credentials and CAN reach grants the named agent has no delegation for. Use new Agent({ apiKey: 'alter_ak_...' }) for true delegation-scoped access, or request({ provider, userToken }) here to route through the agent's delegations."
       );
     }
-    return this.#client.request(method, url, options);
+    try {
+      return await this.#client.request(method, url, options);
+    } catch (e) {
+      throw this.#toAgentGrantError(e);
+    }
   }
   async proxyRequest(...args) {
-    return this.#client.proxyRequest(...args);
+    try {
+      return await this.#client.proxyRequest(...args);
+    } catch (e) {
+      throw this.#toAgentGrantError(e);
+    }
+  }
+  // On the agent path a bare `grant_not_found` 404 is ambiguous — the grant
+  // may not exist, may not be delegated to THIS agent, or a user/base grant_id
+  // was passed where the agent's own delegation id was required (an agent can
+  // only address its own delegation by id). The generic
+  // `GrantNotFoundError` message reads as "stale grant → reconnect", which
+  // sends integrators into a loop. Re-map it to the actionable
+  // `AgentDelegationMissingError` (a `GrantNotFoundError` subclass, so existing
+  // `instanceof GrantNotFoundError` catches still fire). Leave every other
+  // error untouched — including the already-typed `NoDelegatedGrantError`
+  // (a distinct class, not a subclass) and an already-remapped subclass.
+  #toAgentGrantError(e) {
+    if (e instanceof GrantNotFoundError && !(e instanceof AgentDelegationMissingError)) {
+      return new AgentDelegationMissingError(
+        "No grant is resolvable for this agent by the grant_id supplied. The grant may exist but not be delegated to this agent, or a user/base grant_id was passed where the agent's own delegation id is required (get it from agent.listGrants). Run agent.createConnectSession(...) to delegate this agent, or resolve by provider (omit grantId) to route through the agent's existing delegations.",
+        e.details,
+        e.providerId,
+        e.agentId,
+        e.appUserId
+      );
+    }
+    return e;
   }
   // ── trace — audit-context scope for nested calls (TS callback shape) ───
   /**
@@ -8870,6 +9594,8 @@ var App = class _App {
   keys;
   /** OAuth provider catalog discovery. See {@link OAuthProvidersNamespace}. */
   oauthProviders;
+  /** Provider API spec discovery. See {@link ProviderSpecsNamespace}. */
+  providerSpecs;
   /** Scope catalog discovery. See {@link ScopesNamespace}. */
   scopes;
   /** User-defined trace spans. See {@link SpansNamespace}. */
@@ -8890,6 +9616,7 @@ var App = class _App {
       this.agents = this.#client.agents;
       this.keys = this.#client.keys;
       this.oauthProviders = this.#client.oauthProviders;
+      this.providerSpecs = this.#client.providerSpecs;
       this.scopes = this.#client.scopes;
       this.spans = this.#client.spans;
       return;
@@ -8908,6 +9635,7 @@ var App = class _App {
     this.agents = this.#client.agents;
     this.keys = this.#client.keys;
     this.oauthProviders = this.#client.oauthProviders;
+    this.providerSpecs = this.#client.providerSpecs;
     this.scopes = this.#client.scopes;
     this.spans = this.#client.spans;
     _appCredentials.set(this, {
@@ -9717,7 +10445,7 @@ var DEFAULT_BASE_URL = "https://backend.alterauth.com";
 var PAT_API_PREFIX = "/api/v1/dev-portal";
 var HTTP_ERROR_THRESHOLD = 400;
 var DEFAULT_TIMEOUT_MS = 3e4;
-var CLI_VERSION = "0.5.0";
+var CLI_VERSION = "0.6.0";
 var USER_AGENT = buildUserAgent();
 function buildUserAgent() {
   let osTag = "";
@@ -9885,7 +10613,8 @@ var DashboardClient = class {
   keys;
   /** Managed-agent CRUD (CLI `alter agents` subcommands). */
   agents;
-  /** OAuth provider configs (CLI `alter providers` subcommands). */
+  /** OAuth provider configs + the provider API spec store
+   * (CLI `alter providers` subcommands). */
   providers;
   /** Identity-provider create + discover (CLI `alter identity-providers`
    * subcommands). Requires ``dashboard_identity_providers:create``. */
@@ -10569,6 +11298,13 @@ function isProviderCatalogEntry(value) {
   const v = value;
   return typeof v.id === "string" && typeof v.name === "string" && typeof v.display_name === "string" && (v.category === null || typeof v.category === "string") && (v.supports_refresh === null || typeof v.supports_refresh === "boolean") && (v.supports_pkce === null || typeof v.supports_pkce === "boolean") && typeof v.status === "string";
 }
+function isProviderSpecMeta(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const v = value;
+  return typeof v.provider_kind === "string" && typeof v.provider_id === "string" && typeof v.version === "number" && typeof v.provenance === "string" && (v.source_url === null || typeof v.source_url === "string") && typeof v.content_hash === "string" && typeof v.operation_count === "number" && typeof v.fetched_at === "string" && typeof v.changed_at === "string" && (v.title === null || typeof v.title === "string") && (v.spec_version === null || typeof v.spec_version === "string");
+}
 var ProvidersNamespace = class {
   #client;
   constructor(client) {
@@ -10679,6 +11415,96 @@ var ProvidersNamespace = class {
       query ? { query } : {}
     );
   }
+  // ── Provider API spec store (in-band operation discovery) ──────────
+  //
+  // Read-only catalog data served by ``/provider-specs`` on the
+  // dev-portal surface. Any authenticated PAT — no ``dashboard_*``
+  // scope gate (the specs are public provider documentation, the gate
+  // is just "be a signed-in operator").
+  /**
+   * List every provider's active spec metadata (the freshness /
+   * provenance dashboard). ``GET /provider-specs[?kind=oauth|managed]``.
+   */
+  async listSpecs(options = {}) {
+    const query = {};
+    if (options.kind !== void 0) query.kind = options.kind;
+    const body = await this.#client._call(
+      "GET",
+      "/provider-specs",
+      "providers.list_specs",
+      Object.keys(query).length > 0 ? { query } : {}
+    );
+    const dict = expectDict(body, "providers.list_specs", 200);
+    if (!Array.isArray(dict.items) || typeof dict.total !== "number") {
+      throw makeBackendError(
+        "Dashboard client received an unexpected response shape for providers.list_specs: expected { items, total }",
+        200,
+        body
+      );
+    }
+    for (const [i, row] of dict.items.entries()) {
+      if (!isProviderSpecMeta(row)) {
+        throw makeBackendError(
+          `Dashboard client received an unexpected provider-spec row at index ${i}: expected { provider_kind, provider_id, version, provenance, source_url, content_hash, operation_count, fetched_at, changed_at, title, spec_version }`,
+          200,
+          row
+        );
+      }
+    }
+    return dict;
+  }
+  /**
+   * Page one provider's operations from its active spec.
+   * ``GET /provider-specs/{kind}/{provider_id}/operations``.
+   * ``search`` filters server-side; ``limit`` is server-clamped to
+   * 1–500 (default 100).
+   */
+  async listSpecOperations(kind, providerId, options = {}) {
+    const k = encodePathParam(kind, "kind");
+    const provider = encodePathParam(providerId, "providerId");
+    const query = {};
+    if (options.search !== void 0) query.search = options.search;
+    if (options.limit !== void 0) query.limit = String(options.limit);
+    if (options.offset !== void 0) query.offset = String(options.offset);
+    const body = await this.#client._call(
+      "GET",
+      `/provider-specs/${k}/${provider}/operations`,
+      "providers.list_spec_operations",
+      Object.keys(query).length > 0 ? { query } : {}
+    );
+    const page = expectEnvelope(body, "providers.list_spec_operations", 200);
+    const spec = page.spec;
+    if (!isProviderSpecMeta(spec)) {
+      throw makeBackendError(
+        "Dashboard client received an unexpected response shape for providers.list_spec_operations: envelope is missing the spec metadata",
+        200,
+        body
+      );
+    }
+    return page;
+  }
+  /**
+   * One operation with its full parameter/request/response schemas.
+   * ``GET /provider-specs/{kind}/{provider_id}/operations/{operation_id}``.
+   *
+   * Operation ids may contain slashes (GitHub's ``repos/get``) — the
+   * backend route uses a ``:path`` converter, so each SEGMENT of the id
+   * is encoded individually and the literal ``/`` separators are kept.
+   * ``encodePathParam`` per segment preserves the traversal guard: an
+   * id smuggling ``..`` (or an empty segment) is rejected client-side
+   * instead of URL-normalizing onto a different route.
+   */
+  async getSpecOperation(kind, providerId, operationId) {
+    const k = encodePathParam(kind, "kind");
+    const provider = encodePathParam(providerId, "providerId");
+    const op = operationId.split("/").map((segment) => encodePathParam(segment, "operationId")).join("/");
+    const body = await this.#client._call(
+      "GET",
+      `/provider-specs/${k}/${provider}/operations/${op}`,
+      "providers.get_spec_operation"
+    );
+    return expectDict(body, "providers.get_spec_operation", 200);
+  }
 };
 var IdentityProvidersNamespace = class {
   #client;
@@ -10689,7 +11515,7 @@ var IdentityProvidersNamespace = class {
    * Configure an end-user identity provider for an app. Requires
    * `dashboard_identity_providers:create`. ``create`` and ``webhooks`` are the
    * TWO identity-provider carve-outs on the PAT surface (update / delete /
-   * config-reads stay Clerk-only). ``create`` is additive and conflict-guarded
+   * config-reads stay session-only). ``create`` is additive and conflict-guarded
    * (one IDP per app → the backend returns 409 if one already exists, so it can
    * never re-point an already-trusted issuer) and fail-closed on OIDC
    * discovery. BOTH ``create`` and ``webhooks`` (the latter returns the IDP
@@ -10738,7 +11564,7 @@ var IdentityProvidersNamespace = class {
   }
   // ── Webhook lifecycle — requires `dashboard_identity_providers:webhooks`
   // (catalog v7). Per-IDP, recoverable; does NOT touch the issuer/claim
-  // trust config (update/delete stay Clerk-only).
+  // trust config (update/delete stay session-only).
   /** Enable webhook integration and return the signing secret (shown once). */
   async enableWebhook(appId, providerId, options = {}) {
     const app = encodePathParam(appId, "appId");
@@ -10970,6 +11796,32 @@ var ApprovalsNamespace = class {
     );
     return expectDict(body, "approvals.defaults", 200);
   }
+  /** List an app's HITL approvals (newest first), group-aware (N-of-N). */
+  async list(appId, opts = {}) {
+    const app = encodePathParam(appId, "appId");
+    const params = new URLSearchParams();
+    if (opts.status) params.set("status", opts.status);
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts.offset !== void 0) params.set("offset", String(opts.offset));
+    const qs = params.toString();
+    const body = await this.#client._call(
+      "GET",
+      `/apps/${app}/approvals${qs ? `?${qs}` : ""}`,
+      "approvals.list"
+    );
+    return expectDict(body, "approvals.list", 200);
+  }
+  /** One approval with its full gate breakdown + request-rule snapshot. */
+  async get(appId, approvalId) {
+    const app = encodePathParam(appId, "appId");
+    const id = encodePathParam(approvalId, "approvalId");
+    const body = await this.#client._call(
+      "GET",
+      `/apps/${app}/approvals/${id}`,
+      "approvals.get"
+    );
+    return expectDict(body, "approvals.get", 200);
+  }
 };
 var PolicyNamespace = class {
   #client;
@@ -10978,7 +11830,7 @@ var PolicyNamespace = class {
   }
   // NOTE: ``getOrgKeyPolicy`` + ``updateOrgKeyPolicy`` are NOT exposed.
   // ``GET /organizations/current/key-policy`` AND ``PATCH
-  // /organizations/current/key-policy`` are BOTH Clerk-only — per
+  // /organizations/current/key-policy`` are BOTH session-only — per
   // CLAUDE.md "Destructive-Action Policy", org-wide config (reads
   // AND writes) is dashboard-only. The read carve-out that briefly
   // existed was rolled back because the response body is a
@@ -11037,9 +11889,16 @@ var PolicyNamespace = class {
   }
   /**
    * Dry-run the app's custom policy rules for one request shape (grant / method /
-   * endpoint / agent / client-ip / time) and return the composed verdict + per-rule
-   * trace. A read with no side effects (the route is a GET). Requires
-   * `dashboard_app_policy:read`. Foreign/unknown grant or agent ids → 404.
+   * endpoint / agent / client-ip / time / operation / params) and return the
+   * composed verdict + per-rule trace. A read with no side effects (the route
+   * is a GET). Requires `dashboard_app_policy:read`. Foreign/unknown grant or
+   * agent ids → 404.
+   *
+   * ``operationId`` is the explicit attested-operation override the backend
+   * accepts as the ``operation`` query param (service-layer ``operation_id``);
+   * ``simulatedParams`` is the simulated projected parameter bag, JSON-encoded
+   * onto the ``params`` query param (service-layer ``simulated_params``) —
+   * same wire shape the dashboard's policy explorer sends.
    */
   async simulate(appId, options) {
     const query = {
@@ -11052,6 +11911,10 @@ var PolicyNamespace = class {
     if (options.agentId !== void 0) query.agent_id = options.agentId;
     if (options.clientIp !== void 0) query.client_ip = options.clientIp;
     if (options.at !== void 0) query.at = options.at;
+    if (options.operationId !== void 0)
+      query.operation = options.operationId;
+    if (options.simulatedParams !== void 0)
+      query.params = JSON.stringify(options.simulatedParams);
     const out = await this.#client._call(
       "GET",
       `/apps/${encodePathParam(appId, "appId")}/policies/simulate`,
@@ -12007,6 +12870,7 @@ var isBoolean = (v) => typeof v === "boolean";
 var isOptionalString = (v) => v === null || typeof v === "string";
 var isOptionalNumber = (v) => v === null || typeof v === "number";
 var isOptionalBoolean = (v) => v === null || v === void 0 || typeof v === "boolean";
+var isAbsentOrOptionalString = (v) => v === null || v === void 0 || typeof v === "string";
 var isOptionalStringArray = (v) => v === null || v === void 0 || Array.isArray(v) && v.every((x) => typeof x === "string");
 function extractArrayField(body, field, context) {
   const value = body[field];
@@ -12731,6 +13595,18 @@ function surfaceApproverWarnings(row) {
     );
   }
 }
+function surfaceCatalogWarnings(row) {
+  if (typeof row !== "object" || row === null) return;
+  const warnings = row.catalog_warnings;
+  if (!Array.isArray(warnings)) return;
+  for (const warning of warnings) {
+    if (typeof warning !== "string" || warning.length === 0) continue;
+    process.stderr.write(
+      `alter: catalog warning \u2014 ${sanitizeStderrText(warning)} (save was allowed)
+`
+    );
+  }
+}
 
 // src/commands/agents.ts
 var AGENT_COLUMNS = [
@@ -13646,21 +14522,114 @@ function buildAppsCommand() {
 
 // src/commands/approvals.ts
 import { Command as Command4 } from "commander";
+var APPROVAL_STATUSES = [
+  "pending",
+  "approved",
+  "executing",
+  "denied",
+  "expired",
+  "executed",
+  "failed"
+];
+var APPROVAL_ROW_CHECKS = {
+  approval_id: isString,
+  group_status: isString,
+  gate_count: (v) => typeof v === "number",
+  grant_id: isString,
+  grant_type: isString,
+  provider_id: isOptionalString,
+  created_at: isString,
+  expires_at: isString
+};
+var APPROVAL_LIST_COLUMNS = [
+  { label: "ID", get: (a) => a.approval_id },
+  { label: "GROUP", get: (a) => a.group_status },
+  { label: "GATES", get: (a) => String(a.gate_count) },
+  // provider_id is null for managed-secret grants — fall back to the
+  // grant family so the target column is never blank.
+  {
+    label: "PROVIDER",
+    get: (a) => a.provider_id ?? a.grant_type,
+    maxWidth: 20
+  },
+  { label: "GRANT", get: (a) => a.grant_id, maxWidth: 36 },
+  { label: "REQUESTED", get: (a) => a.created_at, maxWidth: 24 },
+  { label: "EXPIRES", get: (a) => a.expires_at, maxWidth: 24 }
+];
 function buildApprovalsCommand() {
   const approvals = new Command4("approvals").description(
-    "Inspect HITL approval configuration (read-only)"
+    "Inspect HITL approvals and approval configuration (read-only)"
+  );
+  approvals.command("defaults").description("Show HITL approval deployment defaults and per-grant bounds").option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: json)",
+    "json"
+  ).action(async (options) => {
+    const format = coerceOutputFormat(options.output);
+    await withClient(async (client) => {
+      const row = await client.approvals.defaults();
+      emit2(format, row);
+    });
+  });
+  approvals.command("list").description(
+    "List an app's HITL approvals (newest first), with the N-of-N group status per row"
+  ).option("--app <id>", "App ID (or ALTER_APP_ID)").option(
+    "--status <status>",
+    `Filter by row status (${APPROVAL_STATUSES.join("|")})`
+  ).option(
+    "--limit <n>",
+    "Page size (1-200, default 50)",
+    parseBoundedInt("--limit", 1, 200)
+  ).option("--offset <n>", "Page offset", parseNonNegativeInt("--offset")).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(
+    async (options) => {
+      const appId = resolveAppIdOrExit(options.app);
+      const format = coerceOutputFormat(options.output);
+      const status = options.status === void 0 ? void 0 : validateChoice("--status", options.status, APPROVAL_STATUSES);
+      await withClient(async (client) => {
+        const page = await client.approvals.list(appId, {
+          ...status ? { status } : {},
+          ...options.limit !== void 0 ? { limit: options.limit } : {},
+          ...options.offset !== void 0 ? { offset: options.offset } : {}
+        });
+        const items = extractArrayField(page, "items", "approvals.list");
+        const rows = validateRows(
+          items,
+          APPROVAL_ROW_CHECKS,
+          "approvals.list"
+        );
+        emit2(format, rows, APPROVAL_LIST_COLUMNS);
+        const total = page.total;
+        const offset = page.offset;
+        if (page.has_more === true && typeof total === "number" && typeof offset === "number") {
+          process.stderr.write(
+            `alter: showing ${rows.length} of ${total} approvals \u2014 pass --offset ${offset + rows.length} for the next page
+`
+          );
+        }
+      });
+    }
   );
-  approvals.command("defaults").description("Show HITL approval deployment defaults and per-grant bounds").option(
+  approvals.command("show").description(
+    "Show one approval with its full N-of-N gate breakdown (per-gate status/approver) and the request-rule snapshot"
+  ).option("--app <id>", "App ID (or ALTER_APP_ID)").requiredOption("--approval <id>", "Approval ID (any gate of the group)").option(
     "--output <format>",
     "Output format: json|jsonl|table (default: json)",
     "json"
-  ).action(async (options) => {
-    const format = coerceOutputFormat(options.output);
-    await withClient(async (client) => {
-      const row = await client.approvals.defaults();
-      emit2(format, row);
-    });
-  });
+  ).action(
+    async (options) => {
+      const appId = resolveAppIdOrExit(options.app);
+      const format = coerceOutputFormat(options.output);
+      validateUuidOrExit("--approval", options.approval);
+      await withClient(async (client) => {
+        const row = await client.approvals.get(appId, options.approval);
+        emit2(format, row);
+      });
+    }
+  );
   return approvals;
 }
 
@@ -14717,7 +15686,7 @@ var DASHBOARD_RESOURCE_VERBS = {
   // signing secret. BOTH ``create`` and ``webhooks`` are in the backend's
   // ``WILDCARD_EXCLUDED_VERBS`` — only the literal scope grants either, never
   // ``*`` or ``dashboard_identity_providers:*``. Update, delete, and config
-  // reads stay Clerk-only (CLAUDE.md Destructive-Action Policy). Backend source
+  // reads stay session-only (CLAUDE.md Destructive-Action Policy). Backend source
   // of truth: _DASHBOARD_RESOURCES_V7.
   dashboard_identity_providers: ["create", "webhooks"],
   // ``dashboard_analytics`` (catalog v7): read-only org usage observability
@@ -16193,6 +17162,13 @@ var GRANT_COLUMNS = [
   { label: "TYPE", get: (g) => g.grant_type },
   { label: "PROVIDER", get: (g) => g.provider_name, maxWidth: 24 },
   { label: "STATUS", get: (g) => g.status },
+  {
+    // The grant-TTL expiry (access duration chosen at consent) — the axis
+    // STATUS's TTL-aware "expired" derives from. Date-only keeps the table
+    // narrow; "—" = perpetual (no TTL) or a pre-field backend.
+    label: "EXPIRES",
+    get: (g) => g.grant_expires_at ? g.grant_expires_at.slice(0, 10) : "\u2014"
+  },
   {
     label: "USER",
     get: (g) => g.user_identifier ?? g.account_display_name ?? "\u2014",
@@ -16283,6 +17259,7 @@ function buildGrantsCommand() {
             created_at: isString,
             last_used_at: isOptionalString,
             expires_at: isOptionalString,
+            grant_expires_at: isAbsentOrOptionalString,
             parent_grant_id: isOptionalString,
             depth: isOptionalNumber,
             delegable: isOptionalBoolean,
@@ -18911,8 +19888,20 @@ var RULE_TYPES = [
   "ip_allowlist",
   "time_window",
   "require_approval",
-  "restriction"
+  "restriction",
+  "quota",
+  "content_match"
+];
+var TIME_WINDOW_DAYS = [
+  "mon",
+  "tue",
+  "wed",
+  "thu",
+  "fri",
+  "sat",
+  "sun"
 ];
+var QUOTA_PERIODS = ["minute", "hour", "day", "month"];
 var MATCHABLE_ATTRIBUTES = [
   "app_id",
   "environment",
@@ -18921,7 +19910,9 @@ var MATCHABLE_ATTRIBUTES = [
   "provider_id",
   "resource_kind",
   "client_ip",
-  "method"
+  "method",
+  "operation",
+  "family"
 ];
 var MAX_WHEN_LIST_VALUES = 100;
 var MAX_WHEN_VALUE_LEN = 512;
@@ -18987,6 +19978,11 @@ function validateWhenMapOrExit(when) {
           `"when.client_ip" matches EXACT IPs only \u2014 CIDR ranges belong in an ip_allowlist rule (--type ip_allowlist)`
         );
       }
+      if (attr === "family" && !OPERATION_FAMILIES.includes(v)) {
+        fail(
+          `when.family names unknown operation family ${JSON.stringify(v)} (expected one of: ${OPERATION_FAMILIES.join(", ")})`
+        );
+      }
     }
   }
 }
@@ -19004,6 +20000,33 @@ function validateJsonMatchBodyOrExit(body) {
   }
   validateWhenMapOrExit(body.when);
 }
+function validateRequireApprovalWhenOrExit(when) {
+  const fail = failRuleBody;
+  if (typeof when !== "object" || when === null || Array.isArray(when)) {
+    fail(`"when" must be an object of condition keys`);
+  }
+  const record = when;
+  const metadata = {};
+  let hasContent = false;
+  for (const [key, value] of Object.entries(record)) {
+    if (key === "match" || key === "params") {
+      hasContent = true;
+    } else {
+      metadata[key] = value;
+    }
+  }
+  if (Object.keys(metadata).length > 0) validateWhenMapOrExit(metadata);
+  if (hasContent) {
+    validateContentMatchBodyOrExit({
+      match: record.match,
+      ...record.params !== void 0 ? { params: record.params } : {},
+      effect: "deny"
+    });
+  }
+  if (Object.keys(metadata).length === 0 && !hasContent) {
+    fail(`"when" must contain at least one condition`);
+  }
+}
 var HITL_MAX_APPROVERS = 10;
 var HITL_MIN_EXPIRY_SECONDS = 60;
 var HITL_MAX_EXPIRY_SECONDS = 86400;
@@ -19048,7 +20071,7 @@ function validateRequireApprovalBodyOrExit(body) {
   if (body.effect !== "require_approval") {
     fail(`effect must be "require_approval"`);
   }
-  if (body.when !== void 0) validateWhenMapOrExit(body.when);
+  if (body.when !== void 0) validateRequireApprovalWhenOrExit(body.when);
   const approval = body.approval;
   if (typeof approval !== "object" || approval === null || Array.isArray(approval)) {
     fail(
@@ -19190,37 +20213,95 @@ function validateIpAllowlistBodyOrExit(body) {
     );
   }
 }
-var TIME_WINDOW_KEYS = [
-  "business_hours_only",
-  "weekdays_only",
-  "timezone"
-];
+var TIME_WINDOW_KEYS = ["windows", "timezone"];
+var TIME_WINDOW_WINDOW_KEYS = ["days", "start", "end"];
+var HHMM_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
 function validateTimeWindowBodyOrExit(body) {
   const fail = failRuleBody;
   for (const k of Object.keys(body)) {
     if (!TIME_WINDOW_KEYS.includes(k)) {
       fail(
-        `unknown key ${JSON.stringify(k)} (expected: ${TIME_WINDOW_KEYS.join(", ")})`
+        `unknown key ${JSON.stringify(k)} (expected: ${TIME_WINDOW_KEYS.join(", ")}). The legacy business_hours_only/weekdays_only grammar was removed \u2014 use {"windows": [{"days": [...], "start": "HH:MM", "end": "HH:MM"}], "timezone": "<IANA>"}`
       );
     }
   }
-  for (const k of ["business_hours_only", "weekdays_only"]) {
-    if (body[k] !== void 0 && typeof body[k] !== "boolean") {
-      fail(`"${k}" must be a boolean`);
+  const windows = body.windows;
+  if (!Array.isArray(windows) || windows.length === 0) {
+    fail(`"windows" must be a non-empty array`);
+    return;
+  }
+  if (windows.length > 20) {
+    fail(`"windows" may not exceed 20 entries`);
+  }
+  windows.forEach((w, i) => {
+    if (typeof w !== "object" || w === null || Array.isArray(w)) {
+      fail(`windows[${i}] must be an object`);
+      return;
+    }
+    const win = w;
+    for (const k of Object.keys(win)) {
+      if (!TIME_WINDOW_WINDOW_KEYS.includes(k)) {
+        fail(`windows[${i}] has unknown key ${JSON.stringify(k)}`);
+      }
+    }
+    const days = win.days;
+    if (!Array.isArray(days) || days.length === 0) {
+      fail(`windows[${i}].days must be a non-empty array`);
+    } else {
+      for (const d of days) {
+        if (typeof d !== "string" || !TIME_WINDOW_DAYS.includes(d)) {
+          fail(
+            `windows[${i}].days has invalid day ${JSON.stringify(d)} (use ${TIME_WINDOW_DAYS.join("/")})`
+          );
+        }
+      }
+      if (new Set(days).size !== days.length) {
+        fail(`windows[${i}].days has duplicate day(s)`);
+      }
+    }
+    const start = win.start;
+    const end = win.end;
+    if (typeof start !== "string" || !HHMM_RE.test(start)) {
+      fail(`windows[${i}].start must be "HH:MM" (00:00\u201323:59)`);
+    }
+    if (typeof end !== "string" || !(HHMM_RE.test(end) || end === "24:00")) {
+      fail(`windows[${i}].end must be "HH:MM" (00:00\u201323:59) or "24:00"`);
+    }
+    if (typeof start === "string" && start === end) {
+      fail(`windows[${i}] start == end (a zero-length window can never match)`);
     }
+  });
+  if (typeof body.timezone !== "string" || body.timezone.trim().length === 0) {
+    fail(
+      `"timezone" is required \u2014 a non-empty IANA timezone string (e.g. "America/New_York")`
+    );
+    return;
   }
-  if (body.business_hours_only !== true && body.weekdays_only !== true) {
+  try {
+    new Intl.DateTimeFormat(void 0, { timeZone: body.timezone });
+  } catch {
     fail(
-      `at least one of "business_hours_only" / "weekdays_only" must be true`
+      `"timezone" ${JSON.stringify(body.timezone)} is not a valid IANA timezone name (e.g. "America/New_York")`
     );
   }
-  if (body.timezone !== void 0) {
-    if (typeof body.timezone !== "string" || body.timezone.trim().length === 0) {
+}
+var QUOTA_KEYS = ["limit", "period"];
+function validateQuotaBodyOrExit(body) {
+  const fail = failRuleBody;
+  for (const k of Object.keys(body)) {
+    if (!QUOTA_KEYS.includes(k)) {
       fail(
-        `"timezone" must be a non-empty IANA timezone string (e.g. "America/New_York")`
+        `unknown key ${JSON.stringify(k)} (expected: ${QUOTA_KEYS.join(", ")})`
       );
     }
   }
+  const limit = body.limit;
+  if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 1e6) {
+    fail(`"limit" must be an integer between 1 and 1000000`);
+  }
+  if (typeof body.period !== "string" || !QUOTA_PERIODS.includes(body.period)) {
+    fail(`"period" must be one of ${QUOTA_PERIODS.join("/")}`);
+  }
 }
 var RESTRICTION_KEYS = ["allowed_methods", "allowed_endpoints"];
 var MAX_RESTRICTION_METHODS = 7;
@@ -19281,6 +20362,195 @@ function validateRestrictionBodyOrExit(body) {
     );
   }
 }
+var CONTENT_MATCH_KEYS = [
+  "match",
+  "params",
+  "effect",
+  "redact",
+  "step_up"
+];
+var CONTENT_MATCH_MATCH_KEYS = ["operations", "families"];
+var CONTENT_MATCH_EFFECTS = ["deny", "redact", "step_up"];
+var CONTENT_NUMERIC_OPS = ["gt", "gte", "lt", "lte"];
+var CONTENT_PARAM_OPS = [
+  "equals",
+  "any_in",
+  "not_subset_of",
+  "gt",
+  "gte",
+  "lt",
+  "lte"
+];
+var OPERATION_FAMILIES = [
+  "send",
+  "read",
+  "write",
+  "delete",
+  "admin",
+  "payment"
+];
+var MAX_CONTENT_MATCH_ENTRIES = 100;
+var MAX_CONTENT_OPERATION_ID_LEN = 255;
+var MAX_CONTENT_PARAM_CONDITIONS = 20;
+var MAX_CONTENT_PARAM_NAME_LEN = 120;
+var MAX_CONTENT_VALUE_ENTRIES = 200;
+var MAX_CONTENT_VALUE_LEN = 512;
+var MAX_CONTENT_REDACT_FIELDS = 50;
+var MAX_CONTENT_REDACT_FIELD_LEN = 120;
+var CONTENT_STEP_UP_MIN_SECONDS = 1;
+var CONTENT_STEP_UP_MAX_SECONDS = 86400;
+function validateContentMatchBodyOrExit(body) {
+  const fail = failRuleBody;
+  for (const k of Object.keys(body)) {
+    if (!CONTENT_MATCH_KEYS.includes(k)) {
+      fail(
+        `unknown key ${JSON.stringify(k)} (expected: ${CONTENT_MATCH_KEYS.join(", ")})`
+      );
+    }
+  }
+  const match = body.match;
+  if (typeof match !== "object" || match === null || Array.isArray(match)) {
+    fail(
+      `"match" object is required ({"operations"?: [...], "families"?: [...]})`
+    );
+  }
+  const m = match;
+  for (const k of Object.keys(m)) {
+    if (!CONTENT_MATCH_MATCH_KEYS.includes(k)) {
+      fail(
+        `unknown match key ${JSON.stringify(k)} (expected: ${CONTENT_MATCH_MATCH_KEYS.join(", ")})`
+      );
+    }
+  }
+  const operations = m.operations ?? [];
+  const families = m.families ?? [];
+  if (!Array.isArray(operations) || !Array.isArray(families)) {
+    fail(`"match.operations" and "match.families" must be lists`);
+  }
+  const ops = operations;
+  const fams = families;
+  if (ops.length === 0 && fams.length === 0) {
+    fail(`"match" must name at least one operation or family`);
+  }
+  if (ops.length + fams.length > MAX_CONTENT_MATCH_ENTRIES) {
+    fail(
+      `"match" exceeds ${MAX_CONTENT_MATCH_ENTRIES} combined operations/families entries`
+    );
+  }
+  for (const opId of ops) {
+    if (typeof opId !== "string" || opId.length === 0 || opId.length > MAX_CONTENT_OPERATION_ID_LEN) {
+      fail(
+        `"match.operations" entries must be non-empty strings of at most ${MAX_CONTENT_OPERATION_ID_LEN} characters`
+      );
+    }
+  }
+  for (const fam of fams) {
+    if (typeof fam !== "string" || !OPERATION_FAMILIES.includes(fam)) {
+      fail(
+        `"match.families" entry ${JSON.stringify(fam)} is not a known operation family (expected one of: ${OPERATION_FAMILIES.join(", ")})`
+      );
+    }
+  }
+  const effect = body.effect;
+  if (typeof effect !== "string" || !CONTENT_MATCH_EFFECTS.includes(effect)) {
+    fail(`"effect" must be one of ${CONTENT_MATCH_EFFECTS.join("/")}`);
+  }
+  if (effect === "redact") {
+    const redact = body.redact;
+    if (typeof redact !== "object" || redact === null || Array.isArray(redact)) {
+      fail(`effect=redact requires a "redact" object ({"fields": [...]})`);
+    }
+    const r = redact;
+    for (const k of Object.keys(r)) {
+      if (k !== "fields") {
+        fail(`unknown redact key ${JSON.stringify(k)} (expected: fields)`);
+      }
+    }
+    const fields2 = r.fields;
+    if (!Array.isArray(fields2) || fields2.length === 0 || fields2.length > MAX_CONTENT_REDACT_FIELDS) {
+      fail(`"redact.fields" must name 1-${MAX_CONTENT_REDACT_FIELDS} fields`);
+    }
+    for (const f of fields2) {
+      if (typeof f !== "string" || f.length === 0 || f.length > MAX_CONTENT_REDACT_FIELD_LEN) {
+        fail(
+          `"redact.fields" entries must be non-empty strings of at most ${MAX_CONTENT_REDACT_FIELD_LEN} characters`
+        );
+      }
+    }
+  } else if (body.redact !== void 0) {
+    fail(`"redact" only applies to effect=redact`);
+  }
+  if (effect === "step_up") {
+    const stepUp = body.step_up;
+    if (typeof stepUp !== "object" || stepUp === null || Array.isArray(stepUp)) {
+      fail(
+        `effect=step_up requires a "step_up" object ({"max_session_age_seconds": <seconds>})`
+      );
+    }
+    const s = stepUp;
+    for (const k of Object.keys(s)) {
+      if (k !== "max_session_age_seconds") {
+        fail(
+          `unknown step_up key ${JSON.stringify(k)} (expected: max_session_age_seconds)`
+        );
+      }
+    }
+    const maxAge = s.max_session_age_seconds;
+    if (typeof maxAge !== "number" || !Number.isInteger(maxAge) || maxAge < CONTENT_STEP_UP_MIN_SECONDS || maxAge > CONTENT_STEP_UP_MAX_SECONDS) {
+      fail(
+        `"step_up.max_session_age_seconds" must be an integer between ${CONTENT_STEP_UP_MIN_SECONDS} and ${CONTENT_STEP_UP_MAX_SECONDS}`
+      );
+    }
+  } else if (body.step_up !== void 0) {
+    fail(`"step_up" only applies to effect=step_up`);
+  }
+  const params = body.params ?? [];
+  if (!Array.isArray(params) || params.length > MAX_CONTENT_PARAM_CONDITIONS) {
+    fail(
+      `"params" must be a list of at most ${MAX_CONTENT_PARAM_CONDITIONS} conditions`
+    );
+  }
+  params.forEach((cond, i) => {
+    if (typeof cond !== "object" || cond === null || Array.isArray(cond)) {
+      fail(`params[${i}] must be an object ({"name", "op", "value"})`);
+    }
+    const c = cond;
+    const condKeys = Object.keys(c);
+    if (condKeys.length !== 3 || condKeys.some((k) => k !== "name" && k !== "op" && k !== "value")) {
+      fail(`params[${i}] needs exactly the keys name/op/value`);
+    }
+    const name = c.name;
+    if (typeof name !== "string" || name.length === 0 || name.length > MAX_CONTENT_PARAM_NAME_LEN) {
+      fail(
+        `params[${i}].name must be a non-empty string of at most ${MAX_CONTENT_PARAM_NAME_LEN} characters`
+      );
+    }
+    const op = c.op;
+    if (typeof op !== "string" || !CONTENT_PARAM_OPS.includes(op)) {
+      fail(`params[${i}].op must be one of ${CONTENT_PARAM_OPS.join("/")}`);
+    }
+    const value = c.value;
+    if (CONTENT_NUMERIC_OPS.includes(op)) {
+      if (typeof value !== "number") {
+        fail(`params[${i}].op ${op} requires a numeric value`);
+      }
+    } else if (op === "equals") {
+      if (typeof value !== "string" && typeof value !== "number") {
+        fail(
+          `params[${i}].op equals requires a scalar value (string or number)`
+        );
+      }
+    } else {
+      if (!Array.isArray(value) || value.length === 0 || value.length > MAX_CONTENT_VALUE_ENTRIES || value.some(
+        (v) => typeof v !== "string" || v.length === 0 || v.length > MAX_CONTENT_VALUE_LEN
+      )) {
+        fail(
+          `params[${i}].op ${op} requires a non-empty list of strings (max ${MAX_CONTENT_VALUE_ENTRIES} entries, ${MAX_CONTENT_VALUE_LEN} characters each)`
+        );
+      }
+    }
+  });
+}
 function validateRuleBodyForTypeOrExit(ruleType, body) {
   if (pythonCompactJsonLength(body) > MAX_RULE_BODY_BYTES) {
     failRuleBody(
@@ -19303,14 +20573,23 @@ function validateRuleBodyForTypeOrExit(ruleType, body) {
     case "restriction":
       validateRestrictionBodyOrExit(body);
       return;
+    case "quota":
+      validateQuotaBodyOrExit(body);
+      return;
+    case "content_match":
+      validateContentMatchBodyOrExit(body);
+      return;
   }
 }
 function detectRuleBodyType(body) {
   if (body.effect === "require_approval" || "approval" in body)
     return "require_approval";
+  if ("match" in body || body.effect === "redact" || body.effect === "step_up" || "redact" in body || "step_up" in body)
+    return "content_match";
   if ("when" in body || "effect" in body) return "json_match";
   if ("allow" in body) return "ip_allowlist";
   if (TIME_WINDOW_KEYS.some((k) => k in body)) return "time_window";
+  if (QUOTA_KEYS.some((k) => k in body)) return "quota";
   if (RESTRICTION_KEYS.some((k) => k in body)) return "restriction";
   return null;
 }
@@ -19396,6 +20675,9 @@ var SIMULATE_TRACE_CHECKS = {
   matched: isBoolean,
   would_deny: isBoolean
 };
+var MAX_SIMULATE_OPERATION_ID_LEN = 255;
+var MAX_SIMULATE_PARAMS_ENTRIES = 20;
+var MAX_SIMULATE_PARAMS_LEN = 8192;
 var SIMULATE_TRACE_COLUMNS = [
   { label: "LEVEL", get: (r) => r.level },
   { label: "TYPE", get: (r) => r.rule_type },
@@ -19495,6 +20777,7 @@ function buildRulesSubcommand() {
         const row = await client.policy.createRule(appId, target, payload);
         emit2(format, row);
         surfaceApproverWarnings(row);
+        surfaceCatalogWarnings(row);
       });
     }
   );
@@ -19584,7 +20867,7 @@ function buildRulesSubcommand() {
         const ruleBody = loadInputJsonBody(options.body, "--body");
         if (detectRuleBodyType(ruleBody) === null) {
           failRuleBody(
-            `unrecognized rule body shape (expected json_match {"when", "effect"}, require_approval {"effect": "require_approval", "approval"}, ip_allowlist {"allow"}, time_window {${TIME_WINDOW_KEYS.map((k) => `"${k}"`).join(", ")}}, or restriction {${RESTRICTION_KEYS.map((k) => `"${k}"`).join(" / ")}})`
+            `unrecognized rule body shape (expected json_match {"when", "effect"}, require_approval {"effect": "require_approval", "approval"}, content_match {"match", "effect"}, ip_allowlist {"allow"}, time_window {${TIME_WINDOW_KEYS.map((k) => `"${k}"`).join(", ")}}, quota {${QUOTA_KEYS.map((k) => `"${k}"`).join(", ")}}, or restriction {${RESTRICTION_KEYS.map((k) => `"${k}"`).join(" / ")}})`
           );
         }
         pendingRuleBody = ruleBody;
@@ -19646,6 +20929,7 @@ function buildRulesSubcommand() {
         );
         emit2(format, row);
         surfaceApproverWarnings(row);
+        surfaceCatalogWarnings(row);
       });
     }
   );
@@ -19720,7 +21004,7 @@ function buildPolicyCommand() {
     });
   });
   policy.command("simulate").description(
-    "Dry-run the app's policy rules for one request shape (grant / method / endpoint / agent / client-ip / time) and print the verdict + per-rule trace. Read-only, no side effects (requires dashboard_app_policy:read)"
+    "Dry-run the app's policy rules for one request shape (grant / method / endpoint / agent / client-ip / time / operation / params) and print the verdict + per-rule trace. Read-only, no side effects (requires dashboard_app_policy:read)"
   ).option(
     "--app <app-id>",
     "App ID. Falls back to ALTER_APP_ID env or .alter/config.yaml"
@@ -19739,6 +21023,12 @@ function buildPolicyCommand() {
   ).option(
     "--at <iso8601>",
     "Instant for time-window rules (ISO 8601; e.g. 2026-05-21T09:00:00Z)"
+  ).option(
+    "--operation <id>",
+    "Explicit attested-operation id override for content_match rules (e.g. gmail.users.messages.send); omit to classify from --endpoint like the live gate"
+  ).option(
+    "--params <json>",
+    `Simulated projected parameter bag for content_match rules, as a JSON object (e.g. '{"recipients": ["bob@other.io"]}'). Values are used only for the dry-run evaluation and never stored`
   ).option(
     "--output <format>",
     "Output format: json|jsonl|table (default: table)",
@@ -19771,6 +21061,49 @@ function buildPolicyCommand() {
         process.exit(EXIT_USAGE);
       }
       const at = options.at !== void 0 ? parseIsoDateArgument("--at")(options.at) : void 0;
+      let operationId;
+      if (options.operation !== void 0) {
+        operationId = options.operation.trim();
+        if (operationId.length === 0 || operationId.length > MAX_SIMULATE_OPERATION_ID_LEN) {
+          process.stderr.write(
+            `alter: --operation must be a non-empty operation id of at most ${MAX_SIMULATE_OPERATION_ID_LEN} characters
+`
+          );
+          process.exit(EXIT_USAGE);
+        }
+      }
+      let simulatedParams;
+      if (options.params !== void 0) {
+        let parsed;
+        try {
+          parsed = JSON.parse(options.params);
+        } catch {
+          process.stderr.write("alter: --params must be valid JSON\n");
+          process.exit(EXIT_USAGE);
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          process.stderr.write(
+            `alter: --params must be a JSON object (not an array or scalar), e.g. '{"recipients": ["bob@other.io"]}'
+`
+          );
+          process.exit(EXIT_USAGE);
+        }
+        simulatedParams = parsed;
+        if (Object.keys(simulatedParams).length > MAX_SIMULATE_PARAMS_ENTRIES) {
+          process.stderr.write(
+            `alter: --params must be a JSON object of at most ${MAX_SIMULATE_PARAMS_ENTRIES} entries
+`
+          );
+          process.exit(EXIT_USAGE);
+        }
+        if (JSON.stringify(simulatedParams).length > MAX_SIMULATE_PARAMS_LEN) {
+          process.stderr.write(
+            `alter: --params exceeds ${MAX_SIMULATE_PARAMS_LEN} characters when JSON-encoded
+`
+          );
+          process.exit(EXIT_USAGE);
+        }
+      }
       await withClient(async (client) => {
         const verdict = await client.policy.simulate(appId, {
           grantId: options.grant,
@@ -19778,7 +21111,9 @@ function buildPolicyCommand() {
           endpoint: options.endpoint,
           agentId: options.agent,
           clientIp: options.clientIp?.trim(),
-          at
+          at,
+          operationId,
+          simulatedParams
         });
         if (format === "json" || format === "jsonl") {
           emit2(format, verdict);
@@ -19796,6 +21131,21 @@ function buildPolicyCommand() {
             "alter: node liveness NOT simulated \u2014 a revoked/expired ancestor in this delegation chain could still deny the live request\n"
           );
         }
+        const classificationReason = typeof verdict.classification_reason === "string" ? verdict.classification_reason : null;
+        const classifiedOperation = typeof verdict.classified_operation === "string" ? verdict.classified_operation : null;
+        if (classificationReason !== null && classificationReason !== "not_simulated") {
+          if (classifiedOperation !== null) {
+            process.stderr.write(
+              `alter: classified operation: ${classifiedOperation}
+`
+            );
+          } else {
+            process.stderr.write(
+              `alter: unclassified request (${classificationReason}) \u2014 content rules targeting this provider DENY unclassified traffic (endpoints outside the policy catalog are refused for ruled traffic)
+`
+            );
+          }
+        }
         const items = extractArrayField(verdict, "rules", "policy.simulate");
         const rows = validateRows(
           items,
@@ -19828,6 +21178,51 @@ var PROVIDER_COLUMNS = [
   { label: "GRANTS", get: (p) => String(p.grants_count) },
   { label: "STATUS", get: (p) => p.status }
 ];
+var PROVIDER_SPEC_KINDS = ["oauth", "managed"];
+var SPEC_COLUMNS = [
+  { label: "KIND", get: (s) => s.provider_kind },
+  { label: "PROVIDER", get: (s) => s.provider_id },
+  { label: "VER", get: (s) => String(s.version) },
+  { label: "OPS", get: (s) => String(s.operation_count) },
+  { label: "PROVENANCE", get: (s) => s.provenance, maxWidth: 16 },
+  { label: "SPEC", get: (s) => s.spec_version ?? "\u2014", maxWidth: 16 },
+  { label: "CHANGED", get: (s) => s.changed_at, maxWidth: 24 },
+  { label: "FETCHED", get: (s) => s.fetched_at, maxWidth: 24 }
+];
+var SPEC_OPERATION_COLUMNS = [
+  { label: "OPERATION", get: (o) => o.operation_id, maxWidth: 40 },
+  { label: "METHOD", get: (o) => o.method },
+  { label: "PATH", get: (o) => o.path_template, maxWidth: 48 },
+  { label: "SUMMARY", get: (o) => o.summary ?? "\u2014", maxWidth: 48 }
+];
+function resolveSpecForProvider(items, providerId) {
+  const matches = items.filter((s) => s.provider_id === providerId);
+  if (new Set(matches.map((s) => s.provider_kind)).size > 1) {
+    return { outcome: "ambiguous" };
+  }
+  const spec = matches[0];
+  if (spec === void 0 || spec.provider_kind !== "oauth" && spec.provider_kind !== "managed") {
+    return { outcome: "not_found" };
+  }
+  return { outcome: "resolved", kind: spec.provider_kind, spec };
+}
+function unwrapSpecResolutionOrExit(resolution, providerId, kind) {
+  if (resolution.outcome === "ambiguous") {
+    process.stderr.write(
+      `alter: provider "${sanitizeStderrText(providerId)}" has API specs in BOTH the oauth and managed families \u2014 pass --kind oauth or --kind managed to pick one
+`
+    );
+    process.exit(EXIT_USAGE);
+  }
+  if (resolution.outcome === "not_found") {
+    process.stderr.write(
+      `alter: no ${kind !== void 0 ? `${kind} ` : ""}provider API spec found for "${sanitizeStderrText(providerId)}" \u2014 run \`alter providers spec list\` to see every provider with an active spec
+`
+    );
+    process.exit(EXIT_NOT_FOUND);
+  }
+  return { kind: resolution.kind, spec: resolution.spec };
+}
 function resolveClientSecret(raw) {
   return resolveSecretArg(raw, "--client-secret");
 }
@@ -19879,7 +21274,7 @@ function surfaceProviderResponse(row) {
 }
 function buildProvidersCommand() {
   const providers = new Command20("providers").description(
-    "Manage OAuth provider configs"
+    "Manage OAuth provider configs and browse provider API specs"
   );
   providers.command("list").description("List OAuth provider configs for an app").option(
     "--app <app-id>",
@@ -20200,6 +21595,170 @@ function buildProvidersCommand() {
       });
     }
   );
+  const spec = new Command20("spec").description(
+    "Inspect provider API spec freshness, provenance, and versions"
+  );
+  spec.command("list").description(
+    "List every provider's active API spec metadata \u2014 version, provenance, operation count, fetch freshness. The spec store's freshness/provenance dashboard, from the CLI."
+  ).option("--kind <kind>", "Filter by provider family: oauth | managed").option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(async (options) => {
+    const format = coerceOutputFormat(options.output);
+    const kind = validateChoice("--kind", options.kind, PROVIDER_SPEC_KINDS);
+    await withClient(async (client) => {
+      const res = await client.providers.listSpecs(
+        kind !== void 0 ? { kind } : {}
+      );
+      emit2(format, res.items, SPEC_COLUMNS);
+    });
+  });
+  spec.command("status").description(
+    "Show one provider's active spec metadata \u2014 version, provenance, operation count, fetch freshness"
+  ).argument("<provider>", "Provider ID (e.g. google, github)").option(
+    "--kind <kind>",
+    "Provider family: oauth | managed. Required only when the provider id exists in both families (e.g. github); otherwise auto-resolved from the spec store."
+  ).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: json)",
+    "json"
+  ).action(
+    async (provider, options) => {
+      const format = coerceOutputFormat(options.output);
+      const kind = validateChoice(
+        "--kind",
+        options.kind,
+        PROVIDER_SPEC_KINDS
+      );
+      const resolution = await withClient(async (client) => {
+        const res = await client.providers.listSpecs(
+          kind !== void 0 ? { kind } : {}
+        );
+        return resolveSpecForProvider(res.items, provider);
+      });
+      const { spec: row } = unwrapSpecResolutionOrExit(
+        resolution,
+        provider,
+        kind
+      );
+      emit2(format, row);
+    }
+  );
+  providers.addCommand(spec);
+  const operations = new Command20("operations").description(
+    "Discover a provider's API operations from its active spec"
+  );
+  operations.command("list").description(
+    "Page one provider's API operations from its active spec (in-band operation discovery)"
+  ).argument("<provider>", "Provider ID (e.g. google, github)").option(
+    "--kind <kind>",
+    "Provider family: oauth | managed. Required only when the provider id exists in both families (e.g. github); otherwise auto-resolved from the spec store."
+  ).option(
+    "--search <q>",
+    "Server-side filter over operation id, method, path, and summary"
+  ).option(
+    "--limit <n>",
+    "Page size (1-500, default 100)",
+    parseBoundedInt("--limit", 1, 500)
+  ).option("--offset <n>", "Page offset", parseNonNegativeInt("--offset")).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: table)",
+    "table"
+  ).action(
+    async (provider, options) => {
+      const format = coerceOutputFormat(options.output);
+      const kindFlag = validateChoice(
+        "--kind",
+        options.kind,
+        PROVIDER_SPEC_KINDS
+      );
+      const outcome = await withClient(async (client) => {
+        let kind = kindFlag;
+        if (kind === void 0) {
+          const res = await client.providers.listSpecs();
+          const resolution = resolveSpecForProvider(res.items, provider);
+          if (resolution.outcome !== "resolved") return resolution;
+          kind = resolution.kind;
+        }
+        const page2 = await client.providers.listSpecOperations(
+          kind,
+          provider,
+          {
+            ...options.search !== void 0 ? { search: options.search } : {},
+            ...options.limit !== void 0 ? { limit: options.limit } : {},
+            ...options.offset !== void 0 ? { offset: options.offset } : {}
+          }
+        );
+        return { outcome: "ok", page: page2 };
+      });
+      if (outcome.outcome !== "ok") {
+        unwrapSpecResolutionOrExit(outcome, provider, kindFlag);
+        return;
+      }
+      const page = outcome.page;
+      const rows = validateRows(
+        page.items,
+        {
+          operation_id: isString,
+          method: isString,
+          path_template: isString,
+          summary: isOptionalString
+        },
+        "providers.list_spec_operations"
+      );
+      emit2(format, rows, SPEC_OPERATION_COLUMNS);
+      if (page.has_more) {
+        process.stderr.write(
+          `alter: showing ${rows.length} of ${page.total} operations \u2014 pass --offset ${page.offset + rows.length} for the next page
+`
+        );
+      }
+    }
+  );
+  operations.command("get").description(
+    "Show one API operation with its full parameter/request/response schemas"
+  ).argument("<provider>", "Provider ID (e.g. google, github)").argument(
+    "<operation-id>",
+    "Operation ID from `alter providers operations list` (may contain slashes, e.g. repos/get)"
+  ).option(
+    "--kind <kind>",
+    "Provider family: oauth | managed. Required only when the provider id exists in both families (e.g. github); otherwise auto-resolved from the spec store."
+  ).option(
+    "--output <format>",
+    "Output format: json|jsonl|table (default: json)",
+    "json"
+  ).action(
+    async (provider, operationId, options) => {
+      const format = coerceOutputFormat(options.output);
+      const kindFlag = validateChoice(
+        "--kind",
+        options.kind,
+        PROVIDER_SPEC_KINDS
+      );
+      const outcome = await withClient(async (client) => {
+        let kind = kindFlag;
+        if (kind === void 0) {
+          const res = await client.providers.listSpecs();
+          const resolution = resolveSpecForProvider(res.items, provider);
+          if (resolution.outcome !== "resolved") return resolution;
+          kind = resolution.kind;
+        }
+        const row = await client.providers.getSpecOperation(
+          kind,
+          provider,
+          operationId
+        );
+        return { outcome: "ok", row };
+      });
+      if (outcome.outcome !== "ok") {
+        unwrapSpecResolutionOrExit(outcome, provider, kindFlag);
+        return;
+      }
+      emit2(format, outcome.row);
+    }
+  );
+  providers.addCommand(operations);
   return providers;
 }