@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.11

package/docs/multi-environment.md

@@ -11,20 +11,42 @@ Deployment commands resolve the target workspace from, in priority order, the `-
 For one-off commands, pass the workspace explicitly:
 
 ```bash
-tailor-sdk deploy -w <staging-workspace-id>
+tailor deploy -w <staging-workspace-id>
 ```
 
 For environments you switch between regularly, create a named profile per environment with the [profile commands](./cli/workspace.md#profile-create) and select it with `--profile` (`-p`) or `TAILOR_PLATFORM_PROFILE`:
 
 ```bash
-tailor-sdk profile create staging -u you@example.com -w <staging-workspace-id>
-tailor-sdk profile create production -u you@example.com -w <production-workspace-id> --permission read
+tailor profile create staging -u you@example.com -w <staging-workspace-id>
+tailor profile create production -u you@example.com -w <production-workspace-id> --permission read
 
-tailor-sdk deploy -p staging
+tailor deploy -p staging
 ```
 
 Profiles are created with `write` permission by default. The production profile above opts into `--permission read`, which blocks write commands such as `deploy` while the profile is active — a guard against deploying to production by accident. To deploy to production deliberately, pass the workspace explicitly with `-w` without selecting the profile — the guard applies only while a profile is selected via `-p` or `TAILOR_PLATFORM_PROFILE` — or use a separate profile created with `write` permission.
 
+If a profile targets a non-default Tailor Platform API, save that connection on the profile as well. User login tokens are stored per Platform URL, so you can log in once for each Platform and then switch with only the profile:
+
+```bash
+export TAILOR_PLATFORM_URL=<platform-api-url>
+export TAILOR_PLATFORM_OAUTH2_CLIENT_ID=<oauth2-client-id>
+export TAILOR_PLATFORM_CONSOLE_URL=<console-url>
+
+tailor login
+tailor profile create development \
+  -u you@example.com \
+  -w <development-workspace-id> \
+  --platform-url "$TAILOR_PLATFORM_URL" \
+  --oauth2-client-id "$TAILOR_PLATFORM_OAUTH2_CLIENT_ID" \
+  --console-url "$TAILOR_PLATFORM_CONSOLE_URL"
+
+unset TAILOR_PLATFORM_URL TAILOR_PLATFORM_OAUTH2_CLIENT_ID TAILOR_PLATFORM_CONSOLE_URL
+tailor deploy -p development
+tailor open -p development
+```
+
+After the profile exists, run `tailor login -p development` to refresh the login for that Platform without re-exporting the connection variables.
+
 ## Varying config values per environment
 
 `tailor.config.ts` is a TypeScript module evaluated locally each time an SDK command loads it, so any value can branch on `process.env`. If the config also defines an auth before-login hook, mind the `process.env` caveat in [Environment Variables](./configuration.md#environment-variables). Keep one env file per environment and load it with the global [`--env-file`](./cli-reference.md#environment-file-loading) option:
@@ -32,17 +54,17 @@ Profiles are created with `write` permission by default. The production profile
 ```ini
 # .env.production
 APP_ENV=production
-LOG_LEVEL=WARN
+TAILOR_APP_LOG_LEVEL=WARN
 ```
 
 ```bash
-tailor-sdk deploy -w <production-workspace-id> --env-file .env.production
+tailor deploy -w <production-workspace-id> --env-file .env.production
 ```
 
 ```typescript
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 

package/docs/plugin/custom.md

@@ -93,7 +93,7 @@ interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
 onTypeLoaded(context) {
   const { type, typeConfig, namespace } = context;
   return {
-    types: { archive: db.type(`Deleted_${type.name}`, { ... }) },
+    types: { archive: db.table(`Deleted_${type.name}`, { ... }) },
     extends: { fields: { deletedAt: db.datetime({ optional: true }) } },
     executors: [{ name: `${type.name}-on-delete`, resolve: async () => await import("./on-delete"), context: { sourceType: type, namespace } }],
   };
@@ -122,7 +122,7 @@ Same as `TypePluginOutput` but without `extends` (namespace plugins cannot exten
 ```typescript
 onNamespaceLoaded(context) {
   return {
-    types: { auditLog: db.type("AuditLog", { action: db.string(), ... }) },
+    types: { auditLog: db.table("AuditLog", { action: db.string(), ... }) },
   };
 },
 ```
@@ -343,7 +343,7 @@ function processSoftDelete(
 
   // Generate archive type
   const archiveType = db
-    .type(`${prefix}${type.name}`, {
+    .table(`${prefix}${type.name}`, {
       originalId: db.uuid().description("ID of the deleted record"),
       originalData: db.string().description("JSON snapshot of deleted record"),
       deletedAt: db.datetime().description("When the record was deleted"),
@@ -450,7 +450,7 @@ export const plugins = definePlugins(
 
 // tailordb/customer.ts
 export const customer = db
-  .type("Customer", {
+  .table("Customer", {
     name: db.string(),
     email: db.string(),
   })

package/docs/plugin/index.md

@@ -6,7 +6,7 @@ Plugins extend TailorDB types by automatically generating additional types, exec
 
 ## Overview
 
-When you run `tailor-sdk generate`, the SDK:
+When you run `tailor generate`, the SDK:
 
 1. Loads all TailorDB types with plugin attachments
 2. Passes each type to the attached plugins
@@ -43,7 +43,7 @@ Use the `.plugin()` method to attach plugins to specific types:
 import { db } from "@tailor-platform/sdk";
 
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string(),
     email: db.string(),
   })
@@ -58,7 +58,7 @@ Some plugins accept per-type configuration:
 
 ```typescript
 export const customer = db
-  .type("Customer", {
+  .table("Customer", {
     name: db.string(),
     // ...
   })
@@ -102,18 +102,18 @@ Plugins can generate:
 - **Field Extensions**: Additional fields added to the source type
 - **Output Files**: TypeScript code and other files via generation-time hooks
 
-Generated files are placed under `.tailor-sdk/<plugin-id>/` (the plugin ID is sanitized,
+Generated files are placed under `.tailor/<plugin-id>/` (the plugin ID is sanitized,
 e.g. `@example/soft-delete` → `example-soft-delete`), such as:
 
-- `.tailor-sdk/example-soft-delete/types`
-- `.tailor-sdk/example-soft-delete/executors`
+- `.tailor/example-soft-delete/types`
+- `.tailor/example-soft-delete/executors`
 
 ## Plugin Lifecycle
 
-Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor-sdk generate` pipeline:
+Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor generate` pipeline:
 
 ```
-tailor-sdk generate
+tailor generate
 │
 ├─ Load TailorDB types
 │   ├─ onTypeLoaded        ← per type with .plugin() attached

package/docs/quickstart.md

@@ -12,7 +12,7 @@ Contact us [here](https://www.tailor.tech/demo) to get started.
 
 ### Install Node.js
 
-The SDK requires Node.js 22 or later. Install Node.js via your package manager by following the official Node.js instructions.
+The SDK requires Node.js 22.15.0 or later. Install Node.js via your package manager by following the official Node.js instructions.
 
 Alternatively, you can use [Bun](https://bun.sh/) as the runtime.
 
@@ -24,20 +24,22 @@ The following command creates a new project with the required configuration file
 
 ```bash
 npm create @tailor-platform/sdk -- --template hello-world example-app
+cd example-app
 # Or with Bun:
 # bun create @tailor-platform/sdk --template hello-world example-app
+# cd example-app
 ```
 
 Before deploying your app, you need to create a workspace:
 
 ```bash
-npx tailor-sdk login
-npx tailor-sdk workspace create --name <workspace-name> --region <workspace-region>
-npx tailor-sdk workspace list
+npx tailor login
+npx tailor workspace create --name <workspace-name> --region <workspace-region>
+npx tailor workspace list
 
 # Or with Bun:
-# bunx tailor-sdk login
-# bunx tailor-sdk workspace create --name <workspace-name> --region <workspace-region>
+# bunx tailor login
+# bunx tailor workspace create --name <workspace-name> --region <workspace-region>
 
 # OR
 # Create a new workspace using Tailor Platform Console
@@ -49,7 +51,6 @@ npx tailor-sdk workspace list
 Run the deploy command to deploy your project:
 
 ```bash
-cd example-app
 npm run deploy -- --workspace-id <your-workspace-id>
 # Or with Bun:
 # bun run deploy --workspace-id <your-workspace-id>

package/docs/runtime.md

@@ -19,6 +19,8 @@ import {
   workflow,
   context,
   file,
+  aigateway,
+  logger,
 } from "@tailor-platform/sdk/runtime";
 
 const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
@@ -30,11 +32,15 @@ const token = await authconnection.getConnectionToken("google");
 const client = new idp.Client({ namespace: "my-namespace" });
 const { users } = await client.users({ first: 10 });
 
-const executionId = await workflow.triggerWorkflow("approval", { reportId });
+const executionId = await workflow.startWorkflow("approval", { reportId });
 
 const invoker = context.getInvoker();
 
 const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
+
+const { url } = await aigateway.get("my-aigateway");
+
+logger.info("order processed", { orderId: "o-1", total: 99.5 });
 ```
 
 ## Subpath imports
@@ -42,10 +48,12 @@ const { metadata } = await file.upload("my-namespace", "Document", "attachment",
 Each namespace can also be imported individually so you only pull what you need:
 
 ```ts
-import * as iconv from "@tailor-platform/sdk/runtime/iconv";
-import type { ListUsersResponse, ClientConfig } from "@tailor-platform/sdk/runtime/idp";
+import { iconv } from "@tailor-platform/sdk/runtime/iconv";
+import { idp, type ListUsersResponse, type ClientConfig } from "@tailor-platform/sdk/runtime/idp";
 ```
 
+`TailorContextAPI` and `TailorWorkflowAPI` describe the imported SDK wrapper objects. When typing direct access to the platform-provided globals or a runtime mock, use `PlatformContextAPI` or `PlatformWorkflowAPI` instead.
+
 ## Activating the global types
 
 Most users do not need to touch the globals entry — `@tailor-platform/sdk/runtime` (and its subpath modules) cover the same surface without depending on any ambient declaration.
@@ -76,9 +84,11 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
 - `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
 - `idp` — IdP user management (`new Client({ namespace })`)
-- `workflow` — workflow & job control (`triggerWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
-- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`, `openDownloadStream` _(deprecated)_)
+- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
+- `aigateway` — AI Gateway URL resolution (`get`)
+- `logger` — structured logging with severity and attributes; the message is written to standard output, the full entry with its attributes is exported over OpenTelemetry where the attributes are queryable (`debug`, `info`, `warn`, `error`, `setAttributes`)
 
 ## Testing
 
@@ -91,17 +101,16 @@ import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
   using iconvM = mockIconv();
-  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvM.calls[0]?.method).toBe("convert");
+  expect(iconvM.convert).toHaveBeenCalledWith("あ", "UTF-8", "Shift_JIS");
 }); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/aigateway.md

@@ -1,12 +1,12 @@
 # AI Gateway
 
-AI Gateway provides a unified endpoint for accessing multiple LLM providers (Azure OpenAI, Google Vertex AI Gemini, Anthropic via Vertex AI) through a single OpenAI-compatible API, with platform-managed credentials and workspace-scoped authentication.
+AI Gateway provides a unified endpoint for accessing a range of large language models through a single OpenAI-compatible API, with platform-managed credentials and workspace-scoped authentication.
 
 ## Overview
 
 AI Gateway provides:
 
-- A unified, OpenAI-compatible endpoint for multiple LLM providers
+- A unified, OpenAI-compatible endpoint for multiple LLM models
 - Mandatory authentication via your workspace's auth (request tokens are resolved against the configured auth namespace)
 - Per-workspace isolation: each gateway is provisioned with its own platform-assigned URL
 - Optional CORS allow-list for browser-based clients
@@ -31,6 +31,7 @@ const aiGateway = defineAIGateway("my-aigateway", {
 });
 
 export default defineConfig({
+  name: "my-app",
   aiGateways: [aiGateway],
 });
 ```
@@ -80,6 +81,7 @@ const website = defineStaticWebSite("my-frontend", {
 });
 
 const aiGateway = defineAIGateway("my-aigateway", {
+  // Name of an auth namespace in your workspace; request tokens are resolved against it.
   authNamespace: "default",
   cors: [website.url],
 });
@@ -95,3 +97,19 @@ export default defineConfig({
   aiGateways: [aiGateway],
 });
 ```
+
+## Runtime Usage
+
+Resolvers, executors, and workflow jobs can resolve a gateway's platform-assigned URL by name via `aigateway.get()`. The name is type-checked and autocompleted against the AI Gateways defined in `aiGateways`:
+
+```typescript
+import { aigateway } from "@tailor-platform/sdk/runtime";
+
+const { url } = await aigateway.get("my-aigateway");
+
+// await aigateway.get("unknown"); // Type error — only "my-aigateway" is allowed
+```
+
+Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.
+
+The same URL is also shown by `tailor show`, which lists the URL of each AI Gateway defined in `aiGateways` once it has been deployed.

package/docs/services/auth.md

@@ -86,7 +86,7 @@ Example TailorDB type for user profile:
 // tailordb/user.ts
 import { db } from "@tailor-platform/sdk";
 
-export const user = db.type("User", {
+export const user = db.table("User", {
   email: db.string().unique(), // usernameField must have unique constraint
   role: db.enum(["admin", "user"]),
   ...db.fields.timestamps(),
@@ -107,7 +107,7 @@ userProfile: {
 
 **usernameField**: The field in the TailorDB type used as the username. This field must have a unique constraint (`.unique()`) since it is used to uniquely identify users.
 
-**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Enabled attributes must be assigned values in all machine user definitions. Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
+**attributes**: Specifies which fields from the TailorDB type are used as user attributes. Set to `true` to enable a field. Machine user definitions must assign values to attributes derived from required fields; attributes derived from optional fields may be omitted (see [Machine Users](#machine-users)). Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes. The `id` field and datetime/date/time types are excluded.
 
 ## Attribute List
 
@@ -130,7 +130,7 @@ Example TailorDB type with UUID fields for attribute list:
 // tailordb/user.ts
 import { db } from "@tailor-platform/sdk";
 
-export const user = db.type("User", {
+export const user = db.table("User", {
   email: db.string().unique(),
   role: db.enum(["admin", "user"]),
   organizationId: db.uuid(), // Can be used in attributeList
@@ -139,18 +139,18 @@ export const user = db.type("User", {
 });
 ```
 
-The `attributeList` values are accessible via `user.attributeList` as a tuple:
+The `attributeList` values are accessible via the runtime principal's `attributeList` as a tuple:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributeList[0], // First UUID from list
+    create: ({ invoker }) => invoker?.attributeList[0] ?? null, // First UUID from list
   },
 })
 ```
@@ -160,7 +160,7 @@ body: (context) => {
 When you want to use machine users without defining a `userProfile`, define `machineUserAttributes` instead. These attributes are used for:
 
 - type-safe `machineUsers[*].attributes`
-- `context.user.attributes` typing (via `tailor.d.ts`)
+- runtime principal `attributes` typing (via `tailor.d.ts`)
 
 ```typescript
 import { defineAuth, t } from "@tailor-platform/sdk";
@@ -182,7 +182,7 @@ export const auth = defineAuth("my-auth", {
 To update types in `tailor.d.ts`, run:
 
 ```bash
-tailor-sdk generate
+tailor generate
 ```
 
 ## Machine Users
@@ -200,12 +200,12 @@ machineUsers: {
 },
 ```
 
-**attributes**: Values for attributes enabled in `userProfile.attributes` (or all fields defined in `machineUserAttributes` when `userProfile` is omitted). All enabled fields must be set here. These values are accessible via `user.attributes`:
+**attributes**: Values for attributes enabled in `userProfile.attributes` (or fields defined in `machineUserAttributes` when `userProfile` is omitted). Attribute keys mirror the field's optionality: attributes derived from required fields must be set, while attributes derived from optional fields may be omitted. Setting an attribute to `null` or `undefined` is equivalent to omitting it — the attribute is deployed as unset. These values are accessible via the runtime principal's `attributes`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const role = context.user.attributes?.role;
+  const role = context.caller?.attributes.role;
 },
 ```
 
@@ -230,25 +230,25 @@ machineUsers: {
 },
 ```
 
-These values are accessible via `user.attributeList`:
+These values are accessible via the runtime principal's `attributeList`:
 
 ```typescript
 // In a resolver
 body: (context) => {
-  const [organizationId, teamId] = context.user.attributeList;
+  const [organizationId, teamId] = context.caller?.attributeList ?? [];
 },
 
 // In TailorDB hooks
 .hooks({
   field: {
-    create: ({ user }) => user.attributes?.role === "ADMIN" ? "default" : null,
+    create: ({ invoker }) => invoker?.attributes.role === "ADMIN" ? "default" : null,
   },
 })
 
 // In TailorDB validate
 .validate({
   field: [
-    ({ user }) => user.attributes?.role === "ADMIN",
+    ({ invoker }) => invoker?.attributes.role === "ADMIN",
     "Only admins can set this field",
   ],
 })
@@ -264,12 +264,12 @@ Machine users are useful for:
 Get a machine user token using the CLI:
 
 ```bash
-tailor-sdk machineuser token <name>
+tailor machineuser token <name>
 ```
 
 ### Specifying a machine user invoker
 
-Resolvers, executors, and `workflow.trigger()` accept an `authInvoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
+Resolvers, executors, and `workflow.start()` accept an `invoker` option that chooses which machine user runs the operation. Pass the machine user name as a plain string — it is type-narrowed to the names you registered in `machineUsers`.
 
 ```typescript
 // tailor.config.ts
@@ -284,21 +284,21 @@ export const auth = defineAuth("my-auth", {
 ```
 
 ```typescript
-// resolvers/trigger-workflow.ts
+// resolvers/start-workflow.ts
 import { createResolver, t } from "@tailor-platform/sdk";
 import myWorkflow from "../workflows/my-workflow";
 
 export default createResolver({
-  name: "triggerMyWorkflow",
+  name: "startMyWorkflow",
   operation: "mutation",
   input: {
     id: t.string(),
   },
   body: async ({ input }) => {
-    // Trigger workflow with machine user permissions
-    const workflowRunId = await myWorkflow.trigger(
+    // Start workflow with machine user permissions
+    const workflowRunId = await myWorkflow.start(
       { id: input.id },
-      { authInvoker: "admin-machine-user" },
+      { invoker: "admin-machine-user" },
     );
     return { workflowRunId };
   },
@@ -308,7 +308,7 @@ export default createResolver({
 });
 ```
 
-Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor-sdk generate` (or `apply`) after defining new machine users to refresh it.
+Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new machine users to refresh it.
 
 ## OAuth 2.0 Clients
 
@@ -348,7 +348,7 @@ oauth2Clients: {
 Get OAuth2 client credentials using the CLI:
 
 ```bash
-tailor-sdk oauth2client get <name>
+tailor oauth2client get <name>
 ```
 
 ## Identity Provider
@@ -363,21 +363,18 @@ See [IdP](./idp.md) for configuring identity providers.
 
 ## Auth Connections
 
-Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `tailor.authconnection.getConnectionToken()`.
+Auth connections enable OAuth2 authentication with external providers (Google, Microsoft 365, QuickBooks, etc.) for application-to-application flows. Functions can access connection tokens at runtime via `authconnection.getConnectionToken()` (from `@tailor-platform/sdk/runtime`).
 
 For the official Tailor Platform documentation, see [AuthConnection Guide](https://docs.tailor.tech/guides/auth/authconnection).
 
-> [!WARNING]
-> **Managing connections through `tailor.config.ts` is unreliable for shared and CI deploys.**
-> A deploy revokes and recreates the connection — discarding the token obtained via `authconnection authorize` — whenever it cannot confirm the secret is unchanged. That check relies on a hash stored locally in `.tailor-sdk/secrets-state.json`, which is gitignored and therefore not shared across machines. So a deploy from CI, a clean checkout, another developer's machine, or after deleting `.tailor-sdk/` recreates the connection and drops its token. Only repeated deploys from the same machine that still holds that state keep the token.
->
-> Because of this, prefer to **create the connection and its token from the Console**. You can jump to the connections page with:
+> [!NOTE]
+> Deploy updates connections **in-place**, preserving the OAuth token. If the connection requires re-authorization after an update, the deploy will warn you:
 >
 > ```bash
-> tailor-sdk authconnection open
+> tailor authconnection authorize --name <connection-name>
+> # Or via the Console:
+> tailor authconnection open
 > ```
->
-> The `connections` field in `defineAuth()` and the `authconnection authorize` flow are documented below for reference.
 
 ### Setup Flow
 
@@ -409,10 +406,10 @@ export const auth = defineAuth("my-auth", {
 });
 ```
 
-After `tailor-sdk deploy`, authorize the connection:
+After `tailor deploy`, authorize the connection:
 
 ```bash
-tailor-sdk authconnection authorize --name google-connection \
+tailor authconnection authorize --name google-connection \
   --scopes "openid,profile,email"
 ```
 
@@ -430,30 +427,25 @@ The authorize command opens a browser for the OAuth2 flow. The authorization cod
 | `authUrl`      | `string` | No       | Override for the authorization endpoint.    |
 | `tokenUrl`     | `string` | No       | Override for the token endpoint.            |
 
-### Change Detection
-
-The SDK uses hash-based change detection for connection configs. Only connections whose configuration has changed since the last `apply` are updated (revoked and recreated). Deleting the `.tailor-sdk/` directory forces all connections to be re-sent.
+### Retrieving Connection Tokens
 
-> [!WARNING]
-> The secret hash lives in `.tailor-sdk/secrets-state.json`, which is gitignored and not shared across machines or CI. When that state is missing — a clean checkout, CI, another machine, or after deleting `.tailor-sdk/` — a deploy cannot confirm the secret is unchanged, so it revokes and recreates the connection and discards the token stored by `authconnection authorize`. For shared and CI workflows, manage the connection and create its token from the Console (`tailor-sdk authconnection open`) instead.
-
-### `auth.getConnectionToken()`
-
-`auth.getConnectionToken()` retrieves connection tokens at runtime by calling `tailor.authconnection.getConnectionToken()` internally. When `connections` is defined in `defineAuth()`, the connection name is type-checked and autocompleted against the defined keys:
+Use `authconnection.getConnectionToken()` from `@tailor-platform/sdk/runtime` to retrieve connection tokens at runtime. The connection name is type-checked and autocompleted against the connections defined in `defineAuth()`'s `connections`:
 
 ```typescript
-import { auth } from "../tailor.config";
+import { authconnection } from "@tailor-platform/sdk/runtime";
 
 // In a resolver, executor, or workflow:
-const tokens = await auth.getConnectionToken("google-connection");
+const tokens = await authconnection.getConnectionToken("google-connection");
 const response = await fetch("https://www.googleapis.com/...", {
   headers: { Authorization: `Bearer ${tokens.access_token}` },
 });
 
-// auth.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed
+// authconnection.getConnectionToken("unknown"); // Type error — only "google-connection" is allowed
 ```
 
-When `connections` is not defined, `getConnectionToken()` accepts any string. This supports connections managed entirely via the CLI.
+Type narrowing is provided by the generated `tailor.d.ts` (the `ConnectionNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new connections to refresh it. Before the first generate, or when `connections` is not defined in `defineAuth()`, `getConnectionToken()` accepts any string — this also supports connections managed entirely via the CLI.
+
+This keeps runtime files independent from `tailor.config.ts`.
 
 See [Built-in Interfaces](https://docs.tailor.tech/guides/function/builtin-interfaces.html#auth-connection) for the full runtime API.
 
@@ -463,19 +455,19 @@ Auth connections can also be managed via the CLI:
 
 ```bash
 # Open the connections page in the Console (recommended for creating connections/tokens)
-tailor-sdk authconnection open
+tailor authconnection open
 
 # Authorize (opens browser for OAuth2 flow)
-tailor-sdk authconnection authorize --name google-connection
+tailor authconnection authorize --name google-connection
 
 # List all connections
-tailor-sdk authconnection list
+tailor authconnection list
 
 # Revoke a connection
-tailor-sdk authconnection revoke --name google-connection
+tailor authconnection revoke --name google-connection
 ```
 
-Connection creation is handled by `tailor-sdk deploy` via the config, but recreation on deploy can drop the authorized token (see the warning at the top of this section) — for shared and CI workflows, create connections and tokens from the Console (`tailor-sdk authconnection open`) instead.
+Connection creation and updates are handled by `tailor deploy` via the config. Deploy updates connections in-place, preserving the authorized token, and warns you if an update requires re-authorization (see the note above).
 
 See [Auth Resource Commands](../cli/auth.md) for full CLI documentation.
 
@@ -538,21 +530,21 @@ Manage Auth resources using the CLI:
 
 ```bash
 # Auth connections
-tailor-sdk authconnection authorize --name <name>
-tailor-sdk authconnection list
-tailor-sdk authconnection revoke --name <name>
+tailor authconnection authorize --name <name>
+tailor authconnection list
+tailor authconnection revoke --name <name>
 
 # List machine users
-tailor-sdk machineuser list
+tailor machineuser list
 
 # Get machine user token
-tailor-sdk machineuser token <name>
+tailor machineuser token <name>
 
 # List OAuth2 clients
-tailor-sdk oauth2client list
+tailor oauth2client list
 
 # Get OAuth2 client credentials
-tailor-sdk oauth2client get <name>
+tailor oauth2client get <name>
 ```
 
 See [Auth Resource Commands](../cli/auth.md) for full documentation.