@topolo/sdk 0.4.0 → 0.4.2

package/README.md

@@ -4,6 +4,11 @@ Typed client SDK for the Topolo platform. Consumed by `@topolo/cli` and
 `@topolo/mcp`, and available to any first- or third-party code that needs to
 call Topolo APIs on a user's behalf.
 
+Use `@topolo/login` for Login with Topolo OAuth/OIDC provider integration,
+token exchange, userinfo, ID-token verification, and local account linking.
+Use `@topolo/sdk` after login, when the app already has a Topolo API credential
+and needs to call Topolo APIs.
+
 This package is the single place where cross-org isolation is enforced on the
 client side.
 
@@ -80,9 +85,19 @@ Additional modules land per-app as each backend contract stabilizes.
 ## Application catalog
 
 `APPLICATIONS` describes every Topolo platform application discovered from the
-PlatformApplications metadata, including pages-only apps that do not expose a
-callable service. `DEFAULT_SERVICE_URLS` remains the callable API service map
-used by `TopoloClient`.
+PlatformApplications metadata, including Worker apps that do not expose a
+callable service. `DEFAULT_SERVICE_URLS` is the bundled callable API service
+snapshot generated from `topolo.cloudcontrol.json`.
+
+For agent-scale fleets, the bundle is packaging metadata, not an authorization
+source. `TopoloClient.listServices()` always calls the live TopoloAuth catalog
+with the current credential and returns only services that credential can use in
+its organization, including the granted permissions. `TopoloClient.request()`
+uses that credential-scoped catalog before routing any non-Auth service, so a
+bundled service ID is only a convenient alias after Auth confirms access.
+
+`listBundledServices()` is available for packaging/audit tooling that needs the
+generated snapshot. Do not use it to decide what an end user or agent may call.
 
 `APPLICATION_REQUIREMENTS` is the versioned app-build contract agents should
 read before creating or expanding a Topolo app. `requirementsForApplication()`
@@ -139,7 +154,7 @@ Still routes through auth + audit headers. Mutating methods still require
 | `TopoloHttpError`        | Other non-2xx responses                  |
 | `TopoloSdkError`         | Base class                               |
 
-## Service URL overrides
+## Service URL Overrides
 
 Defaults target production. Override per-service for staging/dev: