@vectros-ai/mcp-server 0.13.0 → 0.15.0

package/dist/cli.js

@@ -87,6 +87,7 @@ __export(api_exports, {
   TooManyRequestsError: () => TooManyRequestsError,
   TruncationWarningEvent: () => TruncationWarningEvent,
   UnauthorizedError: () => UnauthorizedError,
+  UserExistsResponse: () => UserExistsResponse,
   UserRequest: () => UserRequest,
   UserResponse: () => UserResponse,
   auth: () => auth_exports,
@@ -763,6 +764,14 @@ var TruncationWarningEvent;
     ContextWindowBudget: "context_window_budget"
   };
 })(TruncationWarningEvent || (TruncationWarningEvent = {}));
+var UserExistsResponse;
+((UserExistsResponse2) => {
+  UserExistsResponse2.Status = {
+    Active: "ACTIVE",
+    Suspended: "SUSPENDED",
+    Pending: "PENDING"
+  };
+})(UserExistsResponse || (UserExistsResponse = {}));
 var UserRequest;
 ((UserRequest2) => {
   UserRequest2.Status = {
@@ -2506,7 +2515,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/admin/keys/scoped");
   }
   /**
-   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope.
+   * Creates a scoped API key (an `ssk_*` secret) that inherits its permissions from an existing access profile in your account. The call is idempotent on the combination of tenant, context, user, and key name: re-issuing the same request returns the existing key WITHOUT re-disclosing its raw secret. The raw key is returned ONLY in this response — store it securely, as it cannot be retrieved again. Requires the `keys:c` scope. If you use a scoped credential, `keys:c` alone is not sufficient: because the minted key is durably bound to the profile you name, the profile's effective scopes may not exceed your own, and you may only mint against a profile whose `identityOverrides` values your own identity holds. A root API key (`sk_`) is exempt from both bounds.
    *
    * @param {Vectros.CreateScopedKeyRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -2838,7 +2847,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope, and applies the same `identityOverrides` bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
+   * Creates a new access profile under the given app context. This call is idempotent by `principalId`: if a profile with the same `principalId` already exists, the existing profile is returned (with status 200) instead of creating a duplicate. The response's `created` field (and the HTTP status — 201 when created, 200 when an existing profile was returned) tells the two apart. To overwrite an existing profile's `scopes`/`roleId`, `identityOverrides`, and `status` instead of returning it unchanged, set `?upsert=true` (this also requires the `profiles:u` scope, and applies the same `identityOverrides` bounds the update endpoint documents — a scoped credential may not repoint or clear an identity value it does not itself hold). The `principalId` must name a principal that already exists: a `usr_` principal must be a live user in your tenant, so create the user before granting it a profile. A `usr_` id that names no such user is rejected, and no profile is created. `key_` principals are not checked this way. You must provide exactly one of `scopes` (an inline list of scopes) or `roleId` (a reference to a role); supplying both, or neither, is rejected. `identityOverrides` is keyed by ownership namespace in `scope:<namespace>` form — `scope:org` and `scope:client` for the reserved namespaces, or any namespace you have registered — and may name at most two; any other key (including the account identifier or `userId`) is rejected. If you use a scoped credential, the profile's effective scopes may not exceed your own; a root API key (`sk_`) is exempt. Requires the `profiles:c` scope.
    *
    * @param {Vectros.CreateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3256,11 +3265,12 @@ var AuthClient = class {
     );
   }
   /**
-   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its `identityOverrides` are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (`sk_`) is exempt. Requires the `profiles:u` scope.
+   * Updates an access profile. This is a partial update: any field you omit (or send as null) keeps its existing value. A profile must reference either inline `scopes` or a `roleId`, never both — so setting `scopes` clears any `roleId`, and setting `roleId` clears any inline `scopes`. The `contextId` and `principalId` are immutable. Status changes (for example active to suspended) take effect within about five minutes. If you use a scoped credential, the profile's effective scopes may not exceed your own, and its `identityOverrides` are bounded twice: you may only set a value your own identity holds, and you may only change or clear a value the profile already holds if that value is yours as well. Repointing or clearing another principal's established identity therefore returns 403. A root API key (`sk_`) is exempt. If you set `roleId`, it must reference a role that already exists in this context. Requires the `profiles:u` scope.
    *
    * @param {Vectros.UpdateAccessProfileRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
    *
+   * @throws {@link Vectros.BadRequestError}
    * @throws {@link Vectros.ForbiddenError}
    * @throws {@link Vectros.NotFoundError}
    * @throws {@link Vectros.TooManyRequestsError}
@@ -3307,6 +3317,8 @@ var AuthClient = class {
     }
     if (_response.error.reason === "status-code") {
       switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
         case 403:
           throw new ForbiddenError(_response.error.body, _response.rawResponse);
         case 404:
@@ -3936,7 +3948,7 @@ var AuthClient = class {
     );
   }
   /**
-   * Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when `year` and `month` are omitted. Requires the `billing:r` scope on scoped tokens; API keys always have access.
+   * Returns full usage detail for the requested calendar month, broken down by category (search, documents, and records) with per-category credit estimates and a split between your live and test environments. Defaults to the current month when `year` and `month` are omitted. Requires the `billing:r` scope on scoped tokens; API keys always have access. **A token confined to a single app context sees only that context's usage**: totals, the environment split, and the `contexts` breakdown narrow to it, and the environment your context is not bound to is omitted (`null`), not zeroed. Only a token with cross-context reach sees your full account-wide totals. Two exceptions to the narrowing, since they have no per-context breakdown to narrow to: `reads.calls.used`/`reads.dataOut.bytes` (metered per account, not per context) read as `0` for a confined token rather than a narrowed figure — the corresponding overage-credit charge fields narrow correctly; and `credits.limit` stays your whole plan's ceiling, so `credits.remaining` may overstate the account's true remaining room.
    *
    * @param {Vectros.GetUsageRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -3998,6 +4010,257 @@ var AuthClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/usage");
   }
+  /**
+   * Retrieves a single registered issuer by issuerId. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key sees every context.
+   *
+   * @param {Vectros.GetIssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   *
+   * @example
+   *     await client.auth.getIssuer({
+   *         issuerId: "auth0-prod"
+   *     })
+   */
+  getIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__getIssuer(request, requestOptions));
+  }
+  async __getIssuer(request, requestOptions) {
+    const { issuerId } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/auth/issuers/${url_exports.encodePathParam(issuerId)}`
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers/{issuerId}");
+  }
+  /**
+   * Deregisters a trusted third-party IdP issuer. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context may only deregister an issuer registered in that context; naming one registered in another context returns 404, identically to a nonexistent issuerId. A root API key may deregister any issuer. Refused if any user account was ever created or matched via this issuer (by a prior self-signup or accepted invite, through `POST /v1/auth/token/exchange`) — that access cannot be silently orphaned. Deactivate the affected users first if you intend to cut off their access, or register a replacement issuer before removing this one. An issuer that has never been used for an exchange (no bound users yet) can always be deregistered.
+   *
+   * @param {Vectros.DeleteIssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.deleteIssuer({
+   *         issuerId: "auth0-prod"
+   *     })
+   */
+  deleteIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__deleteIssuer(request, requestOptions));
+  }
+  async __deleteIssuer(request, requestOptions) {
+    const { issuerId } = request;
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        `v1/auth/issuers/${url_exports.encodePathParam(issuerId)}`
+      ),
+      method: "DELETE",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: void 0, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(
+      _response.error,
+      _response.rawResponse,
+      "DELETE",
+      "/v1/auth/issuers/{issuerId}"
+    );
+  }
+  /**
+   * Returns the issuers registered in your tenant. Requires a root API key or the bootstrap's provisioning capability. A credential confined to one app context sees only the issuers registered in that context; a root API key sees every context. Returns a `{data, nextCursor}` envelope.
+   *
+   * @param {Vectros.ListIssuersRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.ForbiddenError}
+   *
+   * @example
+   *     await client.auth.listIssuers()
+   */
+  listIssuers(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__listIssuers(request, requestOptions));
+  }
+  async __listIssuers(request = {}, requestOptions) {
+    const { startFrom, limit } = request;
+    const _queryParams = {
+      startFrom,
+      limit
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/issuers"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/auth/issuers");
+  }
+  /**
+   * Registers a trusted third-party IdP issuer that BYO-IdP token exchange (`POST /v1/auth/token/exchange`) may accept a `subject_token` from. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. Idempotent by `issuerId` within your tenant; the `(issuer, audience)` pair must not already be registered by a different issuerId/tenant. An app context may have at most one active issuer — deregister the existing one first if you need to replace it. One issuer MAY serve several contexts today, each via its own registration row with a distinct `audience`.
+   *
+   * @param {Vectros.IssuerRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.registerIssuer({
+   *         issuerId: "auth0-prod",
+   *         issuer: "https://your-tenant.us.auth0.com/",
+   *         jwksUri: "https://your-tenant.us.auth0.com/.well-known/jwks.json",
+   *         audience: "https://api.your-app.example.com",
+   *         contextId: "casework"
+   *     })
+   */
+  registerIssuer(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__registerIssuer(request, requestOptions));
+  }
+  async __registerIssuer(request, requestOptions) {
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/issuers"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/issuers");
+  }
   /**
    * Returns the identity bound to your credential — your account, principal type, key id, and scope details — so you can confirm who you are authenticated as and that the credential is valid. MCP clients use this to render "signed in as ..." in a chat UI without a separate identity endpoint.
    *
@@ -4043,7 +4306,7 @@ var AuthClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/ping");
   }
   /**
-   * Returns the access profiles for the given principal across all of your contexts. Use this to answer questions like "which apps does this user have access to?" — for example, to build a member-access summary. Results are confined to your account. Requires the `profiles:r` scope.
+   * Returns the access profiles for the given principal. Looking up your OWN principal — or holding the `context-directory-read` capability — returns the profiles across ALL of your contexts, letting you answer questions like "which apps does this user have access to?". A context-bound credential looking up a DIFFERENT principal instead sees only that principal's profile in your credential's own context (at most one result), never across contexts it has no authority over. Results are always confined to your account. Requires the `profiles:r` scope.
    *
    * @param {Vectros.ListProfilesForPrincipalRequest} request
    * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -4321,6 +4584,72 @@ var AuthClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/invite/resend");
   }
+  /**
+   * RFC 8693 OAuth 2.0 Token Exchange. Trades a JWT issued by a third-party identity provider you've registered (`POST /v1/auth/issuers`) for a Vectros `st_*` scoped bearer token — no Vectros credential required to call this endpoint. The exchanged token's scope is resolved entirely server-side from the matched user's access profile; this endpoint accepts no caller-supplied scope, resource, or audience parameter (RFC 8693 §2.1's `resource`/`audience`/`scope` are not used in v1 — the registered `(issuer, audience)` pair alone pins the target tenant and app context). On a first-time login (no existing Vectros identity for this subject), two opt-in binding paths exist: `invite_token` (a `PENDING` sub-user invitation), and — if the registration declares one or more self-signup policies — `signup_type` (a brand-new user is created and bound to the policy's configured role). If `invite_token` is present at all, it is the ONLY path tried — a failed invite never falls through to self-signup. Neither field is required for a subject with an existing identity. If your issuer is registered against more than one app context (each via its own audience), `context_id` selects which one to target; omit it when your token's `aud` claim matches only one registered context — the common case, unaffected by this field. Uses the OAuth-standard error envelope (`{"error":..., "error_description":...}`, RFC 6749 §5.2), NOT this API's usual `{"message":...}` shape — its client is generic OAuth tooling, not the Vectros SDK.
+   *
+   * @param {Vectros.TokenExchangeRequest} request
+   * @param {AuthClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.UnauthorizedError}
+   * @throws {@link Vectros.ForbiddenError}
+   * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.TooManyRequestsError}
+   *
+   * @example
+   *     await client.auth.exchangeToken({
+   *         grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+   *         subject_token: "subject_token",
+   *         subject_token_type: "urn:ietf:params:oauth:token-type:jwt"
+   *     })
+   */
+  exchangeToken(request, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__exchangeToken(request, requestOptions));
+  }
+  async __exchangeToken(request, requestOptions) {
+    const _headers = mergeHeaders(this._options?.headers, requestOptions?.headers);
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/auth/token/exchange"
+      ),
+      method: "POST",
+      headers: _headers,
+      contentType: "application/json",
+      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      requestType: "json",
+      body: request,
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 401:
+          throw new UnauthorizedError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        case 404:
+          throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 429:
+          throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/auth/token/exchange");
+  }
 };
 var ComplianceClient = class {
   constructor(options) {
@@ -5798,6 +6127,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.listEntities({
    *         namespace: "team",
+   *         contextId: "myapp",
    *         startFrom: "b3BhcXVlLWN1cnNvci1mcm9tLXRoZS1wcmV2aW91cy1wYWdl"
    *     })
    */
@@ -5807,6 +6137,7 @@ var IdentityClient = class {
   async __listEntities(request, requestOptions) {
     const {
       namespace,
+      contextId,
       userId,
       externalId,
       scope,
@@ -5821,6 +6152,7 @@ var IdentityClient = class {
       limit
     } = request;
     const _queryParams = {
+      contextId,
       userId,
       externalId,
       scope,
@@ -5879,6 +6211,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.createEntity({
    *         namespace: "team",
+   *         contextId: "myapp",
    *         body: {
    *             externalId: "team_eng_platform"
    *         }
@@ -5888,9 +6221,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__createEntity(request, requestOptions));
   }
   async __createEntity(request, requestOptions) {
-    const { namespace, upsert, body: _body } = request;
+    const { namespace, upsert, contextId, body: _body } = request;
     const _queryParams = {
-      upsert
+      upsert,
+      contextId
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -5947,14 +6281,18 @@ var IdentityClient = class {
    * @example
    *     await client.identity.getEntity({
    *         namespace: "team",
-   *         id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+   *         id: "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+   *         contextId: "myapp"
    *     })
    */
   getEntity(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__getEntity(request, requestOptions));
   }
   async __getEntity(request, requestOptions) {
-    const { namespace, id } = request;
+    const { namespace, id, contextId } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -5968,7 +6306,7 @@ var IdentityClient = class {
       ),
       method: "GET",
       headers: _headers,
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6005,6 +6343,7 @@ var IdentityClient = class {
    *     await client.identity.updateEntity({
    *         namespace: "team",
    *         id: "id",
+   *         contextId: "myapp",
    *         body: {
    *             externalId: "team_eng_platform"
    *         }
@@ -6014,7 +6353,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__updateEntity(request, requestOptions));
   }
   async __updateEntity(request, requestOptions) {
-    const { namespace, id, body: _body } = request;
+    const { namespace, id, contextId, body: _body } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6029,7 +6371,7 @@ var IdentityClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -6069,14 +6411,18 @@ var IdentityClient = class {
    * @example
    *     await client.identity.deleteEntity({
    *         namespace: "team",
-   *         id: "id"
+   *         id: "id",
+   *         contextId: "myapp"
    *     })
    */
   deleteEntity(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__deleteEntity(request, requestOptions));
   }
   async __deleteEntity(request, requestOptions) {
-    const { namespace, id } = request;
+    const { namespace, id, contextId } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6090,7 +6436,7 @@ var IdentityClient = class {
       ),
       method: "DELETE",
       headers: _headers,
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6133,6 +6479,7 @@ var IdentityClient = class {
    * @example
    *     await client.identity.lookupEntities({
    *         namespace: "team",
+   *         contextId: "myapp",
    *         body: {
    *             type: "person_v1",
    *             field: "ssn"
@@ -6143,7 +6490,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__lookupEntities(request, requestOptions));
   }
   async __lookupEntities(request, requestOptions) {
-    const { namespace, body: _body } = request;
+    const { namespace, contextId, body: _body } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6158,7 +6508,7 @@ var IdentityClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -6202,15 +6552,17 @@ var IdentityClient = class {
    * @example
    *     await client.identity.getEntityVersions({
    *         namespace: "team",
-   *         id: "id"
+   *         id: "id",
+   *         contextId: "myapp"
    *     })
    */
   getEntityVersions(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__getEntityVersions(request, requestOptions));
   }
   async __getEntityVersions(request, requestOptions) {
-    const { namespace, id, startFrom } = request;
+    const { namespace, id, contextId, startFrom } = request;
     const _queryParams = {
+      contextId,
       startFrom
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
@@ -6272,7 +6624,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__getNamespace(request, requestOptions));
   }
   async __getNamespace(request, requestOptions) {
-    const { namespace } = request;
+    const { namespace, contextId } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6286,7 +6641,7 @@ var IdentityClient = class {
       ),
       method: "GET",
       headers: _headers,
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6311,7 +6666,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces/{namespace}");
   }
   /**
-   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`, `specificityRank`) of a registered namespace. The namespace name itself is immutable. Requires a root API key. The reserved built-ins cannot be updated.
+   * Updates the mutable fields (`entityBacked`, `defaultSchemaId`, `specificityRank`) of a registered namespace. The namespace name and its `contextId` (which row is selected) are both immutable. Requires a root API key. `org` and `client` are updatable like any other namespace — there is no reserved-built-in exception.
    *
    * @param {Vectros.UpdateNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6333,7 +6688,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__updateNamespace(request, requestOptions));
   }
   async __updateNamespace(request, requestOptions) {
-    const { namespace, body: _body } = request;
+    const { namespace, contextId, body: _body } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6348,7 +6706,7 @@ var IdentityClient = class {
       method: "PUT",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
       body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
@@ -6379,7 +6737,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/namespaces/{namespace}");
   }
   /**
-   * Deletes a registered scope namespace. Requires a root API key. The reserved built-ins cannot be deleted. A namespace that still has entities cannot be deleted (409) — delete its entities first; this keeps them reachable by the account-teardown and erasure sweeps.
+   * Deletes a registered scope namespace. Requires a root API key. `org` and `client` are deletable like any other namespace — there is no reserved-built-in exception. A namespace that still has entities cannot be deleted (409) — delete its entities first; this keeps them reachable by the account-teardown and erasure sweeps.
    *
    * @param {Vectros.DeleteNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6397,7 +6755,10 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__deleteNamespace(request, requestOptions));
   }
   async __deleteNamespace(request, requestOptions) {
-    const { namespace } = request;
+    const { namespace, contextId } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6411,7 +6772,7 @@ var IdentityClient = class {
       ),
       method: "DELETE",
       headers: _headers,
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6440,7 +6801,7 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "DELETE", "/v1/namespaces/{namespace}");
   }
   /**
-   * Returns the scope namespaces registered in your account, with the reserved built-ins `org` and `client` listed first. Returns a `{data, nextCursor}` envelope.
+   * Returns the scope namespaces in your account, including `org` and `client`, which are provisioned for you when the account is created. Returns a `{data, nextCursor}` envelope.
    *
    * @param {Vectros.ListNamespacesRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -6452,10 +6813,11 @@ var IdentityClient = class {
     return HttpResponsePromise.fromPromise(this.__listNamespaces(request, requestOptions));
   }
   async __listNamespaces(request = {}, requestOptions) {
-    const { startFrom, limit } = request;
+    const { startFrom, limit, contextId } = request;
     const _queryParams = {
       startFrom,
-      limit
+      limit,
+      contextId
     };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
@@ -6490,9 +6852,9 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/namespaces");
   }
   /**
-   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Also requires `specificityRank`, an explicit, account-unique position in the specificity order used to break recordType schema-resolution ties. Requires a root API key. The reserved names `org` and `client` are built in and cannot be registered.
+   * Registers a new scope namespace and declares whether its values resolve to identity entities (`entityBacked`). Also requires `specificityRank`, an explicit, account-unique position in the specificity order used to break recordType schema-resolution ties. Requires a root API key or the CLI bootstrap's provisioning capability — never an ordinary partner-grantable scope. `org` and `client` are provisioned when your account is created, so registering either returns the already-registered error.
    *
-   * @param {Vectros.NamespaceRequest} request
+   * @param {Vectros.RegisterNamespaceRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.BadRequestError}
@@ -6501,14 +6863,20 @@ var IdentityClient = class {
    *
    * @example
    *     await client.identity.registerNamespace({
-   *         namespace: "team",
-   *         specificityRank: 1500
+   *         body: {
+   *             namespace: "team",
+   *             specificityRank: 1500
+   *         }
    *     })
    */
   registerNamespace(request, requestOptions) {
     return HttpResponsePromise.fromPromise(this.__registerNamespace(request, requestOptions));
   }
   async __registerNamespace(request, requestOptions) {
+    const { contextId, body: _body } = request;
+    const _queryParams = {
+      contextId
+    };
     const _authRequest = await this._options.authProvider.getAuthRequest();
     const _headers = mergeHeaders(
       _authRequest.headers,
@@ -6523,9 +6891,9 @@ var IdentityClient = class {
       method: "POST",
       headers: _headers,
       contentType: "application/json",
-      queryString: url_exports.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
       requestType: "json",
-      body: request,
+      body: _body,
       timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
       maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
       abortSignal: requestOptions?.abortSignal,
@@ -6810,12 +7178,13 @@ var IdentityClient = class {
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "PUT", "/v1/users/{id}");
   }
   /**
-   * Permanently deletes a user identity. This cannot be undone. If the user is a pending invitation, the associated access profile created for that invitation is also removed. Requires the `users:d` scope.
+   * Permanently deletes a user identity. This cannot be undone. If the user is a pending invitation, the associated access profile created for that invitation is also removed. Requires the `users:d` scope. Deleting your account's last OWNER is refused (409) — an account must always retain at least one owner.
    *
    * @param {Vectros.DeleteUserRequest} request
    * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
    *
    * @throws {@link Vectros.NotFoundError}
+   * @throws {@link Vectros.ConflictError}
    * @throws {@link Vectros.TooManyRequestsError}
    *
    * @example
@@ -6855,6 +7224,8 @@ var IdentityClient = class {
       switch (_response.error.statusCode) {
         case 404:
           throw new NotFoundError(_response.error.body, _response.rawResponse);
+        case 409:
+          throw new ConflictError(_response.error.body, _response.rawResponse);
         case 429:
           throw new TooManyRequestsError(_response.error.body, _response.rawResponse);
         default:
@@ -6928,6 +7299,69 @@ var IdentityClient = class {
     }
     return handleNonStatusCodeError(_response.error, _response.rawResponse, "POST", "/v1/users/lookup");
   }
+  /**
+   * Answers "does a user with this email hold an ACTIVE access profile in this app context" — a narrow existence check, not a general lookup. `exists` is false for a member whose access to this context has been suspended, not only for a member who was never granted it. The answer is scoped to the `contextId` you supply: it does not reveal whether the email exists elsewhere in your tenant or account, only whether it belongs to an active member of the named context. Returns `{exists, userId, status}` — never the full user record — so a caller asking "does X exist" cannot receive that user's payload/schema binding/etc. as a side effect. Useful for resolving an email you were handed (for example, by an org-admin adding an existing member to another org) to a `userId`, without paging through the full context membership. Requires the `users:r` scope.
+   *
+   * @param {Vectros.UserExistsByEmailRequest} request
+   * @param {IdentityClient.RequestOptions} requestOptions - Request-specific configuration.
+   *
+   * @throws {@link Vectros.BadRequestError}
+   * @throws {@link Vectros.ForbiddenError}
+   *
+   * @example
+   *     await client.identity.userExistsByEmail({
+   *         email: "user@example.com",
+   *         contextId: "myapp"
+   *     })
+   */
+  userExistsByEmail(request = {}, requestOptions) {
+    return HttpResponsePromise.fromPromise(this.__userExistsByEmail(request, requestOptions));
+  }
+  async __userExistsByEmail(request = {}, requestOptions) {
+    const { email, contextId } = request;
+    const _queryParams = {
+      email,
+      contextId
+    };
+    const _authRequest = await this._options.authProvider.getAuthRequest();
+    const _headers = mergeHeaders(
+      _authRequest.headers,
+      this._options?.headers,
+      requestOptions?.headers
+    );
+    const _response = await fetcher({
+      url: url_exports.join(
+        await Supplier.get(this._options.baseUrl) ?? await Supplier.get(this._options.environment),
+        "v1/users/exists-by-email"
+      ),
+      method: "GET",
+      headers: _headers,
+      queryString: url_exports.queryBuilder().addMany(_queryParams).mergeAdditional(requestOptions?.queryParams).build(),
+      timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1e3,
+      maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+      abortSignal: requestOptions?.abortSignal,
+      fetchFn: this._options?.fetch,
+      logging: this._options.logging
+    });
+    if (_response.ok) {
+      return { data: _response.body, rawResponse: _response.rawResponse };
+    }
+    if (_response.error.reason === "status-code") {
+      switch (_response.error.statusCode) {
+        case 400:
+          throw new BadRequestError(_response.error.body, _response.rawResponse);
+        case 403:
+          throw new ForbiddenError(_response.error.body, _response.rawResponse);
+        default:
+          throw new VectrosError({
+            statusCode: _response.error.statusCode,
+            body: _response.error.body,
+            rawResponse: _response.rawResponse
+          });
+      }
+    }
+    return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/users/exists-by-email");
+  }
   /**
    * Returns the audit trail of changes to a user, most recent first. Identity history is always recorded and always available. Sensitive field values are redacted in every historical version. Returns a page in the `{data, nextCursor}` envelope. Requires the `users:r` scope.
    *
@@ -8684,15 +9118,15 @@ function warnOnSuboptimalKey(key, log) {
   } else if (key.prefix === "st") {
     log.warn(
       { prefix: key.prefix, env: key.env },
-      "short-lived token (st_*) will expire mid-session (1h default, 24h max). For long-running MCP installs, prefer a long-lived ssk_* key."
+      "short-lived token (st_*) will expire mid-session (1h max). For long-running MCP installs, prefer a long-lived ssk_* key."
     );
   }
 }
 
 // src/build-info.ts
 var BUILD_INFO = {
-  mcpServer: true ? "0.13.0" : "dev",
-  sdk: true ? "0.38.0" : "dev"
+  mcpServer: true ? "0.15.0" : "dev",
+  sdk: true ? "0.40.0" : "dev"
 };
 function formatBuildInfo() {
   return `vectros-mcp-server ${BUILD_INFO.mcpServer} (sdk ${BUILD_INFO.sdk})`;
@@ -9003,7 +9437,7 @@ var inputSchema = {
   // Ownership.
   userId: import_zod.z.string().optional().describe("Restrict to content owned by this user (Vectros UUID)."),
   scope: import_zod.z.string().optional().describe(
-    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces; others are custom scopes you define.'
+    'Restrict to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
   // Date window.
   createdAfter: import_zod.z.string().optional().describe("Restrict to content created at/after this ISO 8601 UTC timestamp."),
@@ -9143,7 +9577,7 @@ var inputSchema2 = {
   // List-mode args:
   userId: import_zod2.z.string().optional().describe("List mode: scope to records owned by this user."),
   scope: import_zod2.z.string().optional().describe(
-    'List mode: filter to records carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces; others are custom scopes you define.'
+    'List mode: filter to records carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
   startFrom: import_zod2.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: import_zod2.z.number().int().min(1).max(MCP_MAX_LIMIT2).optional().describe(
@@ -9394,7 +9828,7 @@ var inputSchema4 = {
   folderId: import_zod4.z.string().optional().describe("Group this record into a folder."),
   userId: import_zod4.z.string().optional().describe("Owning user id."),
   scopes: import_zod4.z.array(import_zod4.z.string()).optional().describe(
-    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are built-in namespaces; others are custom scopes you define. This is the record\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the record\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE record owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
   )
 };
 var recordCreate = ({ client, log }) => ({
@@ -9518,7 +9952,7 @@ var inputSchema7 = {
     // whole-tenant corpus.
     userId: import_zod7.z.string().optional().describe("Restrict retrieval to content owned by this user (Vectros UUID)."),
     scope: import_zod7.z.string().optional().describe(
-      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces; others are custom scopes you define.'
+      'Restrict retrieval to content carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
     ),
     folderId: import_zod7.z.string().optional().describe("Restrict retrieval to this exact folder."),
     rootFolderId: import_zod7.z.string().optional().describe("Restrict retrieval to this folder and all its descendants."),
@@ -9692,7 +10126,7 @@ var inputSchema9 = {
     "Filter to schemas visible to a specific user. Optional; default returns all schemas the credential can see."
   ),
   scope: import_zod9.z.string().optional().describe(
-    'Filter to schemas carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces. Optional; default returns all schemas the credential can see.'
+    'Filter to schemas carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other. Optional; default returns all schemas the credential can see.'
   ),
   surface: import_zod9.z.enum(["record", "document", "user", "entity"]).optional().describe(
     "Filter to schemas bindable to this surface \u2014 e.g. `document` to list only document types, or `record` for record types. Identity entities in any namespace (org/client/one you registered) bind under the single `entity` surface; `user` and `entity` are account-wide. Optional."
@@ -9842,7 +10276,7 @@ var inputSchema11 = {
   folderId: import_zod11.z.string().optional().describe("List mode: only documents in this folder (Vectros folder id)."),
   userId: import_zod11.z.string().optional().describe("List mode: scope to documents owned by this user."),
   scope: import_zod11.z.string().optional().describe(
-    'List mode: filter to documents carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces; others are custom scopes you define.'
+    'List mode: filter to documents carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
   startFrom: import_zod11.z.string().optional().describe("Pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next. Works in both list and lookup mode."),
   limit: import_zod11.z.number().int().min(1).max(MCP_MAX_LIMIT3).optional().describe(
@@ -9953,7 +10387,7 @@ var inputSchema12 = {
   ),
   userId: import_zod12.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
   scopes: import_zod12.z.array(import_zod12.z.string()).optional().describe(
-    'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are built-in namespaces. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
+    'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are reserved namespace names, registered like any other. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
   ),
   expectedVersion: import_zod12.z.number().int().optional().describe(
     "Optimistic concurrency: the version you last read. If the document changed since, the update is refused as a conflict (re-read and retry). Omit for last-write-wins."
@@ -10037,7 +10471,7 @@ var inputSchema14 = {
   parentId: import_zod14.z.string().optional().describe("List mode: direct children of this folder (tree navigation). Omit for a flat tenant list."),
   userId: import_zod14.z.string().optional().describe("List mode: scope to folders owned by this user."),
   scope: import_zod14.z.string().optional().describe(
-    'List mode: filter to folders carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are built-in namespaces; others are custom scopes you define.'
+    'List mode: filter to folders carrying this scope value, in `namespace:value` form (e.g. "org:<uuid>", "client:<uuid>", "group:eng-team"). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself.'
   ),
   startFrom: import_zod14.z.string().optional().describe("List mode: pagination cursor \u2014 pass the `nextCursor` from the previous page to fetch the next."),
   limit: import_zod14.z.number().int().min(1).max(MCP_MAX_LIMIT4).optional().describe(
@@ -10086,7 +10520,7 @@ var inputSchema15 = {
   slug: import_zod15.z.string().optional().describe("Optional stable slug (sibling-unique; idempotency key). Lowercase letters/digits/hyphens. Derived from name when omitted."),
   userId: import_zod15.z.string().optional().describe("Owning user (Vectros UUID)."),
   scopes: import_zod15.z.array(import_zod15.z.string()).optional().describe(
-    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are built-in namespaces; others are custom scopes you define. This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
+    'Scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the folder\'s COMPLETE scope declaration and values must come from the credential\'s own identity. An empty array `[]` creates a PRIVATE folder owned by the calling user alone. Omit to stamp the credential\'s full identity \u2014 the default.'
   )
 };
 var folderCreate = ({ client, log }) => ({
@@ -10124,7 +10558,7 @@ var inputSchema16 = {
   description: import_zod16.z.string().optional().describe("New description. Omit to leave unchanged."),
   userId: import_zod16.z.string().optional().describe("Reassign the owning user (Vectros UUID)."),
   scopes: import_zod16.z.array(import_zod16.z.string()).optional().describe(
-    'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are built-in namespaces. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
+    'Reassign scope ownership as `namespace:value` entries, at most 2 (e.g. ["org:<uuid>", "group:eng-team"]) \u2014 the COMPLETE new parent set. `org`/`client` are reserved namespace names, registered like any other. Omit to leave ownership unchanged; `[]` clears it (private to the owning user).'
   ),
   expectedVersion: import_zod16.z.number().int().optional().describe(
     "Optimistic concurrency: the version you last read. If the folder changed since, the update is refused as a conflict (re-read and retry). Omit for last-write-wins."
@@ -10191,7 +10625,7 @@ var inputSchema18 = {
 var currentIdentity = ({ log, apiKey, environment }) => ({
   name: "current_identity",
   title: "Current identity (tenant + principal scope)",
-  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
+  description: "Describe the credential the MCP server is operating under. Returns tenantId, environment (staging|production), principalType (root_key|scoped_key|token), principalKeyId, principalLabel, and (for scoped credentials) allowedActions plus dataScope \u2014 the credential's verb+ownership reach as { userId, scopes[] }, where each scope is a `namespace:value` string (e.g. \"org:<uuid>\"). Note: this does not yet include granted_capabilities (member-lifecycle / forensic-read / context-directory-read / delegate-mint) \u2014 a separate reach dimension a scope clause can carry as of API 0.40.0 that /v1/ping does not report yet, so allowedActions+dataScope may understate a credential's true reach. Also reports mcpServerVersion (this server's own package version) and sdkVersion (the bundled @vectros-ai/sdk version) so a caller can tell what build it's talking to. Use this when the user asks 'what can you do here?', 'what tenant am I in?', or 'what version is this?'. Calls GET /v1/ping under the hood.",
   inputSchema: inputSchema18,
   handler: async () => {
     try {
@@ -10314,7 +10748,7 @@ var inputSchema19 = {
   folderId: import_zod18.z.string().optional().describe("Optional folder to ingest into. Default: tenant root."),
   userId: import_zod18.z.string().optional().describe("Owning user ID. Optional."),
   scopes: import_zod18.z.array(import_zod18.z.string()).optional().describe(
-    "TEXT MODE ONLY. Scope ownership as `namespace:value` entries, at most 2 (e.g. [\"org:<uuid>\", \"group:eng-team\"]). `org` and `client` are built-in namespaces; others are custom scopes you define. This is the document's COMPLETE scope declaration and values must come from the credential's own identity. An empty array `[]` creates a PRIVATE document owned by the calling user alone. Omit to stamp the credential's full identity \u2014 the default. Rejected with `filePath` (file uploads do not accept a scope declaration): a file-uploaded document is stamped with the credential's full identity."
+    "TEXT MODE ONLY. Scope ownership as `namespace:value` entries, at most 2 (e.g. [\"org:<uuid>\", \"group:eng-team\"]). `org` and `client` are reserved namespace names, registered like any other; others are namespaces you registered yourself. This is the document's COMPLETE scope declaration and values must come from the credential's own identity. An empty array `[]` creates a PRIVATE document owned by the calling user alone. Omit to stamp the credential's full identity \u2014 the default. Rejected with `filePath` (file uploads do not accept a scope declaration): a file-uploaded document is stamped with the credential's full identity."
   )
 };
 var documentIngest = ({ client, log, transport, ingestRoot }) => ({
@@ -10478,11 +10912,14 @@ var MCP_DEFAULT_LIMIT5 = 10;
 var MCP_MAX_LIMIT5 = 100;
 var inputSchema20 = {
   kind: import_zod19.z.string().describe(
-    'Which principal to look up: "user" (the fixed principal surface), or an entity namespace \u2014 "org", "client" (built in), or a namespace you registered.'
+    'Which principal to look up: "user" (the fixed principal surface), or an entity namespace \u2014 "org", "client" (reserved, registered like any other), or a namespace you registered.'
   ),
   externalId: import_zod19.z.string().optional().describe(
     "Resolve mode: your own stable identifier for the principal. Returns the single matching principal (with its Vectros UUID), or an empty array if none. The fastest path to the UUID the ownership filters need. Takes precedence if both this and a `field` lookup are supplied."
   ),
+  contextId: import_zod19.z.string().optional().describe(
+    "Entity kinds only (not `user`, which is always tenant-wide): the app context to look up entities in, for a namespace registered as context-owned rather than tenant-wide. A context-confined credential's own context is used automatically without this; supply it to name a context explicitly (required for an unconfined/root credential to reach a context-owned namespace). Rejected if the namespace turns out to be tenant-wide."
+  ),
   // Lookup-mode args — provide `field` plus EXACTLY ONE of: value | from+to | prefix.
   type: import_zod19.z.string().optional().describe('Lookup mode: the identity schema\'s record type (e.g. "person_v1"). Required with `field`.'),
   field: import_zod19.z.string().optional().describe('Lookup mode: name of the schema-declared lookup field to query by (e.g. "email").'),
@@ -10499,13 +10936,14 @@ var inputSchema20 = {
 var lookupPrincipal = ({ client, log }) => ({
   name: "lookup_principal",
   title: "Look up a user identity or a namespaced identity entity",
-  description: "Resolve a user, or an identity entity in a namespace (org/client/one you registered). Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
+  description: "Resolve a user, or an identity entity in a namespace (org/client/one you registered). Two modes:\n  \u2022 Resolve by your own id: pass `externalId` \u2192 the matching principal incl. its Vectros UUID (the id the ownership filters on record_query / hybrid_search / rag_ask expect).\n  \u2022 Lookup by a schema field: pass `type` and `field` plus exactly one of `value` (exact), `from`+`to` (range), or `prefix`. Sensitive-field-safe. (If both `externalId` and a `field` lookup are given, `externalId` wins.) For an entity kind, `contextId` names a specific app context when the namespace is context-owned rather than tenant-wide; a context-confined credential's own context is used automatically without it. Returns a `{ data, nextCursor }` page (default 10, max 100 \u2014 raise it in one call when you can accept the payload); a non-null `nextCursor` means more remain \u2014 pass it back as `startFrom`. Read-only \u2014 does not create or modify identities.",
   inputSchema: inputSchema20,
   handler: async (args) => {
     const kind = args.kind;
     const isUser = kind === "user";
     const limit = args.limit ?? MCP_DEFAULT_LIMIT5;
     const externalId = args.externalId;
+    const contextId = args.contextId;
     const type = args.type;
     const field = args.field;
     const value = args.value;
@@ -10514,11 +10952,18 @@ var lookupPrincipal = ({ client, log }) => ({
     const prefix = args.prefix;
     const order = args.order;
     const startFrom = args.startFrom;
+    if (contextId !== void 0 && isUser) {
+      return toolError(
+        "lookup_principal",
+        new Error("'contextId' does not apply to kind 'user' \u2014 the user surface is always tenant-wide.")
+      );
+    }
+    const contextIdArg = contextId !== void 0 ? { contextId } : {};
     try {
       let page;
       if (externalId !== void 0) {
-        page = isUser ? await client.identity.listUsers({ externalId, limit }) : await client.identity.listEntities({ namespace: kind, externalId, limit });
-        log.debug({ tool: "lookup_principal", mode: "resolve", kind }, "lookup_principal resolve ok");
+        page = isUser ? await client.identity.listUsers({ externalId, limit }) : await client.identity.listEntities({ namespace: kind, ...contextIdArg, externalId, limit });
+        log.debug({ tool: "lookup_principal", mode: "resolve", kind, contextId }, "lookup_principal resolve ok");
       } else if (field !== void 0) {
         const hasEquality = value !== void 0;
         const hasRange = from !== void 0 || to !== void 0;
@@ -10546,8 +10991,8 @@ var lookupPrincipal = ({ client, log }) => ({
           );
         }
         const req = { type, field, value, from, to, prefix, order, startFrom, limit };
-        page = isUser ? await client.identity.lookupUsers(req) : await client.identity.lookupEntities({ namespace: kind, body: req });
-        log.debug({ tool: "lookup_principal", mode: "lookup", kind, type, field }, "lookup_principal lookup ok");
+        page = isUser ? await client.identity.lookupUsers(req) : await client.identity.lookupEntities({ namespace: kind, ...contextIdArg, body: req });
+        log.debug({ tool: "lookup_principal", mode: "lookup", kind, type, field, contextId }, "lookup_principal lookup ok");
       } else {
         return toolError(
           "lookup_principal",
@@ -10558,7 +11003,7 @@ var lookupPrincipal = ({ client, log }) => ({
       const nextCursor = page.nextCursor ?? null;
       return { content: [{ type: "text", text: JSON.stringify({ data: principals, nextCursor }, null, 2) }] };
     } catch (err) {
-      log.warn({ tool: "lookup_principal", kind, err: String(err) }, "lookup_principal failed");
+      log.warn({ tool: "lookup_principal", kind, contextId, err: String(err) }, "lookup_principal failed");
       return toolError("lookup_principal", err);
     }
   }
@@ -10669,7 +11114,7 @@ var identityResource = ({ log, apiKey, environment }) => ({
   name: "identity",
   uri: "vectros://identity",
   title: "Current identity (tenant + principal scope)",
-  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }), plus mcpServerVersion and sdkVersion (this build's own version and the bundled @vectros-ai/sdk version). The /v1/ping backing call ships the extended shape today; the version fields are always client-derived.",
+  description: "The tenant + principal scope the MCP server is authenticated as. Returns the same payload as the `current_identity` tool: status, tenantId, environment, principalType, principalKeyId, principalLabel, (for scoped credentials) allowedActions + dataScope ({ userId, scopes[] }). Note: this does not yet include granted_capabilities (member-lifecycle / forensic-read / context-directory-read / delegate-mint) \u2014 a separate reach dimension a scope clause can carry as of API 0.40.0 that /v1/ping does not report yet, so allowedActions+dataScope may understate a credential's true reach. Also reports mcpServerVersion and sdkVersion (this build's own version and the bundled @vectros-ai/sdk version). The /v1/ping backing call ships the extended shape today; the version fields are always client-derived.",
   mimeType: "application/json",
   read: async () => {
     const identity = await resolveIdentity({ log, apiKey, environment });