@spec0/sdk-public-platform 1.3.1 → 1.4.0

package/dist/generated/models/PublicPublishRequestV1.d.ts

@@ -1,9 +1,9 @@
 import type { Visibility } from './Visibility.js';
 /**
- * Provide exactly one of `version` or `versionBump`. `version` pins an explicit
- * semver tag. `versionBump` asks the registry to compute the next version
- * atomically from the highest existing clean-semver tag — preferred for
- * CI publishes since it avoids races between concurrent main pushes.
+ * Provide `version` (explicit pin) and/or `semver` (auto-bump PATCH). When both
+ * are omitted, the server falls through to `info.version` from the spec, then
+ * the `0.1.0` default. `version` accepts arbitrary strings (semver, sha-prefixed
+ * tags, calendar tags, UUIDs) — see ADR-0026.
  *
  */
 export type PublicPublishRequestV1 = {
@@ -22,24 +22,30 @@ export type PublicPublishRequestV1 = {
     description?: string;
     visibility?: Visibility;
     /**
-     * Explicit semver tag for this version (e.g. "1.2.0"). Mutually
-     * exclusive with `versionBump`.
+     * Explicit version tag for this publish. Accepts arbitrary strings — semver,
+     * sha-prefixed tags (e.g. "staging-abc1234"), calendar tags (e.g. "v2026-Q3"),
+     * UUIDs, etc. The registry stores what you pass; uniqueness is enforced per
+     * API. When set together with `semver`, `version` wins.
      *
      */
     version?: string;
     /**
-     * Ask the registry to compute the next version. `MINOR` bumps the minor
-     * segment of the highest existing clean-semver tag (1.4.0 → 1.5.0);
-     * `PATCH` bumps the patch segment. The very first publish to an API
-     * (no clean-semver tag exists) always goes at "1.0.0" regardless of
-     * bump type. `MAJOR` is intentionally not supported — per Spec0's
-     * versioning policy, breaking changes create a new API rather than
-     * bumping the major version. Mutually exclusive with `version`.
-     * Resolution and version-row insert are wrapped in a single
-     * transaction with a pessimistic lock on the api row, so concurrent
-     * publishes serialise cleanly.
+     * If true and the previous stored version is a valid semver, increment the
+     * PATCH component atomically (1.2.3 → 1.2.4). If the previous version is not
+     * a valid semver, or this is the first publish, falls through to the
+     * resolution order — `info.version` from the spec, then `0.1.0`. No spec
+     * parsing, no oasdiff classification — see ADR-0026.
      *
      */
+    semver?: boolean;
+    /**
+     * Deprecated. Pass `semver: true` instead. The server ignores this field
+     * since ADR-0026 unified version-bump semantics; it is kept in the schema
+     * so old clients sending `versionBump=PATCH|MINOR` continue to parse
+     * cleanly. New code should not set it.
+     *
+     * @deprecated
+     */
     versionBump?: 'MINOR' | 'PATCH';
     /**
      * Full OpenAPI spec content (YAML or JSON)

package/dist/generated/models/PublicPublishRequestV1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicPublishRequestV1.d.ts","sourceRoot":"","sources":["../../../src/generated/models/PublicPublishRequestV1.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC"}
+{"version":3,"file":"PublicPublishRequestV1.d.ts","sourceRoot":"","sources":["../../../src/generated/models/PublicPublishRequestV1.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC"}

package/dist/generated/models/TeamPublishRequestV1.d.ts

@@ -22,8 +22,11 @@ export type TeamPublishRequestV1 = {
      */
     team?: string;
     /**
-     * Semver version to publish (MAJOR.MINOR.PATCH). If omitted, the version is
-     * extracted from `info.version` in the spec. Ignored when `semver` is true.
+     * Explicit version tag for this publish. Accepts arbitrary strings — semver
+     * ("1.2.3"), sha-prefixed tags ("staging-abc1234"), calendar tags
+     * ("v2026-Q3"), UUIDs, etc. If omitted and `semver` is not set, falls through
+     * to `info.version` from the spec, then the `0.1.0` default. When set
+     * together with `semver`, `version` wins. See ADR-0026.
      *
      */
     version?: string;
@@ -44,10 +47,22 @@ export type TeamPublishRequestV1 = {
      */
     specFilePath?: string;
     /**
-     * If true, the backend runs oasdiff to classify the change and auto-computes
-     * the next semver tag (PATCH / NON_BREAKING / BREAKING).
+     * If true and the previous stored version is a valid semver, increment the
+     * PATCH component atomically (1.2.3 → 1.2.4). If the previous version is not
+     * a valid semver, or this is the first publish, falls through to the
+     * resolution order — `version` flag, then `info.version` from the spec, then
+     * `0.1.0`. No spec parsing, no oasdiff — see ADR-0026.
      *
      */
     semver?: boolean;
+    /**
+     * Operator-supplied changelog prose for this version. When non-blank,
+     * becomes the version's `changelog_text` with `changelogSource = MANUAL`
+     * and the async AI listener skips generation. Powers the dashboard's
+     * Edit-API form (title + description combined) and the future
+     * `spec0 push --release-notes` flag.
+     *
+     */
+    releaseNotes?: string;
 };
 //# sourceMappingURL=TeamPublishRequestV1.d.ts.map

package/dist/generated/models/TeamPublishRequestV1.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TeamPublishRequestV1.d.ts","sourceRoot":"","sources":["../../../src/generated/models/TeamPublishRequestV1.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC"}
+{"version":3,"file":"TeamPublishRequestV1.d.ts","sourceRoot":"","sources":["../../../src/generated/models/TeamPublishRequestV1.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC"}

package/dist/generated/services/PublicApisService.d.ts

@@ -3,6 +3,7 @@ import type { PublicApiListItem } from '../models/PublicApiListItem.js';
 import type { PublicApiMetaV1 } from '../models/PublicApiMetaV1.js';
 import type { PublicPublishRequestV1 } from '../models/PublicPublishRequestV1.js';
 import type { PublicPublishResponseV1 } from '../models/PublicPublishResponseV1.js';
+import type { SpecVersionListItemV1 } from '../models/SpecVersionListItemV1.js';
 import type { TeamPublishRequestV1 } from '../models/TeamPublishRequestV1.js';
 import type { TeamPublishResponseV1 } from '../models/TeamPublishResponseV1.js';
 import type { VisibilityUpdateRequestV1 } from '../models/VisibilityUpdateRequestV1.js';
@@ -71,8 +72,59 @@ export declare class PublicApisService {
     static deleteTeamApi({ apiId, }: {
         apiId: string;
     }): CancelablePromise<void>;
+    /**
+     * Fetch the latest spec body for a team-scoped private API
+     * Returns the OpenAPI document content (YAML or JSON, as published) for the latest
+     * version of a team-scoped private API. Mirrors the public-registry equivalent
+     * (`GET /api/v1/public/registry/{orgSlug}/{apiName}`) but resolves the API by its
+     * internal UUID so callers can target private APIs without a public org slug.
+     *
+     * Authorization stack:
+     * - scope: `read:specs`
+     * - ABAC v2: caller must be permitted to `view` the API resource (cross-org and
+     * cross-team isolation collapse to 404 to avoid leaking existence).
+     *
+     * Backs `spec0 pull --team` (issue #149).
+     *
+     * @returns string OpenAPI spec content for the latest published version
+     * @throws ApiError
+     */
+    static getTeamApiSpec({ apiId, }: {
+        apiId: string;
+    }): CancelablePromise<string>;
+    /**
+     * List published versions of a team-scoped private API
+     * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions` for the
+     * team-scoped surface. Returns the version history ordered by `publishedAt` desc.
+     * Cross-org / cross-team callers see 404 (same ABAC v2 collapse used by the spec body
+     * endpoint).
+     *
+     * @returns SpecVersionListItemV1 Version history
+     * @throws ApiError
+     */
+    static listTeamApiVersions({ apiId, }: {
+        apiId: string;
+    }): CancelablePromise<Array<SpecVersionListItemV1>>;
+    /**
+     * Fetch a specific tagged version of a team-scoped private API
+     * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions/{tag}` for the
+     * team-scoped surface. Returns the OpenAPI document content for the requested tag.
+     * Cross-org / cross-team callers see 404; unknown tag also 404.
+     *
+     * @returns string OpenAPI spec content for the requested version
+     * @throws ApiError
+     */
+    static getTeamApiSpecByTag({ apiId, tag, }: {
+        apiId: string;
+        tag: string;
+    }): CancelablePromise<string>;
     /**
      * Update visibility for a public API
+     * Toggle a public API between `PRIVATE`, `UNLISTED`, and `PUBLISHED` without
+     * republishing its spec. Visibility controls whether the API and its versions are
+     * readable through the unauthenticated public registry; the spec content itself is
+     * untouched. Callable by any token in the owning org that holds `write:apis`.
+     *
      * @returns PublicApiMetaV1 Updated visibility
      * @throws ApiError
      */

package/dist/generated/services/PublicApisService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicApisService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicApisService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,iBAAiB;IAC5B;;;;;OAKG;WACW,cAAc,IAAI,iBAAiB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAU3E;;;;;;;;OAQG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,sBAAsB,CAAC;KACrC,GAAG,iBAAiB,CAAC,uBAAuB,CAAC;IAe9C;;;;;;;;;;OAUG;WACW,YAAY,IAAI,iBAAiB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAUzE;;;;;;;;;;;;;OAaG;WACW,cAAc,CAAC,EAC3B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,oBAAoB,CAAC;KACnC,GAAG,iBAAiB,CAAC,qBAAqB,CAAC;IAgB5C;;;;;;;;;;;OAWG;WACW,aAAa,CAAC,EAC1B,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,IAAI,CAAC;IAc3B;;;;OAIG;WACW,yBAAyB,CAAC,EACtC,WAAW,EACX,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,yBAAyB,CAAC;KACxC,GAAG,iBAAiB,CAAC,eAAe,CAAC;IAgBtC;;;;;;;OAOG;WACW,eAAe,CAAC,EAC5B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAc5B"}
+{"version":3,"file":"PublicApisService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicApisService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,iBAAiB;IAC5B;;;;;OAKG;WACW,cAAc,IAAI,iBAAiB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAU3E;;;;;;;;OAQG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,sBAAsB,CAAC;KACrC,GAAG,iBAAiB,CAAC,uBAAuB,CAAC;IAe9C;;;;;;;;;;OAUG;WACW,YAAY,IAAI,iBAAiB,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAUzE;;;;;;;;;;;;;OAaG;WACW,cAAc,CAAC,EAC3B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,oBAAoB,CAAC;KACnC,GAAG,iBAAiB,CAAC,qBAAqB,CAAC;IAgB5C;;;;;;;;;;;OAWG;WACW,aAAa,CAAC,EAC1B,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,IAAI,CAAC;IAc3B;;;;;;;;;;;;;;;;OAgBG;WACW,cAAc,CAAC,EAC3B,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAc7B;;;;;;;;;OASG;WACW,mBAAmB,CAAC,EAChC,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAcnD;;;;;;;;OAQG;WACW,mBAAmB,CAAC,EAChC,KAAK,EACL,GAAG,GACJ,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAe7B;;;;;;;;;OASG;WACW,yBAAyB,CAAC,EACtC,WAAW,EACX,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,yBAAyB,CAAC;KACxC,GAAG,iBAAiB,CAAC,eAAe,CAAC;IAgBtC;;;;;;;OAOG;WACW,eAAe,CAAC,EAC5B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAc5B"}

package/dist/generated/services/PublicApisService.js

@@ -121,8 +121,92 @@ class PublicApisService {
             },
         });
     }
+    /**
+     * Fetch the latest spec body for a team-scoped private API
+     * Returns the OpenAPI document content (YAML or JSON, as published) for the latest
+     * version of a team-scoped private API. Mirrors the public-registry equivalent
+     * (`GET /api/v1/public/registry/{orgSlug}/{apiName}`) but resolves the API by its
+     * internal UUID so callers can target private APIs without a public org slug.
+     *
+     * Authorization stack:
+     * - scope: `read:specs`
+     * - ABAC v2: caller must be permitted to `view` the API resource (cross-org and
+     * cross-team isolation collapse to 404 to avoid leaking existence).
+     *
+     * Backs `spec0 pull --team` (issue #149).
+     *
+     * @returns string OpenAPI spec content for the latest published version
+     * @throws ApiError
+     */
+    static getTeamApiSpec({ apiId, }) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/api/v1/public/apis/team/{apiId}/spec',
+            path: {
+                'apiId': apiId,
+            },
+            errors: {
+                401: `Missing, invalid, expired, or revoked token`,
+                403: `Token does not carry the required scope`,
+                404: `Resource not found (or not visible to the calling org)`,
+            },
+        });
+    }
+    /**
+     * List published versions of a team-scoped private API
+     * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions` for the
+     * team-scoped surface. Returns the version history ordered by `publishedAt` desc.
+     * Cross-org / cross-team callers see 404 (same ABAC v2 collapse used by the spec body
+     * endpoint).
+     *
+     * @returns SpecVersionListItemV1 Version history
+     * @throws ApiError
+     */
+    static listTeamApiVersions({ apiId, }) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/api/v1/public/apis/team/{apiId}/versions',
+            path: {
+                'apiId': apiId,
+            },
+            errors: {
+                401: `Missing, invalid, expired, or revoked token`,
+                403: `Token does not carry the required scope`,
+                404: `Resource not found (or not visible to the calling org)`,
+            },
+        });
+    }
+    /**
+     * Fetch a specific tagged version of a team-scoped private API
+     * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions/{tag}` for the
+     * team-scoped surface. Returns the OpenAPI document content for the requested tag.
+     * Cross-org / cross-team callers see 404; unknown tag also 404.
+     *
+     * @returns string OpenAPI spec content for the requested version
+     * @throws ApiError
+     */
+    static getTeamApiSpecByTag({ apiId, tag, }) {
+        return (0, request_js_1.request)(OpenAPI_js_1.OpenAPI, {
+            method: 'GET',
+            url: '/api/v1/public/apis/team/{apiId}/versions/{tag}',
+            path: {
+                'apiId': apiId,
+                'tag': tag,
+            },
+            errors: {
+                401: `Missing, invalid, expired, or revoked token`,
+                403: `Token does not carry the required scope`,
+                404: `Resource not found (or not visible to the calling org)`,
+            },
+        });
+    }
     /**
      * Update visibility for a public API
+     * Toggle a public API between `PRIVATE`, `UNLISTED`, and `PUBLISHED` without
+     * republishing its spec. Visibility controls whether the API and its versions are
+     * readable through the unauthenticated public registry; the spec content itself is
+     * untouched. Callable by any token in the owning org that holds `write:apis`.
+     *
      * @returns PublicApiMetaV1 Updated visibility
      * @throws ApiError
      */

package/dist/generated/services/PublicApisService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicApisService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicApisService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PublicApisService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicApisService.ts"],"names":[],"mappings":";;;AAcA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,iBAAiB;IAC5B;;;;;OAKG;IACI,MAAM,CAAC,cAAc;QAC1B,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,qBAAqB;YAC1B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,qBAAqB;YAC1B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,0EAA0E;gBAC/E,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACI,MAAM,CAAC,YAAY;QACxB,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,0BAA0B;YAC/B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;;;;OAaG;IACI,MAAM,CAAC,cAAc,CAAC,EAC3B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,0BAA0B;YAC/B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;gBAC7D,GAAG,EAAE,oGAAoG;gBACzG,GAAG,EAAE,kDAAkD;aACxD;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;;OAWG;IACI,MAAM,CAAC,aAAa,CAAC,EAC1B,KAAK,GAGN;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,kCAAkC;YACvC,IAAI,EAAE;gBACJ,OAAO,EAAE,KAAK;aACf;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;;;;;;;OAgBG;IACI,MAAM,CAAC,cAAc,CAAC,EAC3B,KAAK,GAGN;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,uCAAuC;YAC5C,IAAI,EAAE;gBACJ,OAAO,EAAE,KAAK;aACf;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;OASG;IACI,MAAM,CAAC,mBAAmB,CAAC,EAChC,KAAK,GAGN;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,2CAA2C;YAChD,IAAI,EAAE;gBACJ,OAAO,EAAE,KAAK;aACf;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,mBAAmB,CAAC,EAChC,KAAK,EACL,GAAG,GAIJ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,iDAAiD;YACtD,IAAI,EAAE;gBACJ,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG;aACX;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;OASG;IACI,MAAM,CAAC,yBAAyB,CAAC,EACtC,WAAW,EACX,WAAW,GAIZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,8CAA8C;YACnD,IAAI,EAAE;gBACJ,aAAa,EAAE,WAAW;aAC3B;YACD,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,eAAe,CAAC,EAC5B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,mCAAmC;YACxC,IAAI,EAAE;gBACJ,aAAa,EAAE,WAAW;aAC3B;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAzRD,8CAyRC"}

package/dist/generated/services/PublicMocksService.d.ts

@@ -5,6 +5,11 @@ import type { CancelablePromise } from '../core/CancelablePromise.js';
 export declare class PublicMocksService {
     /**
      * List mock servers for the calling org
+     * Returns every mock server owned by the calling token's org, with the parent API
+     * id/name and the mock's base URL. Backs the `spec0 mock list` CLI command and is
+     * the discovery surface SDK consumers use before deciding whether to point a
+     * client at a mock vs. a real environment.
+     *
      * @returns MockItemV1 Mock servers
      * @throws ApiError
      */

package/dist/generated/services/PublicMocksService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicMocksService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicMocksService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;OAIG;WACW,eAAe,IAAI,iBAAiB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAUrE;;;;;;;OAOG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,mBAAmB,CAAC;KAClC,GAAG,iBAAiB,CAAC,oBAAoB,CAAC;IAc3C;;;;;;;;OAQG;WACW,gBAAgB,CAAC,EAC7B,YAAY,GACb,EAAE;QACD,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAc5B"}
+{"version":3,"file":"PublicMocksService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicMocksService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;;;;;;OASG;WACW,eAAe,IAAI,iBAAiB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAUrE;;;;;;;OAOG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,mBAAmB,CAAC;KAClC,GAAG,iBAAiB,CAAC,oBAAoB,CAAC;IAc3C;;;;;;;;OAQG;WACW,gBAAgB,CAAC,EAC7B,YAAY,GACb,EAAE;QACD,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAc5B"}

package/dist/generated/services/PublicMocksService.js

@@ -6,6 +6,11 @@ const request_js_1 = require("../core/request.js");
 class PublicMocksService {
     /**
      * List mock servers for the calling org
+     * Returns every mock server owned by the calling token's org, with the parent API
+     * id/name and the mock's base URL. Backs the `spec0 mock list` CLI command and is
+     * the discovery surface SDK consumers use before deciding whether to point a
+     * client at a mock vs. a real environment.
+     *
      * @returns MockItemV1 Mock servers
      * @throws ApiError
      */

package/dist/generated/services/PublicMocksService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicMocksService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicMocksService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;OAIG;IACI,MAAM,CAAC,eAAe;QAC3B,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,sBAAsB;YAC3B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,YAAY,GAGb;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,qCAAqC;YAC1C,IAAI,EAAE;gBACJ,cAAc,EAAE,YAAY;aAC7B;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AArED,gDAqEC"}
+{"version":3,"file":"PublicMocksService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicMocksService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;;;;;;OASG;IACI,MAAM,CAAC,eAAe;QAC3B,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,sBAAsB;YAC3B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,YAAY,GAGb;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,qCAAqC;YAC1C,IAAI,EAAE;gBACJ,cAAc,EAAE,YAAY;aAC7B;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA1ED,gDA0EC"}

package/dist/generated/services/PublicRegistryService.d.ts

@@ -5,6 +5,11 @@ import type { CancelablePromise } from '../core/CancelablePromise.js';
 export declare class PublicRegistryService {
     /**
      * Fetch latest published spec
+     * Returns the raw OpenAPI document of the most recently published version of the
+     * API, addressed by its org slug and API name. This is the canonical entry point
+     * for SDK generators and the `spec0 pull` CLI command — it short-circuits the
+     * version-listing round-trip when the caller just wants "the current spec".
+     *
      * @returns string OpenAPI spec content
      * @throws ApiError
      */
@@ -14,6 +19,12 @@ export declare class PublicRegistryService {
     }): CancelablePromise<string>;
     /**
      * List version history
+     * Returns every published version of the API in reverse-chronological order,
+     * including the SemVer tag, git SHA recorded at publish, publish timestamp, and a
+     * flag indicating whether breaking changes were detected against the previous
+     * version. The spec content itself is not inlined — fetch individual versions with
+     * `GET /versions/{tag}`.
+     *
      * @returns SpecVersionListItemV1 Version history
      * @throws ApiError
      */
@@ -23,6 +34,11 @@ export declare class PublicRegistryService {
     }): CancelablePromise<Array<SpecVersionListItemV1>>;
     /**
      * Fetch a specific spec version
+     * Returns the immutable OpenAPI document published under the given SemVer tag.
+     * Use this when a consumer needs to pin to a specific contract — e.g. CI
+     * regenerating SDKs from `1.2.3` even after `1.3.0` ships. Returns 404 if either
+     * the API or that specific tag does not exist.
+     *
      * @returns string OpenAPI spec content for the requested version
      * @throws ApiError
      */
@@ -33,6 +49,12 @@ export declare class PublicRegistryService {
     }): CancelablePromise<string>;
     /**
      * Semantic search over the calling org's APIs
+     * Natural-language search across the calling org's API titles, descriptions, and
+     * operation summaries, backed by the RAG service. Results are ranked by semantic
+     * similarity to `query` and capped at `maxResults` (default 10). Scope is
+     * org-internal — the token's org is the only corpus searched; there is no
+     * cross-org discovery on this endpoint.
+     *
      * @returns AiSearchResponseV1 Search results
      * @throws ApiError
      */

package/dist/generated/services/PublicRegistryService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicRegistryService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicRegistryService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,qBAAqB;IAChC;;;;OAIG;WACW,mBAAmB,CAAC,EAChC,OAAO,EACP,OAAO,GACR,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAe7B;;;;OAIG;WACW,sBAAsB,CAAC,EACnC,OAAO,EACP,OAAO,GACR,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,iBAAiB,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAenD;;;;OAIG;WACW,kBAAkB,CAAC,EAC/B,OAAO,EACP,OAAO,EACP,GAAG,GACJ,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAgB7B;;;;OAIG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,iBAAiB,CAAC;KAChC,GAAG,iBAAiB,CAAC,kBAAkB,CAAC;CAa1C"}
+{"version":3,"file":"PublicRegistryService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicRegistryService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,qBAAqB;IAChC;;;;;;;;;OASG;WACW,mBAAmB,CAAC,EAChC,OAAO,EACP,OAAO,GACR,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAe7B;;;;;;;;;;OAUG;WACW,sBAAsB,CAAC,EACnC,OAAO,EACP,OAAO,GACR,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,iBAAiB,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IAenD;;;;;;;;;OASG;WACW,kBAAkB,CAAC,EAC/B,OAAO,EACP,OAAO,EACP,GAAG,GACJ,EAAE;QACD,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAgB7B;;;;;;;;;;OAUG;WACW,gBAAgB,CAAC,EAC7B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,iBAAiB,CAAC;KAChC,GAAG,iBAAiB,CAAC,kBAAkB,CAAC;CAa1C"}

package/dist/generated/services/PublicRegistryService.js

@@ -6,6 +6,11 @@ const request_js_1 = require("../core/request.js");
 class PublicRegistryService {
     /**
      * Fetch latest published spec
+     * Returns the raw OpenAPI document of the most recently published version of the
+     * API, addressed by its org slug and API name. This is the canonical entry point
+     * for SDK generators and the `spec0 pull` CLI command — it short-circuits the
+     * version-listing round-trip when the caller just wants "the current spec".
+     *
      * @returns string OpenAPI spec content
      * @throws ApiError
      */
@@ -26,6 +31,12 @@ class PublicRegistryService {
     }
     /**
      * List version history
+     * Returns every published version of the API in reverse-chronological order,
+     * including the SemVer tag, git SHA recorded at publish, publish timestamp, and a
+     * flag indicating whether breaking changes were detected against the previous
+     * version. The spec content itself is not inlined — fetch individual versions with
+     * `GET /versions/{tag}`.
+     *
      * @returns SpecVersionListItemV1 Version history
      * @throws ApiError
      */
@@ -46,6 +57,11 @@ class PublicRegistryService {
     }
     /**
      * Fetch a specific spec version
+     * Returns the immutable OpenAPI document published under the given SemVer tag.
+     * Use this when a consumer needs to pin to a specific contract — e.g. CI
+     * regenerating SDKs from `1.2.3` even after `1.3.0` ships. Returns 404 if either
+     * the API or that specific tag does not exist.
+     *
      * @returns string OpenAPI spec content for the requested version
      * @throws ApiError
      */
@@ -67,6 +83,12 @@ class PublicRegistryService {
     }
     /**
      * Semantic search over the calling org's APIs
+     * Natural-language search across the calling org's API titles, descriptions, and
+     * operation summaries, backed by the RAG service. Results are ranked by semantic
+     * similarity to `query` and capped at `maxResults` (default 10). Scope is
+     * org-internal — the token's org is the only corpus searched; there is no
+     * cross-org discovery on this endpoint.
+     *
      * @returns AiSearchResponseV1 Search results
      * @throws ApiError
      */

package/dist/generated/services/PublicRegistryService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicRegistryService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicRegistryService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,qBAAqB;IAChC;;;;OAIG;IACI,MAAM,CAAC,mBAAmB,CAAC,EAChC,OAAO,EACP,OAAO,GAIR;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,6CAA6C;YAClD,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;aACnB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,sBAAsB,CAAC,EACnC,OAAO,EACP,OAAO,GAIR;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sDAAsD;YAC3D,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;aACnB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,kBAAkB,CAAC,EAC/B,OAAO,EACP,OAAO,EACP,GAAG,GAKJ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,4DAA4D;YACjE,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;gBAClB,KAAK,EAAE,GAAG;aACX;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,gCAAgC;YACrC,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAxGD,sDAwGC"}
+{"version":3,"file":"PublicRegistryService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicRegistryService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,qBAAqB;IAChC;;;;;;;;;OASG;IACI,MAAM,CAAC,mBAAmB,CAAC,EAChC,OAAO,EACP,OAAO,GAIR;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,6CAA6C;YAClD,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;aACnB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACI,MAAM,CAAC,sBAAsB,CAAC,EACnC,OAAO,EACP,OAAO,GAIR;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sDAAsD;YAC3D,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;aACnB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;OASG;IACI,MAAM,CAAC,kBAAkB,CAAC,EAC/B,OAAO,EACP,OAAO,EACP,GAAG,GAKJ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,4DAA4D;YACjE,IAAI,EAAE;gBACJ,SAAS,EAAE,OAAO;gBAClB,SAAS,EAAE,OAAO;gBAClB,KAAK,EAAE,GAAG;aACX;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACI,MAAM,CAAC,gBAAgB,CAAC,EAC7B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,gCAAgC;YACrC,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA9HD,sDA8HC"}

package/dist/generated/services/PublicSpecsService.d.ts

@@ -23,6 +23,13 @@ export declare class PublicSpecsService {
     }): CancelablePromise<SpecDiffResponseV1>;
     /**
      * Diff two published versions of an API
+     * Compares two already-published versions of the same API (addressed by `apiId` +
+     * `fromTag` + `toTag`) and returns the oasdiff-backed structured changelog plus a
+     * breaking-change list. Lighter-weight than the multipart `/specs/diff` endpoint
+     * because the caller doesn't have to upload either spec — the backend reads them
+     * from its own version history. Returns 503 if the oasdiff service is disabled in
+     * this deployment.
+     *
      * @returns VersionDiffResponseV1 Diff result
      * @throws ApiError
      */

package/dist/generated/services/PublicSpecsService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicSpecsService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicSpecsService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;;OAKG;WACW,SAAS,CAAC,EACtB,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE;YACR;;eAEG;YACH,IAAI,EAAE,IAAI,CAAC;YACX;;eAEG;YACH,QAAQ,EAAE,IAAI,CAAC;SAChB,CAAC;KACH,GAAG,iBAAiB,CAAC,kBAAkB,CAAC;IAazC;;;;OAIG;WACW,cAAc,CAAC,EAC3B,KAAK,EACL,OAAO,EACP,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,qBAAqB,CAAC;IAiB5C;;;;;;;OAOG;WACW,aAAa,CAAC,EAC1B,MAAM,EACN,KAAK,EACL,IAAI,GACL,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,oBAAoB,CAAC;CAiB5C"}
+{"version":3,"file":"PublicSpecsService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicSpecsService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;;OAKG;WACW,SAAS,CAAC,EACtB,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE;YACR;;eAEG;YACH,IAAI,EAAE,IAAI,CAAC;YACX;;eAEG;YACH,QAAQ,EAAE,IAAI,CAAC;SAChB,CAAC;KACH,GAAG,iBAAiB,CAAC,kBAAkB,CAAC;IAazC;;;;;;;;;;;OAWG;WACW,cAAc,CAAC,EAC3B,KAAK,EACL,OAAO,EACP,KAAK,GACN,EAAE;QACD,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,qBAAqB,CAAC;IAiB5C;;;;;;;OAOG;WACW,aAAa,CAAC,EAC1B,MAAM,EACN,KAAK,EACL,IAAI,GACL,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,iBAAiB,CAAC,oBAAoB,CAAC;CAiB5C"}

package/dist/generated/services/PublicSpecsService.js

@@ -25,6 +25,13 @@ class PublicSpecsService {
     }
     /**
      * Diff two published versions of an API
+     * Compares two already-published versions of the same API (addressed by `apiId` +
+     * `fromTag` + `toTag`) and returns the oasdiff-backed structured changelog plus a
+     * breaking-change list. Lighter-weight than the multipart `/specs/diff` endpoint
+     * because the caller doesn't have to upload either spec — the backend reads them
+     * from its own version history. Returns 503 if the oasdiff service is disabled in
+     * this deployment.
+     *
      * @returns VersionDiffResponseV1 Diff result
      * @throws ApiError
      */

package/dist/generated/services/PublicSpecsService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicSpecsService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicSpecsService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;;OAKG;IACI,MAAM,CAAC,SAAS,CAAC,EACtB,QAAQ,GAYT;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,2BAA2B;YAChC,QAAQ,EAAE,QAAQ;YAClB,SAAS,EAAE,qBAAqB;YAChC,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,gDAAgD;aACtD;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,cAAc,CAAC,EAC3B,KAAK,EACL,OAAO,EACP,KAAK,GAKN;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,mCAAmC;YACxC,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,OAAO;gBAClB,OAAO,EAAE,KAAK;aACf;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;gBAC7D,GAAG,EAAE,6BAA6B;aACnC;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,aAAa,CAAC,EAC1B,MAAM,EACN,KAAK,EACL,IAAI,GAKL;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,kCAAkC;YACvC,KAAK,EAAE;gBACL,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,IAAI;aACb;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAhGD,gDAgGC"}
+{"version":3,"file":"PublicSpecsService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicSpecsService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;;OAKG;IACI,MAAM,CAAC,SAAS,CAAC,EACtB,QAAQ,GAYT;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,2BAA2B;YAChC,QAAQ,EAAE,QAAQ;YAClB,SAAS,EAAE,qBAAqB;YAChC,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,gDAAgD;aACtD;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;;OAWG;IACI,MAAM,CAAC,cAAc,CAAC,EAC3B,KAAK,EACL,OAAO,EACP,KAAK,GAKN;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,mCAAmC;YACxC,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,OAAO;gBAClB,OAAO,EAAE,KAAK;aACf;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;gBAC7D,GAAG,EAAE,6BAA6B;aACnC;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,aAAa,CAAC,EAC1B,MAAM,EACN,KAAK,EACL,IAAI,GAKL;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,kCAAkC;YACvC,KAAK,EAAE;gBACL,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,IAAI;aACb;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;aAC9D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAvGD,gDAuGC"}

package/dist/generated/services/PublicSpectralService.d.ts

@@ -5,6 +5,11 @@ import type { CancelablePromise } from '../core/CancelablePromise.js';
 export declare class PublicSpectralService {
     /**
      * Get the calling org's Spectral ruleset
+     * Returns the org's custom Spectral ruleset YAML, or an empty string when the org
+     * has not configured one. The CLI fetches this on every `spec0 lint` invocation so
+     * lint behaviour stays consistent between local dev and CI. Built-in rulesets are
+     * applied regardless of whether a custom ruleset is set.
+     *
      * @returns SpectralRulesetResponseV1 Current ruleset
      * @throws ApiError
      */

package/dist/generated/services/PublicSpectralService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicSpectralService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicSpectralService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,qBAAqB;IAChC;;;;OAIG;WACW,kBAAkB,IAAI,iBAAiB,CAAC,yBAAyB,CAAC;IAUhF;;;;;OAKG;WACW,kBAAkB,CAAC,EAC/B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,2BAA2B,CAAC;KAC1C,GAAG,iBAAiB,CAAC,gBAAgB,CAAC;CAaxC"}
+{"version":3,"file":"PublicSpectralService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicSpectralService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,qBAAqB;IAChC;;;;;;;;;OASG;WACW,kBAAkB,IAAI,iBAAiB,CAAC,yBAAyB,CAAC;IAUhF;;;;;OAKG;WACW,kBAAkB,CAAC,EAC/B,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,2BAA2B,CAAC;KAC1C,GAAG,iBAAiB,CAAC,gBAAgB,CAAC;CAaxC"}

package/dist/generated/services/PublicSpectralService.js

@@ -6,6 +6,11 @@ const request_js_1 = require("../core/request.js");
 class PublicSpectralService {
     /**
      * Get the calling org's Spectral ruleset
+     * Returns the org's custom Spectral ruleset YAML, or an empty string when the org
+     * has not configured one. The CLI fetches this on every `spec0 lint` invocation so
+     * lint behaviour stays consistent between local dev and CI. Built-in rulesets are
+     * applied regardless of whether a custom ruleset is set.
+     *
      * @returns SpectralRulesetResponseV1 Current ruleset
      * @throws ApiError
      */

package/dist/generated/services/PublicSpectralService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicSpectralService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicSpectralService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,qBAAqB;IAChC;;;;OAIG;IACI,MAAM,CAAC,kBAAkB;QAC9B,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,iCAAiC;YACtC,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,kBAAkB,CAAC,EAC/B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,iCAAiC;YACtC,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,qDAAqD;gBAC1D,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;CACF;AAvCD,sDAuCC"}
+{"version":3,"file":"PublicSpectralService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicSpectralService.ts"],"names":[],"mappings":";;;AAQA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,qBAAqB;IAChC;;;;;;;;;OASG;IACI,MAAM,CAAC,kBAAkB;QAC9B,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,iCAAiC;YACtC,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,kBAAkB,CAAC,EAC/B,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,iCAAiC;YACtC,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,qDAAqD;gBAC1D,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA5CD,sDA4CC"}

package/dist/generated/services/PublicTeamsService.d.ts

@@ -4,6 +4,11 @@ import type { CancelablePromise } from '../core/CancelablePromise.js';
 export declare class PublicTeamsService {
     /**
      * List teams for the calling org
+     * Returns every team in the calling token's org with its id, name, and
+     * description. Use this to resolve a team slug or human-readable name to the UUID
+     * expected by other endpoints (e.g. `team` on team-API publish, or `teamId` on
+     * delete). Scope is org-internal — teams in other orgs are never returned.
+     *
      * @returns TeamV1 Teams in the calling org
      * @throws ApiError
      */

package/dist/generated/services/PublicTeamsService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicTeamsService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicTeamsService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;OAIG;WACW,SAAS,IAAI,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAU3D;;;;;;;OAOG;WACW,UAAU,CAAC,EACvB,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,mBAAmB,CAAC;KAClC,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAa7B;;;;;;;;OAQG;WACW,UAAU,CAAC,EACvB,MAAM,GACP,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAe5B"}
+{"version":3,"file":"PublicTeamsService.d.ts","sourceRoot":"","sources":["../../../src/generated/services/PublicTeamsService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGtE,qBAAa,kBAAkB;IAC7B;;;;;;;;;OASG;WACW,SAAS,IAAI,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAU3D;;;;;;;OAOG;WACW,UAAU,CAAC,EACvB,WAAW,GACZ,EAAE;QACD,WAAW,EAAE,mBAAmB,CAAC;KAClC,GAAG,iBAAiB,CAAC,MAAM,CAAC;IAa7B;;;;;;;;OAQG;WACW,UAAU,CAAC,EACvB,MAAM,GACP,EAAE;QACD,MAAM,EAAE,MAAM,CAAC;KAChB,GAAG,iBAAiB,CAAC,IAAI,CAAC;CAe5B"}

package/dist/generated/services/PublicTeamsService.js

@@ -6,6 +6,11 @@ const request_js_1 = require("../core/request.js");
 class PublicTeamsService {
     /**
      * List teams for the calling org
+     * Returns every team in the calling token's org with its id, name, and
+     * description. Use this to resolve a team slug or human-readable name to the UUID
+     * expected by other endpoints (e.g. `team` on team-API publish, or `teamId` on
+     * delete). Scope is org-internal — teams in other orgs are never returned.
+     *
      * @returns TeamV1 Teams in the calling org
      * @throws ApiError
      */

package/dist/generated/services/PublicTeamsService.js.map

@@ -1 +1 @@
-{"version":3,"file":"PublicTeamsService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicTeamsService.ts"],"names":[],"mappings":";;;AAOA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;OAIG;IACI,MAAM,CAAC,SAAS;QACrB,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,UAAU,CAAC,EACvB,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,sBAAsB;YAC3B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,UAAU,CAAC,EACvB,MAAM,GAGP;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,+BAA+B;YACpC,IAAI,EAAE;gBACJ,QAAQ,EAAE,MAAM;aACjB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;gBAC7D,GAAG,EAAE,uDAAuD;aAC7D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AArED,gDAqEC"}
+{"version":3,"file":"PublicTeamsService.js","sourceRoot":"","sources":["../../../src/generated/services/PublicTeamsService.ts"],"names":[],"mappings":";;;AAOA,mDAA6C;AAC7C,mDAA0D;AAC1D,MAAa,kBAAkB;IAC7B;;;;;;;;;OASG;IACI,MAAM,CAAC,SAAS;QACrB,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,KAAK;YACb,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,UAAU,CAAC,EACvB,WAAW,GAGZ;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,MAAM;YACd,GAAG,EAAE,sBAAsB;YAC3B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,kBAAkB;YAC7B,MAAM,EAAE;gBACN,GAAG,EAAE,aAAa;gBAClB,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;aAC/C;SACF,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;OAQG;IACI,MAAM,CAAC,UAAU,CAAC,EACvB,MAAM,GAGP;QACC,OAAO,IAAA,oBAAS,EAAC,oBAAO,EAAE;YACxB,MAAM,EAAE,QAAQ;YAChB,GAAG,EAAE,+BAA+B;YACpC,IAAI,EAAE;gBACJ,QAAQ,EAAE,MAAM;aACjB;YACD,MAAM,EAAE;gBACN,GAAG,EAAE,6CAA6C;gBAClD,GAAG,EAAE,yCAAyC;gBAC9C,GAAG,EAAE,wDAAwD;gBAC7D,GAAG,EAAE,uDAAuD;aAC7D;SACF,CAAC,CAAC;IACL,CAAC;CACF;AA1ED,gDA0EC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec0/sdk-public-platform",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "TypeScript SDK for Spec0's public API surface (https://app.spec0.io). Generated from the OpenAPI spec published at spec0/spec0-platform.",
   "license": "MIT",
   "main": "./dist/index.js",

package/src/generated/models/PublicPublishRequestV1.ts

@@ -4,10 +4,10 @@
 /* eslint-disable */
 import type { Visibility } from './Visibility.js';
 /**
- * Provide exactly one of `version` or `versionBump`. `version` pins an explicit
- * semver tag. `versionBump` asks the registry to compute the next version
- * atomically from the highest existing clean-semver tag — preferred for
- * CI publishes since it avoids races between concurrent main pushes.
+ * Provide `version` (explicit pin) and/or `semver` (auto-bump PATCH). When both
+ * are omitted, the server falls through to `info.version` from the spec, then
+ * the `0.1.0` default. `version` accepts arbitrary strings (semver, sha-prefixed
+ * tags, calendar tags, UUIDs) — see ADR-0026.
  *
  */
 export type PublicPublishRequestV1 = {
@@ -26,24 +26,30 @@ export type PublicPublishRequestV1 = {
   description?: string;
   visibility?: Visibility;
   /**
-   * Explicit semver tag for this version (e.g. "1.2.0"). Mutually
-   * exclusive with `versionBump`.
+   * Explicit version tag for this publish. Accepts arbitrary strings — semver,
+   * sha-prefixed tags (e.g. "staging-abc1234"), calendar tags (e.g. "v2026-Q3"),
+   * UUIDs, etc. The registry stores what you pass; uniqueness is enforced per
+   * API. When set together with `semver`, `version` wins.
    *
    */
   version?: string;
   /**
-   * Ask the registry to compute the next version. `MINOR` bumps the minor
-   * segment of the highest existing clean-semver tag (1.4.0 → 1.5.0);
-   * `PATCH` bumps the patch segment. The very first publish to an API
-   * (no clean-semver tag exists) always goes at "1.0.0" regardless of
-   * bump type. `MAJOR` is intentionally not supported — per Spec0's
-   * versioning policy, breaking changes create a new API rather than
-   * bumping the major version. Mutually exclusive with `version`.
-   * Resolution and version-row insert are wrapped in a single
-   * transaction with a pessimistic lock on the api row, so concurrent
-   * publishes serialise cleanly.
+   * If true and the previous stored version is a valid semver, increment the
+   * PATCH component atomically (1.2.3 → 1.2.4). If the previous version is not
+   * a valid semver, or this is the first publish, falls through to the
+   * resolution order — `info.version` from the spec, then `0.1.0`. No spec
+   * parsing, no oasdiff classification — see ADR-0026.
    *
    */
+  semver?: boolean;
+  /**
+   * Deprecated. Pass `semver: true` instead. The server ignores this field
+   * since ADR-0026 unified version-bump semantics; it is kept in the schema
+   * so old clients sending `versionBump=PATCH|MINOR` continue to parse
+   * cleanly. New code should not set it.
+   *
+   * @deprecated
+   */
   versionBump?: 'MINOR' | 'PATCH';
   /**
    * Full OpenAPI spec content (YAML or JSON)

package/src/generated/models/TeamPublishRequestV1.ts

@@ -26,8 +26,11 @@ export type TeamPublishRequestV1 = {
    */
   team?: string;
   /**
-   * Semver version to publish (MAJOR.MINOR.PATCH). If omitted, the version is
-   * extracted from `info.version` in the spec. Ignored when `semver` is true.
+   * Explicit version tag for this publish. Accepts arbitrary strings — semver
+   * ("1.2.3"), sha-prefixed tags ("staging-abc1234"), calendar tags
+   * ("v2026-Q3"), UUIDs, etc. If omitted and `semver` is not set, falls through
+   * to `info.version` from the spec, then the `0.1.0` default. When set
+   * together with `semver`, `version` wins. See ADR-0026.
    *
    */
   version?: string;
@@ -48,10 +51,22 @@ export type TeamPublishRequestV1 = {
    */
   specFilePath?: string;
   /**
-   * If true, the backend runs oasdiff to classify the change and auto-computes
-   * the next semver tag (PATCH / NON_BREAKING / BREAKING).
+   * If true and the previous stored version is a valid semver, increment the
+   * PATCH component atomically (1.2.3 → 1.2.4). If the previous version is not
+   * a valid semver, or this is the first publish, falls through to the
+   * resolution order — `version` flag, then `info.version` from the spec, then
+   * `0.1.0`. No spec parsing, no oasdiff — see ADR-0026.
    *
    */
   semver?: boolean;
+  /**
+   * Operator-supplied changelog prose for this version. When non-blank,
+   * becomes the version's `changelog_text` with `changelogSource = MANUAL`
+   * and the async AI listener skips generation. Powers the dashboard's
+   * Edit-API form (title + description combined) and the future
+   * `spec0 push --release-notes` flag.
+   *
+   */
+  releaseNotes?: string;
 };
 

package/src/generated/services/PublicApisService.ts

@@ -7,6 +7,7 @@ import type { PublicApiListItem } from '../models/PublicApiListItem.js';
 import type { PublicApiMetaV1 } from '../models/PublicApiMetaV1.js';
 import type { PublicPublishRequestV1 } from '../models/PublicPublishRequestV1.js';
 import type { PublicPublishResponseV1 } from '../models/PublicPublishResponseV1.js';
+import type { SpecVersionListItemV1 } from '../models/SpecVersionListItemV1.js';
 import type { TeamPublishRequestV1 } from '../models/TeamPublishRequestV1.js';
 import type { TeamPublishResponseV1 } from '../models/TeamPublishResponseV1.js';
 import type { VisibilityUpdateRequestV1 } from '../models/VisibilityUpdateRequestV1.js';
@@ -143,8 +144,106 @@ export class PublicApisService {
       },
     });
   }
+  /**
+   * Fetch the latest spec body for a team-scoped private API
+   * Returns the OpenAPI document content (YAML or JSON, as published) for the latest
+   * version of a team-scoped private API. Mirrors the public-registry equivalent
+   * (`GET /api/v1/public/registry/{orgSlug}/{apiName}`) but resolves the API by its
+   * internal UUID so callers can target private APIs without a public org slug.
+   *
+   * Authorization stack:
+   * - scope: `read:specs`
+   * - ABAC v2: caller must be permitted to `view` the API resource (cross-org and
+   * cross-team isolation collapse to 404 to avoid leaking existence).
+   *
+   * Backs `spec0 pull --team` (issue #149).
+   *
+   * @returns string OpenAPI spec content for the latest published version
+   * @throws ApiError
+   */
+  public static getTeamApiSpec({
+    apiId,
+  }: {
+    apiId: string,
+  }): CancelablePromise<string> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/public/apis/team/{apiId}/spec',
+      path: {
+        'apiId': apiId,
+      },
+      errors: {
+        401: `Missing, invalid, expired, or revoked token`,
+        403: `Token does not carry the required scope`,
+        404: `Resource not found (or not visible to the calling org)`,
+      },
+    });
+  }
+  /**
+   * List published versions of a team-scoped private API
+   * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions` for the
+   * team-scoped surface. Returns the version history ordered by `publishedAt` desc.
+   * Cross-org / cross-team callers see 404 (same ABAC v2 collapse used by the spec body
+   * endpoint).
+   *
+   * @returns SpecVersionListItemV1 Version history
+   * @throws ApiError
+   */
+  public static listTeamApiVersions({
+    apiId,
+  }: {
+    apiId: string,
+  }): CancelablePromise<Array<SpecVersionListItemV1>> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/public/apis/team/{apiId}/versions',
+      path: {
+        'apiId': apiId,
+      },
+      errors: {
+        401: `Missing, invalid, expired, or revoked token`,
+        403: `Token does not carry the required scope`,
+        404: `Resource not found (or not visible to the calling org)`,
+      },
+    });
+  }
+  /**
+   * Fetch a specific tagged version of a team-scoped private API
+   * Mirrors `GET /api/v1/public/registry/{orgSlug}/{apiName}/versions/{tag}` for the
+   * team-scoped surface. Returns the OpenAPI document content for the requested tag.
+   * Cross-org / cross-team callers see 404; unknown tag also 404.
+   *
+   * @returns string OpenAPI spec content for the requested version
+   * @throws ApiError
+   */
+  public static getTeamApiSpecByTag({
+    apiId,
+    tag,
+  }: {
+    apiId: string,
+    tag: string,
+  }): CancelablePromise<string> {
+    return __request(OpenAPI, {
+      method: 'GET',
+      url: '/api/v1/public/apis/team/{apiId}/versions/{tag}',
+      path: {
+        'apiId': apiId,
+        'tag': tag,
+      },
+      errors: {
+        401: `Missing, invalid, expired, or revoked token`,
+        403: `Token does not carry the required scope`,
+        404: `Resource not found (or not visible to the calling org)`,
+      },
+    });
+  }
   /**
    * Update visibility for a public API
+   * Toggle a public API between `PRIVATE`, `UNLISTED`, and `PUBLISHED` without
+   * republishing its spec. Visibility controls whether the API and its versions are
+   * readable through the unauthenticated public registry; the spec content itself is
+   * untouched. Callable by any token in the owning org that holds `write:apis`.
+   *
    * @returns PublicApiMetaV1 Updated visibility
    * @throws ApiError
    */

package/src/generated/services/PublicMocksService.ts

@@ -11,6 +11,11 @@ import { request as __request } from '../core/request.js';
 export class PublicMocksService {
   /**
    * List mock servers for the calling org
+   * Returns every mock server owned by the calling token's org, with the parent API
+   * id/name and the mock's base URL. Backs the `spec0 mock list` CLI command and is
+   * the discovery surface SDK consumers use before deciding whether to point a
+   * client at a mock vs. a real environment.
+   *
    * @returns MockItemV1 Mock servers
    * @throws ApiError
    */

package/src/generated/services/PublicRegistryService.ts

@@ -11,6 +11,11 @@ import { request as __request } from '../core/request.js';
 export class PublicRegistryService {
   /**
    * Fetch latest published spec
+   * Returns the raw OpenAPI document of the most recently published version of the
+   * API, addressed by its org slug and API name. This is the canonical entry point
+   * for SDK generators and the `spec0 pull` CLI command — it short-circuits the
+   * version-listing round-trip when the caller just wants "the current spec".
+   *
    * @returns string OpenAPI spec content
    * @throws ApiError
    */
@@ -37,6 +42,12 @@ export class PublicRegistryService {
   }
   /**
    * List version history
+   * Returns every published version of the API in reverse-chronological order,
+   * including the SemVer tag, git SHA recorded at publish, publish timestamp, and a
+   * flag indicating whether breaking changes were detected against the previous
+   * version. The spec content itself is not inlined — fetch individual versions with
+   * `GET /versions/{tag}`.
+   *
    * @returns SpecVersionListItemV1 Version history
    * @throws ApiError
    */
@@ -63,6 +74,11 @@ export class PublicRegistryService {
   }
   /**
    * Fetch a specific spec version
+   * Returns the immutable OpenAPI document published under the given SemVer tag.
+   * Use this when a consumer needs to pin to a specific contract — e.g. CI
+   * regenerating SDKs from `1.2.3` even after `1.3.0` ships. Returns 404 if either
+   * the API or that specific tag does not exist.
+   *
    * @returns string OpenAPI spec content for the requested version
    * @throws ApiError
    */
@@ -92,6 +108,12 @@ export class PublicRegistryService {
   }
   /**
    * Semantic search over the calling org's APIs
+   * Natural-language search across the calling org's API titles, descriptions, and
+   * operation summaries, backed by the RAG service. Results are ranked by semantic
+   * similarity to `query` and capped at `maxResults` (default 10). Scope is
+   * org-internal — the token's org is the only corpus searched; there is no
+   * cross-org discovery on this endpoint.
+   *
    * @returns AiSearchResponseV1 Search results
    * @throws ApiError
    */

package/src/generated/services/PublicSpecsService.ts

@@ -43,6 +43,13 @@ export class PublicSpecsService {
   }
   /**
    * Diff two published versions of an API
+   * Compares two already-published versions of the same API (addressed by `apiId` +
+   * `fromTag` + `toTag`) and returns the oasdiff-backed structured changelog plus a
+   * breaking-change list. Lighter-weight than the multipart `/specs/diff` endpoint
+   * because the caller doesn't have to upload either spec — the backend reads them
+   * from its own version history. Returns 503 if the oasdiff service is disabled in
+   * this deployment.
+   *
    * @returns VersionDiffResponseV1 Diff result
    * @throws ApiError
    */

package/src/generated/services/PublicSpectralService.ts

@@ -11,6 +11,11 @@ import { request as __request } from '../core/request.js';
 export class PublicSpectralService {
   /**
    * Get the calling org's Spectral ruleset
+   * Returns the org's custom Spectral ruleset YAML, or an empty string when the org
+   * has not configured one. The CLI fetches this on every `spec0 lint` invocation so
+   * lint behaviour stays consistent between local dev and CI. Built-in rulesets are
+   * applied regardless of whether a custom ruleset is set.
+   *
    * @returns SpectralRulesetResponseV1 Current ruleset
    * @throws ApiError
    */

package/src/generated/services/PublicTeamsService.ts

@@ -10,6 +10,11 @@ import { request as __request } from '../core/request.js';
 export class PublicTeamsService {
   /**
    * List teams for the calling org
+   * Returns every team in the calling token's org with its id, name, and
+   * description. Use this to resolve a team slug or human-readable name to the UUID
+   * expected by other endpoints (e.g. `team` on team-API publish, or `teamId` on
+   * delete). Scope is org-internal — teams in other orgs are never returned.
+   *
    * @returns TeamV1 Teams in the calling org
    * @throws ApiError
    */