@tailor-platform/sdk 2.0.0-next.2 → 2.0.0-next.3

package/docs/migration/v2.md

@@ -68,25 +68,25 @@ import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
 
 **Migration:** Automatic
 
-Strip the deprecated {input: ...} wrapper from `tailor-sdk function test-run --arg` JSON in scripts and docs
+Strip the deprecated {input: ...} wrapper from `tailor function test-run --arg` JSON in scripts and docs
 
 Before:
 
 ```sh
-tailor-sdk function test-run resolvers/add.ts --arg '{"input":{"a":1}}'
+tailor function test-run resolvers/add.ts --arg '{"input":{"a":1}}'
 ```
 
 After:
 
 ```sh
-tailor-sdk function test-run resolvers/add.ts --arg '{"a":1}'
+tailor function test-run resolvers/add.ts --arg '{"a":1}'
 ```
 
-## tailor-sdk-skills → tailor-sdk skills install
+## tailor-sdk-skills → tailor skills add
 
 **Migration:** Partially automatic
 
-Replace deprecated `tailor-sdk-skills` invocations with `tailor-sdk skills install`
+Replace deprecated `tailor-sdk-skills` invocations with `tailor skills add`
 
 Before:
 
@@ -97,17 +97,17 @@ npx tailor-sdk-skills
 After:
 
 ```sh
-tailor-sdk skills install
+tailor skills add
 ```
 
 <details>
 <summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
 
 ```text
-The standalone tailor-sdk-skills binary is removed in v2; call the skills install
-subcommand on the main tailor-sdk CLI instead. Replace any remaining
+The standalone tailor-sdk-skills binary is removed in v2; call the skills add
+subcommand on the main tailor CLI instead. Replace any remaining
 tailor-sdk-skills invocations the codemod did not rewrite with
-`tailor-sdk skills install`.
+`tailor skills add`.
 ```
 
 </details>
@@ -167,6 +167,48 @@ Use TailorPrincipal for the unified user/actor/invoker type.
 
 </details>
 
+## AttributeMap → Attributes
+
+**Migration:** Partially automatic
+
+Rename auth attribute module augmentation and related SDK type names from `AttributeMap` to `Attributes`
+
+Module augmentation uses `Attributes`:
+
+Before:
+
+```ts
+declare module "@tailor-platform/sdk" {
+  interface AttributeMap {
+    role: string;
+  }
+}
+```
+
+After:
+
+```ts
+declare module "@tailor-platform/sdk" {
+  interface Attributes {
+    role: string;
+  }
+}
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2, the auth attribute type API is renamed from `AttributeMap`
+to `Attributes`; related SDK types are renamed to `UserAttributes` and
+`InferredAttributes`. The codemod rewrites SDK imports, re-exports,
+namespace-qualified references, import() type references, and module
+augmentations. Review any remaining matches manually and leave unrelated
+local names or deploy/proto wire field names unchanged.
+```
+
+</details>
+
 ## tailor-sdk apply → tailor-sdk deploy
 
 **Migration:** Automatic
@@ -217,11 +259,98 @@ happen to use `--machineuser` alone.
 
 </details>
 
+## SDK environment variable rename
+
+**Migration:** Partially automatic
+
+Rewrite unambiguous removed SDK environment variable names to their v2 `TAILOR_*` names and flag generic names for manual review
+
+Before:
+
+```sh
+TAILOR_PLATFORM_SDK_BUILD_ONLY=true tailor-sdk deploy
+```
+
+After:
+
+```sh
+TAILOR_DEPLOY_BUILD_ONLY=true tailor-sdk deploy
+```
+
+Before:
+
+```ts
+const token = process.env.TAILOR_TOKEN;
+```
+
+After:
+
+```ts
+const token = process.env.TAILOR_PLATFORM_TOKEN;
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Review any remaining removed SDK environment variable names after the codemod
+runs. The codemod intentionally leaves generic names such as `LOG_LEVEL`,
+`PLATFORM_URL`, and `PLATFORM_OAUTH2_CLIENT_ID` for manual review because
+they can configure non-SDK tools. Replace only actual SDK usages with their
+v2 names. If a remaining match is an unrelated local identifier, fixture
+label, or historical documentation that intentionally does not configure the
+SDK, leave it unchanged.
+```
+
+</details>
+
 ## auth.invoker("name") → "name"
 
 **Migration:** Partially automatic
 
-Replace `auth.invoker("name")` calls with the bare `"name"` string and drop the `auth` import when no other reference remains. The `auth.invoker()` helper is deprecated in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
+Replace statically identified SDK `auth.invoker("name")` option values with the bare `"name"` string while preserving the `authInvoker` key for SDK versions before the option rename.
+
+Before:
+
+```ts
+createResolver({ authInvoker: auth.invoker("manager") });
+```
+
+After:
+
+```ts
+createResolver({ authInvoker: "manager" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
+machine user name passed directly as a string. The codemod already rewrote the
+statically identified SDK option form authInvoker: auth.invoker("name") to authInvoker: "name". These files still contain
+auth.invoker(...) calls that need manual review.
+
+For each remaining auth.invoker(<expr>) call:
+1. Replace the whole call with <expr> only where the target option expects a
+   machine user name string; platform/runtime authInvoker payloads still expect
+   the object form.
+2. Keep the authInvoker key when targeting SDK versions before the invoker
+   option rename; later v2 targets run a separate codemod for that key rename.
+3. After removing every auth.invoker usage in a file, delete the now-unused auth
+   import (keeping it pulls Node-only config modules into runtime bundles); leave
+   the import if auth is still referenced elsewhere.
+
+Do not change behavior beyond the auth.invoker() removal.
+```
+
+</details>
+
+## auth.invoker("name") → invoker: "name"
+
+**Migration:** Partially automatic
+
+Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker("name")` there with the bare `"name"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.trigger()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
 
 Before:
 
@@ -241,19 +370,68 @@ createResolver({ invoker: "manager" });
 ```text
 In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
 machine user name passed directly as a string. The codemod already rewrote the
-string-literal form auth.invoker("name") to "name". These files still contain
-auth.invoker(...) because the argument is not a plain string literal (a variable,
-template literal, function call, or property access).
+statically identified SDK option form authInvoker: auth.invoker("name") to invoker: "name" and renamed supported authInvoker option keys. These files still contain
+auth.invoker(...) calls or authInvoker keys that need manual review.
 
 For each remaining auth.invoker(<expr>) call:
-1. Replace the whole call with <expr> as-is (e.g. auth.invoker(name) becomes name).
-2. Make sure <expr> evaluates to the machine user name (a string); adjust it if it
-   resolves to an object or an auth config value instead.
+1. Replace the whole call with <expr> only where the target option expects a
+   machine user name string; platform/runtime authInvoker payloads still expect
+   the object form.
+2. Rename remaining authInvoker option keys to invoker only for SDK resolver,
+   executor, workflow.trigger(), or startWorkflow() options. Keep platform/runtime
+   payload keys such as tailor.workflow.triggerWorkflow(..., { authInvoker: ... }).
 3. After removing every auth.invoker usage in a file, delete the now-unused auth
    import (keeping it pulls Node-only config modules into runtime bundles); leave
    the import if auth is still referenced elsewhere.
 
-Do not change behavior beyond removing the auth.invoker() indirection.
+Do not change behavior beyond the SDK option rename and auth.invoker() removal.
+```
+
+</details>
+
+## auth.getConnectionToken() → runtime authconnection
+
+**Migration:** Partially automatic
+
+The deprecated `auth.getConnectionToken()` helper returned by `defineAuth()` is removed in v2. Use `authconnection.getConnectionToken(...)` from `@tailor-platform/sdk/runtime` in resolvers, executors, and workflows instead.
+
+Before:
+
+```ts
+import { auth } from "../tailor.config";
+
+const token = await auth.getConnectionToken("google");
+```
+
+After:
+
+```ts
+import { authconnection } from "@tailor-platform/sdk/runtime";
+
+const token = await authconnection.getConnectionToken("google");
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.getConnectionToken() helper returned by defineAuth()
+is removed. Runtime code should call authconnection.getConnectionToken(...) from
+@tailor-platform/sdk/runtime instead of importing auth from tailor.config.ts.
+
+For each getConnectionToken usage where <receiver> is a defineAuth() result
+imported from tailor.config.ts:
+1. Replace <receiver>.getConnectionToken(<expr>) calls with
+   authconnection.getConnectionToken(<expr>).
+2. Update non-call references, including <receiver>.getConnectionToken,
+   <receiver>["getConnectionToken"], and destructuring from <receiver>, to
+   reference authconnection instead.
+3. Add or reuse `import { authconnection } from "@tailor-platform/sdk/runtime"`.
+4. Remove the auth import from tailor.config.ts only when no other auth reference
+   remains in the file.
+
+Leave usages unchanged when the receiver is already the runtime authconnection
+wrapper or global tailor.authconnection.
 ```
 
 </details>
@@ -331,6 +509,32 @@ already pass a plain value unchanged.
 
 </details>
 
+## defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints
+
+**Migration:** Partially automatic
+
+Rename `defineWaitPoint` and `defineWaitPoints` to `createWaitPoint` and `createWaitPoints`. The functions create runtime instances with `.wait()` / `.resolve()` methods, so the `create*` prefix is used consistently.
+
+Before:
+
+```ts
+import { defineWaitPoints } from "@tailor-platform/sdk";
+
+export const { approval } = defineWaitPoints((define) => ({
+  approval: define<{ message: string }, { approved: boolean }>(),
+}));
+```
+
+After:
+
+```ts
+import { createWaitPoints } from "@tailor-platform/sdk";
+
+export const { approval } = createWaitPoints((define) => ({
+  approval: define<{ message: string }, { approved: boolean }>(),
+}));
+```
+
 ## openDownloadStream → downloadStream
 
 **Migration:** Manual
@@ -363,9 +567,9 @@ downloadStream and returns FileDownloadStreamResponse.
 
 ## Ambient runtime globals are opt-in
 
-**Migration:** Manual
+**Migration:** Partially automatic
 
-Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. Normal SDK development does not need them — use the SDK APIs and the typed wrappers from `@tailor-platform/sdk/runtime`. Only if you relied on the ambient globals directly, add `import "@tailor-platform/sdk/runtime/globals"`. (The capital-cased `Tailordb.*` namespace is removed separately — see the `Tailordb → tailordb` codemod.)
+Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. The codemod rewrites simple direct `new tailor.idp.Client(...)` calls to the typed `idp.Client` wrapper from `@tailor-platform/sdk/runtime`; broader runtime global usage remains review-only. Only if you relied on the ambient globals directly, add `import "@tailor-platform/sdk/runtime/globals"`. (The capital-cased `Tailordb.*` namespace is removed separately — see the `Tailordb → tailordb` codemod.)
 
 Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:
 
@@ -398,16 +602,17 @@ const client = new tailor.idp.Client();
 ```
 
 <details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
 
 ```text
 The v2 SDK no longer enables ambient Tailor runtime globals from
 `@tailor-platform/sdk`. For each flagged file that uses `tailor.*`,
 `tailordb.*`, or Tailor runtime error globals, prefer migrating to the
-typed wrappers from `@tailor-platform/sdk/runtime` (e.g. replace
-`new tailor.idp.Client()` with `import { idp } from "@tailor-platform/sdk/runtime"`
-and `new idp.Client({ namespace })`). The wrappers are self-contained, so the
-ambient globals are no longer needed.
+typed wrappers from `@tailor-platform/sdk/runtime`. The codemod already
+rewrites direct `new tailor.idp.Client(...)` calls to `new idp.Client(...)`
+when the file has no conflicting `tailor` or `idp` binding. For any remaining
+`tailor.idp.Client` references, either resolve the binding collision and use
+`idp.Client`, or keep the ambient global deliberately.
 
 Only when the file must keep referencing the bare `tailor.*` names directly,
 opt into the global declarations instead by adding one of these:
@@ -416,7 +621,9 @@ opt into the global declarations instead by adding one of these:
   the relevant tsconfig compilerOptions
 
 Leave files unchanged when the matching name is local, imported from another
-module, or appears only in comments or strings.
+module, or appears only in comments or prose strings. Embedded code strings
+that use runtime globals are review-only findings; do not insert imports inside
+string literals.
 ```
 
 </details>
@@ -458,6 +665,55 @@ trigger result as the job output directly (no Promise wrapper to unwrap).
 
 </details>
 
+## tailor-sdk binary → tailor
+
+**Migration:** Partially automatic
+
+Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod.
+
+Before:
+
+```sh
+tailor-sdk deploy
+npx tailor-sdk@latest login
+```
+
+After:
+
+```sh
+tailor deploy
+npx @tailor-platform/sdk@latest login
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Rename any remaining `tailor-sdk` binary invocations to `tailor`. Only rewrite
+the binary name — leave `.tailor-sdk` directory paths and `create-tailor-sdk`
+package references unchanged.
+```
+
+</details>
+
+## .tailor-sdk ignore entries → .tailor
+
+**Migration:** Automatic
+
+Rewrite exact ignore-file entries for the v1 generated output directory from `.tailor-sdk` to the v2 `.tailor` directory. Other `.tailor-sdk` paths and prose are left unchanged.
+
+Before:
+
+```gitignore
+.tailor-sdk/
+```
+
+After:
+
+```gitignore
+.tailor/
+```
+
 ## Behavioral changes (no migration required)
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.
@@ -472,4 +728,8 @@ The CLI stores human users by their stable subject ID instead of email (email is
 
 ### function logs require a content hash for source mapping
 
-`tailor-sdk function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.
+`tailor function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.
+
+### Node.js minimum version raised to 22.15.0
+
+v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. No source change is required; ensure your environment runs Node.js 22.15.0+.

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/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
@@ -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,7 @@ import {
   workflow,
   context,
   file,
+  aigateway,
 } from "@tailor-platform/sdk/runtime";
 
 const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
@@ -35,6 +36,8 @@ const executionId = await workflow.triggerWorkflow("approval", { reportId });
 const invoker = context.getInvoker();
 
 const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
+
+const { url } = await aigateway.get("my-aigateway");
 ```
 
 ## Subpath imports
@@ -76,9 +79,10 @@ 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 (`triggerWorkflow`, `resumeWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
+- `aigateway` — AI Gateway URL resolution (`get`)
 
 ## Testing
 

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,17 @@ 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.